Embedding Agents as Widgets
Xagent can expose an agent through an embeddable chat widget for website or product integration. The widget flow is guest-oriented and runs on the public chat runtime.
How Widgets Work
- The client authenticates a guest against a specific agent.
- It receives a guest chat token.
- It creates a widget chat task.
- The session continues over the widget's WebSocket chat runtime.
POST /api/widget/auth # issue a guest token
POST /api/widget/chat/task/create # create a widget chat task
WS /api/widget/chat/ws/{task_id} # widget chat session (WebSocket)Agent-Level Controls
Widget access is controlled per agent, not globally, through two settings:
| Field | Description |
|---|---|
widget_enabled | Whether the agent can be embedded as a widget. |
allowed_domains | Origins permitted to load the widget. |
Domain Allowlist
The widget authentication flow validates the request origin against the agent's allowed domains. You can allow exact domains, subdomains, or * for unrestricted access.
Prefer a strict allowlist
Use * only if you deliberately want the widget embeddable anywhere. For production, list the exact domains where the widget should run.
Recommended Setup
- Use a focused prompt and keep tools narrow and predictable.
- Add safe suggested prompts.
- Restrict
allowed_domains. - Test guest file uploads and session continuity.