9. Go live

Everything works on localhost. Here is what to settle before the widget is in front of customers.

Checklist

Origins. Your production origins are on the allowed list, and * is not. Include every host that embeds the widget, with the scheme.

Network allowlist. The agent’s Security tab lists your API hosts and nothing else. An empty list means the agent’s code can reach anything.

Allowed secrets. Only the secrets this agent needs, and the instructions say never to print them.

Step cap. Low enough that a stuck agent gives up quickly. For a chat widget, 10 to 15 is usually right.

Knowledge collections checked. The agent is attached to the collections it needs and to no internal one you would not show a customer. Every document in them is ready, and superseded material is filed where the instructions tell the agent not to quote it.

Skills reviewed. Every published skill has been read by a human. Candidates extracted from threads are edited before publishing, not published as they land.

Library pinned to something stable. Agents in production depend on your exported signatures. Adding exports is safe; renaming or reordering arguments breaks conversations mid-flight.

Visitor ids are stable and unguessable. The same person gets the same id across reloads, different people never share one, and the id is not something another user could guess.

Your API authorizes agent traffic properly. Anything the agent calls on your side verifies a token your backend minted, and takes the tenant and the role from that token rather than from vars. Work through securing your app before this is public.

Copy is yours. Welcome message, suggested questions, brand name, and any disclaimer your legal team wants on generated replies.

Failure is graceful. Try it with the network throttled and with the agent’s API returning 500. The reply should say something useful rather than nothing.

Common errors

403 on every request, including the stream. The origin is not allowed. Copy the exact origin from the browser address bar, scheme and port included, and add it on the widget’s Security tab. This is the most common setup problem by a wide margin.

The widget never appears. Check the browser console. A missing data-widget-token or data-user-id logs an error and stops the mount.

The widget loads but every message fails. The widget may be disabled, or the token may have been rotated without updating the snippet. Rotation breaks the old token immediately.

The agent answers without doing anything. It has no library that covers the task, or the instructions do not require a call. Check the thread; if there is no execute, the model decided it could answer alone.

The agent loops on the same error. Read the observation in the thread. A missing secret, a host that is not on the allowlist, and an expired credential all look like this.

The agent ignores a skill you wrote. Confirm it is published, that its tags overlap the agent’s skill tags, and that the description reads like a trigger condition rather than a title.

Answers are correct in the console and wrong in the widget. The widget passes vars the console does not. Print meta.vars from a scratch script and check what actually arrives.

Operating it

Threads created through the widget show up in the console under the agent, so support and engineering can read what customers asked and what the agent ran. Read them weekly at first. The questions the agent handles badly become library functions, and the ones it handles well but slowly become skills.

Instructions, skills, and widget appearance all change without a deploy. Only your embed snippet and your command handlers live in your application, so most tuning happens in the console while your app stays still.

Where to go next

The concepts page is the reference for how organizations, projects, agents, libraries, skills, and widgets relate. Come back to step 4 whenever a conversation teaches you something worth writing down.