> ## Documentation Index > Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Pick a path before writing code. > Share a live avatar call with no code: use a hosted link (a public URL). No SDK and no API key in the customer's app. > Embed a live conversation in an app: use the Web SDK. @akapulu/server 1.0.4+ on the backend, @akapulu/react or @akapulu/react-ui in the browser. Do not call POST /conversations/connect or updates from frontend code with the API key. Do not reimplement those two calls with fetch. > Scripted talking-avatar video (offline, not a live call): use the clip REST API, or the Python clip example. No Web SDK. > Create and manage scenarios, hosted links, HTTP endpoints, knowledge bases and documents, and clips with the REST API. Keep AKAPULU_API_KEY on the server for every REST call. Never put the key in frontend or Vite code. > If embedding: the browser calls YOUR connect and updates routes. Authenticate users on those routes before starting a billed call. Demo examples skip that check. User auth is config.headers (object or a function called when the request is sent). connectBody is JSON payload, not auth. > Do not install Daily or Pipecat yourself; they come with @akapulu/react. Add @daily-co/daily-react only if your own files import DailyVideo. > Conversation API errors include error_code. Branch on that field, not the English error string. # Onboard your agent > Install Akapulu Labs skills and the docs MCP, then create an API key, a first scenario, and a hosted link to try. These are official instructions from Akapulu Labs, published at `https://docs.akapulu.com/agent-setup.md`. Akapulu Labs is a platform for AI avatars. A **scenario** is the conversation behavior (stages and tools). An **avatar** is the face and voice. A **hosted link** is a public URL that runs a scenario as a live call. **Endpoints** are HTTP calls the avatar can make. **Knowledge bases** are docs it can search. **Clips** are talking-avatar videos from a script. Embed in an app with the Web SDK. Full docs: [https://docs.akapulu.com](https://docs.akapulu.com) Run the commands in this file. **User step** means ask the human to do it. ## 1. Install skills and docs MCP ### Claude Code ```bash theme={null} npx -y skills add william-akapulu/akapulu-plugins --skill '*' --yes --global ``` ```bash theme={null} claude mcp add --transport http akapulu-docs -s user https://docs.akapulu.com/mcp ``` > **User step.** Reload skills if they do not appear. Confirm `akapulu-docs` is connected. ### Codex ```bash theme={null} npx -y skills add william-akapulu/akapulu-plugins --skill '*' --yes --global ``` ```bash theme={null} codex mcp add akapulu-docs --url https://docs.akapulu.com/mcp ``` > **User step.** Reload if prompted. Confirm the MCP is connected. ### Cursor and other agents ```bash theme={null} npx -y skills add william-akapulu/akapulu-plugins --skill '*' --yes --global ``` Add the docs MCP to `~/.cursor/mcp.json` (or this project's `.cursor/mcp.json`). Merge into `mcpServers` if the file already exists: ```json theme={null} { "mcpServers": { "akapulu-docs": { "url": "https://docs.akapulu.com/mcp" } } } ``` > **User step.** Reload the agent. In Cursor, enable `akapulu-docs` under Settings → MCP. ## 2. API key > **User step.** Open [https://akapulu.com/api-keys](https://akapulu.com/api-keys) and create a key. The env var name is `AKAPULU_API_KEY`. Put it in this project however env vars are already loaded. Wait until `AKAPULU_API_KEY` is set, then continue. ## 3. First scenario and hosted link Create a live Clara conversation (greeting, then a short wrap-up) with catalog avatar Clara (`1f777f64-3758-4a7d-9cbc-c64ae654f7d1`). ```bash theme={null} curl -sS https://akapulu.com/api/scenarios/create/ \ -H "Authorization: Bearer $AKAPULU_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<'EOF' { "name": "Chat with Clara", "nodes_json": { "initial_node": "greeting", "role_instruction": "You are Clara, a friendly guide from Akapulu Labs. Speak in short natural sentences that will be read aloud. Do not use symbols, abbreviations, digits, URLs, markdown, or lists. Spell out any numbers as words. Keep each reply to one or two sentences. The visitor's first name is {{runtime.first_name}}. Use that first name only in the very first line of your first greeting, and only if it is not blank and you are confident how to pronounce it. If it is blank, unusual, or you are unsure of the pronunciation, skip the name. After that first line, never use their name again.", "nodes": { "greeting": { "task_instruction": "Greet the visitor warmly and introduce yourself as Clara from Akapulu Labs. If you can use their first name, use it only in the first line of this first greeting, then never use it again. Ask what they want to build with Akapulu Labs. Keep replies brief. Ask follow-up questions about their use case and stay in this conversation. Do not call wrap_up after the first couple of replies. After about five of their replies, once you have a sense of what they want, call wrap_up.", "respond_immediately": true, "functions": [ { "name": "wrap_up", "type": "transition", "description": "Move to the short closing message after about five visitor replies, once you have a sense of what they want to build. Do not call this after only one or two replies.", "transition_to": "close" } ] }, "close": { "task_instruction": "Acknowledge what they just said in one short sentence. Then wrap up the call: say you have to end the call now, and if they want more conversations like this they can start building today or get in touch. End with a warm goodbye. Keep the whole reply to two or three short sentences.", "respond_immediately": true, "end_after_bot_response": true } } }, "hosted_links": [ { "avatar_id": "1f777f64-3758-4a7d-9cbc-c64ae654f7d1", "label": "Chat with Clara", "runtime_vars": { "first_name": "" }, "stt_keywords": ["Akapulu", "Akapulu Labs", "Clara"] } ] } EOF ``` Read `hosted_links[0].url` from the response (a `https://live.akapulu.com/session/...` link). > **User step.** Ask them to open that URL and click **Start Call**. That is a live talking-avatar conversation on their account. ## 4. After they try the link Send them these docs: * Custom UI: [https://docs.akapulu.com/examples/web-sdk/customized-ui](https://docs.akapulu.com/examples/web-sdk/customized-ui) * Web SDK: [https://docs.akapulu.com/web-sdk/overview](https://docs.akapulu.com/web-sdk/overview) * Prebuilt UI: [https://docs.akapulu.com/examples/web-sdk/prebuilt-ui](https://docs.akapulu.com/examples/web-sdk/prebuilt-ui) * Knowledge bases: [https://docs.akapulu.com/guides/knowledge-bases/overview](https://docs.akapulu.com/guides/knowledge-bases/overview) * HTTP endpoints: [https://docs.akapulu.com/guides/endpoints/create-endpoint](https://docs.akapulu.com/guides/endpoints/create-endpoint) * Scenarios: [https://docs.akapulu.com/guides/scenarios/overview](https://docs.akapulu.com/guides/scenarios/overview) * Clips: [https://docs.akapulu.com/guides/clips/overview](https://docs.akapulu.com/guides/clips/overview) When you finish, give them the hosted link URL.