# Software Factory: 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 software factory 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 software factory SaaS project (created via the standard flow) - Project admin privileges in the software factory ## 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 the software factory, 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 the project agent 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, the agent 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 software factory 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 ## Upgrading and licenses The embedded Chipp agent pack is free and has no license. Its install record shows no license ID, and that is correct. To upgrade it, run **Generate chat UI + backend integration** again (in chat, the agent calls `install_embedded_chipp_agent` again). The generic `preview_pack_install` and `apply_pack_install` tools do not upgrade it: they answer `PACK_NOT_SOLD_NO_LICENSE` and name this call. If a pack is sold in the marketplace, the platform never records it as installed without a license. A refused install or upgrade returns one of these codes, and the installed version keeps working unchanged: - `PACK_ENTITLEMENT_REQUIRED`: the project holds no active license for the pack. Buy or redeem a license for this project, then retry. - `PACK_ENTITLEMENT_PROVISIONING_FAILED`: the installed copy was recorded without a license. Buy or redeem a license for this project, then retry. `entitlement_id` is optional on `preview_pack_install` and `apply_pack_install`. Leave it out and the project's active license for the pack is used. ## 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: - **[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