Alchemist: Embedded Agent: Inline Panel

The inline panel is a native chat interface that lives in your application alongside other content. Unlike the floating widget, it is part of your page layout and does not float over content.

When to use the inline panel

Use the inline panel when:

• You want the agent on a dedicated page or section (for example a “Chat” or “Assistant” page)
• The agent is a core feature of your application, not supplementary
• You need control over where the panel appears (sidebar, main column, modal, and so on)

For a launcher button that floats over your site, use the floating widget instead.

Basic setup

1. Install the feature pack

Follow the installation guide first and check Inline panel. The pack adds the Svelte component web/src/lib/embedded-agent/EmbeddedAgentPanel.svelte.

2. Render the panel

Import it in any page and place it where the chat should appear:

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

<main class="page">
  <EmbeddedAgentPanel />
</main>

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 chat. The panel has a minimum height of 20rem and fills the width of its container.

Component props

The component takes one optional prop:

<EmbeddedAgentPanel context={{ page: "billing" }} />

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).

Everything else (identity, token handling, styling) is handled for you.

Authentication & identity

The identity mode you chose at install time decides which session route the panel 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 user’s conversations are kept across sessions, and the panel loads previous messages on mount. The panel 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 panel 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.

If the session cannot be minted (the user is signed out, or the feature is not configured), the panel shows “Chat is not available right now.” instead of failing the page.

Styling & customization

The panel renders natively (no iframe), so it inherits your page’s fonts. Colors and shapes come from --chipp-embed-* CSS variables, which fall back to your design tokens (--primary, --background, --foreground, --border, --radius):

Set any of them on a wrapper element:

.chat-wrapper {
  --chipp-embed-accent-color: #0f766e;
  --chipp-embed-radius: 0.75rem;
}

Errors and retries

If a message fails to send (network, CORS, a 4xx or 5xx, a stream error), the panel marks it “not sent” with an inline error and a Retry button. If history fails to load, the panel shows a banner with Retry.

Troubleshooting

Panel 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.

Messages not persisting across sessions

• In anonymous mode this is expected: each page load is a new visitor.
• In authenticated mode, conversations are tied to the signed-in user.

Styling does not match my design system

• Set the --chipp-embed-* variables (see “Styling & customization” above), or define the design tokens they fall back to.

Next steps

• Floating widget: add a floating chat widget
• Backend client: call the agent from your server routes