Embeddable Widget

Overview

The widget is a standard Web Component (<agent-chat>). Drop one script tag and one HTML element into any page — React, Angular, Vue, plain HTML — and it works. The host app doesn’t need to install React or any chat dependencies. Requires agent-manager running (not agentctl serve). See Quickstart — Path 2.

Basic embed

<script type="module" src="https://your-backend.example/widget.js"></script>
<agent-chat title="Support" color="#6366f1"></agent-chat>

Modes

Floating (launcher button)

A circular button in the corner. Clicking it opens the chat panel.

<agent-chat
  title="Support"
  color="#6366f1"
  greeting="Hi! How can I help you today?"
  mode="floating"
  position="bottom-right">
</agent-chat>

position options: bottom-right (default), bottom-left

Inline

Renders as a fixed panel directly in the page — no launcher button.

<agent-chat
  title="Assistant"
  color="#7c3aed"
  mode="inline">
</agent-chat>

All attributes

Attribute	Default	Description
`title`	`"Assistant"`	Header text
`color`	`"#6366f1"`	Accent color (launcher button, send button, focus ring)
`greeting`	—	First message shown when the chat opens
`mode`	`"floating"`	`"floating"` or `"inline"`
`position`	`"bottom-right"`	Floating position: `"bottom-right"` or `"bottom-left"`
`token-url`	—	URL on the host backend returning `{ "token": "…" }` for the signed-in user. Resolved relative to the page. See Identity
`require-identity`	off	Never fall back to an anonymous visitor when identity cannot be obtained
`endpoint`	the directory `widget.js` was served from	Base URL of the manager API. Only needed when the script and the API live at different URLs

The element also exposes these hooks for host apps:

element.tokenProvider = async () => token — for a SPA holding its token in memory instead of exposing token-url.
element.refreshIdentity() — re-resolves the caller after a SPA signs a user in or switches user.
element.logout() — clears the stored identity and thread when the host signs a user out.
agent-chat:identity-error event — raised when a configured token-url cannot be used.

With neither configured, the widget asks the manager for a visitor pass, so a product with no login still gets one isolated conversation per browser.

Script-only embed (no HTML tag)

For apps where you can only inject a <script> — like a CMS or a platform that restricts HTML — the widget auto-mounts if you set window.agentChatConfig:

<script>
  window.agentChatConfig = {
    title: "Support",
    color: "#6366f1",
    greeting: "Hi! How can I help?",
    mode: "floating"
  };
</script>
<script type="module" src="https://your-backend.example/widget.js"></script>

If no <agent-chat> element exists on the page, the widget creates one on <body> automatically.

Framework integration

React

export function SupportChat() {
  return <agent-chat title="Support" color="#6366f1" mode="floating" />;
}

Angular

Allow custom elements in your module:

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Then use it in a template:

<agent-chat title="Support" color="#6366f1"></agent-chat>

Vue / plain HTML

No setup needed — just the script tag and the element.

Listening to events

The widget emits a DOM event after each answer, with routing and tool metadata:

document.querySelector("agent-chat").addEventListener("agent-chat:answer", (e) => {
  console.log(e.detail.answer);        // final text response
  console.log(e.detail.visited);       // routing path, e.g. ["router", "router/orders_agent"]
  console.log(e.detail.used_tools);    // tools called during this run
});

Only safe metadata is exposed — no internal reasoning, no prompt content.

Streaming

The widget connects to the streaming endpoint (POST /conversations/{id}/messages/stream) and renders tokens as they arrive. If streaming fails before a usable answer, it falls back to the standard endpoint automatically.

Tool approvals

When a tool requires human approval, the widget pauses the current run and shows the tool’s human-readable description and three actions:

Approve — allow only this tool invocation.
Deny — reject this invocation without running the tool.
Approve for this session — allow this invocation and stop asking for the same scoped tool during the current conversation.

The decision resumes the existing run through the conversation approval API; it does not resend the user’s message. Hosts must keep the same authenticated conversation identity for the decision. Afterward, the run either completes or shows the next approval request.

Session recovery

The widget stores the conversation_id in localStorage. If the backend restarts and no longer knows that conversation, the widget detects it, clears the stale id, and starts a fresh conversation automatically — no action needed from the user.

Get Started

Core Concepts

Features

Widget

Reference

Embeddable Widget

Overview

Basic embed

Modes

Floating (launcher button)

Inline

All attributes

Script-only embed (no HTML tag)

Framework integration

React

Angular

Vue / plain HTML

Listening to events

Streaming

Tool approvals

Session recovery

​Overview

​Basic embed

​Modes

​Floating (launcher button)

​Inline

​All attributes

​Script-only embed (no HTML tag)

​Framework integration

​React

​Angular

​Vue / plain HTML

​Listening to events

​Streaming

​Tool approvals

​Session recovery

Overview

Basic embed

Modes

Floating (launcher button)

Inline

All attributes

Script-only embed (no HTML tag)

Framework integration

React

Angular

Vue / plain HTML

Listening to events

Streaming

Tool approvals

Session recovery