Alchemist: Embedded Agent: Floating Widget

The floating widget is a toggleable chat interface that floats over your application content. It appears as a launcher button in the bottom-right corner and opens a chat panel when clicked.

When to use the floating widget

Use the floating widget when:

• The agent is supplementary to your main application (support, help, search assistant)
• You want a low-intrusion interface that users can open, minimize, and close
• You want the agent available on every page with one line of code

For an agent interface that is part of your page layout, use the inline panel instead.

Basic setup

1. Install the feature pack

Follow the installation guide first and check Floating widget. The pack adds the Svelte component web/src/lib/embedded-agent/EmbeddedAgentWidget.svelte.

2. Render the widget

Place it once, for example in App.svelte:

<script lang="ts">
  import EmbeddedAgentWidget from "$lib/embedded-agent/EmbeddedAgentWidget.svelte";
</script>

<!-- your app layout -->
<EmbeddedAgentWidget />

On mount, the component calls your project’s own session route (POST /api/embedded-agent/session; /api/embedded-agent/session/anonymous in anonymous mode; in “Both” mode the first, then the second if the visitor is signed out), gets a short-lived chat token, and renders the launcher.

Component props

The component takes one optional prop:

<EmbeddedAgentWidget context={{ page }} />

Rules for context:

• Use only keys the binding allows (set in Settings > Embedded agent settings > Page context keys, or from contextKeys in chipp/agent.json, which replaces that list on every agent sync). The runtime drops other keys.
• Never put personal data in it (names, emails, dates of birth, record IDs).

The generated component docks to the bottom-right corner. The vendored client in web/src/lib/embedded-agent/embed-client/ also supports position: "bottom-left", initiallyOpen, launcherLabel, panelLabel, and onStateChange; edit the mountChippEmbedWidget(...) call in the component to use them.

Widget behavior

• The launcher opens the chat. The open panel has Minimize chat and Close chat buttons.
• The launcher shows an unread badge when the agent replies while the panel is closed or minimized.
• On screens 480px wide or narrower, the open panel fills the whole screen and respects the device safe areas.
• If the session cannot be minted (the user is signed out, or the feature is not configured), the widget shows “Chat is not available right now.” instead of failing the page.

Authentication & identity

The identity mode you chose at install time decides which session route the widget calls. You do not pass identity as a prop.

• Authenticated: the session route requires a signed-in user in your project and mints the session with that user’s ID and email. The widget re-mints the session every 10 minutes so the agent keeps access to your app’s tools in a long conversation.
• Anonymous: the session route mints a pseudonymous visitor session. Nothing is stored in a cookie, so a page reload starts a new visitor and a new conversation.
• Both: a signed-in user gets an authenticated session; a signed-out visitor gets an anonymous one. When the visitor signs in, the widget upgrades the session and keeps the conversation. After an SPA login (no page reload), call notifyEmbeddedAgentSignedIn() from web/src/lib/embedded-agent/session-client.ts. See Session upgrading.

Styling & customization

The widget uses the same --chipp-embed-* variables as the inline panel, plus these for the floating chrome:

:root {
  --chipp-embed-widget-offset: 2rem;
  --chipp-embed-widget-z-index: 50;
}

Troubleshooting

Widget button not visible

• Verify the component is rendered (not inside a conditional that is false).
• If another element covers it, check --chipp-embed-widget-z-index.
• If the widget shows “Chat is not available right now.”, the session could not be minted (see below).

Widget shows “Chat is not available right now.”

• In authenticated mode, confirm the user is signed in to your project.
• Confirm the binding is active in the project’s Settings tab.
• Check your server logs for Embedded agent session entries. A missing CHIPP_PROJECT_CLIENT_KEY returns 503; a failed mint returns 502.

Chat resets

• Chat tokens last 1 hour. In authenticated mode the widget re-mints every 10 minutes.
• In anonymous mode each page load is a new visitor, so a reload starts a new conversation.

Next steps

• Inline panel: embed a panel as part of your layout
• Backend client: call the agent from your server routes