Alchemist Operations

Alchemist: Embedded Chipp Agent

Bind a Chipp AI agent to your Alchemist project and embed it in your application using inline panels, floating widgets, or backend calls.

|View as Markdown
Chipp EngineeringEngineering at Chipp
||1 min read
#alchemist#embedded-agent#chipp-agent#chatbot

The Embedded Chipp Agent feature allows you to bind an existing Chipp AI agent to your Alchemist project and offer it to your end users through multiple interfaces: an inline chat panel, a floating widget, or backend API calls from your application server.

This guide covers the complete workflow: installing the feature pack, binding an agent, and deploying one or more user interfaces.

What is an embedded Chipp agent?

A Chipp agent is a configured AI application with its own models, prompts, knowledge, and actions. When you bind an agent to an Alchemist project, you enable:

  • Native UI: inline panels and floating widgets styled to your project’s design system (no iframe, no external domain)
  • Backend integration: your server can invoke the agent programmatically to power search, recommendations, or autonomous workflows
  • Session management: authenticated end-user sessions (with email) or anonymous visitor sessions (pseudonymous, no auth required)
  • Consolidated billing: usage is metered under the organization that owns the Chipp agent, appearing in the standard Chipp billing dashboard

Core concepts

Bindings

A binding is the configuration that links a Chipp agent to an Alchemist project. It stores the application ID of the Chipp agent, whether anonymous visitors are allowed and how their chats are retained, and which page context keys the agent accepts. The identity mode (authenticated, anonymous, or both) and the installed surfaces are recorded when you generate the integration, and generating sets the binding’s anonymous access to match the mode. You change retention, page context keys, and the chat session key in the project’s Settings tab, under Embedded agent settings.

A project has one active binding at a time. You can replace or remove it at any time; the generated session route resolves the active binding server-side. The binding itself is secure: secrets are never committed to your codebase.

Identity modes

When a user interacts with an embedded agent, they authenticate in one of two ways:

  1. Authenticated mode: the user is signed in to your project. Your project’s backend passes the signed-in user’s ID and email when it mints the session, and Chipp keeps their conversation history across sessions. This is the default.

  2. Anonymous mode: the user is not required to sign in. A pseudonymous visitor session is minted each time the chat mounts. Nothing is stored in a cookie, so a page reload starts a new visitor and a new conversation. This suits public websites where users should not be asked to sign up.

You can also choose both: signed-in users get a signed-in session, everyone else an anonymous one. When an anonymous visitor signs in, the session is upgraded and the conversation moves to their account. This mode generates three session routes: /session, /session/anonymous, and /session/upgrade.

For backend API calls, your server specifies the identity explicitly, with no implicit inference.

Session endpoints

The Alchemist project provides private backend endpoints (/api/client/embed/session*) for minting and managing user sessions. Your application’s backend uses these endpoints to:

  • Create or upgrade user sessions
  • Rotate existing sessions
  • Revoke sessions on logout

All endpoints require your project’s client key with scope: "full". (The Builder preview runs with a narrower key that can mint sessions but cannot upgrade, rotate, or revoke them.) These endpoints are never exposed to the browser; your frontend calls your own backend instead, which delegates to Chipp.

Product rules

To preserve data consistency and security:

  • Same-org only: You can only bind agents created in the same organization. Cross-org agents are never visible or bindable.
  • No duplication: Bindings reference existing agents; they never clone or provision new agents. Create agents through the normal Chipp app-creation flow, then bind them.
  • Uninstall safety: Removing the generated integration deletes the installed code and the binding (removing only the binding leaves the code in place), but never deletes the underlying Chipp agent or user conversations. Your agent data is preserved.
  • Billing continuity: Usage is billed normally through Chipp’s metering, attributed to the organization that owns the bound agent’s application. No new billing path.

Next steps

Choose your path based on how you want to surface the agent: