# Alchemist: Install & Bind the Embedded Agent

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

---

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:
```
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:

- **[Inline chat panel](/docs/guides/alchemist-embedded-chipp-agent-inline-panel/)** — Add the panel to specific pages
- **[Floating widget](/docs/guides/alchemist-embedded-chipp-agent-widget/)** — Deploy a persistent chat widget
- **[Backend client](/docs/guides/alchemist-embedded-chipp-agent-backend/)** — Integrate agent calls in your server routes