# 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.

---

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. Each binding stores:
- The **application ID** of the Chipp agent
- The **external user/tenant mapping** (how your end users identify in Chipp)
- Session and identity configuration (authenticated vs anonymous)

An Alchemist project can have one or more bindings; you can add, replace, or remove bindings at any time without modifying your application code. 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 logs in with email via OTP (one-time password). Chipp records the user's email and maintains their conversation history across sessions. This is the default for most SaaS applications.

2. **Anonymous mode** — The user is not required to log in. Instead, a pseudonymous visitor session is created (stored in a browser cookie). Conversations are retained for the duration of that session. This is ideal for public websites and floating widgets where users should not be asked to sign up.

For backend API calls, your server specifies the identity explicitly — 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"`. 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 feature pack or a binding deletes the installed code and session configuration, 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:

- **[Install the feature pack](/docs/guides/alchemist-embedded-chipp-agent-install/)** — Register the feature and bind an agent to your project
- **[Embed an inline panel](/docs/guides/alchemist-embedded-chipp-agent-inline-panel/)** — Display the agent as a built-in part of your application interface
- **[Embed a floating widget](/docs/guides/alchemist-embedded-chipp-agent-widget/)** — Display the agent as a persistent floating button that opens a chat window
- **[Backend client integration](/docs/guides/alchemist-embedded-chipp-agent-backend/)** — Call the agent from your application server for search, recommendations, or workflows