Alchemist Operations

Alchemist: Install & Bind the Embedded Agent

Install the embedded-Chipp-agent feature pack and bind it to an existing agent in your organization.

|View as Markdown
Chipp EngineeringEngineering at Chipp
||1 min read
#alchemist#embedded-agent#feature-pack#installation

This guide walks you through installing the embedded-Chipp-agent feature pack in an existing Alchemist project and binding it to a Chipp agent in your organization.

Prerequisites

  • A Chipp application (agent) in your organization, already created through the normal Chipp app-builder interface
  • An existing Alchemist SaaS project (created via the standard flow)
  • Project admin privileges in Alchemist

Installation flow

Installing the pack does these steps:

  1. List same-org agents: shows the Chipp agents in your project’s organization (cross-org agents are never listed)
  2. Select & bind: you choose which agent to bind; the binding is created server-side
  3. Generate the integration: the pack commits these files into your project:
    • src/services/embedded-agent/router.ts: the session proxy, mounted at /api/embedded-agent. Authenticated mode adds /session, anonymous mode adds /session/anonymous, and “Both” adds /session, /session/anonymous, and /session/upgrade
  4. Set anonymous access: the binding’s anonymous access is turned on for “Anonymous visitors only” and “Both”, and off for “Authenticated users only”. Without this, anonymous sessions are refused.
    • src/services/embedded-agent/client.ts: the server-side client that mints chat tokens
    • src/services/embedded-agent/backend-example.ts: a server-to-server example
    • web/src/lib/embedded-agent/EmbeddedAgentPanel.svelte (inline panel) and/or EmbeddedAgentWidget.svelte (floating widget)
    • A vendored browser client in web/src/lib/embedded-agent/embed-client/, a test, and agent guidance in docs/agent-guidance/embedded-chipp-agent.md

Installation steps

1. Open the project’s Settings tab

In Alchemist, open the project and go to the Settings tab.

2. Bind an agent

In the Embedded agent card, pick an agent from the dropdown (it lists the agents in your project’s organization) and click Bind agent. The card then shows “Currently bound: [Agent Name]“.

3. Generate the integration

In the Generate chat UI + backend integration card below it:

  1. Choose an Identity mode: “Authenticated users only”, “Anonymous visitors only”, or “Both”.
  2. Check the surfaces you want: Inline panel, Floating widget, or both.
  3. Click Generate integration.

When it finishes, the card shows “Integration active for [Agent Name]” with the identity mode, the installed surfaces, and the pack version.

You can also ask Alchemist in chat to do this. It uses the install_embedded_chipp_agent tool.

4. Adjust the settings (optional)

The Embedded agent settings card below has three controls:

  • Anonymous visitors: “Saved (like signed-in chats)” or “Not saved (kept up to 4 hours)”. Shown only when anonymous access is on.
  • Page context keys: the context keys the agent accepts from your pages, comma separated, plus an optional max value length. Empty means no page context. If the project defines its agent in chipp/agent.json, every agent sync replaces this list with the file’s contextKeys.
  • Chat session key: Rotate key replaces CHIPP_PROJECT_CLIENT_KEY and pushes the new key to your deployed app. The old key keeps working until you click Revoke old key, so revoke it after the app has restarted.

Managing the binding

Replace the binding

In the Embedded agent card, pick a different agent and click Replace binding. The generated session route resolves the active binding server-side, so the session endpoint stays the same.

Add a surface

If you installed only one surface, the Generate chat UI + backend integration card shows Add panel or Add widget. Click it to add the missing surface. (In chat, Alchemist uses add_embedded_chipp_agent_surfaces.)

Remove the integration

In the Generate chat UI + backend integration card, click Remove generated integration.

This:

  • Deletes the generated panel, widget, and session-route code from your project
  • Removes the binding
  • Preserves the Chipp agent and all user conversations

The Remove button in the Embedded agent card removes only the binding and leaves the generated code in place.

Environment & secrets

The generated session proxy authenticates to the Alchemist API with a project client key (alch_proj_...) in the CHIPP_PROJECT_CLIENT_KEY environment variable. The platform provisions it when the pack is installed; you do not need to create it. If it is missing, the session route returns a 503 and the chat shows “Chat is not available right now.”

Two optional settings override the default hosts:

  • CHIPP_PLATFORM_API_URL (default https://build.chipp.ai/alchemist-api): where sessions are minted
  • CHIPP_API_BASE_URL (default https://build.chipp.ai): the Chipp chat runtime

Troubleshooting

”No agents found in this project’s organization yet”

  • Create an agent in Chipp first, then come back to the Settings tab to bind it.
  • Only agents in the project’s own organization are listed. An agent in a different organization cannot be bound.

”Install was successful but I see no new files”

  • The pack commits its files to your project’s repository. They live under src/services/embedded-agent/ and web/src/lib/embedded-agent/.
  • Pull the latest changes or refresh your file tree.

Chat shows “Chat is not available right now.”

  • The session could not be minted. In authenticated mode the user must be signed in to your project. (“Both” mode falls back to an anonymous session for signed-out visitors.)
  • In anonymous or “Both” mode, check that the Embedded agent settings card does not say “Anonymous visitors are off”. If it does, generate the integration again.
  • Verify the binding is still active in the Settings tab.

Next steps

Once the feature pack is installed and your agent is bound: