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

The feature pack install process performs these steps automatically:

  1. List same-org agents — Displays all Chipp agents in your organization (enforces cross-org authorization)
  2. Select & bind — You choose which agent to bind; a secure binding is created server-side
  3. Generate endpoints — Session endpoints (/api/client/embed/session*) are scaffolded
  4. Install UI templates — The feature pack adds:
    • An inline chat panel component (ready to embed in any page)
    • A floating widget component (persistent, toggleable)
    • A backend proxy route example (for server-side agent calls)
    • Full TypeScript types for session identity

Installation steps

1. Open the project in Alchemist

In your Alchemist workspace, open the project where you want to add the agent.

2. Add the feature pack

Go to Project Settings → Feature Packs and click Add Pack.

3. Select embedded-Chipp-agent

From the available packs, select Embedded Chipp Agent. The pack details show:

  • Description of the feature
  • System requirements (specific to your project stack)
  • Pricing note: “Billing continues through normal Chipp metering, attributed to the bound agent’s organization.”

Click Install.

4. Choose your agent

A dialog appears listing all agents in your organization (same-org authorization enforced). Select the agent you want to bind. The agent’s details display:

  • Agent name & description
  • Model & system prompt summary
  • Number of threads & recent activity

Click Bind.

5. Install confirmation

The install completes. You see:

  • Binding status: “Active, bound to [Agent Name]”
  • Session endpoint: The generated project-side session endpoint (never the Chipp endpoint)
  • Code templates: Links to the installed panel, widget, and backend examples
  • Environment setup: Instructions for any required secrets (client key, API endpoint)

The feature pack also creates a code generation output showing:

  • Session initialization examples
  • Inline panel component ready to import
  • Floating widget initialization code
  • Backend client setup with retries & timeouts

Managing the binding

View the binding

In Project Settings → Embedded Agent, you see the current binding status:

  • Bound agent name
  • Session creation date
  • Last activity
  • Uninstall button (removes code and binding, not the agent)

Replace the binding

To bind a different agent:

  1. Go to Project Settings → Embedded Agent
  2. Click Replace Agent
  3. Select a new agent from your organization
  4. Confirm; the binding updates immediately
  5. No code regeneration is needed (the session endpoint remains the same)

Add more panels or widgets

To generate additional copies of the inline panel or floating widget for different pages:

  1. Go to Project Settings → Embedded Agent → Generate Component
  2. Choose Inline Panel or Floating Widget
  3. Specify the page or region where it will be installed
  4. Generate; a new component is added to your project with a unique instance ID

Uninstall the feature pack

In Project Settings → Feature Packs, find the embedded-agent pack and click Remove.

Uninstalling:

  • Deletes the installed panel, widget, and endpoint code from your project
  • Removes the binding configuration
  • Preserves the Chipp agent and all user conversations
  • Does not affect billing; it stops after uninstall

Environment & secrets

The feature pack uses your project’s existing client key (alch_proj_...) to authenticate session creation. This key is already generated and stored securely; you do not need to provision it manually.

For local development, ensure your .env.local includes:

plaintext
ALCHEMIST_PROJECT_CLIENT_KEY=alch_proj_...

This is typically auto-populated by the project’s setup script. If you need to rotate the key, use Project Settings → API Keys → Rotate Client Key.

Troubleshooting

”No agents found in your organization”

  • Verify at least one Chipp agent exists by going to the main Chipp workspace and viewing your applications.
  • Confirm you are logged into the correct organization (check the org switcher in Alchemist).
  • If the agent exists but is not listed, it may belong to a different organization.

”Binding failed: unauthorized”

  • Ensure your project’s client key has scope "full" (check Project Settings → API Keys).
  • If you see a scope mismatch, rotate the key and try again.

”Install was successful but I see no new files”

  • The install generates files in your project’s source tree. Check Project Settings → Embedded Agent → View Generated Code for the exact file paths.
  • If files are not visible in your editor, refresh your file tree or restart your development server.

Agent offline or conversations not loading

  • Verify the bound Chipp agent is deployed and online (check the agent’s status in Chipp).
  • If the agent is offline, conversations may appear as “unavailable” until it comes back online. This is temporary.

Next steps

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