# Software Factory: Embedded Agent: Inline Panel Embed a native chat panel as part of your application interface. --- 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](/docs/guides/alchemist-embedded-chipp-agent-widget/) instead. ## Basic setup ### 1. Install the feature pack Follow the [installation guide](/docs/guides/alchemist-embedded-chipp-agent-install/) 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: ```svelte
``` 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: | Prop | Type | Purpose | |------|------|---------| | `context` | `Record` | Page context sent with each message, for example `{ page: "billing" }` | ```svelte ``` 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](/docs/guides/alchemist-embedded-chipp-agent-identity-and-billing/#session-upgrading-anonymous-to-authenticated). 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`): | Variable | Default | |----------|---------| | `--chipp-embed-accent-color` | `var(--primary, #4f46e5)` | | `--chipp-embed-background` | `var(--background, #ffffff)` | | `--chipp-embed-foreground` | `var(--foreground, #111111)` | | `--chipp-embed-muted` | `var(--muted-foreground, #6b7280)` | | `--chipp-embed-border-color` | `var(--border, #e5e7eb)` | | `--chipp-embed-radius` | `var(--radius, 0.5rem)` | | `--chipp-embed-error-color` | `#dc2626` | | `--chipp-embed-font-family` | `inherit` | Set any of them on a wrapper element: ```css .chat-wrapper { --chipp-embed-accent-color: #0f766e; --chipp-embed-radius: 0.75rem; } ``` ## Voice Turn voice on with the `voice` switch in `chipp/agent.json` (`"capabilities": { "voice": true }`), then sync the agent. The panel then offers: - **Mic**: record a message. The transcript goes into the message box. - **Read aloud**: a play button under each reply, and a toggle that reads each new reply aloud. Replies are read in the agent's selected voice. If you picked a voice under **Bring your own voice** (ElevenLabs) in the agent's Voice settings, that voice reads the replies, billed to your own ElevenLabs account. If the selected voice cannot be used (for example your ElevenLabs key ran out of credits), the panel says so. It never swaps in a stock voice. - **Voice mode**: a live, two-way voice conversation. The button shows when the agent's **Voice agent** is also turned on in Chipp. Voice mode opens an animated voice view with **Mute**, **Transcript** and **Exit voice mode**. You can talk over the agent at any time, and it stops to listen. The conversation continues the open chat thread, so when you exit, everything that was said is in the text chat. Voice mode runs through Chipp: your app never holds an ElevenLabs or LiveKit key, and usage is billed and limited like every other voice call. If voice mode cannot start (the microphone is blocked, the plan does not include voice, voice is turned off for the agent, or the session fails), the panel shows one sentence and the text chat keeps working. The panel loads the LiveKit web client for voice mode from a pinned public build. If your app installs `livekit-client` itself, or its content security policy blocks that host, ask the AI Engineer to pass `loadLiveKit: () => import("livekit-client")` to the panel. ## 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](/docs/guides/alchemist-embedded-chipp-agent-widget/)**: add a floating chat widget - **[Backend client](/docs/guides/alchemist-embedded-chipp-agent-backend/)**: call the agent from your server routes