# Get your API Key
Source: https://docs.anam.ai/api-key



Your API key is used to authenticate your requests to the Anam API and is required for integrating the Personas you create into your own applications.
API keys are managed via the [Anam Lab](https://lab.anam.ai/).

### Create a new API key

From the [API keys page](https://lab.anam.ai/api-keys), click on the "Create API key" button.

<Note>
  The label is only used to help you identify the API key. It is not used for authentication.
</Note>

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=620bfe2d6cd123ad08330f99e0cd490a" alt="Create a new API key" data-og-width="533" width="533" data-og-height="257" height="257" data-path="images/get-started/create-api-key-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=bd8d59aaee729403640a10fc10b3c8a1 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=9b484a13e011b5b570994c9437a6be32 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=3282d374f8ac885b4b7fa11d3e2e9edc 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=3fd001b8d03df24bc4fcadbdeb7bf16b 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=ca2719e2f1c2f6c5c500193cf4aa6089 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/create-api-key-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=9723b3dd51830f7fe6885965b65a759b 2500w" />
</Frame>

Click "Create" and your new API key will be shown to you. Remember to save it somewhere safe as you will not be able to access it later.
You will be prevented from closing the dialog until you have clicked the "Copy" button.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=6f0ad497ea5d0a807b5d2779719c18c7" alt="API key created" data-og-width="537" width="537" data-og-height="294" height="294" data-path="images/get-started/new-api-key-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=e995fa08bf1775603aa4c9c6c1594abc 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=3612256b7a6fb435de1b315ab1a12f9c 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=0f29fe1722ee2e353aad2ee5d42d75be 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=556772646ec9d3e84ca575262f093ee4 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=39f71bd9fa72ba8e079506d128342522 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/get-started/new-api-key-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=3bf23c40c79fcb09060ef987f4233b34 2500w" />
</Frame>

<Warning>
  Anam encrypts and store your API keys securely. For this reason, we are unable to recover lost API keys.
  If you lose your API key, you will need to create a new key via the Anam Lab.
</Warning>


# Create knowledge group
Source: https://docs.anam.ai/api-reference/create-knowledge-group

openapi.json post /v1/knowledge/groups
Create a new knowledge group



# Create LLM
Source: https://docs.anam.ai/api-reference/create-llm

openapi.json post /v1/llms
Create a new LLM configuration



# Create one-shot avatar
Source: https://docs.anam.ai/api-reference/create-one-shot-avatar

openapi.json post /v1/avatars
Create a new one-shot avatar from an image file or image URL. This API is only available for enterprise and pro plans.



# Create persona
Source: https://docs.anam.ai/api-reference/create-persona

openapi.json post /v1/personas
Create a new persona



# Create session token
Source: https://docs.anam.ai/api-reference/create-session-token

openapi.json post /v1/auth/session-token
Create a new session token used to initialise the anam client



# Create share link
Source: https://docs.anam.ai/api-reference/create-share-link

openapi.json post /v1/share-links
Create a new share link



# Create tool
Source: https://docs.anam.ai/api-reference/create-tool

openapi.json post /v1/tools
Create a new tool



# Create voice
Source: https://docs.anam.ai/api-reference/create-voice

openapi.json post /v1/voices
Create a new voice by cloning from an audio file



# Delete avatar
Source: https://docs.anam.ai/api-reference/delete-avatar

openapi.json delete /v1/avatars/{id}
Delete an avatar by ID



# Delete document
Source: https://docs.anam.ai/api-reference/delete-document

openapi.json delete /v1/knowledge/documents/{id}
Delete a document from a RAG group



# Delete knowledge group
Source: https://docs.anam.ai/api-reference/delete-knowledge-group

openapi.json delete /v1/knowledge/groups/{id}
Delete a RAG group



# Delete LLM
Source: https://docs.anam.ai/api-reference/delete-llm

openapi.json delete /v1/llms/{id}
Delete an LLM configuration



# Delete persona
Source: https://docs.anam.ai/api-reference/delete-persona

openapi.json delete /v1/personas/{id}
Delete a persona by id



# Delete share link
Source: https://docs.anam.ai/api-reference/delete-share-link

openapi.json delete /v1/share-links/{id}
Delete a share link by ID



# Delete tool
Source: https://docs.anam.ai/api-reference/delete-tool

openapi.json delete /v1/tools/{id}
Delete a tool



# Delete voice
Source: https://docs.anam.ai/api-reference/delete-voice

openapi.json delete /v1/voices/{id}
Delete a voice by ID



# Get avatar by ID
Source: https://docs.anam.ai/api-reference/get-avatar-by-id

openapi.json get /v1/avatars/{id}
Returns an avatar by ID



# Get document
Source: https://docs.anam.ai/api-reference/get-document

openapi.json get /v1/knowledge/documents/{id}
Get a single document by ID



# Get knowledge group
Source: https://docs.anam.ai/api-reference/get-knowledge-group

openapi.json get /v1/knowledge/groups/{id}
Get a single RAG group by ID



# Get LLM
Source: https://docs.anam.ai/api-reference/get-llm

openapi.json get /v1/llms/{id}
Get a specific LLM by ID



# Get persona
Source: https://docs.anam.ai/api-reference/get-persona

openapi.json get /v1/personas/{id}
Returns a persona by id



# Get session
Source: https://docs.anam.ai/api-reference/get-session

openapi.json get /v1/sessions/{id}
Returns a session by ID



# Get share link
Source: https://docs.anam.ai/api-reference/get-share-link

openapi.json get /v1/share-links/{id}
Returns a share link by ID



# Get tool
Source: https://docs.anam.ai/api-reference/get-tool

openapi.json get /v1/tools/{id}
Get a tool by ID



# Get voice
Source: https://docs.anam.ai/api-reference/get-voice

openapi.json get /v1/voices/{id}
Returns a voice by ID



# List avatars
Source: https://docs.anam.ai/api-reference/list-avatars

openapi.json get /v1/avatars
Returns a list of all avatars with pagination support



# List group documents
Source: https://docs.anam.ai/api-reference/list-group-documents

openapi.json get /v1/knowledge/groups/{id}/documents
Get all documents in a RAG group



# List knowledge groups
Source: https://docs.anam.ai/api-reference/list-knowledge-groups

openapi.json get /v1/knowledge/groups
Returns a list of all knowledge groups for the organization



# List LLMs
Source: https://docs.anam.ai/api-reference/list-llms

openapi.json get /v1/llms
Returns a list of all LLMs available to the organization



# List personas
Source: https://docs.anam.ai/api-reference/list-personas

openapi.json get /v1/personas
Returns a list of all personas with pagination support



# List sessions
Source: https://docs.anam.ai/api-reference/list-sessions

openapi.json get /v1/sessions
Returns a list of all sessions for the organization



# List share links
Source: https://docs.anam.ai/api-reference/list-share-links

openapi.json get /v1/share-links
Returns a list of all share links for the organization



# List tools
Source: https://docs.anam.ai/api-reference/list-tools

openapi.json get /v1/tools
Returns a list of all tools for the organization



# List voices
Source: https://docs.anam.ai/api-reference/list-voices

openapi.json get /v1/voices
Returns a list of all voices with pagination support



# Search knowledge group
Source: https://docs.anam.ai/api-reference/search-knowledge-group

openapi.json post /v1/knowledge/groups/{id}/search
Search for similar content in a RAG group using vector similarity



# Update avatar
Source: https://docs.anam.ai/api-reference/update-avatar

openapi.json put /v1/avatars/{id}
Update an avatar by ID (only display name can be updated)



# Update document
Source: https://docs.anam.ai/api-reference/update-document

openapi.json put /v1/knowledge/documents/{id}
Update a document (rename)



# Update knowledge group
Source: https://docs.anam.ai/api-reference/update-knowledge-group

openapi.json put /v1/knowledge/groups/{id}
Update a RAG group



# Update LLM
Source: https://docs.anam.ai/api-reference/update-llm

openapi.json put /v1/llms/{id}
Update an LLM configuration



# Update persona
Source: https://docs.anam.ai/api-reference/update-persona

openapi.json put /v1/personas/{id}
Update a persona by id



# Update share link
Source: https://docs.anam.ai/api-reference/update-share-link

openapi.json put /v1/share-links/{id}
Update a share link by ID



# Update tool
Source: https://docs.anam.ai/api-reference/update-tool

openapi.json put /v1/tools/{id}
Update a tool



# Update voice
Source: https://docs.anam.ai/api-reference/update-voice

openapi.json put /v1/voices/{id}
Update a voice by ID (display name and provider model ID can be updated)



# Upload document
Source: https://docs.anam.ai/api-reference/upload-document

openapi.json post /v1/knowledge/groups/{id}/documents
Upload a document to a RAG group (Supports TXT, MD, DOCX, CSV up to 50MB)



# Changelog
Source: https://docs.anam.ai/changelog

New features, improvements, and fixes

<Update label="November 27th, 2025" description="Livekit out of Beta and new sub-latency record" tags={["LiveKit","Latency"]}>
  ## 🎥 Livekit out of Beta and new latency record

  LiveKit integration is now generally available: drop Anam’s expressive real-time avatars into any LiveKit Agents app so your AI can join LiveKit rooms as synchronised voice + video participants.\
  It turns voice-only agents into face-and-voice experiences for calls, livestreams, and collaborative WebRTC spaces, with LiveKit handling infra and Anam handling the human layer. Docs

  ***

  ## ⚡ Record-breaking latency: 330 ms decrease in latency for all customers

  Server-side optimisations cuts average end-to-end latency by 330 ms for all customers, thanks to cumulative engine optimisations across transcription, frame generation, and frame writing, plus upgraded Deepgram Flux endpointing for faster, best in class turn-taking without regressions in voice quality or TTS.

  ***

  ## Lab Changes

  **Improvements**
  • Overhaul to avatar video upload and management system

  • Upgraded default Cartesia voices to Sonic 3

  • Standardised voice model selection across the platform

  **Fixes**
  • Enhanced share link management capabilities

  • Corrected LiveKit persona type identification logic

  ***

  ## Persona Changes

  **Improvements**
  • Server-side optimisations to our frame buffering to reduce latency of responses by \~250ms for all personas.

  **Fixes**
  • Changed timeout behavior to never time out based on heartbeats; only time out when websocket is disconnected for 10 seconds or more.

  • Fixed intermittent issue where persona stopped responding

  • Set pix\_fmt for video output, moving from yuvj420p (JPEG) to yuv420 color space to avoid incorrect encoding/output.

  • Added timeout in our silence breaking logic to prevent hangs.
</Update>

<Update label="November 6th, 2025" description="Introducing Anam Agents" tags={["Agents"]}>
  ## 🚀 Introducing Anam Agents

  Build and deploy AI agents in Anam that can engage alongside you.

  With Anam Agents, your Personas can now interact with your applications, access your knowledge, and trigger workflows directly through natural conversation. This marks Anam's evolution from conversational Personas to agentic Personas that think, decide, and execute.

  ## Knowledge Tools

  Give your Personas access to your company's knowledge. Upload docs to the Lab, and they'll use semantic retrieval to integrate the right info.\
  [Docs for Knowledge Base](https://docs.anam.ai/concepts/knowledge-base)

  ## Client Tools

  Personas can control your interface in real time—open checkout, display modals, navigate UI, and update state by voice.\
  [Docs for Client Tools](https://docs.anam.ai/concepts/tools)

  ## Webhook Tools

  Connect your Personas to external APIs and services. Create tickets, fetch status, update records, or fetch live data.\
  [Docs for Webhook Tools](https://docs.anam.ai/concepts/tools)

  ## Intelligent Tool Selection

  Each Persona's LLM chooses tools based on intent—not scripts.

  You can create/manage tools on the Tools page in the Lab and attach them to any Persona from Build.

  **Anam Agents are available in beta for all users:** [https://lab.anam.ai/login](https://lab.anam.ai/login)

  ***

  ## Lab Changes

  **Improvements**

  * Cartesia Sonic-3 voices: the most expressive TTS model.
  * Voice modal expanded: 50+ languages, voice samples, Cartesia TTS now default.
  * Session reports work for custom LLMs.

  **Fixes**

  * Prevented auto-logout when switching contexts.
  * Fixed race conditions in cookie handling.
  * Resolved legacy session token issues.
  * Removed problematic voices.
  * Corrected player/stream aspect ratios on mobile.

  ## Persona Changes

  **Improvements**

  * Deepgram Flux support for turn-taking ([Deepgram Flux Details](https://deepgram.com/learn/introducing-flux-conversational-speech-recognition))
  * Server-side optimization: reduced GIL contention and latency, faster connections.

  **Fixes**

  * Bug-fix for dangling LiveKit connections.

  ## Research

  **Improvements**

  * Our first open-source library!\
    Metaxy, a metadata layer for ML/data pipelines:\
    [Read more](https://anam-org.github.io/metaxy/main/#3-run-user-defined-computation-over-the-metadata-increment) | [GitHub](https://github.com/anam-org/metaxy)
</Update>

<Update label="October 6, 2025" description="Anam is now HIPAA compliant" tags={["Trust Centre"]}>
  ## 🛡️ Anam is now HIPAA compliant

  A big milestone for our customers and partners. Anam now meets HIPAA requirements for handling protected health information.

  [**Learn more at the Anam Trust Center**](https://trust.anam.ai/)

  ## Lab Changes

  **Improvements**

  * Enhanced voice selection: search by use case/conversational style, 50+ languages.
  * Product tour update.
  * Streamlined One-Shot avatar creation.
  * Auto-generated Persona names based on selected avatar.
  * Session start now 1.1s faster.

  **Fixes**

  * Share links: fixed extra concurrency slot usage.

  ## Persona Changes

  **Improvements**

  * Improved TTS pronunciation via smarter text chunking.
  * Traceability and monitoring for session IDs.
  * Increased internal audio sampling rate to 24kHz.
  * Increased max websocket size to 16Mb.

  **Fixes**

  * Concurrency calculation now only considers sessions from last 2 hours.
  * Less freezing for slower LLMs.
</Update>

<Update label="September 21, 2025" description="Session Analytics" tags={["Analytics", "Lab"]}>
  ## 📊 Session Analytics

  Once a conversation ends, how do you review what happened? To help you understand and improve your Persona's performance, we're launching Session Analytics in the Lab. Now you can access a detailed report for every conversation, complete with a full transcript, performance metrics, and AI-powered analysis.

  * **Full Conversation Transcripts.** Review every turn of a conversation with a complete, time-stamped transcript. See what the user said and how your Persona responded, making it easy to diagnose issues and identify successful interaction patterns.
  * **Detailed Analytics & Timeline.** Alongside the transcript, a new Analytics tab provides key metrics grouped into "Transcript Metrics" (word count, turns) and "Processing Metrics" (e.g., LLM latency). A visual timeline charts the entire conversation, showing who spoke when and highlighting any technical warnings.
  * **AI-Powered Insights.** For a deeper analysis, you can generate an AI-powered summary and review key insights. This feature, currently powered by gpt-5-mini, evaluates the conversation for highlights, adherence to the system prompt, and user interruption rates.

  You can find your session history on the Sessions page in the Lab. Click on any past session to explore the new analytics report. This is available today for all session types, except for LiveKit sessions. For privacy-sensitive applications, session logging can be disabled via the SDK.

  ## Lab Changes

  **Improvements**

  * Improved Voice Discovery: The Voices page has been updated to be more searchable, allowing you to preview voices with a single click, and view new details like gender, TTS-model and language.

  **Fixes**

  * Fixed share-link session bug: Fixed bug of share-link sessions taking an extra concurrency slot.

  ## Persona Changes

  **Improvements**

  * Small improvement to connection time: Tweaks to how we perform webrtc signalling which allows for slightly faster connection times (\~900ms faster for p95 connection time).
  * Improvement to output audio quality for poor connections: Enabled Opus in-band FEC to improve audio quality under packet loss.
  * Small reduction in network latency: Optimisations have been made to our outbound media streams to reduce A/V jitter (and hence jitter buffer delay). Expected latency improvement is modest (\<50ms).

  **Fixes**

  * Fix for livekit sessions with slow TTS audio: Stabilizes LiveKit streaming by pacing output and duplicating frames during slowdowns to prevent underflow.
</Update>

<Update label="September 11, 2025" description="Intelligent LLM Routing for Faster Responses" tags={["Performance", "LLM"]}>
  ## ⚡ Intelligent LLM Routing for Faster Responses

  The performance of LLM endpoints can be highly variable, with time-to-first-token latencies sometimes fluctuating by as much as 500ms from one day to the next depending on regional load. To solve this and ensure your personas respond as quickly and reliably as possible, we've rolled out a new intelligent routing system for LLM requests. This is active for both our turnkey customers and for customers using their own server-side **Custom LLMs** if they deploy multiple endpoints.

  This new system constantly monitors the health and performance of all configured LLM endpoints by sending lightweight probes at regular intervals. Using a time-aware moving average, it builds a real-time picture of network latency and processing speed for each endpoint. When a request is made, the system uses this data to calculate the optimal route, automatically shedding load from any overloaded or slow endpoints within a region.

  ## Lab Changes

  **Improvements**

  * Generate one-shot avatars from text prompts: You can now generate one-shot avatars from text prompts within the lab, powered by Gemini's new Nano Banana model. The one-shot creation flow has been redesigned for speed and ease-of-use, and is now available to all plans. Image upload and webcam avatars remain exclusive to Pro and Enterprise.
  * Improved management of published embed widgets: Published embed widgets can now be configured and monitored from the lab at [https://lab.anam.ai/personas/published](https://lab.anam.ai/personas/published).

  ## Persona Changes

  **Improvements**

  * Automatic failover to backup data centres: To ensure maximum uptime and reliability for our personas, we've implemented automatic failover to backup data centres.

  **Fixes**

  * Prevent session crash on long user speech: Previously, unbroken user speech exceeding 30 seconds would trigger a transcription error and crash the session. We now automatically truncate continuous speech to 30 seconds, preventing sessions from failing in these rare cases.
  * Allow configurable session lengths of up to 2 hours for Enterprise plans: We had a bug where sessions had a max timeout of 30 mins instead of 2 hours for enterprise plans. This has now been fixed.
  * Resolved slow connection times caused by incorrect database region selection: An undocumented issue with our database provider led to incorrect region selection for our databases. Simply refreshing our credentials resolved the problem, resulting in a \~1s improvement in median connection times and \~3s faster p95 times. While our provider works on a permanent fix, we're actively monitoring for any recurrence.
</Update>

<Update label="September 4, 2025" description="Embed Widget" tags={["Embed", "Lab"]}>
  ## 🔌 Embed Widget

  Embed personas directly into your website with our new widget. Within the **lab's build page** click Publish then generate your unique html snippet. This snippet will work in most common website builders, eg Wordpress.org or SquareSpace.

  For added security we recommend adding a whitelist with your domain url. This will lock down the persona to only work on your website. You can also cap the number of sessions or give the widget an expiration period.

  ## Lab Changes

  **Improvements**

  * ONE-SHOT avatars available via API: Professional and Enterprise accounts can now create one-shot avatars via API. Docs **here**.
  * Spend caps: It's now possible to set a spend cap on your account. Available in **profile settings**.

  ## Persona Changes

  **Fixes**

  * Prevent Cartesia from timing out when using slow custom LLMs: We've added a safeguard to prevent Cartesia contexts from unexpectedly closing during pauses in text streaming. With slower llms or if there's a break or slow-down in text being sent, your connection will now stay alive, ensuring smoother, uninterrupted interactions.
</Update>

For full legal and policy information, see:

* [Trust Center](https://trust.anam.ai/)
* [AI Governance](https://anam.ai/ai-governance)
* [Terms of Service](https://anam.ai/terms-of-service)
* [DPA](https://anam.ai/data-processing)
* [Acceptable Use Policy](https://anam.ai/acceptable-use-policy)
* [Privacy Policy](https://anam.ai/privacy-policy)


# Community SDKs
Source: https://docs.anam.ai/community/sdks

This page lists SDKs, libraries, and tools developed by our community. They can help you integrate Anam into a wider variety of platforms and frameworks.

<Warning>
  **Disclaimer:** The projects listed below are not officially maintained or supported by Anam. They are provided as-is. While we're excited to see the community build with our API, we cannot guarantee the functionality, security, or maintenance of these packages. Please use them at your own discretion and report any issues directly to the project's maintainer on GitHub.
</Warning>

## SDKs

<Card title="Flutter SDK" icon="code-fork" href="https://github.com/stukennedy/anam_flutter_sdk">
  An unofficial, community-maintained Flutter SDK created by Stu Kennedy. Enables integration of Anam personas into mobile applications built with Flutter.
</Card>

## Contributing

Have you built a tool, library, or integration for Anam? Please reach out to us at [info@anam.ai](mailto:info@anam.ai).


# Authentication
Source: https://docs.anam.ai/concepts/authentication

Secure your API keys and manage session tokens

Anam uses a two-tier authentication system to keep your API keys secure while enabling real-time client connections.

## Tier 1: API Key

Your API key is used to authenticate your requests to the Anam API. It is a secret key that is used to sign your requests and is stored on your server.

<Warning>
  **Never expose your API key on the client side**. It should only exist in your
  server environment.
</Warning>

### Getting Your API Key

See the [API key page](/api-key) for details on how to get your API key from the Anam Lab.

## Tier 2: Session Tokens

Session tokens are temporary credentials that allow your client applications to connect directly to Anam's streaming infrastructure while keeping your API keys secure.

### How Session Tokens Work

<Steps>
  <Step title="Token Request">
    Your server requests a session token from Anam using your API key and
    persona configuration
  </Step>

  <Step title="Token Generation">
    Anam generates a temporary token tied to your specific persona configuration
  </Step>

  <Step title="Client Connection">
    Your client uses the session token with the Anam SDK to establish a direct
    WebRTC connection
  </Step>

  <Step title="Real-time Communication">
    Once connected, the client can send messages and receive video/audio streams
    directly
  </Step>
</Steps>

### Basic Token Creation

Below is a basic express server example that exposes a single endpoint which a client application can use to create a session token.

```javascript server.js theme={"dark"}
const express = require("express");
const app = express();

app.post("/api/session-token", async (req, res) => {
  try {
    const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
      },
      body: JSON.stringify({
        personaConfig: {
          name: "Cara",
          avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
          voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
          llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
          systemPrompt: "You are a helpful assistant.",
        },
      }),
    });

    const { sessionToken } = await response.json();
    res.json({ sessionToken });
  } catch (error) {
    res.status(500).json({ error: "Failed to create session" });
  }
});
```

### Advanced Token Creation

Instead of using the same persona configuration for all users, you can utilise context to create different persona configurations for different situations.

#### Pattern 1: User-based Personalization

For applications with different user types or preferences:

```javascript  theme={"dark"}
app.post("/api/session-token", authenticateUser, async (req, res) => {
  const user = req.user;

  const personaConfig = {
    name: `Persona for user: ${user.id}`,
    avatarId: user.preferredAvatar || defaultAvatarId,
    voiceId: user.preferredVoice || defaultVoiceId,
    llmId: user.preferredllmId || "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
    systemPrompt: buildPersonalizedPrompt(user),
  };

  const sessionToken = await fetchAnamSessionToken(personaConfig);
  res.json({ sessionToken });
});
```

### Pattern 2: Context-aware Sessions

For applications where the persona changes based on context:

```javascript  theme={"dark"}
app.post("/api/session-token", authenticateUser, async (req, res) => {
  const { context, metadata } = req.body;

  let personaConfig;

  switch (context) {
    case "customer-support":
      personaConfig = buildSupportPersona(metadata);
      break;
    case "sales":
      personaConfig = buildSalesPersona(metadata);
      break;
    case "training":
      personaConfig = buildTrainingPersona(metadata);
      break;
    default:
      personaConfig = defaultPersonaConfig;
  }

  const sessionToken = await fetchAnamSessionToken(personaConfig);
  res.json({ sessionToken });
});
```

## Error Handling

Common authentication errors and how to handle them:

```javascript  theme={"dark"}
app.post("/api/session-token", async (req, res) => {
  try {
    const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
      // ... config
    });

    if (!response.ok) {
      const errorData = await response.json();

      switch (response.status) {
        case 401:
          console.error("Invalid API key");
          return res.status(500).json({ error: "Authentication failed" });
        case 400:
          console.error("Invalid persona config:", errorData);
          return res.status(400).json({ error: "Invalid configuration" });
        default:
          console.error("Unexpected error:", errorData);
          return res.status(500).json({ error: "Service unavailable" });
      }
    }

    const { sessionToken } = await response.json();
    res.json({ sessionToken });
  } catch (error) {
    console.error("Network error:", error);
    res.status(500).json({ error: "Network error" });
  }
});
```

## Environment Setup

Store your API key securely:

<CodeGroup>
  ```bash .env theme={"dark"}
  ANAM_API_KEY=your-api-key-here
  NODE_ENV=production
  ```

  ```javascript config.js theme={"dark"}
  const config = {
    anamApiKey: process.env.ANAM_API_KEY,
    anamApiUrl: process.env.ANAM_API_URL || "https://api.anam.ai",
  };

  if (!config.anamApiKey) {
    throw new Error("ANAM_API_KEY environment variable is required");
  }

  module.exports = config;
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Your First Persona" icon="user" href="/your-first-persona">
    Create and customize your first persona
  </Card>

  <Card title="Session Tokens Deep Dive" icon="key" href="/concepts/session-tokens">
    Learn more about token lifecycle and management
  </Card>

  <Card title="Production Security" icon="shield" href="/best-practices/security">
    Secure your production deployment
  </Card>

  <Card title="Error Handling" icon="alert-triangle" href="/sdk/error-handling">
    Handle authentication and connection errors
  </Card>
</CardGroup>


# Custom LLMs
Source: https://docs.anam.ai/concepts/custom-llms

Use your own language models with Anam's digital personas

# Custom LLMs

Anam now supports integration with custom Large Language Models (LLMs), giving you complete control over the AI powering your digital personas. This feature enables you to use your own models while benefiting from Anam's persona, voice, and streaming infrastructure.

<Info>
  Custom LLMs are processed directly from Anam's servers, improving latency and
  simplifying your development workflow. All API credentials you provide are
  encrypted for security.
</Info>

## How Custom LLMs Work

When you create a custom LLM configuration in Anam:

1. **Model Registration**: You register your LLM details with Anam, including the model endpoint and authentication credentials
2. **Server-Side Processing**: Anam handles all LLM calls from our servers, reducing latency and complexity
3. **Secure Storage**: Your API keys and credentials are encrypted and securely stored
4. **Seamless Integration**: Use your custom LLM ID in place of Anam's built-in models

## Creating a Custom LLM

To create a custom LLM, you'll need to:

1. Register your LLM configuration through the Anam API or dashboard
2. Provide the necessary connection details (endpoint, API keys, model parameters)
3. Receive a unique LLM ID for your custom model
4. Use this ID when creating session tokens

<Note>
  Custom LLM creation API endpoints and dashboard features are coming soon.
  Contact [support@anam.ai](mailto:support@anam.ai) for early access.
</Note>

## Supported LLM Specifications

Anam supports custom LLMs that comply with one of the following API specifications:

* **OpenAI API Specification** - Compatible with OpenAI's chat completion endpoints
* **Azure OpenAI API Specification** - Compatible with Azure's OpenAI service endpoints
* **Gemini API Specification** - Compatible with Google's Gemini API endpoints

<Warning>
  Your custom LLM must support streaming responses. Non-streaming LLMs will not
  work with Anam's real-time persona interactions.
</Warning>

## Specifying Multiple Endpoints

Anam allows you to specify multiple endpoints per LLM. The Anam backend will automatically route to the fastest available LLM from the data centre where the Anam engine is running, and fallback to other endpoints in the case of an error.

<Note>
  To ensure routing selects the fastest available endpoint, Anam may occasionally send small probe prompts to your configured endpoints. These only occur while sessions are active for that LLM, and are lightweight—around 1500 tokens in size. Probes are infrequent (a few times per hour at most), have no effect on active conversations, and exist solely to maintain reliable performance.
</Note>

### Technical Requirements

<Steps>
  <Step title="API Compatibility">
    Your LLM server must implement one of the supported API specifications mentioned above. This includes:

    * Matching the request/response format
    * Supporting the same authentication methods
    * Implementing compatible endpoint paths
  </Step>

  <Step title="Streaming Support">
    Enable streaming responses in your LLM implementation: - Return responses with
    `stream: true` support - Use Server-Sent Events (SSE) for streaming chunks -
    Include proper content types and formatting
  </Step>

  <Step title="Validation Testing">
    When you add your LLM in the Anam Lab, automatic tests verify:

    * API specification compliance
    * Streaming functionality
    * Response format compatibility
    * Authentication mechanisms

    <Tip>
      The Lab will provide feedback if your LLM doesn't meet the requirements, helping you identify what needs to be fixed.
    </Tip>
  </Step>
</Steps>

<Note>
  **Testing Tip**: We recommend using `curl` commands to compare your custom
  LLM's raw HTTP responses with those from the actual providers (OpenAI, Azure
  OpenAI, or Gemini). Client libraries like the OpenAI SDK often transform
  responses and extract specific values, which can mask differences in the
  actual HTTP response format. Your custom implementation must match the raw
  HTTP response structure, not the transformed output from client libraries.
</Note>

### Example Custom LLM Endpoints

If you're building your own LLM server, ensure your endpoints match one of these patterns:

<CodeGroup>
  ```bash OpenAI Spec theme={"dark"}
  POST /v1/chat/completions
  Content-Type: application/json
  Authorization: Bearer YOUR_API_KEY

  {
  "model": "your-model-name",
  "messages": [...],
  "stream": true
  }
  ```

  ```bash Azure OpenAI Spec theme={"dark"}
  POST /openai/deployments/{deployment-id}/chat/completions?api-version=2024-02-01
  Content-Type: application/json
  api-key: YOUR_API_KEY

  {
    "messages": [...],
    "stream": true
  }
  ```

  ```bash Gemini Spec theme={"dark"}
  POST /v1beta/models/{model}:streamGenerateContent
  Content-Type: application/json
  x-goog-api-key: YOUR_API_KEY

  {
    "contents": [...],
    "generationConfig": {...}
  }
  ```
</CodeGroup>

## Using Custom LLMs

Once you have your custom LLM ID, use it when requesting session tokens:

<CodeGroup>
  ```javascript Node.js theme={"dark"}
  const response = await fetch('https://api.anam.ai/v1/session-token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ANAM_API_KEY}`
    },
    body: JSON.stringify({
      personaConfig: {
        name: 'Sebastian',
        avatarId: '30fa96d0-26c4-4e55-94a0-517025942e18',
        voiceId: '6bfbe25a-979d-40f3-a92b-5394170af54b',
        llmId: 'your-custom-llm-id', // Your custom LLM ID
        systemPrompt: 'You are a helpful customer service representative.',
      },
    })
  });
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch('https://api.anam.ai/v1/session-token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ANAM_API_KEY}`
    },
    body: JSON.stringify({
      personaId: 'your-persona-id', // Your persona ID
    })
  ```
</CodeGroup>

## Migration from brainType

<Warning>
  The `brainType` parameter is deprecated and has been replaced with `llmId` to
  better reflect support for custom models. For backwards compatibility, you can
  pass your existing `brainType` value as the `llmId` and it will continue to
  work.
</Warning>

### Migration Guide

<Steps>
  <Step title="Update your code">
    Replace all instances of `brainType` with `llmId` in your session token requests:

    ```diff  theme={"dark"}
    personaConfig: JSON.stringify({
    - brainType: 'ANAM_GPT_4O_MINI_V1',
    + llmId: 'ANAM_GPT_4O_MINI_V1',
    })
    ```
  </Step>

  <Step title="No functional changes needed">
    Your existing brain type values will work as LLM IDs: - `ANAM_GPT_4O_MINI_V1`
    → Works as `llmId` - `ANAM_LLAMA_v3_3_70B_V1` → Works as `llmId` -
    `CUSTOMER_CLIENT_V1` → Works as `llmId`
  </Step>

  <Step title="Consider custom LLMs">
    Evaluate if a custom LLM would better serve your use case. Custom LLMs provide:

    * Full control over model behavior
    * Ability to use specialized or fine-tuned models
    * Consistent persona experience with your chosen AI
  </Step>
</Steps>

## Available Built-in LLM IDs

These built-in models are available as LLM IDs:

| LLM ID                                 | Description               | Best For                                    |
| -------------------------------------- | ------------------------- | ------------------------------------------- |
| `ANAM_GPT_4O_MINI_V1`                  | OpenAI GPT-4 Mini model   | Available for backwards compatibility       |
| `0934d97d-0c3a-4f33-91b0-5e136a0ef466` | OpenAI GPT-4.1 Mini model | Recommended for new projects                |
| `ANAM_LLAMA_v3_3_70B_V1`               | Llama 3.3 70B model       | Open-source preference, larger context      |
| `9d8900ee-257d-4401-8817-ba9c835e9d36` | Gemini 2.5 Flash model    | Our fastest model                           |
| `CUSTOMER_CLIENT_V1`                   | Client-side LLM           | When you only use .talk() commands to speak |

## Security Considerations

<Check>
  **Encryption at Rest**: All API keys and credentials are encrypted using
  industry-standard encryption before storage.
</Check>

<Check>
  **Secure Transmission**: Credentials are transmitted over HTTPS and never
  exposed in logs or responses.
</Check>

<Check>
  **Access Control**: Only your account can use your custom LLM configurations.
</Check>

## Benefits of Server-Side Processing

By processing custom LLMs from Anam's servers, you get:

1. **Reduced Latency**: Direct server-to-server communication eliminates client-side round trips
2. **Simplified Development**: No need to manage LLM connections in your client code
3. **Unified Streaming**: Seamless integration with Anam's voice and video streaming
4. **Credential Security**: API keys never exposed to client-side code
5. **Automatic Scaling**: Anam handles load balancing and scaling

## Next Steps

<CardGroup cols={2}>
  <Card title="Personas with Custom LLMs" icon="user" href="/concepts/personas">
    Learn how personas work with custom language models
  </Card>

  <Card title="Server-Side LLM Example" icon="code" href="https://lab.anam.ai/llms">
    Setup a custom LLM in the Anam Lab
  </Card>
</CardGroup>


# Event Handling
Source: https://docs.anam.ai/concepts/events

React to conversation events and user interactions with Anam personas

Anam personas communicate through a rich event system that lets you respond to connection changes, conversation updates, and user interactions. Understanding these events is key to building responsive, interactive applications.

## How Events Work

The Anam SDK uses an event-driven architecture where your application can listen for specific events and react accordingly. This allows you to:

* Update your UI based on connection status
* Track conversation history in real-time
* Handle user interruptions gracefully
* Monitor stream quality and performance

<Steps>
  <Step title="Initialize Client">
    Create your Anam client with a session token
  </Step>

  <Step title="Add Event Listeners">Register listeners for the events you care about</Step>

  <Step title="React to Events">Update your UI and application state based on event data</Step>

  <Step title="Clean Up">
    Remove listeners when components unmount or sessions end
  </Step>
</Steps>

## Available Events

### Connection Events

These events track the connection lifecycle between your client and Anam's streaming infrastructure:

#### `CONNECTION_ESTABLISHED`

Fired when the WebRTC connection is successfully established.

```javascript  theme={"dark"}
import { AnamEvent } from "@anam-ai/js-sdk/dist/module/types";

anamClient.addListener(AnamEvent.CONNECTION_ESTABLISHED, () => {
  console.log("Connected to Anam streaming service");
  updateConnectionStatus("connected");
  hideLoadingSpinner();
});
```

#### `CONNECTION_CLOSED`

Fired when the connection is terminated.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.CONNECTION_CLOSED, () => {
  console.log("Connection closed");
  updateConnectionStatus("disconnected");
  showReconnectButton();
});
```

### Video Events

#### `VIDEO_PLAY_STARTED`

Fired when the first video frames begin playing. Ideal for removing loading indicators.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.VIDEO_PLAY_STARTED, () => {
  console.log("Video stream started");
  hideVideoLoadingState();
  showPersonaInterface();
});
```

### Conversation Events

These events help you track and respond to conversation flow:

#### `MESSAGE_HISTORY_UPDATED`

Provides the complete conversation history each time a participant finishes speaking.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
  console.log("Conversation updated:", messages);
  updateChatHistory(messages);

  // Example message structure:
  // [
  //   { role: "user", content: "Hello" },
  //   { role: "assistant", content: "Hi there! How can I help?" }
  // ]
});
```

#### `MESSAGE_STREAM_EVENT_RECEIVED`

Provides real-time transcription updates as speech occurs.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.MESSAGE_STREAM_EVENT_RECEIVED, (event) => {
  if (event.type === "persona") {
    // Persona is speaking - show real-time transcription
    updatePersonaTranscript(event.text);
  } else if (event.type === "user") {
    // User finished speaking - complete transcription
    updateUserTranscript(event.text);
  }
});
```

### Audio Events

#### `INPUT_AUDIO_STREAM_STARTED`

Fired when microphone input is successfully initialized.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.INPUT_AUDIO_STREAM_STARTED, (stream) => {
  console.log("Microphone access granted");
  showMicrophoneIndicator();
  updateAudioInputStatus("active");
});
```

### Talk Stream Events

#### `TALK_STREAM_INTERRUPTED`

Fired when a user interrupts a `TalkMessageStream` by speaking.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.TALK_STREAM_INTERRUPTED, (event) => {
  console.log("Talk stream interrupted:", event.correlationId);
  handleStreamInterruption(event.correlationId);
  stopCurrentGeneration();
});
```

### Client Tool Call Events

#### `TOOL_CALL`

Fired when the AI persona invokes a client tool, allowing your application to respond to requests for UI actions like navigation, opening modals, or updating state.

```javascript  theme={"dark"}
anamClient.addListener(AnamEvent.TOOL_CALL, (event) => {
  const { toolName, arguments: args } = event;

  switch (toolName) {
    case "navigate_to_page":
      window.location.href = `/${args.page}`;
      break;
    case "open_modal":
      openModal(args.modalType, args.data);
      break;
    case "update_filters":
      applyFilters(args);
      break;
    default:
      console.warn(`Unhandled tool: ${toolName}`);
  }
});
```

<Note>Client tools enable voice-driven or chat-driven UI control. For a complete guide on creating and configuring client tools, see the [Client Tools Guide](/tools/client-tools).</Note>


# Knowledge Base (RAG)
Source: https://docs.anam.ai/concepts/knowledge-base

Give your AI personas access to your documents using semantic search and Retrieval-Augmented Generation

## Overview

Anam's Knowledge Base enables your AI personas to search and retrieve information from your documents using Retrieval-Augmented Generation (RAG). Instead of relying solely on the LLM's training data, your personas can access up-to-date, organization-specific information from your uploaded documents.

<Warning>
  **Beta Feature**: Knowledge Base is currently in beta. You may encounter some
  issues as we continue to improve the feature. Please report any feedback or
  issues to help us make it better.
</Warning>

This enables personas to:

* Answer questions accurately from your documentation
* Provide information about your products, policies, or procedures
* Stay current with your latest content updates
* Ground responses in verified sources

## How It Works

Knowledge tools let your AI persona search your documents to answer questions accurately.

<Steps>
  <Step title="Upload">
    You upload a file using a secure and efficient three-step signed upload process.

    <CodeGroup>
      ```javascript Signed URL Upload theme={"dark"}
      // Step 1: Get an upload URL from Anam
      const response = await fetch(
        `/v1/knowledge/groups/{folderId}/documents/presigned-upload`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            filename: 'user-guide.pdf',
            contentType: 'application/pdf',
            fileSize: 2048000
          })
        }
      );
      const { uploadUrl, documentId } = await response.json();

      // Step 2: Upload your file directly to the URL
      await fetch(uploadUrl, {
      method: 'PUT',
      body: fileData
      });

      // Step 3: Confirm the upload with Anam
      await fetch(`/v1/knowledge/documents/{documentId}/confirm-upload`, {
      method: 'POST',
      headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
      },
      body: JSON.stringify({ fileSize: 2048000 })
      });

      ```
    </CodeGroup>

    This process stores the document and begins the processing pipeline.
  </Step>

  <Step title="Processing">
    A background job processes the document to make it searchable. This typically takes \~30 seconds.

    Status changes to `PROCESSING`.
  </Step>

  <Step title="Ready">
    Once processing completes (typically \~30 seconds), the document status changes to `READY` and becomes searchable.

    <Check>
      You can now attach this folder to knowledge tools and start searching.
    </Check>
  </Step>
</Steps>

<Warning>
  Documents must be in READY status to be searchable. If a document fails
  processing, its status will be set to FAILED with an error message.
</Warning>

## Document Processing

The system automatically processes different file types appropriately:

| File Type          | How It's Processed                               |
| ------------------ | ------------------------------------------------ |
| PDF, TXT, MD, DOCX | Split into paragraphs for precise search results |
| CSV                | Each row is searchable independently             |
| JSON               | Entire file kept intact                          |
| LOG                | Each line is searchable independently            |

<Info>
  The system automatically optimizes how your documents are processed based on
  file type.
</Info>

### Optimizing Document Structure

For best search results, structure your documents with:

**Clear headings and sections**:

```markdown  theme={"dark"}
# Installation Guide

## Prerequisites

Before installing, ensure you have...

## Step 1: Download the software

Navigate to our downloads page...

## Step 2: Run the installer

Double-click the downloaded file...
```

**Self-contained paragraphs**:
Each paragraph should make sense independently, as it may be retrieved without surrounding context.

**Descriptive filenames**:

* ✅ `product-installation-guide.pdf`
* ✅ `billing-faq-2024.md`
* ❌ `document1.pdf`
* ❌ `untitled.txt`

## Storage Limits and Quotas

### Upload Limits

Document uploads are subject to file size and monthly storage limits based on your plan.

<Info>
  **Need higher limits?** Contact us about Enterprise plans with custom upload
  limits tailored to your needs.
</Info>

**File uploads**:

* Maximum file size per document varies by plan
* Batch uploads supported (multiple files at once)
* Storage quotas count only non-deleted documents

Deleting documents frees up quota for new uploads.

### Checking Your Usage

You can view your current usage in the Anam Lab UI at `/knowledge` or via API:

```javascript  theme={"dark"}
const response = await fetch("/v1/knowledge/usage", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

const usage = await response.json();
console.log(`Used: ${usage.totalBytes} / ${usage.quotaBytes}`);
```

## Search Performance

### How Search Works

When your AI searches documents, it finds the most relevant information to answer the user's question. The system automatically ranks results by relevance and provides the best matches to the LLM.

<Tip>
  The AI automatically focuses on the most relevant information when generating
  responses.
</Tip>

### Improving Search Results

**Use descriptive folder names and document titles**:
Metadata helps the system understand context.

**Keep documents focused on specific topics**:
Instead of one 500-page manual, upload focused documents on individual topics.

**Update documents regularly**:
Delete outdated documents and upload current versions.

**Organize by knowledge domain**:
Create separate folders for different areas:

* Product documentation
* FAQs
* Policies
* Troubleshooting guides

## Using Knowledge Tools

Once your documents are uploaded and processed, create knowledge tools to enable search:

```typescript  theme={"dark"}
{
  type: 'server',
  subtype: 'knowledge',
  name: 'search_product_docs',
  description: 'Search product documentation when users ask technical questions about features, installation, or usage',
  documentFolderIds: ['550e8400-e29b-41d4-a716-446655440000', '6ba7b810-9dad-11d1-80b4-00c04fd430c8']
}
```

Attach the tool to a persona, and the LLM will automatically invoke it when relevant:

**User**: "How do I configure SSL?"

**LLM internal process**:

1. Recognizes this is a technical question
2. Invokes `search_product_docs` with query "SSL configuration"
3. Receives relevant chunks from documentation
4. Generates response: "To configure SSL, you'll need to..."

<Note>
  Learn more about creating and using knowledge tools in the [Tools
  documentation](/concepts/tools).
</Note>

## Security and Privacy

### Organization Isolation

All knowledge base data is organization-scoped:

* Users can only access their organization's folders and documents
* API requests are filtered by organization ID at the database level
* Even with knowledge of folder IDs, users cannot access other organizations' data

<Warning>
  Always use HTTPS for API requests. Never commit API keys to version control or
  expose them client-side.
</Warning>

## Troubleshooting

### No Search Results

**Possible causes**:

* Documents still in PROCESSING status (wait \~30 seconds)
* Query semantically unrelated to document content
* Folder contains no READY documents
* Documents in wrong folder (check folder assignments)

**Solutions**:

1. Check document status in the UI or via API
2. Test query using debug modal (`Ctrl+Shift+K`)
3. Try rephrasing query with more specific terms
4. Verify folder contains relevant documents

### Upload Failures

**File too large** (>50MB):

* Split document into smaller files
* Remove images in PDFs
* Remove unnecessary pages

**Processing failed**:

* Check file isn't corrupted
* Verify file format is supported
* Try re-uploading the file

### Slow Processing

**Normal processing time**: 30 seconds for typical documents

**Longer processing times** may occur with:

* Very large files (40-50MB)
* Complex PDFs with many images
* High system load

<Info>
  You can upload multiple documents simultaneously. The system processes up to 4
  documents concurrently.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Organize folders by topic">
    Create focused folders instead of dumping all documents in one place:

    ```
    ✅ Good:
    ├── Product Features
    ├── Installation Guides
    └── Troubleshooting

    ❌ Bad:
    └── All Documents
    ```
  </Accordion>

  <Accordion title="Use meaningful file names">
    ```
    ✅ Good:
    - password-reset-guide.pdf
    - api-authentication-v2.md
    - billing-faq-2024.txt

    ❌ Bad:

    - document.pdf
    - file1.md
    - untitled.txt

    ```
  </Accordion>

  <Accordion title="Keep documents up to date">
    Regularly audit and update your knowledge base:

    * Delete outdated documentation
    * Upload new versions when content changes
    * Archive superseded documents
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Knowledge Base Setup" icon="upload" href="/guides/knowledge/setup">
    Step-by-step guide to creating folders and uploading documents
  </Card>

  <Card title="Knowledge Tools Guide" icon="magnifying-glass" href="/guides/tools/knowledge-tools">
    Create knowledge tools and attach them to personas
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/knowledge/introduction">
    Complete API documentation for knowledge base
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/concepts/tools">
    Learn about all available tool types
  </Card>
</CardGroup>

```
```


# Understanding Personas
Source: https://docs.anam.ai/concepts/personas

Learn how AI personas work and how to customize them

<Warning>
  **Breaking Change**: The `brainType` parameter has been deprecated and replaced with `llmId` to support custom language models. For backwards compatibility, you can still pass your existing `brainType` value as `llmId`. See our [Custom LLMs guide](/concepts/custom-llms) for more details.
</Warning>

A persona in Anam is an AI-powered digital human that can have natural, real-time conversations with your users. Think of it as a customizable avatar with a brain, voice, and personality.

## The Persona Configuration

Every persona is defined by a configuration object that brings together three essential components. Here's what a complete persona config looks like:

```javascript  theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt:
    "You are Cara, a helpful customer service representative. You're friendly, knowledgeable, and always try to solve problems efficiently. Keep responses conversational and under 50 words unless explaining something complex.",
};
```

This single configuration object defines everything about your persona - how they look, sound, and behave. Let's break down each component and how it maps to the configuration.

## Anatomy of a Persona

### 1. Persona Name

**`Config field: name`**

The name of your persona. This is optional but recommended for internal organization and debugging. It doesn't affect how the persona behaves, but helps you identify different personas in logs and analytics.

```javascript {2} theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt:
    "You are Cara, a helpful customer service representative. You're friendly, knowledgeable, and always try to solve problems efficiently. Keep responses conversational and under 50 words unless explaining something complex.",
};
```

### 2. Avatar (Visual Appearance)

**`Config field: avatarId`**

The face and expressions users see. You can choose from our [gallery](/resources/avatar-gallery) or create custom avatars using our one-shot avatar generator (enterprise only).

```javascript {3} theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt:
    "You are Cara, a helpful customer service representative. You're friendly, knowledgeable, and always try to solve problems efficiently. Keep responses conversational and under 50 words unless explaining something complex.",
};
```

### 3. Voice (How They Sound)

**`Config field: voiceId`**

The speech synthesis that brings your persona to life. Different voices convey different personalities and work better for different use cases. You can sample some of the available voices in our [voice gallery](/resources/voice-gallery).

```javascript {4} theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt:
    "You are Cara, a helpful customer service representative. You're friendly, knowledgeable, and always try to solve problems efficiently. Keep responses conversational and under 50 words unless explaining something complex.",
};
```

### 4. Brain (Intelligence & Personality)

**`Config fields: llmId and systemPrompt`**

The AI model and instructions that define how your persona thinks, responds, and behaves during conversations.

```javascript {5,6} theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt:
    "You are Cara, a helpful customer service representative. You're friendly, knowledgeable, and always try to solve problems efficiently. Keep responses conversational and under 50 words unless explaining something complex.",
};
```

#### Making Your Personas Smarter

While the `llmId` and `systemPrompt` define the foundation of your persona's intelligence, you can make your personas significantly smarter and more capable by:

* [**Adding a Knowledge Base**](/concepts/knowledge-base): Give your persona access to your company's documents, FAQs, and resources so it can provide accurate, contextual information drawn from your specific content.
* [**Implementing Tool Calling**](/concepts/tools): Enable your persona to take actions and access real-time data by connecting it to external systems, databases, and APIs. This allows your persona to look up information, perform operations, and interact with your business systems dynamically.

<Tip>
  Combining a well-crafted system prompt with knowledge bases and tool calling creates personas that are not only conversational but also deeply integrated with your business operations and information systems.
</Tip>

#### Available LLM IDs

Choose the LLM ID that best fits your use case and performance requirements:

<Tabs>
  <Tab title="GPT-4.1 Mini">
    **Best for: Most applications**

    A fast, cost-effective brain powered by GPT-4.1 Mini. Offers excellent performance for conversational AI with quick response times and reasonable costs.

    ```javascript  theme={"dark"}
    llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466";
    ```
  </Tab>

  <Tab title="Custom LLM">
    **Best for: Custom AI integration**

    Use your own custom LLM or disable Anam's built-in AI to integrate your own AI models and processing logic.

    ```javascript  theme={"dark"}
    llmId: "CUSTOMER_CLIENT_V1"; // For client-side LLM
    // OR
    llmId: "your-custom-llm-id"; // For custom server-side LLM
    ```

    <Info>
      When using `CUSTOMER_CLIENT_V1`, you'll handle AI responses through your own backend and use Anam purely for avatar rendering and voice synthesis. See the [custom LLM guide](/examples/custom-llm) for more information.
    </Info>
  </Tab>
</Tabs>

## Experimenting with configurations

The easiest way to experiment with the available avatars, voices, and brain options is to use the playground in the [Anam Lab](https://lab.anam.ai). From the build page, you can use the settings menu to change the available options and preview over 400 available voices. When you're happy with your configuration, you can copy the avatar ID and voice ID from the settings bar to use in your own application.

## Persona Lifecycle

Understanding how personas work helps you build better experiences:

<Steps>
  <Step title="Configuration">
    You define the persona's appearance, voice, and personality in the persona configuration object
  </Step>

  <Step title="Session Token Creation">
    Your server uses your API key to exchange your persona configuration for a secure session token
  </Step>

  <Step title="Initialization">
    The client uses the session token to initialize the persona and start the session
  </Step>

  <Step title="Conversation">
    Real-time back-and-forth communication begins between the persona and the user
  </Step>

  <Step title="Session End">
    The conversation concludes and the session is cleaned up
  </Step>
</Steps>

## Creating Effective Personas

Creating an effective persona requires thoughtful design across multiple dimensions. When you create a persona, the system prompt you choose defines how the persona will respond to your users. Focus on crafting a well-defined identity, personality, and communication style.

### Defining Core Identity

Your persona's identity is the foundation of its interactions. Start by clearly establishing:

* **Specific role**: What function will your persona fulfil (customer support, sales assistant, product specialist, etc.)
* **Areas of expertise**: Knowledge relevant to your business and users
* **Interaction scope**: Types of conversations it should handle
* **Clear boundaries**: Capabilities and limitations to prevent confusion

### System Prompts That Work

Your system prompt is crucial - it defines your persona's personality and behavior.

```javascript  theme={"dark"}
// ❌ Too vague
systemPrompt: "You are helpful.";

// ✅ Specific and actionable
systemPrompt: `You are Marcus, a fitness coach with 10 years of experience. 
You're enthusiastic but not pushy, and you always ask about injuries or 
limitations before suggesting exercises. Keep responses under 50 words 
unless explaining a complex exercise.`;
```

```javascript  theme={"dark"}
// ❌ No personality
systemPrompt: "Answer customer service questions.";

// ✅ Clear personality and boundaries
systemPrompt: `You are Emma, a customer support specialist for SoftwareCorp. 
You're patient, empathetic, and solution-focused. You can help with account 
issues, billing questions, and technical troubleshooting. If you can't 
solve something, always offer to escalate to a human specialist.`;
```

### Personality and Communication Style

The way your persona communicates is just as important as what it communicates. Consider:

* **Tone of voice**: Professional, friendly, casual, or authoritative
* **Communication style**: Concise vs detailed, formal vs informal
* **User addressing**: How it should greet and interact with users
* **Cultural sensitivity**: Adaptability to different user backgrounds

Your persona should maintain consistency while adapting to user needs. For example:

```javascript  theme={"dark"}
systemPrompt: `You are Alex, a friendly customer service representative. 
Your communication style:
- Use a warm but professional tone
- Address users respectfully 
- Break down complex information into simple steps
- Always acknowledge user frustration with empathy

Example response: "I understand you're having trouble with the login process. 
Let me help you resolve this step by step. First, could you tell me what 
error message you're seeing?"`;
```

### Handling Different Scenarios

Guide your persona on how to handle various situations:

#### When Facing Uncertainty

```javascript  theme={"dark"}
"If you're not completely sure about something, acknowledge it and ask for
clarification. It's better to say 'I want to make sure I understand your
question correctly' than to provide incorrect information."
```

#### For Complex Requests

```javascript  theme={"dark"}
"Break down complex problems into smaller, manageable steps. Guide users
through the process gradually, confirming understanding at each step."
```

#### Response Structure Guidelines

```javascript  theme={"dark"}
"Keep responses concise and relevant. Break down complex information into
digestible parts. Use numbered steps for procedures and bullet points for
lists of options."
```

### Testing and Refinement

<Warning>
  Personas can be sensitive to even small changes in the system prompt. If your persona isn't performing as expected, try small incremental changes rather than major overhauls.
</Warning>

**Iterative improvement process:**

1. **Start simple**: Begin with basic functionality and expand gradually
2. **Use example interactions**: Include specific examples in your system prompt
3. **Monitor performance**: Track how well the persona handles real conversations
4. **Collect feedback**: Gather input from users and team members
5. **Make incremental adjustments**: Small changes often yield better results than major rewrites

## Controlling session duration

You can control how long a persona session remains active by setting the optional `maxSessionLengthSeconds` parameter in your persona configuration. This is useful for managing costs, ensuring security, or creating time-limited experiences.

```javascript  theme={"dark"}
const personaConfig = {
  name: "Cara",
  avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
  voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt: "You are Cara, a helpful customer service representative.",
  maxSessionLengthSeconds: 300, // 5 minutes
};
```

### How Session Duration Works

When you set `maxSessionLengthSeconds`, the session will automatically end after the specified time limit, regardless of whether the conversation is ongoing. The countdown begins when the persona starts streaming.

<Info>
  If you don't specify `maxSessionLengthSeconds`, the session will continue until manually ended or until it reaches the maximum session length limit of 30 minutes (or 2 hours for Enterprise plans).
</Info>

### Common Use Cases

**Customer Support (10-30 minutes)**

```javascript  theme={"dark"}
maxSessionLengthSeconds: 1800; // 30 minutes
```

Allows enough time for complex support issues while preventing sessions from running indefinitely.

**Product Demos (5-15 minutes)**

```javascript  theme={"dark"}
maxSessionLengthSeconds: 900; // 15 minutes
```

Perfect for showcasing key features without overwhelming prospects with lengthy demonstrations.

**Trial Experiences (2-5 minutes)**

```javascript  theme={"dark"}
maxSessionLengthSeconds: 300; // 5 minutes
```

Gives users a taste of your persona's capabilities while encouraging them to sign up for full access.

### Best Practices

<Tip>
  Set session durations based on your specific use case. Consider the typical length of conversations in your domain and add a buffer for natural conclusion.
</Tip>

* **Factor in conversation flow**: Allow enough time for natural conversation completion
* **Consider user experience**: Abrupt session endings can frustrate users, so consider displaying a countdown timer to the user
* **Monitor usage patterns**: Track actual session lengths to optimize your limits
* **Communicate limits**: Let users know when sessions are time-limited

## Example: Building a Sales Assistant

Here's how to create a persona optimized for sales conversations using the recommended system prompt structure:

```javascript  theme={"dark"}
const salesPersonaConfig = {
  name: "Jordan",
  avatarId: "professional-avatar-id",
  voiceId: "confident-voice-id",
  llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
  systemPrompt: `[ROLE]
You are Jordan, a consultative sales specialist for SaaS products. You help prospects understand how our solutions can solve their business challenges.

[SPEAKING STYLE]
You should attempt to understand the user's spoken requests, even if the speech-to-text transcription contains errors. Your responses will be converted to speech using a text-to-speech system. Therefore, your output must be plain, unformatted text.

When you receive a transcribed user request:

1. Silently correct for likely transcription errors. Focus on the intended meaning, not the literal text. If a word sounds like another word in the given context, infer and correct.
2. Provide concise, focused responses that move the conversation forward. Ask one discovery question at a time rather than overwhelming prospects.
3. Always prioritize clarity and building trust. Respond in plain text, without any formatting, bullet points, or extra conversational filler.
4. Occasionally add natural pauses "..." or conversational elements like "Well" or "You know" to sound more human and less scripted.

Your output will be directly converted to speech, so your response should be natural-sounding and appropriate for a sales conversation.

[USEFUL CONTEXT]
Your sales approach:
- Lead with curiosity about their business challenges
- Ask 2-3 discovery questions before presenting solutions
- Use social proof and case studies when relevant
- Address objections with empathy and alternative perspectives
- Always respect budget constraints and timeline pressures
- Guide toward a demo, trial, or next meeting when appropriate
- If you don't know specific product details, acknowledge it and don't make up information`,
};
```


# Create Personas via API
Source: https://docs.anam.ai/concepts/personas/create-your-own/create-your-own-api

Create and customize personas programmatically using Anam's API

With Anam's API, you can create custom personas on the fly. This allows you to dynamically generate personas based on user preferences, context, or any other criteria.

<Note>
  **Deprecation Notice**: The `brainType` field has been replaced with `llmId`
  to support custom language models. For backwards compatibility, you can still
  use your existing `brainType` values as `llmId`. See our [Custom LLMs
  guide](/concepts/custom-llms) for more details.
</Note>

## Creating Custom Personas with the API

You can create your own custom personas using the Anam API's `/v1/personas` endpoint. Custom personas allow you to define specific characteristics and behaviors for your use case.

## Required Parameters

### Persona Parameters

| Parameter      | Description                                                                        | Type   | Required | Default                                |
| -------------- | ---------------------------------------------------------------------------------- | ------ | -------- | -------------------------------------- |
| `avatarId`     | The ID of the avatar to use (get from [Avatar Gallery](/resources/avatar-gallery)) | string | Yes      |                                        |
| `voiceId`      | The ID of the voice to use (get from [Voice Gallery](/resources/voice-gallery))    | string | Yes      |                                        |
| `llmId`        | Which LLM used to power the responses                                              | string | No       | `0934d97d-0c3a-4f33-91b0-5e136a0ef466` |
| `systemPrompt` | Initial instructions that define the persona's behavior and personality            | string | No       | Default helpful assistant persona      |
| `name`         | Optional name for internal organization                                            | string | No       |                                        |

### Brain Parameters

| Parameter      | Description                                        |
| -------------- | -------------------------------------------------- |
| `systemPrompt` | The prompt used for initializing LLM interactions. |

## Implementation Example

Here's how to create a custom persona using the API:

```bash  theme={"dark"}
curl -X POST "https://api.anam.ai/v1/personas" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "name": "Leo",
    "avatarId": "121d5df1-3f3e-4a48-a237-8ff488e9eed8",
    "voiceId": "b7274f87-8b72-4c5b-bf52-954768b28c75",
    "llmId": "ANAM_LLAMA_v3_3_70B_V1",
    "systemPrompt": "You are Leo, a virtual receptionist..."
  }'
```

The API will respond with the created persona's details, including its ID:

```json  theme={"dark"}
{
  "id": "new_persona_id",
  "name": "Leo",
  "avatar": {
    "id": "121d5df1-3f3e-4a48-a237-8ff488e9eed8",
    "displayName": "Leo",
    "variantName": "window sofa corner",
    "imageUrl": "https://lab.anam.ai/persona_thumbnails/leo_windowsofacorner.png",
    "createdAt": "2021-01-01T00:00:00Z",
    "updatedAt": "2021-01-02T00:00:00Z"
  },
  "voice": {
    "id": "b7274f87-8b72-4c5b-bf52-954768b28c75",
    "displayName": "Leo",
    "createdAt": "2021-01-01T00:00:00Z",
    "updatedAt": "2021-01-02T00:00:00Z"
  },
  "llmId": "ANAM_LLAMA_v3_3_70B_V1",
  "brain": {
    "systemPrompt": "You are Leo, a virtual receptionist..."
  }
}
```

## Using Your Custom Persona

Once created, you can use your custom persona following the [Production Usage](/production) guide.


# Create your own persona using the Anam Lab
Source: https://docs.anam.ai/concepts/personas/create-your-own/create-your-own-lab

Learn how to create and customize your own Anam persona

## Creating Custom Personas with the Anam Lab

From the [Anam Lab](https://lab.anam.ai) homepage, click "Chat to Persona" to start designing your persona.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=8a01e727e2488e9a14332f04103db094" alt="Chat to Persona" data-og-width="2557" width="2557" data-og-height="1316" height="1316" data-path="images/personas/create-persona-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=40ac10b16640676a291987927d67f831 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=b0ef11dc685fa924ba5ae3a6596eaa0a 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=68f98ac2ebc091642a47f4bdecca5d00 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=e731f75e4c54d94da32bf2e2e9753636 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=777b0abb0417c78e327f64dabee532ed 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/create-persona-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=0f64cdbee5b72a3a1d405bf16d3dd2f7 2500w" />
</Frame>

### Name and Description

Click the "Unnamed Persona" button in the top bar to give your persona a name and description.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=d24af2c6edab7a384ab34bbc58954bf7" alt="name and description" data-og-width="2553" width="2553" data-og-height="1317" height="1317" data-path="images/personas/name-description-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=fa9d4840d0641d98e0fd0b0136f38274 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=1589078a983b75114c4c1fca90d64b13 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=5773b82ac083cbd5bd8c411710797ddb 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=7974d629627e1c51389061397c9dd57e 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=724358d60abbe81263c419703d4b9ff7 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/name-description-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=9ee711ca4e481ff5084faa2cca7bc5f9 2500w" />
</Frame>

### Avatar and voice

The avatar is the visual representation of the persona. Changing the avatar will alter the persona's appearance. The voice controls how the persona speaks.
You can select from a range of included avatars and voices depending on your plan.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=e49aa2bca4a49f0aaa53be418270ccc4" alt="avatar and voice" data-og-width="473" width="473" data-og-height="187" height="187" data-path="images/personas/avatar-voice-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=db17aa60d0288f2d167d7ca4dd2e3def 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=9f441688a4c699b1fbd1278a7d41ee23 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=54ab7a2d46222d0f68c45cdcc8473993 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=6ed9c066e9741f3b86e131b8d2711814 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=5702aef3bfd08570b43a782fdb4a7b60 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/avatar-voice-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=5fdac57dce9028e99428c6b1e7169be7 2500w" />
</Frame>

### Personality

The personality defines the persona's brain. It is the persona's knowledge base and instructions for how to respond to user input. Try to clearly define the persona's role and how it should respond to user input.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=5e62e6b7ad79fecf90b9ea6558cbe6b4" alt="personality" data-og-width="466" width="466" data-og-height="217" height="217" data-path="images/personas/personality-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=fa8848b54e414394f529a402a611d7f0 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=e684169e703a1bddbf616deea49d45f5 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=48f5edfeda3e06f632839ca72e9ba6f1 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=11af8d416b4a6b47834880edea2e176a 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=207bf688e68622309f40a81bc4884c7f 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/personality-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=33f85e05d7f9c1ec458ef51e6e3be55a 2500w" />
</Frame>

### Confirm

Once you've filled in all the fields, click "Save Persona" to create your persona. You can chat with it right away by clicking the "Chat" button.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=9d645c63614d81d4076ee065bbe1dcca" alt="create persona" data-og-width="549" width="549" data-og-height="109" height="109" data-path="images/personas/save-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=71ed025962a5aa5fdef0f8db964294b5 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=5918b0ea006d7e4f8b510381466a3e30 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=179902fd262d06723702be88ac6f0caf 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=17bf6c5029fef8175fcdc9c0e8f55bc4 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=fff15f5cc6eaba1750da782bfce49e29 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/save-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=a7ada5cdd6cf242b6b44a5fdf6c298df 2500w" />
</Frame>

### Using your custom persona

Once you've created your persona you can integrate into your application by using the Persona ID with the Anam SDK. From the chat interface, click "Try with API" to see an example of how to create a session token using the persona ID.

<Frame>
  <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=21fc4b8ee7f76f7f8d5e80a61423055d" alt="create persona" data-og-width="634" width="634" data-og-height="403" height="403" data-path="images/personas/try-with-api-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=f73a042ed1e752c24d269943e1c73483 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=3d5d32d205ea9a632147a58e67ff5ccc 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=04b644fe7588f0fb08f68177214f9635 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=d68eff68d873e2d2d11afe22df311163 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=1005b8e21a23b84a8e7312847e90addf 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/personas/try-with-api-dark.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=a911ee39aa3df8612b8a16349bda8a93 2500w" />
</Frame>


# Create your own persona
Source: https://docs.anam.ai/concepts/personas/create-your-own/overview

Learn how to create and customize your own Anam persona

Custom personas allow you to build personas that are tailored to your specific use case. You can create your own custom personas visually using the Anam Lab web UI or programmatically using your API key with the Anam API.

<CardGroup cols={2}>
  <Card title="Create your own persona using the Anam Lab" href="/guides/personas/create-your-own/create-your-own-lab" icon="window" />

  <Card title="Create your own persona using the Anam API" href="/guides/personas/create-your-own/create-your-own-api" icon="code" />
</CardGroup>


# Default Personas
Source: https://docs.anam.ai/concepts/personas/default-personas

Explore our pre-built personas ready for immediate use

Every Anam account has access to a pre-defined list of 'default personas'. You can use these personas immediately or use them as a guide for creating your own custom personas.
You can view the full list of available default personas in the [Anam Lab](https://lab.anam.ai) or via the [Anam API](https://api.anam.ai/api).

## Available Default Personas

The following personas are available to all accounts.

### Leo - The Virtual Receptionist

**ID:** `773a8ca8-efd8-4449-9305-8b8bc1591475`

Leo is the virtual receptionist of the fictional Sunset Hotel. He'll guide you through the process of checking in and reserving a room.

### Maya - AI Therapist

**ID:** `1a5588b4-a717-468c-ad8b-03b323e78e78`

Maya is a virtual therapist designed to provide emotional support and suggest mindfulness techniques.

### Aria - The Healthcare Assistant

**ID:** `1e9a0de0-1190-4ede-b946-ff451430848e`

Aria is a virtual healthcare assistant designed to help patients book appointments, manage prescriptions, and answer general health-related queries.

### Alex - Virtual Sales Coach

**ID:** `67fb9278-e049-4937-9af1-d771b88b6875`

Alex is a sales coach designed to help users practice cold calls, pitch delivery, and objection handling.

### Sophie - Language Teacher

**ID:** `ebc07e30-64a2-40e3-9584-28f44d62ee0c`

Sophie is a language teacher designed to help users practice speaking and listening skills, specialising in French.

## Next Steps

Whilst default personas are a great way to get started, you'll likely want something more tailored to your specific use case.
Next we'll look at how to create your own custom persona which gives you full control over the persona's appearance and behaviour.

<CardGroup cols={1}>
  <Card title="Creating your own persona" href="/guides/personas/create-your-own" icon="person-circle-plus" />
</CardGroup>


# Introduction to Personas
Source: https://docs.anam.ai/concepts/personas/introduction

Learn about Anam personas and how they power your AI interactions

## What are Personas?

Personas are AI powered digital humans that can be integrated into your applications using the Anam JavaScript SDK. Each persona is designed with specific characteristics and capabilities to handle different use cases and roles.

## Managing Personas

Personas can be managed through the [Anam Lab](https://lab.anam.ai) or via the [Anam API](https://api.anam.ai/api). With either method you can:

* List available personas for your account
* View detailed information about specific personas
* Create custom personas with unique configurations

## Types of Personas

### Default Personas

Every Anam account has access to pre-defined 'default personas', which can be used immediately or used as a guide for creating your own custom personas. When first integrating Anam with your product we recommend starting with a default persona.

### Custom Personas

Custom personas are created by you and can be used in the same way as default personas. With a custom persona you have control over:

* Name and description
* Persona preset (defining face and voice)
* Brain configuration (system prompt, personality, and filler phrases)

## Getting Started

To start using personas in your application, you can:

1. Use one of our [default personas](/concepts/personas/default-personas)
2. [Create your own persona](/concepts/personas/create-your-own/overview)
3. [Implement your own brain](/concepts/custom-llms) for custom knowledge integration

## Best Practices

* Choose personas that align with your use case and brand identity
* Test personas in your target environment before deployment
* Consider your audience when selecting or creating persona characteristics


# Real-time Streaming
Source: https://docs.anam.ai/concepts/streaming

Understand how video and audio streaming works with Anam personas

Anam uses WebRTC technology to deliver real-time video and audio streaming of AI personas. This enables sub-second response times and natural conversation flow that feels truly interactive.

## How Streaming Works

<Steps>
  <Step title="Connection Establishment">
    Your client establishes a WebRTC peer-to-peer connection using the session token
  </Step>

  <Step title="Media Stream Setup">
    Anam begins streaming the persona's video feed to your specified video element
  </Step>

  <Step title="Bidirectional Communication">
    Your application can send messages while receiving real-time video and audio responses
  </Step>

  <Step title="Synchronized Output">
    The persona's speech is automatically synchronized with lip movements and facial expressions
  </Step>
</Steps>

## Stream Architecture

Understanding the streaming architecture helps you optimize performance and handle edge cases:

```mermaid  theme={"dark"}
graph TD
    A[Client Application] -->|Session Token| B[Anam Streaming Service]
    B -->|WebRTC Connection| C[Video Stream]
    B -->|WebRTC Connection| D[Audio Stream]
    C --> E[HTML Video Element]
    D --> E
    A -->|Send Message| B
    B -->|Generate Response| F[AI Engine]
    F -->|Synchronized A/V| B
```

## Basic Streaming Setup

### Simple Video Streaming

The most basic streaming setup connects a persona to a video element:

```javascript  theme={"dark"}
import { createClient } from '@anam-ai/js-sdk';

async function initializeStreaming() {
  // Get session token from your server
  const sessionToken = await getSessionToken();
  
  // Create client
  const anamClient = createClient(sessionToken);
  
  // Start streaming to video element
  await anamClient.streamToVideoElement('persona-video');
  
  console.log('Streaming started successfully');
}

// HTML video element
// <video id="persona-video" autoplay playsinline muted></video>
```

### Advanced Streaming Configuration

For more control over the streaming experience:

```javascript  theme={"dark"}
class PersonaStreaming {
  constructor(sessionToken) {
    this.client = createClient(sessionToken);
    this.isConnected = false;
    this.streamQuality = 'high';
  }

  async initialize(videoElementId, options = {}) {
    const defaultOptions = {
      autoplay: true,
      muted: true, // Start muted to comply with browser policies
      controls: false,
      playsInline: true
    };

    const streamOptions = { ...defaultOptions, ...options };

    try {
      // Set up event listeners before connecting
      this.setupEventListeners();
      
      // Configure stream quality
      await this.client.setStreamQuality(this.streamQuality);
      
      // Start streaming
      await this.client.streamToVideoElement(videoElementId, streamOptions);
      
      this.isConnected = true;
      console.log('Streaming initialized with options:', streamOptions);
      
    } catch (error) {
      console.error('Failed to initialize streaming:', error);
      throw error;
    }
  }

  setupEventListeners() {
    this.client.on('stream_started', () => {
      console.log('Video stream started');
      this.handleStreamStart();
    });

    this.client.on('stream_ended', () => {
      console.log('Video stream ended');
      this.handleStreamEnd();
    });

    this.client.on('stream_error', (error) => {
      console.error('Stream error:', error);
      this.handleStreamError(error);
    });

    this.client.on('quality_changed', (quality) => {
      console.log('Stream quality changed to:', quality);
      this.streamQuality = quality;
    });
  }

  handleStreamStart() {
    // Update UI to show streaming state
    document.getElementById('status').textContent = 'Connected';
    document.getElementById('persona-video').classList.add('streaming');
  }

  handleStreamEnd() {
    // Update UI and potentially reconnect
    document.getElementById('status').textContent = 'Disconnected';
    this.isConnected = false;
  }

  handleStreamError(error) {
    // Implement retry logic or user notification
    if (error.code === 'NETWORK_ERROR') {
      this.retryConnection();
    } else {
      this.showErrorToUser(error.message);
    }
  }

  async retryConnection() {
    const maxRetries = 3;
    let retryCount = 0;

    while (retryCount < maxRetries && !this.isConnected) {
      try {
        await new Promise(resolve => setTimeout(resolve, 1000 * (retryCount + 1)));
        await this.client.reconnect();
        break;
      } catch (error) {
        retryCount++;
        console.warn(`Retry ${retryCount} failed:`, error);
      }
    }
  }
}
```

## Stream Quality Management

### Adaptive Quality

Anam automatically adjusts stream quality based on network conditions, but you can also control it manually:

```javascript  theme={"dark"}
class AdaptiveStreaming {
  constructor(anamClient) {
    this.client = anamClient;
    this.networkMonitor = new NetworkQualityMonitor();
  }

  async optimizeStreamQuality() {
    // Monitor network conditions
    this.networkMonitor.on('quality_change', async (networkQuality) => {
      let streamQuality;
      
      switch (networkQuality) {
        case 'excellent':
          streamQuality = 'ultra';
          break;
        case 'good':
          streamQuality = 'high';
          break;
        case 'fair':
          streamQuality = 'medium';
          break;
        case 'poor':
          streamQuality = 'low';
          break;
        default:
          streamQuality = 'auto';
      }

      try {
        await this.client.setStreamQuality(streamQuality);
        console.log(`Stream quality adjusted to: ${streamQuality}`);
      } catch (error) {
        console.error('Failed to adjust stream quality:', error);
      }
    });
  }

  // Manual quality control
  async setQuality(quality) {
    const validQualities = ['auto', 'low', 'medium', 'high', 'ultra'];
    
    if (!validQualities.includes(quality)) {
      throw new Error(`Invalid quality setting: ${quality}`);
    }

    await this.client.setStreamQuality(quality);
  }
}

// Usage
const adaptiveStreaming = new AdaptiveStreaming(anamClient);
await adaptiveStreaming.optimizeStreamQuality();

// Manual quality adjustment
await adaptiveStreaming.setQuality('high');
```

### Quality Settings

<CardGroup cols={2}>
  <Card title="Ultra Quality" icon="star">
    **1080p, 60fps** - Best visual quality for high-end applications
  </Card>

  <Card title="High Quality" icon="eye">
    **720p, 30fps** - Great balance of quality and performance
  </Card>

  <Card title="Medium Quality" icon="zap">
    **480p, 30fps** - Good quality with lower bandwidth usage
  </Card>

  <Card title="Low Quality" icon="wifi">
    **360p, 24fps** - Optimized for poor network conditions
  </Card>
</CardGroup>

## Audio Management

### Audio Controls

Handle audio playback and user interactions:

```javascript  theme={"dark"}
class AudioManager {
  constructor(anamClient) {
    this.client = anamClient;
    this.isMuted = true; // Start muted for browser compliance
    this.volume = 1.0;
  }

  async enableAudio() {
    try {
      // Request user interaction first (required by browsers)
      await this.requestUserInteraction();
      
      // Unmute the stream
      await this.client.setMuted(false);
      this.isMuted = false;
      
      console.log('Audio enabled');
      this.updateAudioUI();
      
    } catch (error) {
      console.error('Failed to enable audio:', error);
      throw error;
    }
  }

  async requestUserInteraction() {
    return new Promise((resolve) => {
      const button = document.getElementById('enable-audio-btn');
      const handleClick = () => {
        button.removeEventListener('click', handleClick);
        button.style.display = 'none';
        resolve();
      };
      button.addEventListener('click', handleClick);
      button.style.display = 'block';
      button.textContent = 'Click to Enable Audio';
    });
  }

  async toggleMute() {
    this.isMuted = !this.isMuted;
    await this.client.setMuted(this.isMuted);
    this.updateAudioUI();
  }

  async setVolume(volume) {
    this.volume = Math.max(0, Math.min(1, volume));
    await this.client.setVolume(this.volume);
    this.updateAudioUI();
  }

  updateAudioUI() {
    const muteButton = document.getElementById('mute-button');
    const volumeSlider = document.getElementById('volume-slider');
    
    muteButton.textContent = this.isMuted ? '🔇' : '🔊';
    volumeSlider.value = this.volume;
  }
}

// HTML controls
/*
<button id="enable-audio-btn" style="display: none;">Enable Audio</button>
<button id="mute-button" onclick="audioManager.toggleMute()">🔇</button>
<input id="volume-slider" type="range" min="0" max="1" step="0.1" 
       onchange="audioManager.setVolume(this.value)">
*/
```

## Performance Optimization

### Connection Optimization

Optimize streaming performance for different scenarios:

```javascript  theme={"dark"}
class StreamOptimizer {
  constructor(anamClient) {
    this.client = anamClient;
    this.performanceMetrics = {
      latency: 0,
      frameRate: 0,
      bandwidth: 0
    };
  }

  async optimizeForMobile() {
    // Reduce quality for mobile devices
    await this.client.setStreamQuality('medium');
    
    // Enable battery optimization
    await this.client.setConfig({
      powerSaveMode: true,
      adaptiveFrameRate: true,
      reducedMotion: true
    });
    
    console.log('Mobile optimizations applied');
  }

  async optimizeForDesktop() {
    // Higher quality for desktop
    await this.client.setStreamQuality('high');
    
    // Full feature set
    await this.client.setConfig({
      powerSaveMode: false,
      adaptiveFrameRate: false,
      reducedMotion: false
    });
    
    console.log('Desktop optimizations applied');
  }

  monitorPerformance() {
    setInterval(async () => {
      try {
        const stats = await this.client.getStreamStats();
        this.performanceMetrics = {
          latency: stats.latency,
          frameRate: stats.frameRate,
          bandwidth: stats.bandwidth
        };
        
        this.adjustBasedOnPerformance();
      } catch (error) {
        console.error('Failed to get stream stats:', error);
      }
    }, 5000); // Check every 5 seconds
  }

  adjustBasedOnPerformance() {
    const { latency, frameRate, bandwidth } = this.performanceMetrics;
    
    // Auto-adjust quality based on performance
    if (latency > 500 || frameRate < 20) {
      this.client.setStreamQuality('low');
      console.log('Quality reduced due to performance issues');
    } else if (latency < 100 && frameRate > 28 && bandwidth > 2000) {
      this.client.setStreamQuality('high');
      console.log('Quality increased due to good performance');
    }
  }
}
```

### Bandwidth Management

<Tabs>
  <Tab title="Low Bandwidth">
    ```javascript  theme={"dark"}
    // Optimize for poor network conditions
    await anamClient.setConfig({
      streamQuality: 'low',
      audioQuality: 'compressed',
      frameRate: 15,
      adaptiveBitrate: true
    });
    ```
  </Tab>

  <Tab title="High Bandwidth">
    ```javascript  theme={"dark"}
    // Optimize for excellent network conditions
    await anamClient.setConfig({
      streamQuality: 'ultra',
      audioQuality: 'high',
      frameRate: 60,
      adaptiveBitrate: false
    });
    ```
  </Tab>

  <Tab title="Variable Network">
    ```javascript  theme={"dark"}
    // Let Anam handle optimization automatically
    await anamClient.setConfig({
      streamQuality: 'auto',
      audioQuality: 'auto',
      adaptiveBitrate: true,
      networkAdaptation: true
    });
    ```
  </Tab>
</Tabs>

## Handling Stream Events

### Connection Lifecycle

Monitor and respond to streaming events:

```javascript  theme={"dark"}
class StreamEventHandler {
  constructor(anamClient) {
    this.client = anamClient;
    this.connectionState = 'disconnected';
    this.setupEventListeners();
  }

  setupEventListeners() {
    // Connection events
    this.client.on('connecting', () => {
      this.connectionState = 'connecting';
      this.showStatus('Connecting to persona...', 'connecting');
    });

    this.client.on('connected', () => {
      this.connectionState = 'connected';
      this.showStatus('Connected', 'success');
      this.enableInteraction();
    });

    this.client.on('disconnected', () => {
      this.connectionState = 'disconnected';
      this.showStatus('Disconnected', 'error');
      this.disableInteraction();
    });

    // Stream quality events
    this.client.on('stream_quality_changed', (quality) => {
      console.log(`Stream quality changed to: ${quality}`);
      this.updateQualityIndicator(quality);
    });

    // Performance events
    this.client.on('poor_connection', (metrics) => {
      console.warn('Poor connection detected:', metrics);
      this.showBandwidthWarning();
    });

    this.client.on('connection_recovered', () => {
      console.log('Connection quality improved');
      this.hideBandwidthWarning();
    });

    // Error events
    this.client.on('stream_error', (error) => {
      this.handleStreamError(error);
    });
  }

  showStatus(message, type) {
    const statusElement = document.getElementById('connection-status');
    statusElement.textContent = message;
    statusElement.className = `status ${type}`;
  }

  enableInteraction() {
    document.getElementById('message-input').disabled = false;
    document.getElementById('send-button').disabled = false;
  }

  disableInteraction() {
    document.getElementById('message-input').disabled = true;
    document.getElementById('send-button').disabled = true;
  }

  updateQualityIndicator(quality) {
    const indicator = document.getElementById('quality-indicator');
    indicator.textContent = quality.toUpperCase();
    indicator.className = `quality-indicator ${quality}`;
  }

  showBandwidthWarning() {
    const warning = document.getElementById('bandwidth-warning');
    warning.style.display = 'block';
    warning.textContent = 'Poor network connection detected. Stream quality may be reduced.';
  }

  hideBandwidthWarning() {
    document.getElementById('bandwidth-warning').style.display = 'none';
  }

  handleStreamError(error) {
    console.error('Stream error:', error);
    
    switch (error.code) {
      case 'MEDIA_ERROR':
        this.showError('Video playback error. Please refresh the page.');
        break;
      case 'NETWORK_ERROR':
        this.showError('Network connection lost. Attempting to reconnect...');
        this.attemptReconnection();
        break;
      case 'PERMISSION_ERROR':
        this.showError('Browser permissions required for video playback.');
        break;
      default:
        this.showError('An unexpected error occurred. Please try again.');
    }
  }

  async attemptReconnection() {
    try {
      await this.client.reconnect();
    } catch (error) {
      this.showError('Failed to reconnect. Please refresh the page.');
    }
  }

  showError(message) {
    const errorElement = document.getElementById('error-message');
    errorElement.textContent = message;
    errorElement.style.display = 'block';
  }
}
```

## Common Streaming Issues

<AccordionGroup>
  <Accordion title="Video Not Appearing">
    **Symptoms**: Black screen or no video element content

    **Common Causes & Solutions**:

    * **Missing autoplay attribute**: Add `autoplay` to video element
    * **Browser autoplay policy**: Require user interaction before streaming
    * **Invalid session token**: Check token creation and expiration
    * **Network connectivity**: Verify internet connection and firewall settings

    ```javascript  theme={"dark"}
    // Ensure proper video element setup
    const video = document.getElementById('persona-video');
    video.autoplay = true;
    video.playsInline = true;
    video.muted = true; // Required for autoplay in most browsers

    // Handle autoplay policy
    anamClient.on('autoplay_blocked', async () => {
      // Show user interaction prompt
      await showPlayButton();
    });
    ```
  </Accordion>

  <Accordion title="Audio Not Playing">
    **Symptoms**: Video appears but no sound

    **Common Causes & Solutions**:

    * **Browser autoplay policy**: Audio requires user interaction
    * **Muted by default**: Browsers often start videos muted
    * **Audio permissions**: Check browser audio permissions
    * **Volume settings**: Verify system and application volume

    ```javascript  theme={"dark"}
    // Handle audio enablement
    const enableAudioButton = document.getElementById('enable-audio');
    enableAudioButton.addEventListener('click', async () => {
      await anamClient.setMuted(false);
      enableAudioButton.style.display = 'none';
    });
    ```
  </Accordion>

  <Accordion title="Poor Video Quality">
    **Symptoms**: Pixelated, blurry, or low-resolution video

    **Common Causes & Solutions**:

    * **Bandwidth limitations**: Stream quality auto-reduced
    * **Device performance**: Lower quality for mobile/older devices
    * **Network congestion**: Temporary quality reduction
    * **Manual quality setting**: Check if quality is manually set to low

    ```javascript  theme={"dark"}
    // Check and adjust quality
    const currentQuality = await anamClient.getStreamQuality();
    console.log('Current quality:', currentQuality);

    // Force higher quality if network allows
    if (currentQuality === 'low') {
      try {
        await anamClient.setStreamQuality('medium');
      } catch (error) {
        console.log('Cannot increase quality due to network constraints');
      }
    }
    ```
  </Accordion>

  <Accordion title="High Latency / Lag">
    **Symptoms**: Delayed responses, out-of-sync audio/video

    **Common Causes & Solutions**:

    * **Network latency**: Check internet connection speed
    * **Server distance**: Use CDN or edge servers
    * **Device performance**: Reduce quality on lower-end devices
    * **Browser optimization**: Use hardware acceleration when available

    ```javascript  theme={"dark"}
    // Monitor and optimize for latency
    setInterval(async () => {
      const stats = await anamClient.getStreamStats();
      if (stats.latency > 300) { // 300ms threshold
        console.warn('High latency detected:', stats.latency);
        await anamClient.setStreamQuality('low'); // Reduce quality
      }
    }, 5000);
    ```
  </Accordion>
</AccordionGroup>

## Browser Compatibility

### Supported Browsers

<CardGroup cols={2}>
  <Card title="Chrome/Edge" icon="check">
    **Full Support** - Best performance and feature compatibility
  </Card>

  <Card title="Firefox" icon="check">
    **Full Support** - Excellent WebRTC implementation
  </Card>

  <Card title="Safari" icon="alert-triangle">
    **Partial Support** - Some limitations on iOS, works well on macOS
  </Card>

  <Card title="Mobile Browsers" icon="smartphone">
    **Good Support** - Optimized quality and features for mobile
  </Card>
</CardGroup>

### Browser-Specific Optimizations

```javascript  theme={"dark"}
class BrowserOptimizer {
  constructor(anamClient) {
    this.client = anamClient;
    this.browser = this.detectBrowser();
  }

  detectBrowser() {
    const userAgent = navigator.userAgent;
    if (userAgent.includes('Chrome')) return 'chrome';
    if (userAgent.includes('Firefox')) return 'firefox';
    if (userAgent.includes('Safari')) return 'safari';
    if (userAgent.includes('Edge')) return 'edge';
    return 'unknown';
  }

  async applyOptimizations() {
    switch (this.browser) {
      case 'safari':
        // Safari-specific optimizations
        await this.client.setConfig({
          preferH264: true, // Safari prefers H.264
          reducedFrameRate: true // Better performance on Safari
        });
        break;
        
      case 'firefox':
        // Firefox optimizations
        await this.client.setConfig({
          preferVP9: true, // Firefox handles VP9 well
          enableHardwareAcceleration: true
        });
        break;
        
      case 'chrome':
      case 'edge':
        // Chromium-based optimizations
        await this.client.setConfig({
          enableAdvancedCodecs: true,
          preferAV1: true // Latest Chrome supports AV1
        });
        break;
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Event Handling" icon="bolt" href="/concepts/events">
    Learn about all streaming and conversation events
  </Card>

  <Card title="Performance Best Practices" icon="zap" href="/best-practices/performance">
    Optimize streaming performance for production
  </Card>

  <Card title="Troubleshooting Guide" icon="tool" href="/resources/troubleshooting">
    Solve common streaming and connection issues
  </Card>

  <Card title="Production Deployment" icon="server" href="/best-practices/production-deployment">
    Deploy streaming personas at scale
  </Card>
</CardGroup>


# Tools and Function Calling
Source: https://docs.anam.ai/concepts/tools

Enable your AI personas to interact with external systems, trigger client actions, and search knowledge bases

## Overview

Anam's tool calling system enables AI personas to perform actions beyond conversation. During a session, the LLM can intelligently decide when to invoke tools based on user intent, making your personas capable of:

* Triggering client-side actions (opening modals, redirecting pages, updating UI)
* Searching knowledge bases using semantic search (RAG)
* Calling external APIs via webhooks
* Executing custom business logic

Tools make your AI personas truly agentic, capable of taking actions to help users accomplish their goals.

<Warning>
  **Beta Feature**: Tool calling is currently in beta. You may encounter some
  issues as we continue to improve the feature. Please report any feedback or
  issues to help us make it better.
</Warning>

## How Tool Calling Works

When a user interacts with your persona, the conversation flows through an intelligent decision-making process:

<Steps>
  <Step title="User speaks or types">
    The user makes a request: "What's the status of my order 12345?"
  </Step>

  <Step title="LLM analyzes intent">
    The persona's LLM analyzes the request and determines it needs external information to respond accurately.
  </Step>

  <Step title="Tool invocation">
    The LLM selects the appropriate tool and generates a structured function call:

    ```json  theme={"dark"}
    {
      "name": "check_order_status",
      "arguments": {
        "orderId": "12345"
      }
    }
    ```
  </Step>

  <Step title="Tool execution">
    The system executes the tool based on its type: - **Client tools**: Event sent to your client application - **Knowledge tools**: Semantic search performed on your documents - **Webhook tools**: HTTP request sent to your API endpoint
  </Step>

  <Step title="Response integration">
    The tool result is returned to the LLM, which incorporates it into a natural language response.

    <Check>
      The user hears a complete, informed answer without knowing the technical orchestration behind the scenes.
    </Check>
  </Step>
</Steps>

## Tool Types

Anam supports three types of tools, each designed for different use cases:

### Client Tools

Client tools trigger events in your client application, enabling the persona to control your user interface.

**Common use cases**:

* Opening product pages or checkout flows
* Displaying modals or notifications
* Navigating to specific sections of your app
* Updating UI state based on conversation

```typescript  theme={"dark"}
{
  type: 'client',
  name: 'open_checkout',
  description: 'Opens the checkout page when user wants to purchase',
  parameters: {
    type: 'object',
    properties: {
      productId: {
        type: 'string',
        description: 'The ID of the product to checkout'
      }
    },
    required: ['productId']
  }
}
```

<Tip>
  Client tools are perfect for creating seamless, voice-driven user experiences
  where the AI can guide users through your application.
</Tip>

### Knowledge Tools (RAG)

Knowledge tools enable semantic search across your uploaded documents using Retrieval-Augmented Generation (RAG).

**Common use cases**:

* Answering questions from product documentation
* Searching company policies or FAQs
* Retrieving information from manuals or guides
* Providing accurate, source-based responses

```typescript  theme={"dark"}
{
  type: 'server',
  subtype: 'knowledge',
  name: 'search_documentation',
  description: 'Search product documentation when user asks questions',
  documentFolderIds: ['550e8400-e29b-41d4-a716-446655440000', '6ba7b810-9dad-11d1-80b4-00c04fd430c8']
}
```

<Info>
  Folder IDs are UUIDs. You can find them in the Anam Lab UI at `/knowledge` or
  via the API when creating folders.
</Info>

Knowledge tools automatically handle the complexities of search:

* They understand the user's intent, not just keywords.
* They find the most relevant snippets from your documents.
* They provide this information to the AI to form an accurate answer.

<Note>
  Knowledge tools require you to upload and organize documents in knowledge
  folders before they can be used. Learn more in the [Knowledge Base
  documentation](/concepts/knowledge-base).
</Note>

### Webhook Tools

Webhook tools call external HTTP endpoints, allowing your persona to integrate with any API. This is the key to unlocking advanced agentic capabilities, enabling your persona to interact with the outside world and perform complex actions.

**Common use cases**:

* Checking order or shipment status
* Creating support tickets
* Updating CRM records
* Fetching real-time data (weather, stock prices, etc.)
* Triggering workflows in external systems

```typescript  theme={"dark"}
{
  type: 'server',
  subtype: 'webhook',
  name: 'check_order_status',
  description: 'Check the status of a customer order',
  url: 'https://api.example.com/orders',
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.API_SECRET}`,
    'X-Organization-ID': 'org-uuid'
  },
  parameters: {
    type: 'object',
    properties: {
      orderId: {
        type: 'string',
        description: 'The order ID to check'
      }
    },
    required: ['orderId']
  },
  awaitResponse: true
}
```

<Tip>
  Set `awaitResponse: false` for fire-and-forget webhooks like logging or
  notifications where you don't need the response data.
</Tip>

## Attaching Tools to Personas

Tools can be attached to personas in two ways:

### Stateful Personas (Database-Stored)

For stateful personas, tools must be created first and then attached by their ID.

<Steps>
  <Step title="Create tools">
    Create tools via the UI at `/tools` or via the API. Each tool gets a persistent ID.

    ```http  theme={"dark"}
    POST /v1/tools
    Content-Type: application/json
    Authorization: Bearer YOUR_API_KEY

    {
      "type": "server",
      "subtype": "knowledge",
      "name": "search_docs",
      "description": "Search product documentation",
      "config": {
        "documentFolderIds": ["550e8400-e29b-41d4-a716-446655440000"]
      }
    }
    ```

    Response includes the tool ID:

    ```json  theme={"dark"}
    {
      "id": "tool-uuid-123",
      "name": "search_docs",
      ...
    }
    ```
  </Step>

  <Step title="Attach tools to persona">
    In the UI at `/build/{personaId}`, add tools from your organization's tool library, OR via API when creating/updating a persona:

    ```http  theme={"dark"}
    PUT /v1/personas/{personaId}
    Content-Type: application/json
    Authorization: Bearer YOUR_API_KEY

    {
      "toolIds": ["tool-uuid-123", "tool-uuid-456"]
    }
    ```
  </Step>

  <Step title="Use persona in session">
    When you create a session with this persona, all attached tools are automatically loaded:

    ```http  theme={"dark"}
    POST /v1/auth/session-token
    Content-Type: application/json

    {
      "personaConfig": {
        "personaId": "persona-uuid"
      }
    }
    ```

    <Check>
      The persona's tools are available during the session without needing to specify them again.
    </Check>
  </Step>
</Steps>

## Tool Design Best Practices

### Write Clear Descriptions

The tool description helps the LLM understand **when** to use the tool. Be specific and include context.

<CodeGroup>
  ```typescript Good theme={"dark"}
  {
    name: 'check_order_status',
    description: 'Check the status of a customer order when they ask about delivery, tracking, or order updates. Use the order ID from the conversation.'
  }
  ```

  ```typescript Bad theme={"dark"}
  {
    name: 'check_order_status',
    description: 'Checks orders'
  }
  ```
</CodeGroup>

### Use Semantic Function Names

Follow snake\_case naming conventions and make names descriptive:

* ✅ `search_product_documentation`
* ✅ `create_support_ticket`
* ✅ `open_checkout_page`
* ❌ `search`
* ❌ `doThing`
* ❌ `tool1`

### Define Clear Parameters

Use JSON Schema to define parameters with detailed descriptions:

```typescript  theme={"dark"}
parameters: {
  type: 'object',
  properties: {
    orderId: {
      type: 'string',
      description: 'The order ID mentioned by the user, typically in format ORD-12345'
    },
    includeTracking: {
      type: 'boolean',
      description: 'Whether to include detailed tracking information'
    }
  },
  required: ['orderId']
}
```

<Warning>
  The LLM extracts parameter values from the conversation. If a required
  parameter isn't available, the LLM may ask the user for clarification or skip
  the tool call.
</Warning>

### Organize Knowledge by Domain

Create separate knowledge folders for different topics and assign them to specific tools for better relevance:

```typescript  theme={"dark"}
// Instead of one tool searching everything...
{
  name: 'search_all_docs',
  documentFolderIds: [
    '550e8400-e29b-41d4-a716-446655440000', // product docs
    '6ba7b810-9dad-11d1-80b4-00c04fd430c8', // faqs
    '7c9e6679-7425-40de-944b-e07fc1f90ae7'  // policies
  ]
}

// ...use focused tools.
{
  name: 'search_product_docs',
  description: 'Search product documentation for technical questions',
  documentFolderIds: ['550e8400-e29b-41d4-a716-446655440000']
},
{
  name: 'search_faqs',
  description: 'Search frequently asked questions for common inquiries',
  documentFolderIds: ['6ba7b810-9dad-11d1-80b4-00c04fd430c8']
}
```

## Limitations

**Tool naming**:

* Length: 1-64 characters
* Pattern: `^[a-zA-Z0-9_.-]+$`
* No spaces or special characters

**Tool descriptions**:

* Length: 1-1024 characters

**Knowledge tools**:

* Require at least one folder ID
* Folders must contain at least one READY document for useful results
* Document uploads subject to size and storage limits
* Supported formats: PDF, TXT, MD, DOCX, CSV, JSON, LOG

**Webhook tools**:

* 5-second timeout (Ideally much faster)
* Supported methods: GET, POST, PUT, PATCH, DELETE
* Response size limit: 1MB (ideally lower)

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started with Tools" icon="rocket" href="/guides/tools/introduction">
    Create your first tool in 5 minutes
  </Card>

  <Card title="Knowledge Base Setup" icon="database" href="/guides/knowledge/setup">
    Upload documents and configure RAG search
  </Card>

  <Card title="Client Tool Events" icon="browser" href="/guides/tools/client-tools">
    Handle tool events in your client application
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tools/introduction">
    Complete API documentation for tools
  </Card>
</CardGroup>


# Embed Anam on Your Website
Source: https://docs.anam.ai/embed

Quickly integrate Anam's conversational AI into your website with our Player or SDK embed options

# Embed Anam on Your Website

Get up and running in minutes by embedding Anam directly into your website. Similar to YouTube video embeds, Anam offers flexible embedding options to suit different website architectures and security requirements.

## Quick Decision Guide

<Tip>
  **Choose Player (iframe)** if you:

  * Want an out-of-the-box, full-featured interface
  * Need visual customization isolation
  * Have basic technical requirements
  * Are using platforms with iframe support

  **Choose SDK (JavaScript)** if you:

  * Want to build your own interface
  * Need programmatic control
  * Have full access to page JavaScript
  * Want minimal initial page impact
</Tip>

## Embed Options

### Player (iframe)

The Player embed uses an iframe to display the Anam interface within your website. This option provides the most seamless visual integration.

<Tabs>
  <Tab title="Features">
    * Full-featured Anam interface in an embedded frame
    * Isolated from your site's CSS and JavaScript
    * Easy to implement with a simple iframe tag
    * Responsive design that adapts to container size
  </Tab>

  <Tab title="Requirements">
    * **Microphone permissions**: Required for voice interaction - **Network
      permissions**: Required for API communication - **iframe permissions**: Your
      site must allow iframe embedding - **HTTPS**: Your website must be served over
      HTTPS
  </Tab>

  <Tab title="Example Code">
    ```html index.html theme={"dark"}
    <!-- Basic embed -->
    <iframe 
      src="https://lab.anam.ai/frame/SHARE_TOKEN"
      width="720"
      height="480"
      frameborder="0"
      allow="microphone"
    </iframe>

    <!-- Responsive embed with container -->

    <div style="position: relative; width: 100%; max-width: 720px;">
      <iframe 
        src="https://lab.anam.ai/frame/SHARE_TOKEN"
        style="width: 100%; height: 480px; border: none;"
        allow="microphone">
      </iframe>
    </div>
    ```
  </Tab>
</Tabs>

### SDK (JavaScript)

The SDK embed uses JavaScript directly to embed Anam on your page. This can be used to build your own interface.

<Tabs>
  <Tab title="Features">
    * Full control over the interface
    * Programmatic control over the embed
    * Minimal initial footprint on page load
  </Tab>

  <Tab title="Requirements">
    * **Microphone permissions**: Required for voice interaction - **Network
      permissions**: Required for API communication - **Script execution**: Your
      site must allow external JavaScript - **HTTPS**: Your website must be served
      over HTTPS
  </Tab>
</Tabs>

## Platform Compatibility

Different website builders and platforms have varying levels of support for embedded content. Use this compatibility matrix to determine which embed option works best for your platform.

<Note>
  **Legend:** - ✅ **Supported** - Works out of the box - ⚠️ **Requires
  Configuration** - Works with additional setup or workarounds - ❌ **Not
  Supported** - Cannot be implemented on this platform
</Note>

| Platform          | Player (iframe) | SDK (JavaScript) | Notes                                                                                     |
| ----------------- | --------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| **WordPress.org** | ✅               | ✅                | • Unrestricted code access<br />• Largest market share<br />• Primary go-to-market target |
| **WordPress.com** | ⚠️              | ❌                | • iframe & script tags require plugin-enabled plan<br />• CSP blocks remote scripts       |
| **Wix**           | ❌               | ❌                | • Microphone permissions denied<br />• DOM manipulation incompatible                      |
| **Shopify**       | ✅               | ⚠️               | • Requires navigation of platform security headers                                        |
| **Squarespace**   | ⚠️              | ⚠️               | • Requires paid plan<br />• Limited custom code support                                   |
| **Webflow**       | ✅               | ⚠️               | • Enterprise plan may be needed for whitelisting                                          |
| **GoDaddy**       | ✅               | ❌                | • No JS injection capability                                                              |
| **Jimdo Creator** | ⚠️              | ⚠️               | • Requires "Creator" mode<br />• Allows custom iframe and JS embeds                       |

<Accordion title="Platform-Specific Instructions">
  ### WordPress.com

  <Warning>
    WordPress.com has strict security policies that limit embed options. Consider
    using WordPress.org (self-hosted) for full functionality.
  </Warning>

  **Player Embed:**

  * Requires Business plan (\$25/month) or higher
  * Add via Custom HTML block in the editor
  * May be blocked by security settings on lower-tier plans

  **SDK Embed:**

  * Not supported due to JavaScript restrictions
  * Cannot add custom scripts on any WordPress.com plan

  ### WordPress.org (Self-Hosted)

  <Check>
    Full support for both Player and SDK embeds with complete control over your
    WordPress installation.
  </Check>

  **Player Embed:**

  1. Add Custom HTML block in Gutenberg editor
  2. Paste the iframe code
  3. Save and preview

  **SDK Embed:**

  1. Add to theme's `footer.php` before `</body>`
  2. Or use a plugin like "Insert Headers and Footers"
  3. Or add via WordPress Customizer > Additional CSS/JS

  ### Wix

  <Warning>
    Wix isolates custom code in sandboxed iframes, preventing the SDK mode from
    functioning. Only the Player mode is available.
  </Warning>

  **Player Embed:**

  1. Add an "HTML iframe" element from the Embed menu
  2. Click "Enter Code"
  3. Paste the iframe code
  4. Adjust sizing as needed

  **SDK Embed:**

  ❌ **Not Supported** - Wix's architecture prevents DOM manipulation required for the SDK mode

  ### Shopify

  <Info>
    Shopify requires navigating platform-specific security headers, but both embed
    options are viable with proper configuration.
  </Info>

  **Player Embed:**

  1. Go to Online Store > Themes > Customize
  2. Add a "Custom Liquid" section
  3. Paste the iframe code
  4. May need to adjust Content Security Policy in theme settings

  **SDK Embed:**

  1. Go to Online Store > Themes > Actions > Edit code
  2. Open `theme.liquid` file
  3. Add script before `</body>` tag
  4. Alternative: Use a custom script app from Shopify App Store

  ### Squarespace

  <Note>
    Squarespace requires a paid plan for custom code injection. Support is limited
    and outside their customer service scope.
  </Note>

  **Player Embed:**

  1. Add a Code Block to your page
  2. Select "HTML" mode
  3. Paste the iframe code
  4. Requires Business plan or higher

  **SDK Embed:**

  1. Go to Settings > Advanced > Code Injection
  2. Add script to Footer section
  3. Requires Business plan or higher
  4. Test thoroughly as debugging support is limited

  ### Webflow

  <Warning>
    Webflow's "Secure Frame Headers" setting can block iframes. Enterprise plans
    may be needed for domain whitelisting.
  </Warning>

  **Player Embed:**

  1. Add an Embed element to your page
  2. Paste the iframe code
  3. Check Site Settings > Security > Secure Frame Headers
  4. May need to disable or whitelist lab.anam.ai

  **SDK Embed:**

  1. Go to Project Settings > Custom Code
  2. Add script to Footer Code section
  3. Publish to see changes (not visible in designer)
  4. Full custom code support on all paid plans

  ### GoDaddy

  <Warning>
    GoDaddy's website builder isolates custom code in iframes, preventing the SDK
    mode from working.
  </Warning>

  **Player Embed:**

  1. Add a "Custom Code" section to your page
  2. Select "HTML" option
  3. Paste the iframe code
  4. Limited customization options available

  **SDK Embed:**

  ❌ **Not Supported** - No capability for JavaScript injection into the main page

  ### Jimdo Creator

  <Info>
    Jimdo supports custom embeds but only in "Creator" mode, not in their
    simplified "Dolphin" mode.
  </Info>

  **Player Embed:**

  1. Ensure you're using Jimdo Creator (not Dolphin)
  2. Add an HTML/Widget element
  3. Paste the iframe code
  4. Adjust dimensions as needed

  **SDK Embed:**

  1. Go to Settings > Edit Head
  2. Add the script code
  3. Requires a paid plan
  4. Test across different page templates
</Accordion>

## Security Considerations

<Warning>
  Both embed options require microphone access for voice interactions. Users
  will be prompted to grant permissions when they first interact with the
  embedded Anam interface.
</Warning>

### Content Security Policy (CSP)

If your website uses a Content Security Policy, you'll need to update it to allow Anam embeds:

```http  theme={"dark"}
# For Player (iframe)
Content-Security-Policy: frame-src https://lab.anam.ai;

# For SDK (JavaScript)
Content-Security-Policy: script-src https://lab.anam.ai; connect-src https://api.anam.ai https://connect.anam.ai https://connect-us.anam.ai https://connect-eu.anam.ai wss://connect.anam.ai wss://connect-us.anam.ai wss://connect-eu.anam.ai;

# Complete example for both options
Content-Security-Policy:
  default-src 'self';
  frame-src https://lab.anam.ai;
  script-src 'self' https://api.anam.ai;
  connect-src https://api.anam.ai https://connect.anam.ai https://connect-us.anam.ai https://connect-eu.anam.ai wss://connect.anam.ai wss://connect-us.anam.ai wss://connect-eu.anam.ai;
  media-src https://api.anam.ai;
```

### HTTPS Requirement

<Note>
  Both embed options require your website to be served over HTTPS. This is
  necessary for microphone access and secure API communication.
</Note>

### Browser Compatibility

<Info>
  Anam embeds support all modern browsers with WebRTC capabilities: -
  **Chrome/Edge**: Version 80+ - **Firefox**: Version 75+ - **Safari**: Version
  14.1+ - **Mobile**: iOS Safari 14.5+, Chrome Android 80+
</Info>

### Performance Considerations

<Tip>
  **Player (iframe)**:

  * Initial load: \~2-3MB
  * Best for: Desktop-first experiences
  * Consider: Lazy loading for below-fold placements

  **SDK (JavaScript)**:

  * Initial load: \~500KB
  * Best for: Mobile-first experiences
  * Consider: Defer loading until user interaction
</Tip>

## Testing Your Embed

<Steps>
  <Step title="Add the embed code">
    Choose either Player or SDK and add the appropriate code to your website.
  </Step>

  <Step title="Verify HTTPS">
    Ensure your website is accessed via `https://` not `http://`.
  </Step>

  <Step title="Test permissions">
    Click on the Anam interface and grant microphone permissions when prompted.
  </Step>

  <Step title="Verify functionality">
    Try having a conversation to ensure audio input and output are working correctly.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Embed not appearing">
    * **Verify token**: Ensure your SHARE\_TOKEN is correct and active
    * **Check console**: Open browser DevTools (F12) and check for errors
    * **Platform limits**: Verify your platform plan supports custom embeds
    * **HTTPS required**: Confirm your site uses https\:// not http\://
    * **Ad blockers**: Disable ad blockers that might block embeds
  </Accordion>

  <Accordion title="Microphone not working">
    * **Browser permissions**: Click the lock icon in address bar to check
      permissions - **HTTPS required**: Microphone API only works on secure
      connections - **Browser support**: Try Chrome/Edge for best compatibility -
      **Extensions**: Disable privacy extensions that block permissions - **Test
      microphone**: Try
      [webrtc.github.io/samples/src/content/devices/input-output/](https://webrtc.github.io/samples/src/content/devices/input-output/)
    * **Console errors**: Look for "NotAllowedError" or "NotFoundError"
  </Accordion>

  <Accordion title="Cross-origin errors">
    * **CSP headers**: Add required domains to Content-Security-Policy -
      **X-Frame-Options**: Remove or set to SAMEORIGIN if blocking - **Platform
      restrictions**: Some platforms have non-configurable security - **Embed
      URLs**: Verify using exact URLs from examples
  </Accordion>

  <Accordion title="Platform-specific issues">
    * **WordPress**: Disable security plugins temporarily to test - **Shopify**:
      Check theme's content\_for\_header liquid tag - **Wix**: Ensure using "HTML
      iframe" element, not "Embed a Site" - **Squarespace**: Use Code Block, not
      Embed Block
  </Accordion>

  <Accordion title="Performance issues">
    * **Slow loading**: Implement lazy loading for below-fold embeds
    * **Mobile performance**: Use SDK mode for lighter initial load
    * **Multiple embeds**: Only load one Anam instance per page
    * **Network speed**: Embed requires stable internet connection
  </Accordion>
</AccordionGroup>

## Best Practices

### Sizing Recommendations

<Info>
  **Player (iframe)**:

  * **Desktop**: 720x480px (minimum), 900x600px (optimal)
  * **Mobile**: 100% width, 400px minimum height
  * **Aspect ratio**: Maintain 3:2 for best experience

  **SDK (JavaScript)**:

  * **Bubble size**: 60x60px default
  * **Expanded view**: 380x600px on mobile, 450x650px on desktop
</Info>

### Accessibility

<Check>
  Anam embeds include built-in accessibility features: - **Keyboard
  navigation**: Full keyboard support - **Screen readers**: ARIA labels and
  announcements - **Focus indicators**: Clear visual focus states -
  **Captions**: Real-time transcription available
</Check>

### Implementation Checklist

Before going live, verify:

* [ ] HTTPS enabled on your domain
* [ ] Token correctly configured
* [ ] Microphone permissions tested
* [ ] Mobile responsiveness verified
* [ ] Error handling implemented
* [ ] Performance impact assessed
* [ ] Accessibility tested

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I use both Player and SDK on the same page?">
    No, you should only use one Anam instance per page. Choose either Player or SDK based on your needs.
  </Accordion>

  <Accordion title="How do I get a share token?">
    Share tokens are generated in the Anam Lab. Create or select a persona, then
    click the share button to generate an embed token.
  </Accordion>

  <Accordion title="Can I customize the appearance?">
    **Player**: Limited customization through iframe parameters. **SDK**: More
    customization options available through JavaScript configuration.
  </Accordion>

  <Accordion title="What happens if users deny microphone access?">
    Anam will display a message prompting users to enable microphone access. Text
    input fallback is not currently available.
  </Accordion>

  <Accordion title="Is there a free tier or trial?">
    Contact [support@anam.ai](mailto:support@anam.ai) for information about trials and pricing options.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Customize Appearance" icon="palette">
    Learn how to customize colors, position, and behavior of your embed.
  </Card>

  <Card title="JavaScript API" icon="code">
    Control the embed programmatically with our JavaScript API.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track user interactions and conversation metrics.
  </Card>

  <Card title="Advanced Integration" icon="plug">
    Integrate with your existing authentication and user systems.
  </Card>
</CardGroup>


# Example Projects
Source: https://docs.anam.ai/examples/anam-examples

Anam personas in the wild

<Card icon="github" title="Anam Examples" description="Example projects" href="https://github.com/anam-org/anam-examples">
  If you're looking for inspiration to help you get started, take a look at some of our example
  projects in github.
</Card>


# Basic application
Source: https://docs.anam.ai/examples/basic-app

Take your first steps with Anam

The Anam API provides a simple interface for implementing digital AI personas within your web applications. This guide will walk you through the process of setting up a minimal example of an interactive AI persona. By the end, you'll have a working persona that can have real-time conversations in your web application.

## Prerequisites

* **Node.js** (version 16 or higher) and **npm** installed on your system
* Basic knowledge of JavaScript
* An Anam API key ([get one here](/api-key))
* A microphone and speakers for voice interaction

## Project Setup

This quickstart creates a minimal web application with three main files organized in a simple project structure:

```
my-anam-app/
├── server.js          # Express server for secure API key handling
├── package.json       # Node.js dependencies
├── public/            # Static files served to the browser
│   ├── index.html     # Main HTML page with video element
│   └── script.js      # Client-side JavaScript for persona control
└── .env               # Environment variables (optional)
```

<Steps>
  <Step title="Create project directory">
    ```bash  theme={"dark"}
    mkdir my-anam-app
    cd my-anam-app
    ```
  </Step>

  <Step title="Initialize Node.js project">
    `bash npm init -y ` This creates a `package.json` file for managing dependencies.
  </Step>

  <Step title="Create public directory">
    `bash mkdir public `

    <Info>
      The `public` folder will contain your HTML and JavaScript files that are served to the browser.
    </Info>
  </Step>

  <Step title="Install dependencies">
    `bash npm install express dotenv `

    <Info>
      We're installing Express for the server and dotenv for environment variable management. The Anam SDK will be loaded directly from a CDN in the browser.
    </Info>
  </Step>

  <Step title="Create environment file">
    Create a `.env` file in your project root to store your API key securely:

    ```bash .env theme={"dark"}
    ANAM_API_KEY=your-api-key-here
    ```

    <Warning>
      Replace `your-api-key-here` with your actual Anam API key. Never commit this file to version control.
    </Warning>
  </Step>
</Steps>

## Step 1: Set up your server

For this example, we'll create a basic Express server to handle session token generation. In a real application, you should integrate this functionality into your existing backend service.

```javascript server.js (Node.js example) theme={"dark"}
require("dotenv").config();
const express = require("express");
const app = express();

app.use(express.json());
app.use(express.static("public"));

app.post("/api/session-token", async (req, res) => {
  try {
    const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
      },
      body: JSON.stringify({
        personaConfig: {
          name: "Cara",
          avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
          voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
          llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
          systemPrompt:
            "You are Cara, a helpful customer service representative. Be friendly and concise in your responses.",
        },
      }),
    });

    const data = await response.json();
    res.json({ sessionToken: data.sessionToken });
  } catch (error) {
    res.status(500).json({ error: "Failed to create session" });
  }
});

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});
```

<Info>
  The server endpoint exchanges your API key and persona configuration for a temporary session token that the client can safely use. This token has limited scope and expires, providing an additional security layer.
</Info>

## Step 2: Set up your HTML

Create a simple HTML page with a video element for the persona and controls to start/stop the chat:

```html index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My First Anam Persona</title>
  </head>
  <body>
    <div style="text-align: center; padding: 20px;">
      <h1>Chat with Cara</h1>
      <video
        id="persona-video"
        autoplay
        playsinline
        style="max-width: 100%; border-radius: 8px;"
      ></video>
      <div style="margin-top: 20px;">
        <button id="start-button">Start Chat</button>
        <button id="stop-button" disabled>Stop Chat</button>
      </div>
    </div>
    <script type="module" src="script.js"></script>
  </body>
</html>
```

## Step 3: Initialize the Anam client

Create the client-side JavaScript to control your persona connection:

```javascript script.js theme={"dark"}
import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById("start-button");
const stopButton = document.getElementById("stop-button");
const videoElement = document.getElementById("persona-video");

async function startChat() {
  try {
    startButton.disabled = true;

    // Get session token from your server
    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    // Create the Anam client
    anamClient = createClient(sessionToken);

    // Start streaming to the video element
    await anamClient.streamToVideoElement("persona-video");

    // Update button states
    startButton.disabled = true;
    stopButton.disabled = false;

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
  }
}

function stopChat() {
  if (anamClient) {
    // Disconnect the client
    anamClient.stopStreaming();
    anamClient = null;

    // Clear video element
    videoElement.srcObject = null;

    // Update button states
    startButton.disabled = false;
    stopButton.disabled = true;

    console.log("Chat stopped.");
  }
}

// Add event listeners
startButton.addEventListener("click", startChat);
stopButton.addEventListener("click", stopChat);
```

## Step 4: Run your application

1. Start your server:

```bash  theme={"dark"}
node server.js
```

2. Open [http://localhost:3000](http://localhost:3000) in your browser
3. Click "Start Chat" to begin your conversation with Cara!

<Check>
  You should see Cara appear in the video element and be ready to chat through voice interaction.
</Check>

## What's happening?

1. **Server-Side Security**: Your server safely exchanges your API key for a session token, keeping credentials secure
2. **Client Connection**: The SDK creates a WebRTC connection for real-time video streaming when you start the chat
3. **Voice Interaction**: Cara listens for your voice input and responds with synchronized audio and video
4. **Connection Control**: Start and stop buttons give you full control over when the persona is active

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/concepts/personas">
    Learn how personas, tokens, and streaming work
  </Card>

  <Card title="Customize Your Persona" icon="paintbrush" href="/concepts/personas">
    Change appearance, voice, and behavior
  </Card>

  <Card title="Handle Events" icon="bolt" href="/concepts/events">
    React to conversation events and user interactions
  </Card>

  <Card title="Production Setup" icon="shield" href="/production">
    Deploy your persona securely at scale
  </Card>
</CardGroup>

## Common Issues

**Persona not appearing?**

* Check that your API key is set correctly
* Ensure the video element has autoplay and playsinline attributes
* Check browser console for errors

**No audio?**

* Make sure your browser allows autoplay with sound
* Check that the user has interacted with the page first (clicking "Start Chat" counts)

**Connection issues?**

* Verify your server can reach api.anam.ai
* Check network connectivity and firewall settings


# Creating Smarter Personas
Source: https://docs.anam.ai/examples/creating-smarter-personas

Learn how to create personas that can understand and respond to your customers.

When [creating a persona](/concepts/personas/create-your-own/create-your-own-lab) the system prompt you choose defines how the persona will respond to your customers. Choosing an effective system prompt is crucial for delivering meaningful interactions with your users. When designing your system prompt focus on crafting a well-defined identity, personality and communication style.
Here's some tips on how to create smarter, more effective personas:

## Defining Core Identity

Your persona's identity is the foundation of its interactions. Start by clearly establishing:

* What specific role your persona will fulfill (customer support, sales assistant, product specialist, etc.)
* Areas of expertise relevant to your business
* The types of interactions it should handle
* Clear boundaries of its capabilities and limitations

For example, if you're creating a customer support persona for a software company, you might define it as:

"A knowledgeable technical support specialist focused on helping users troubleshoot our software products, equipped to handle basic to intermediate technical issues, while suggesting alternate support channels with human support staff for more complex problems."

## Personality and Communication Style

The way your persona communicates is just as important as what it communicates. Consider:

* Tone of voice (professional, friendly, casual)
* Communication style (concise vs detailed, formal vs informal)
* How it should address users
* Cultural sensitivity and adaptability

Your persona should maintain consistency in its communication style while adapting to the user's needs. For instance, it might use a friendly yet professional tone:

"I understand you're having trouble with the login process. Let me help you resolve this step by step. First, could you tell me what error message you're seeing?"

## Handling Different Scenarios

Guide your persona on how to handle various situations:

When facing uncertainty:
"If you're not completely sure about something, acknowledge it and ask for clarification. It's better to say 'I want to make sure I understand your question correctly' than to provide incorrect information."

For complex requests:
"Break down complex problems into smaller, manageable steps. Guide users through the process gradually, confirming understanding at each step."

## Response Structure

Help your persona maintain effective conversations by instructing it to keep responses concise and relevant and to break down complex information into digestible parts.

## Testing and Refinement

Personas can be sensitive to even small changes in the system prompt. If you notice your persona is not performing as expected, try small incremental changes to the system prompt.

## Best Practices

1. Start simple and expand capabilities gradually.
2. Use example interactions in your system prompt.
3. Collect and incorporate user feedback.

Creating an effective persona is an iterative process. Start with these fundamentals and refine based on your specific needs and user interactions. Monitor performance and adjust as needed.


# Custom LLM (client-side)
Source: https://docs.anam.ai/examples/custom-llm

Build your own AI conversation logic with OpenAI, Llama, and other language models

Learn how to bypass Anam's built-in language models and integrate your own custom LLM for complete control over conversation logic. This guide uses OpenAI as an example, but the pattern works with any LLM provider (Anthropic, Cohere, Hugging Face, Ollama, etc.).

<Note>
  **New Feature**: Anam now supports [server-side custom LLMs](/concepts/custom-llms) where we
  handle the LLM calls for you, improving latency and simplifying development. This guide shows the
  client-side approach where you manage the LLM calls yourself.
</Note>

## What You'll Build

By the end of this guide, you'll have a sophisticated persona application featuring:

* **Custom AI Brain** powered by your own language model (OpenAI GPT-4o-mini)
* **Streaming Responses** with real-time text-to-speech conversion
* **Turn-taking Management** that handles conversation flow naturally
* **Message History Integration** that maintains conversation context
* **Production Security** with proper API key handling and rate limiting
* **Error Handling & Recovery** for robust user experience
* **Modern UI/UX** with loading states and real-time feedback

<Tip>
  After completing the initial setup (Steps 1-4), you can extend this foundation by adding features
  like conversation memory, different LLM providers, custom system prompts, or specialized AI
  behaviors.
</Tip>

<Info>
  This guide uses **OpenAI's GPT-4o-mini** as an example custom LLM for demonstration purposes. In
  your actual application, you would replace the OpenAI integration with calls to your specific LLM
  provider. The core integration pattern remains the same regardless of your LLM choice.
</Info>

## Prerequisites

* **Node.js** (version 18 or higher) and **npm** installed
* Understanding of modern JavaScript/TypeScript and streaming APIs
* An Anam API key ([get one here](/api-key))
* An OpenAI API key ([get one here](https://platform.openai.com/api-keys))
* Basic knowledge of Express.js and modern web development
* A microphone and speakers for voice interaction

## Understanding the Custom LLM Flow

Before diving into the implementation, it's important to understand how custom LLM integration works with Anam personas. Regardless of your custom LLM provider, the implementation pattern will always follow these steps:

<Steps>
  <Step title="Disable Default Brain">
    The `llmId: "CUSTOMER_CLIENT_V1"` setting in the session token request disables Anam's default AI, allowing you to handle all conversation logic.
  </Step>

  <Step title="Listen for User Input">
    The `MESSAGE_HISTORY_UPDATED` event fires when the user finishes speaking, providing the complete
    conversation history including the new user message.
  </Step>

  <Step title="Process with Custom LLM">
    Your server endpoint receives the conversation history and generates a streaming response using
    your chosen LLM (OpenAI in this example).
  </Step>

  <Step title="Stream to Persona">
    The LLM response is streamed back to the client and forwarded to the persona using `createTalkMessageStream()` for natural text-to-speech conversion.
  </Step>
</Steps>

Using these core concepts, we'll build a simple web application that allows you to chat with your custom LLM-powered persona.

## Basic Setup

Let's start by building the foundation with custom LLM integration. This setup creates a web application with four main components:

```
anam-custom-llm-app/
├── server.js              # Express server with streaming LLM endpoint
├── package.json           # Node.js dependencies
├── public/                # Static files served to the browser
│   ├── index.html         # Main HTML page with video element
│   └── script.js          # Client-side JavaScript for persona control
└── .env                   # Environment variables
```

<Steps>
  <Step title="Create project directory">
    ```bash  theme={"dark"}
    mkdir anam-custom-llm-app
    cd anam-custom-llm-app
    ```
  </Step>

  <Step title="Initialize Node.js project">
    `bash npm init -y ` This creates a `package.json` file for managing dependencies.
  </Step>

  <Step title="Create public directory">
    `bash mkdir public `

    <Info>
      The `public` folder will contain your HTML and JavaScript files that are served to the browser.
    </Info>
  </Step>

  <Step title="Install dependencies">
    `bash npm install express dotenv openai `

    <Info>
      We're installing Express for the server, dotenv for environment variables, and the OpenAI SDK
      for custom LLM integration. The Anam SDK will be loaded directly from a CDN in the browser.
    </Info>
  </Step>

  <Step title="Configure environment variables">
    Create a `.env` file in your project root to store your API keys securely:

    ```bash .env theme={"dark"}
    ANAM_API_KEY=your-anam-api-key-here
    OPENAI_API_KEY=your-openai-api-key-here
    ```

    <Warning>
      Replace the placeholder values with your actual API keys. Never commit this file to version control.
    </Warning>
  </Step>
</Steps>

### Step 1: Set up your server with LLM streaming

Create an Express server that handles both session token generation and LLM streaming:

```javascript server.js theme={"dark"}
require('dotenv').config();
const express = require('express');
const OpenAI = require('openai');

const app = express();

// Initialize OpenAI client
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

app.use(express.json());
app.use(express.static('public'));

// Session token endpoint with custom brain configuration
app.post('/api/session-token', async (req, res) => {
  try {
    const response = await fetch('https://api.anam.ai/v1/auth/session-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
      },
      body: JSON.stringify({
        personaConfig: {
          name: 'Cara',
          avatarId: '30fa96d0-26c4-4e55-94a0-517025942e18',
          voiceId: '6bfbe25a-979d-40f3-a92b-5394170af54b',
          // This disables Anam's default brain and enables custom LLM integration
          llmId: 'CUSTOMER_CLIENT_V1',
        },
      }),
    });

    const data = await response.json();
    res.json({ sessionToken: data.sessionToken });
  } catch (error) {
    console.error('Session token error:', error);
    res.status(500).json({ error: 'Failed to create session' });
  }
});

// Custom LLM streaming endpoint
app.post('/api/chat-stream', async (req, res) => {
  try {
    const { messages } = req.body;

    // Create a streaming response from OpenAI
    const stream = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        {
          role: 'system',
          content:
            'You are Cara, a helpful AI assistant. Be friendly, concise, and conversational in your responses. Keep responses under 100 words unless specifically asked for detailed information.',
        },
        ...messages,
      ],
      stream: true,
      temperature: 0.7,
    });

    // Set headers for streaming response
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    // Process the OpenAI stream and forward to client
    for await (const chunk of stream) {
      const content = chunk.choices[0]?.delta?.content || '';
      if (content) {
        // Send each chunk as JSON
        res.write(JSON.stringify({ content }) + '\n');
      }
    }

    res.end();
  } catch (error) {
    console.error('LLM streaming error:', error);
    res.status(500).json({ error: 'An error occurred while streaming response' });
  }
});

app.listen(8000, () => {
  console.log('Server running on http://localhost:8000');
  console.log('Custom LLM integration ready!');
});
```

{" "}

<Info>
  The key difference here is setting `llmId: "CUSTOMER_CLIENT_V1"` which disables Anam's default AI
  and enables custom LLM integration. The `/api/chat-stream` endpoint handles the actual AI
  conversation logic.
</Info>

### Step 2: Set up your HTML

Create a simple HTML page with video element and conversation display:

```html public/index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Custom LLM Persona - Anam Integration</title>
  </head>
  <body style="font-family: Arial, sans-serif; margin: 20px; background-color: #f5f5f5;">
    <div style="max-width: 1000px; margin: 0 auto;">
      <h1 style="text-align: center; color: #333;">🤖 Custom LLM Persona</h1>

      <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-bottom: 20px;">
        <!-- Persona Panel -->
        <div
          style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);"
        >
          <video
            id="persona-video"
            autoplay
            playsinline
            muted
            style="width: 100%; max-width: 400px; border-radius: 8px; background: #000; display: block; margin: 0 auto;"
          ></video>

          <div id="status" style="text-align: center; margin: 15px 0; font-weight: bold;">
            Ready to connect
          </div>

          <div style="text-align: center;">
            <button
              id="start-button"
              style="background: #007bff; color: white; border: none; padding: 10px 20px; border-radius: 4px; cursor: pointer; margin: 5px; font-size: 14px;"
            >
              Start Conversation
            </button>
            <button
              id="stop-button"
              disabled
              style="background: #dc3545; color: white; border: none; padding: 10px 20px; border-radius: 4px; cursor: pointer; margin: 5px; font-size: 14px; opacity: 0.6;"
            >
              Stop Conversation
            </button>
          </div>
        </div>

        <!-- Chat Panel -->
        <div
          style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);"
        >
          <h2 style="margin-top: 0; color: #333;">💬 Conversation</h2>
          <div
            id="chat-history"
            style="height: 400px; overflow-y: auto; padding: 10px; border: 1px solid #ddd; border-radius: 4px; background: #fafafa;"
          >
            <div style="font-style: italic; color: #666; text-align: center;">
              Start a conversation to see your chat history...
            </div>
          </div>
        </div>
      </div>
    </div>

    <script type="module" src="script.js"></script>
  </body>
</html>
```

### Step 3: Implement the client-side custom LLM integration

Create the client-side JavaScript that handles the custom LLM integration:

```javascript public/script.js theme={"dark"}
import { createClient } from 'https://esm.sh/@anam-ai/js-sdk@latest';
import { AnamEvent } from 'https://esm.sh/@anam-ai/js-sdk@latest/dist/module/types';

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById('start-button');
const stopButton = document.getElementById('stop-button');
const videoElement = document.getElementById('persona-video');
const statusElement = document.getElementById('status');
const chatHistory = document.getElementById('chat-history');

// Status management
function updateStatus(message, type = 'normal') {
  statusElement.textContent = message;
  const colors = {
    loading: '#f39c12',
    connected: '#28a745',
    error: '#dc3545',
    normal: '#333',
  };
  statusElement.style.color = colors[type] || colors.normal;
}

// Chat history management
function updateChatHistory(messages) {
  if (!chatHistory) return;

  chatHistory.innerHTML = '';

  if (messages.length === 0) {
    chatHistory.innerHTML =
      '<div style="font-style: italic; color: #666; text-align: center;">Start a conversation to see your chat history...</div>';
    return;
  }

  messages.forEach((message) => {
    const messageDiv = document.createElement('div');
    const isUser = message.role === 'user';
    messageDiv.style.cssText = `
      margin-bottom: 10px; 
      padding: 8px 12px; 
      border-radius: 8px; 
      max-width: 85%; 
      background: ${isUser ? '#e3f2fd' : '#f1f8e9'};
      ${isUser ? 'margin-left: auto; text-align: right;' : ''}
    `;
    messageDiv.innerHTML = `<strong>${isUser ? 'You' : 'Cara'}:</strong> ${message.content}`;
    chatHistory.appendChild(messageDiv);
  });

  // Scroll to bottom
  chatHistory.scrollTop = chatHistory.scrollHeight;
}

// Custom LLM response handler
async function handleUserMessage(messageHistory) {
  // Only respond to user messages
  if (messageHistory.length === 0 || messageHistory[messageHistory.length - 1].role !== 'user') {
    return;
  }

  if (!anamClient) return;

  try {
    console.log('🧠 Getting custom LLM response for:', messageHistory);

    // Convert Anam message format to OpenAI format
    const openAIMessages = messageHistory.map((msg) => ({
      role: msg.role === 'user' ? 'user' : 'assistant',
      content: msg.content,
    }));

    // Create a streaming talk session
    const talkStream = anamClient.createTalkMessageStream();

    // Call our custom LLM streaming endpoint
    const response = await fetch('/api/chat-stream', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages: openAIMessages }),
    });

    if (!response.ok) {
      throw new Error(`LLM request failed: ${response.status}`);
    }

    const reader = response.body?.getReader();
    if (!reader) {
      throw new Error('Failed to get response stream reader');
    }

    const textDecoder = new TextDecoder();
    console.log('🎤 Streaming LLM response to persona...');

    // Stream the response chunks to the persona
    while (true) {
      const { done, value } = await reader.read();

      if (done) {
        console.log('✅ LLM streaming complete');
        if (talkStream.isActive()) {
          talkStream.endMessage();
        }
        break;
      }

      if (value) {
        const text = textDecoder.decode(value);
        const lines = text.split('\n').filter((line) => line.trim());

        for (const line of lines) {
          try {
            const data = JSON.parse(line);
            if (data.content && talkStream.isActive()) {
              talkStream.streamMessageChunk(data.content, false);
            }
          } catch (parseError) {
            // Ignore parse errors in streaming
          }
        }
      }
    }
  } catch (error) {
    console.error('❌ Custom LLM error:', error);
    if (anamClient) {
      anamClient.talk(
        "I'm sorry, I encountered an error while processing your request. Please try again."
      );
    }
  }
}

async function startConversation() {
  try {
    startButton.disabled = true;
    updateStatus('Connecting...', 'loading');

    // Get session token from server
    const response = await fetch('/api/session-token', {
      method: 'POST',
    });

    if (!response.ok) {
      throw new Error('Failed to get session token');
    }

    const { sessionToken } = await response.json();

    // Create Anam client
    anamClient = createClient(sessionToken);

    // Set up event listeners
    anamClient.addListener(AnamEvent.SESSION_READY, () => {
      console.log('🎯 Session ready!');
      updateStatus('Connected - Custom LLM active', 'connected');
      startButton.disabled = true;
      stopButton.disabled = false;

      // Send initial greeting
      anamClient.talk("Hello! I'm Cara, powered by a custom AI brain. How can I help you today?");
    });

    anamClient.addListener(AnamEvent.CONNECTION_CLOSED, () => {
      console.log('🔌 Connection closed');
      stopConversation();
    });

    // This is the key event for custom LLM integration
    anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, handleUserMessage);

    // Update chat history in real-time
    anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
      updateChatHistory(messages);
    });

    // Handle stream interruptions
    anamClient.addListener(AnamEvent.TALK_STREAM_INTERRUPTED, () => {
      console.log('🛑 Talk stream interrupted by user');
    });

    // Start streaming to video element
    await anamClient.streamToVideoElement('persona-video');

    console.log('🚀 Custom LLM persona started successfully!');
  } catch (error) {
    console.error('❌ Failed to start conversation:', error);
    updateStatus(`Error: ${error.message}`, 'error');
    startButton.disabled = false;
  }
}

function stopConversation() {
  if (anamClient) {
    anamClient.stopStreaming();
    anamClient = null;
  }

  // Reset UI
  videoElement.srcObject = null;
  updateChatHistory([]);
  updateStatus('Disconnected', 'normal');
  startButton.disabled = false;
  stopButton.disabled = true;

  console.log('🛑 Conversation stopped');
}

// Add event listeners
startButton.addEventListener('click', startConversation);
stopButton.addEventListener('click', stopConversation);

// Cleanup on page unload
window.addEventListener('beforeunload', stopConversation);
```

### Step 4: Test your custom LLM integration

1. Start your server:

```bash  theme={"dark"}
node server.js
```

2. Open [http://localhost:8000](http://localhost:8000) in your browser

3. Click "Start Conversation" to begin chatting with your custom LLM-powered persona!

<Check>
  You should see Cara appear and greet you, powered by your custom OpenAI integration. Try having a
  conversation - your voice will be transcribed, sent to OpenAI's GPT-4o-mini, and the response will
  be streamed back through the persona's voice and video.
</Check>

## Advanced Features

### Enhanced Error Handling

Add robust error handling to improve user experience:

```javascript  theme={"dark"}
// Add this to your script.js handleUserMessage function
async function handleUserMessage(messageHistory) {
  if (messageHistory.length === 0 || messageHistory[messageHistory.length - 1].role !== 'user') {
    return;
  }

  if (!anamClient) return;

  const maxRetries = 3;
  let retryCount = 0;

  while (retryCount < maxRetries) {
    try {
      // ... existing LLM call code ...
      return; // Success, exit retry loop
    } catch (error) {
      retryCount++;
      console.error(`❌ Custom LLM error (attempt ${retryCount}):`, error);

      if (retryCount >= maxRetries) {
        // Final fallback response
        if (anamClient) {
          anamClient.talk(
            "I'm experiencing some technical difficulties. Please try rephrasing your question or try again in a moment."
          );
        }
      } else {
        // Wait before retry
        await new Promise((resolve) => setTimeout(resolve, 1000 * retryCount));
      }
    }
  }
}
```

## What You've Built

Congratulations! You've successfully integrated a custom language model with Anam's persona system. Your application now features:

**Custom AI Brain**: Complete control over your persona's intelligence using OpenAI's GPT-4o-mini, with the ability to customize personality, knowledge, and behavior.

**Real-time Streaming**: Responses stream naturally from your LLM through the persona's voice, creating fluid conversations without noticeable delays.

**Conversation Context**: Full conversation history is maintained and provided to your LLM for contextually aware responses.

**Production Ready**: Error handling, retry logic, and proper API key management make this suitable for real-world deployment.

**Extensible Architecture**: The modular design allows you to easily swap LLM providers, add custom logic, or integrate with other AI services.

## Troubleshooting

<AccordionGroup>
  <Accordion title="LLM Responses Not Streaming">
    **Symptoms**: Persona doesn't speak or responses are delayed

    **Solutions**:

    * Verify OpenAI API key is correctly configured
      * Check that `llmId: "CUSTOMER_CLIENT_V1"` is set in session token
    * Ensure `MESSAGE_HISTORY_UPDATED` event listener is properly connected
    * Check browser console for JavaScript errors
    * Verify the `/api/chat-stream` endpoint is responding correctly
  </Accordion>

  <Accordion title="Streaming Performance Issues">
    **Symptoms**: Slow or choppy persona responses

    **Solutions**:

    * Optimize LLM model parameters (reduce max\_tokens, adjust temperature)
    * Implement response caching for common queries
    * Use faster models like `gpt-4o-mini` instead of `gpt-4`
    * Consider chunking large responses for better streaming
    * Monitor network latency and server performance
  </Accordion>
</AccordionGroup>

***


# Full application
Source: https://docs.anam.ai/examples/full-app

Build a full-featured Anam application with advanced UI/UX and event handling

Build a production-ready web application that showcases the full capabilities of Anam personas. This comprehensive guide walks you through creating an interactive AI assistant with modern UI components, real-time event handling, chat history, talk commands, and production-grade security practices.

## How to use this guide

This comprehensive guide takes an **additive approach**, covering a wide range of Anam features and implementation patterns. Each section builds upon the previous ones, allowing you to create increasingly sophisticated functionality.

<Info>
  We intentionally provide detailed, complete code examples to make integration
  with AI coding assistants seamless. Use the buttons in the top-right corner of
  this page to open the content in your preferred LLM or copy the entire guide
  for easy reference.
</Info>

<Tip>
  You likely won't need every component shown in this guide. After completing
  the initial setup (Steps 1-4), use the **right-hand navigation** to jump
  directly to the specific features you want to implement:
</Tip>

Start with the basic setup, then selectively add the advanced features that match your use case.

## What You'll Build

By the end of this guide, you'll have a sophisticated persona application featuring:

* **Modern UI/UX** with loading states, connection status, and responsive design
* **Chat History Panel** showing conversation transcripts in real-time
* **Advanced Event Handling** for connection management and user feedback
* **Talk Commands** for programmatic persona control
* **Audio Management** with mute/unmute functionality
* **Production Security** with proper authentication and rate limiting
* **Error Handling & Retry Logic** for robust user experience

## Prerequisites

* **Node.js** (version 18 or higher) and **npm** installed
* Understanding of modern JavaScript/TypeScript
* An Anam API key ([get one here](/api-key))
* Basic knowledge of Express.js and modern web development
* A microphone and speakers for voice interaction

## Basic App

Let's start by building a simple working version, then enhance it with advanced features. This foundational setup creates a minimal web application with three main files:

```
anam-production-app/
├── server.js          # Express server for secure API key handling
├── package.json       # Node.js dependencies
├── public/            # Static files served to the browser
│   ├── index.html     # Main HTML page with video element
│   └── script.js      # Client-side JavaScript for persona control
└── .env               # Environment variables
```

<Steps>
  <Step title="Create project directory">
    ```bash  theme={"dark"}
    mkdir anam-production-app
    cd anam-production-app
    ```
  </Step>

  <Step title="Initialize Node.js project">
    `bash npm init -y ` This creates a `package.json` file for managing dependencies.
  </Step>

  <Step title="Create public directory">
    `bash mkdir public `

    <Info>
      The `public` folder will contain your HTML and JavaScript files that are served to the browser.
    </Info>
  </Step>

  <Step title="Install dependencies">
    `bash npm install express dotenv `

    <Info>
      We're installing Express for the server and dotenv for environment variable management. The Anam SDK will be loaded directly from a CDN in the browser.
    </Info>
  </Step>

  <Step title="Configure environment variables">
    Create a `.env` file in your project root to store your API key securely:

    ```bash .env theme={"dark"}
    ANAM_API_KEY=your-api-key-here
    ```

    <Warning>
      Replace `your-api-key-here` with your actual Anam API key. Never commit this file to version control.
    </Warning>
  </Step>
</Steps>

### Step 1: Set up your server

Create a basic Express server to handle session token generation:

```javascript server.js theme={"dark"}
require("dotenv").config();
const express = require("express");
const app = express();

app.use(express.json());
app.use(express.static("public"));

app.post("/api/session-token", async (req, res) => {
  try {
    const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
      },
      body: JSON.stringify({
        personaConfig: {
          name: "Cara",
          avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
          voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
          llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
          systemPrompt:
            "You are Cara, a helpful AI assistant. Be friendly, concise, and helpful in your responses.",
        },
      }),
    });

    const data = await response.json();
    res.json({ sessionToken: data.sessionToken });
  } catch (error) {
    res.status(500).json({ error: "Failed to create session" });
  }
});

app.listen(8000, () => {
  console.log("Server running on http://localhost:8000");
});
```

### Step 2: Set up your HTML

Create a simple HTML page with a video element and basic controls:

```html public/index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Anam AI Assistant - Production App</title>
  </head>
  <body>
    <div style="text-align: center; padding: 20px;">
      <h1>Chat with Cara</h1>
      <video
        id="persona-video"
        autoplay
        playsinline
        style="max-width: 100%; border-radius: 8px;"
      ></video>
      <div style="margin-top: 20px;">
        <button id="start-button">Start Chat</button>
        <button id="stop-button" disabled>Stop Chat</button>
      </div>
    </div>
    <script type="module" src="script.js"></script>
  </body>
</html>
```

### Step 3: Initialize the Anam client

Create the client-side JavaScript to control your persona:

```javascript public/script.js theme={"dark"}
import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById("start-button");
const stopButton = document.getElementById("stop-button");
const videoElement = document.getElementById("persona-video");

async function startChat() {
  try {
    startButton.disabled = true;

    // Get session token from your server
    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    // Create the Anam client
    anamClient = createClient(sessionToken);

    // Start streaming to the video element
    await anamClient.streamToVideoElement("persona-video");

    // Update button states
    startButton.disabled = true;
    stopButton.disabled = false;

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
  }
}

function stopChat() {
  if (anamClient) {
    // Disconnect the client
    anamClient.stopStreaming();
    anamClient = null;

    // Clear video element
    videoElement.srcObject = null;

    // Update button states
    startButton.disabled = false;
    stopButton.disabled = true;

    console.log("Chat stopped.");
  }
}

// Add event listeners
startButton.addEventListener("click", startChat);
stopButton.addEventListener("click", stopChat);
```

### Step 4: Test your basic setup

1. Start your server:

```bash  theme={"dark"}
node server.js
```

2. Open [http://localhost:8000](http://localhost:8000) in your browser
3. Click "Start Chat" to begin your conversation!

<Check>
  You should see Cara appear in the video element and be ready to chat through
  voice interaction.
</Check>

Now that you have a working basic app, let's enhance it with production-ready features.

## Listening to events

Anam personas communicate through an event system that allows your application to respond to connection changes, conversation updates, and user interactions. Let's enhance our basic app with event handling to create a more responsive experience.

### Understanding the Event System

The Anam SDK uses an event-driven architecture where you can listen for specific events and react accordingly. Here's the process for listening to events:

<Steps>
  <Step title="Import the event types">
    Import the specific event types you want to listen to:

    ```javascript  theme={"dark"}
    import { AnamEvent } from "https://esm.sh/@anam-ai/js-sdk@latest/dist/module/types";
    ```
  </Step>

  <Step title="Define your event listener function">
    Create a function to handle the event:

    ```javascript  theme={"dark"}
    function onSessionReady() {
      console.log('Session Ready!');
      // Do something when the session is ready
    }
    ```
  </Step>

  <Step title="Add your event listener to the client">
    Register your listener function with the client:

    ```javascript  theme={"dark"}
    anamClient.addListener(AnamEvent.SESSION_READY, onSessionReady);
    ```
  </Step>
</Steps>

<Tip>
  For a full list of events, see the [Event Handling](/concepts/events)
  documentation.
</Tip>

Now let's implement this pattern in our app by adding a loading state.

### Adding a loading state

Loading states provide important user feedback during connection establishment. Let's add a simple loading indicator to our HTML:

#### Step 1: Update the UI

```html public/index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Anam AI Assistant - Production App</title>
  </head>
  <body>
    <div style="text-align: center; padding: 20px;">
      <h1>🤖 Chat with Cara</h1>

      <div id="loading-message" style="display: none;">Loading...</div>

      <video
        id="persona-video"
        autoplay
        playsinline
        style="max-width: 100%; border-radius: 8px;"
      ></video>

      <div style="margin-top: 20px;">
        <button id="start-button">Start Chat</button>
        <button id="stop-button" disabled>Stop Chat</button>
      </div>
    </div>

    <script type="module" src="script.js"></script>
  </body>
</html>
```

#### Step 2: Adding the event listener

Now let's update our JavaScript to handle the loading state by adding the following to our `script.js` file:

```javascript public/script.js {2,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,39,40,41,42,43,44} theme={"dark"}
import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";
import { AnamEvent } from "https://esm.sh/@anam-ai/js-sdk@latest/dist/module/types";

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById("start-button");
const stopButton = document.getElementById("stop-button");
const videoElement = document.getElementById("persona-video");
const loadingMessage = document.getElementById("loading-message");

function showLoadingState() {
  if (loadingMessage) {
    loadingMessage.style.display = "block";
  }
}

function hideLoadingState() {
  if (loadingMessage) {
    loadingMessage.style.display = "none";
  }
}

async function startChat() {
  try {
    startButton.disabled = true;
    showLoadingState();

    // Get session token from your server
    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    // Create the Anam client
    anamClient = createClient(sessionToken);

    // Listen for SESSION_READY event to hide loading state
    anamClient.addListener(AnamEvent.SESSION_READY, () => {
      console.log("Session is ready!");
      hideLoadingState();
      startButton.disabled = true;
      stopButton.disabled = false;
    });

    // Start streaming to the video element
    await anamClient.streamToVideoElement("persona-video");

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
    hideLoadingState();
  }
}

function stopChat() {
  if (anamClient) {
    // Disconnect the client
    anamClient.stopStreaming();
    anamClient = null;

    // Clear video element
    videoElement.srcObject = null;

    // Update button states
    startButton.disabled = false;
    stopButton.disabled = true;

    console.log("Chat stopped.");
  }
}

// Add event listeners
startButton.addEventListener("click", startChat);
stopButton.addEventListener("click", stopChat);
```

### Adding a chat history panel

A common use case for event listeners is to update the UI based on the transcription of the conversation. Let's look at how we can implement this using Anam events.

#### Understanding Message Events

Anam provides two key events for tracking conversation transcriptions:

| Event                           | Description                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `MESSAGE_HISTORY_UPDATED`       | Provides the complete conversation history each time someone finishes speaking |
| `MESSAGE_STREAM_EVENT_RECEIVED` | Provides real-time transcription updates as speech occurs                      |

Let's start with the `MESSAGE_HISTORY_UPDATED` event to build a basic chat history.

#### Step 1: Add chat history UI

First, update your HTML to include a simple chat panel:

```html public/index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Anam AI Assistant - Production App</title>
  </head>
  <body>
    <div style="text-align: center; padding: 20px;">
      <h1>🤖 Chat with Cara</h1>

      <div id="loading-message" style="display: none;">Loading...</div>

      <video
        id="persona-video"
        autoplay
        playsinline
        style="max-width: 100%; border-radius: 8px;"
      ></video>

      <!-- Chat History Panel -->
      <div
        id="chat-history"
        style="margin-top: 20px; padding: 10px; border: 1px solid #ccc; border-radius: 5px; max-height: 200px; overflow-y: auto;"
      >
        <p>Start a conversation to see your chat history</p>
      </div>

      <div style="margin-top: 20px;">
        <button id="start-button">Start Chat</button>
        <button id="stop-button" disabled>Stop Chat</button>
      </div>
    </div>

    <script type="module" src="script.js"></script>
  </body>
</html>
```

#### Step 2: Listen for updates

Now let's add the event listener to handle complete conversation updates:

```javascript public/script.js {25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,74,75,76,77,78,79,99} theme={"dark"}
import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";
import { AnamEvent } from "https://esm.sh/@anam-ai/js-sdk@latest/dist/module/types";

let anamClient = null;

// Get DOM elements
const startButton = document.getElementById("start-button");
const stopButton = document.getElementById("stop-button");
const videoElement = document.getElementById("persona-video");
const loadingMessage = document.getElementById("loading-message");
const chatHistory = document.getElementById("chat-history");

function showLoadingState() {
  if (loadingMessage) {
    loadingMessage.style.display = "block";
  }
}

function hideLoadingState() {
  if (loadingMessage) {
    loadingMessage.style.display = "none";
  }
}

function updateChatHistory(messages) {
  if (!chatHistory) return;
  // Clear existing content
  chatHistory.innerHTML = "";
  if (messages.length === 0) {
    chatHistory.innerHTML =
      "<p>Start a conversation to see your chat history</p>";
    return;
  }
  // Add each message to the chat history
  messages.forEach((message) => {
    const messageDiv = document.createElement("div");
    messageDiv.style.marginBottom = "10px";
    messageDiv.style.padding = "5px";
    messageDiv.style.borderRadius = "5px";
    if (message.role === "user") {
      messageDiv.style.backgroundColor = "#e3f2fd";
      messageDiv.innerHTML = `<strong>You:</strong> ${message.content}`;
    } else {
      messageDiv.style.backgroundColor = "#f1f8e9";
      messageDiv.innerHTML = `<strong>Cara:</strong> ${message.content}`;
    }
    chatHistory.appendChild(messageDiv);
  });
  // Scroll to bottom
  chatHistory.scrollTop = chatHistory.scrollHeight;
}

async function startChat() {
  try {
    startButton.disabled = true;
    showLoadingState();

    // Get session token from your server
    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    // Create the Anam client
    anamClient = createClient(sessionToken);

    // Listen for SESSION_READY event to hide loading state
    anamClient.addListener(AnamEvent.SESSION_READY, () => {
      console.log("Session is ready!");
      hideLoadingState();
      startButton.disabled = true;
      stopButton.disabled = false;
    });

    // Listen for MESSAGE_HISTORY_UPDATED to update chat history
    anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
      console.log("Conversation updated:", messages);
      updateChatHistory(messages);
    });

    // Start streaming to the video element
    await anamClient.streamToVideoElement("persona-video");

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
    hideLoadingState();
  }
}

function stopChat() {
  if (anamClient) {
    // Disconnect the client
    anamClient.stopStreaming();
    anamClient = null;

    // Clear video element and chat history
    videoElement.srcObject = null;
    updateChatHistory([]);

    // Update button states
    startButton.disabled = false;
    stopButton.disabled = true;

    console.log("Chat stopped.");
  }
}

// Add event listeners
startButton.addEventListener("click", startChat);
stopButton.addEventListener("click", stopChat);
```

<Info>
  The `MESSAGE_HISTORY_UPDATED` event provides an array of message objects with
  `role` ("user" or "assistant") and `content` properties. This gives you the
  complete conversation transcript each time someone finishes speaking.
</Info>

#### Step 3: Add real-time transcription

Now let's enhance the experience by showing live transcription as the persona speaks using the `MESSAGE_STREAM_EVENT_RECEIVED` event:

```html  theme={"dark"}
<!-- Add this to your HTML after the chat history -->
<div
  id="live-transcript"
  style="margin-top: 10px; padding: 10px; background-color: #e6e0ff; border-radius: 5px;"
>
  <strong>Persona Live:</strong> <span id="transcript-text"></span>
</div>
```

And update your JavaScript to handle real-time events:

```javascript  theme={"dark"}
// Add this event listener inside your startChat function after the MESSAGE_HISTORY_UPDATED listener

// Listen for real-time transcription events
anamClient.addListener(AnamEvent.MESSAGE_STREAM_EVENT_RECEIVED, (event) => {
  const liveTranscript = document.getElementById("live-transcript");
  const transcriptText = document.getElementById("transcript-text");

  console.log("event", event);

  if (event.role === "persona") {
    // Show persona speaking in real-time
    if (liveTranscript && transcriptText) {
      transcriptText.textContent = transcriptText.textContent + event.content;
    }
  } else if (event.role === "user") {
    // clear the persona live transcript when the user speaks
    if (liveTranscript && transcriptText) {
      transcriptText.textContent = "";
    }
  }
});
```

<Tip>
  The `MESSAGE_STREAM_EVENT_RECEIVED` event fires continuously as speech is
  being processed. Use `event.role` to distinguish between 'persona' (AI
  speaking) and 'user' (user speaking) events.
</Tip>

<Check>
  Your app now displays both complete conversation history and real-time
  transcription as the persona speaks!
</Check>

## Sending commands

Beyond voice interaction, you can programmatically send messages to your persona using the talk command. This is useful for creating interactive experiences, automated workflows, or custom UI controls.

### Using the talk command

The talk command allows you to send text messages that the persona will speak directly. This can be used to instruct the persona to say something in response to a user action other than voice input, such as a button click or when certain UI elements are shown on screen.

You can send a talk command by calling the `talk` method on the Anam client during a session.

```javascript  theme={"dark"}
anamClient.talk("Hello, how are you?");
```

Let's use this to add a talk command UI to our app.

#### Step 1: Update the UI

First, update your HTML to include a text input and send button

```html public/index.html theme={"dark"}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Anam AI Assistant - Production App</title>
  </head>
  <body>
    <div style="text-align: center; padding: 20px;">
      <h1>🤖 Chat with Cara</h1>

      <div id="loading-message" style="display: none;">Loading...</div>

      <video
        id="persona-video"
        autoplay
        playsinline
        style="max-width: 100%; border-radius: 8px;"
      ></video>

      <!-- Chat History Panel -->
      <div
        id="chat-history"
        style="margin-top: 20px; padding: 10px; border: 1px solid #ccc; border-radius: 5px; max-height: 200px; overflow-y: auto;"
      >
        <p>Start a conversation to see your chat history</p>
      </div>

      <!-- Live Transcript -->
      <div
        id="live-transcript"
        style="margin-top: 10px; padding: 10px; background-color: #e6e0ff; border-radius: 5px;"
      >
        <strong>Persona Live:</strong> <span id="transcript-text"></span>
      </div>

      <!-- Talk Command Panel -->
      <div
        style="margin-top: 20px; padding: 15px; border: 1px solid #ccc; border-radius: 5px;"
      >
        <h3 style="margin: 0 0 10px 0;">💬 Send Message</h3>
        <div style="display: flex; gap: 10px; align-items: flex-end;">
          <textarea
            id="message-input"
            placeholder="Type a message for Cara to respond to..."
            rows="3"
            style="flex: 1; padding: 10px; border: 1px solid #ddd; border-radius: 4px; font-family: inherit;"
          ></textarea>
          <button
            id="send-message"
            disabled
            style="padding: 10px 20px; border: none; border-radius: 4px; background: #4CAF50; color: white; cursor: pointer;"
          >
            Send Message
          </button>
        </div>
      </div>

      <div style="margin-top: 20px;">
        <button id="start-button">Start Chat</button>
        <button id="stop-button" disabled>Stop Chat</button>
      </div>
    </div>

    <script type="module" src="script.js"></script>
  </body>
</html>
```

#### Step 2: Add the code

Now let's add the code to our `script.js` file to send the command to the persona

```javascript public/script.js theme={"dark"}
// Add these functions to your existing script.js file

async function sendTalkMessage() {
  const messageInput = document.getElementById("message-input");
  const sendButton = document.getElementById("send-message");

  if (!anamClient || !messageInput) return;

  const message = messageInput.value.trim();
  if (!message) {
    alert("Please enter a message");
    return;
  }

  try {
    sendButton.disabled = true;
    sendButton.textContent = "Sending...";

    // Send the message to the persona
    await anamClient.talk(message);

    // Clear the input
    messageInput.value = "";
  } catch (error) {
    console.error("Failed to send message:", error);
    alert("Failed to send message. Please try again.");
  } finally {
    sendButton.disabled = false;
    sendButton.textContent = "Send Message";
  }
}

function updateTalkControls(connected) {
  const sendButton = document.getElementById("send-message");
  const messageInput = document.getElementById("message-input");

  if (sendButton) {
    sendButton.disabled = !connected;
    sendButton.style.opacity = connected ? "1" : "0.5";
  }

  if (messageInput) {
    messageInput.disabled = !connected;
    messageInput.placeholder = connected
      ? "Type a message for Cara to respond to..."
      : "Connect to start chatting...";
  }
}

// Update your startChat function to enable talk controls
async function startChat() {
  try {
    startButton.disabled = true;
    showLoadingState();

    const response = await fetch("/api/session-token", {
      method: "POST",
    });
    const { sessionToken } = await response.json();

    anamClient = createClient(sessionToken);

    anamClient.addListener(AnamEvent.SESSION_READY, () => {
      console.log("Session is ready!");
      hideLoadingState();
      startButton.disabled = true;
      stopButton.disabled = false;
      updateTalkControls(true); // Enable talk controls
    });

    anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
      console.log("Conversation updated:", messages);
      updateChatHistory(messages);
    });

    anamClient.addListener(AnamEvent.MESSAGE_STREAM_EVENT_RECEIVED, (event) => {
      const liveTranscript = document.getElementById("live-transcript");
      const transcriptText = document.getElementById("transcript-text");

      if (event.role === "persona") {
        if (liveTranscript && transcriptText) {
          transcriptText.textContent =
            transcriptText.textContent + event.content;
        }
      } else if (event.role === "user") {
        if (liveTranscript && transcriptText) {
          transcriptText.textContent = "";
        }
      }
    });

    await anamClient.streamToVideoElement("persona-video");

    console.log("Chat started successfully!");
  } catch (error) {
    console.error("Failed to start chat:", error);
    startButton.disabled = false;
    hideLoadingState();
  }
}

// Add event listeners for talk functionality
document.addEventListener("DOMContentLoaded", () => {
  const sendButton = document.getElementById("send-message");
  const messageInput = document.getElementById("message-input");

  if (sendButton) {
    sendButton.addEventListener("click", sendTalkMessage);
  }

  if (messageInput) {
    // Send message with Enter key (Shift+Enter for new line)
    messageInput.addEventListener("keydown", (e) => {
      if (e.key === "Enter" && !e.shiftKey) {
        e.preventDefault();
        sendTalkMessage();
      }
    });
  }
});
```

## Advanced Stream Management

For applications that require more control over audio and video streams, you have two main approaches for customizing the streaming behavior:

1. **Custom Input Streams**: Pass your own audio input to `streamToVideoElement`
2. **Output Stream Capture**: Use `stream()` to capture and process persona output

### Custom Input Streams

The `streamToVideoElement()` method accepts an optional audio input stream, allowing you to process or record user audio before sending it to the persona:

```javascript  theme={"dark"}
// Get and potentially process user audio
const userInputStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
});

// Start recording user input
const userRecorder = new MediaRecorder(userInputStream);
userRecorder.start();

// Use the same stream for persona input
await anamClient.streamToVideoElement("persona-video", userInputStream);
```

This approach is useful when you want to:

* Record user audio input
* Apply audio filters or effects to user input
* Monitor user audio levels
* Handle custom microphone setups

### Output Stream Capture

For capturing and processing the persona's output (video and audio), use the `stream()` method which returns the raw output streams:

```javascript  theme={"dark"}
const userInputStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
});
const [videoStream] = await anamClient.stream(userInputStream);

// Now you have full control over the output stream
videoElement.srcObject = videoStream;

// Extract audio for separate processing
const audioTracks = videoStream.getAudioTracks();
const personaAudioStream = new MediaStream(audioTracks);
```

This approach enables:

* Recording persona video and audio output
* Custom video rendering and effects
* Audio analysis and processing
* Streaming to multiple destinations

## What You've Built

Congratulations! You've built a comprehensive Anam application that demonstrates both basic and advanced stream management capabilities. Your application now includes the core patterns needed for building production persona experiences: secure authentication, event-driven updates, real-time communication, programmatic control, and advanced media stream handling.

**Core Persona Functionality**: A complete WebRTC-based streaming connection that enables natural voice conversations with an AI persona, including video rendering and bidirectional audio communication.

**Event-Driven Architecture**: Robust event handling that responds to session state changes, connection events, and conversation updates in real-time using the Anam SDK's event system.

**Live Conversation Tracking**: Real-time transcription display using `MESSAGE_STREAM_EVENT_RECEIVED` events that shows what the persona is saying as they speak, plus complete conversation history through `MESSAGE_HISTORY_UPDATED` events.

**Programmatic Control**: Talk command functionality that allows you to send text messages directly to the persona, enabling you to react to user interactions and trigger automated responses.

**Session Management**: Secure server-side session token generation that properly handles API key protection and provides temporary access tokens for client-side connections.

**Loading State Management**: Responsive loading indicators that use the `SESSION_READY` event to provide proper user feedback during connection establishment and session initialization.

**Advanced Stream Recording**: Manual stream management with separate user and persona audio recording capabilities, enabling conversation logging, quality assurance, and custom audio processing workflows.

## What's Next

Ready to take your persona application further? Here are your next steps:

**Explore Advanced Features**: Continue reading our guides to learn about [audio control](/sdk-reference/audio-control), [custom personas](/concepts/personas/create-your-own/overview), and [production deployment](/production) best practices.

**Integrate Your Own AI**: Want to use your own language model instead of Anam's default brain? Check out our [Custom LLM Integration](/examples/custom-llm) guide to learn how to connect your persona to custom AI models and APIs.

## Advanced Customization

### Persona Configuration

Modify the `getDefaultPersonaConfig()` method to customize:

* Avatar appearance and voice selection
* System prompts and personality traits
* Custom brain types and LLM integration

### UI Theming

Update the CSS variables in `app.css` to match your brand:

* Color schemes and gradients
* Typography and spacing
* Animation timing and effects

### Event Integration

Extend the event handlers to integrate with your existing systems:

* Analytics and user behavior tracking
* Customer service platforms
* CRM and database systems

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Personas" icon="user-cog" href="/guides/personas/create-your-own">
    Create personas with custom avatars, voices, and personalities
  </Card>

  <Card title="Production Deployment" icon="cloud" href="/best-practices/production-deployment">
    Deploy your application with security and scalability best practices
  </Card>

  <Card title="SDK Reference" icon="code" href="/sdk-reference/introduction">
    Explore advanced SDK features and configuration options
  </Card>

  <Card title="API Integration" icon="plug" href="/api-reference/introduction">
    Integrate with additional Anam API endpoints
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Issues">
    **Symptoms**: Persona fails to connect or frequently disconnects

    **Solutions**:

    * Verify your API key is correctly configured
    * Check network connectivity and firewall settings
    * Ensure WebRTC is supported in your browser
    * Review server logs for authentication errors
  </Accordion>

  <Accordion title="Audio Problems">
    **Symptoms**: No audio input/output or poor quality

    **Solutions**:

    * Grant microphone permissions in browser settings
    * Check audio device configuration
    * Ensure HTTPS is enabled (required for microphone access)
    * Test with different browsers or devices
  </Accordion>

  <Accordion title="Performance Issues">
    **Symptoms**: Slow loading or laggy interactions

    **Solutions**:

    * Optimize network bandwidth and connection quality
    * Reduce video quality if needed
    * Implement connection pooling and caching
    * Monitor server resource usage
  </Accordion>

  <Accordion title="UI Responsiveness">
    **Symptoms**: Interface doesn't work on mobile or different screen sizes

    **Solutions**:

    * Test on various devices and screen sizes
    * Verify CSS media queries are working
    * Check touch event handling
    * Validate accessibility compliance
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.anam.ai/examples/use-cases/overview

Anam personas in the wild



# Intro to Anam
Source: https://docs.anam.ai/getting-started

Learn about Anam AI and how to get started

<iframe
  style={{
  width: '100%',
  height: 'auto',
  aspectRatio: '16/9',
}}
  src="https://www.youtube.com/embed/iQGpzk35Kks?si=i9qJlPWrFHXv08-j"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen
/>

## What is Anam?

Anam is a platform for building lifelike, AI-powered personas designed to revolutionize communication, training, and customer interactions.
From personalized AI coaches to customer-facing digital assistants, Anam empowers you to create personas that feel human. You choose the face, define the personality, and Anam brings it to life.

## What You Can Do with Anam

**Create Interactive AI Personas** <br /> Customise the personality, appearance, and behavior to match your brand.

**Integrate with your applications** <br /> Utilise the Anam SDK to integrate your persona into your existing web applications.

**Use your own LLM** <br /> If you already have your own LLM or existing assistant workflow you can integrate directly with Anam.

## What are Anam's unique strengths?

1. **Building lifelike personas has never been this easy.** <br />
   Anam enables you to create a photorealistic persona in under 30 seconds. Customize its appearance, personality, and language capabilities, and deploy it across multiple use cases, from training simulations to customer support. No complex setups—just a simple, intuitive interface.

2. **Deliver emotionally intelligent interactions that go beyond automation.** <br />
   Anam personas aren’t just responsive; they’re expressive. With natural gestures, realistic facial expressions, and multilingual support, they bring empathy and understanding to every interaction, ensuring users stay engaged and feel understood.

3. **Tailored for your specific needs, scalable for your business.** <br />
   Whether you’re a developer testing ideas or a company scaling personalized support, Anam offers the flexibility to design personas that fit your use case. Choose from prebuilt personas or create a custom one that aligns with your brand.

## Creating an account

### Sign Up

Visit the [Anam Lab](https://lab.anam.ai) to create your free account.

### Anam Lab

The [Anam Lab](https://lab.anam.ai) is your control center where you can:

* Create and customize personas
* Manage your API keys
* Monitor your usage
* Control your subscription

## Next Steps

Once you have your account you can either continue to learn more about personas, or start integrating a persona with your own product by creating your first API key.

<CardGroup>
  <Card title="Introduction to Personas" icon="person" href="/guides/personas/introduction">
    Learn how to create your first persona
  </Card>

  <Card title="Get your API key" icon="key" href="/guides/get-started/api-key">
    Create your first API key in the Anam Lab
  </Card>
</CardGroup>


# Knowledge Base Setup
Source: https://docs.anam.ai/knowledge/setup

Create folders and organize your documents for semantic search with RAG

## Overview

Setting up your knowledge base is the first step to enabling your AI personas to search and retrieve information from your documents. This guide walks you through creating folders, understanding the organizational structure, and preparing for document uploads.

## Before You Begin

<Warning>**Beta Feature**: Knowledge Base is currently in beta. You may encounter some issues as we continue to improve the feature. Please report any feedback or issues to help us make it better.</Warning>

<Info>
  **What you'll need**:

  * An Anam account with API access
  * Documents to upload (PDF, TXT, MD, DOCX, CSV, JSON, or LOG files)
  * Basic understanding of your content organization

  **Time to complete**: 10-15 minutes
</Info>

## Understanding Folder Structure

Knowledge folders organize your documents by topic, use case, or category. Think of them as searchable collections that can be assigned to different knowledge tools.

### Example Organization

```
Your Organization
├── Product Documentation (Folder)
│   ├── user-guide.pdf
│   ├── api-reference.md
│   └── faq.pdf
│
├── Technical Support (Folder)
│   ├── troubleshooting-guide.pdf
│   ├── error-codes.txt
│   └── common-issues.md
│
├── Company Policies (Folder)
│   ├── privacy-policy.pdf
│   ├── terms-of-service.md
│   └── refund-policy.pdf
│
└── Customer FAQs (Folder)
    ├── billing-faq.md
    ├── account-faq.md
    └── shipping-faq.pdf
```

### Why Organize by Folder?

<AccordionGroup>
  <Accordion title="Better search relevance">
    Smaller, focused folders return more relevant results than searching across all documents at once.
  </Accordion>

  <Accordion title="Easier tool assignment">Different folders can be assigned to different knowledge tools, allowing the LLM to search only relevant content.</Accordion>

  <Accordion title="Simpler maintenance">Update or replace documents in specific knowledge domains without affecting others.</Accordion>

  <Accordion title="Clear organization">
    Easy to understand what content is available and where it's located.
  </Accordion>
</AccordionGroup>

## Step 1: Plan Your Folder Structure

Before creating folders, plan your organization strategy based on your use case.

### By Content Type

Organize by the type of information:

```
├── Product Documentation
├── API Reference
├── User Guides
├── FAQs
└── Policies
```

**Good for**: SaaS products, developer platforms

### By Department

Organize by who creates or owns the content:

```
├── Sales Resources
├── Support Knowledge Base
├── HR Policies
├── Engineering Docs
└── Marketing Materials
```

**Good for**: Internal knowledge bases, employee assistants

### By User Journey

Organize by when users need the information:

```
├── Getting Started
├── Basic Features
├── Advanced Features
├── Troubleshooting
└── Account Management
```

**Good for**: Customer support, onboarding assistants

### By Product/Service

Organize by different offerings:

```
├── Product A Documentation
├── Product B Documentation
├── Service C Information
└── General Company Info
```

**Good for**: Multi-product companies

<Tip>Start simple with 3-5 folders. You can always create more as your knowledge base grows.</Tip>

## Step 2: Create Your First Folder

<Tabs>
  <Tab title="UI">
    <Steps>
      <Step title="Navigate to Knowledge Base">
        Go to `/knowledge` in the Anam Lab
      </Step>

      <Step title="Create new folder">Click the **Create Folder** button in the top right</Step>

      <Step title="Fill in details">
        Enter folder information:

        **Name**: Descriptive name for the folder

        * Examples: "Product Documentation", "Customer FAQs", "API Reference"
        * Use clear, specific names
        * 1-100 characters

        **Description** (optional): What content is in this folder

        * Helps you remember the folder's purpose
        * Useful when you have many folders
        * 0-500 characters
      </Step>

      <Step title="Create folder">
        Click **Create**

        <Check>
          Your folder is created and appears in the folder list. You'll see:

          * Folder name and description
          * Document count (0 initially)
          * Created date
          * Folder ID (UUID) for API usage
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    Create folders programmatically using the API:

    ```bash cURL theme={"dark"}
    curl -X POST 'https://api.anam.ai/v1/knowledge/groups' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Product Documentation",
        "description": "Technical guides and product information for customer support"
      }'
    ```

    ```javascript JavaScript theme={"dark"}
    const response = await fetch("https://api.anam.ai/v1/knowledge/groups", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Product Documentation",
        description: "Technical guides and product information for customer support",
      }),
    });

    const folder = await response.json();
    console.log("Folder created with ID:", folder.id);
    ```

    ```python Python theme={"dark"}
    import requests

    response = requests.post(
        'https://api.anam.ai/v1/knowledge/groups',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'name': 'Product Documentation',
            'description': 'Technical guides and product information for customer support'
        }
    )

    folder = response.json()
    print(f"Folder created with ID: {folder['id']}")
    ```

    **Response**:

    ```json  theme={"dark"}
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Product Documentation",
      "description": "Technical guides and product information for customer support",
      "documentCount": 0,
      "organizationId": "org-uuid",
      "createdAt": "2024-03-10T10:30:00Z",
      "updatedAt": "2024-03-10T10:30:00Z"
    }
    ```

    <Check>
      Save the folder `id` - you'll need it for uploading documents and creating knowledge tools.
    </Check>
  </Tab>
</Tabs>

## Step 3: Create Additional Folders

Create folders for your other content categories:

<CodeGroup>
  ```bash cURL theme={"dark"}
  # Create Technical Support folder
  curl -X POST 'https://api.anam.ai/v1/knowledge/groups' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "Technical Support",
      "description": "Troubleshooting guides and error documentation"
    }'

  # Create Company Policies folder

  curl -X POST 'https://api.anam.ai/v1/knowledge/groups' \
   -H 'Authorization: Bearer YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
  "name": "Company Policies",
  "description": "Privacy policy, terms of service, and legal documents"
  }'

  # Create Customer FAQs folder

  curl -X POST 'https://api.anam.ai/v1/knowledge/groups' \
   -H 'Authorization: Bearer YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
  "name": "Customer FAQs",
  "description": "Frequently asked questions from customers"
  }'

  ```

  ```javascript JavaScript theme={"dark"}
  const folders = [
    {
      name: 'Technical Support',
      description: 'Troubleshooting guides and error documentation'
    },
    {
      name: 'Company Policies',
      description: 'Privacy policy, terms of service, and legal documents'
    },
    {
      name: 'Customer FAQs',
      description: 'Frequently asked questions from customers'
    }
  ];

  for (const folderData of folders) {
    const response = await fetch('https://api.anam.ai/v1/knowledge/groups', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(folderData)
    });

    const folder = await response.json();
    console.log(`Created: ${folder.name} (${folder.id})`);
  }
  ```
</CodeGroup>

## Step 4: View Your Folders

<Tabs>
  <Tab title="UI">
    All your folders are listed on the Knowledge Base page at `/knowledge`:

    * **Folder cards** show name, description, and document count
    * **Click a folder** to see its documents
    * **Search folders** using the search bar
    * **Sort folders** by name or creation date
  </Tab>

  <Tab title="API">
    List all folders in your organization:

    ```bash  theme={"dark"}
    curl -X GET 'https://api.anam.ai/v1/knowledge/groups' \
      -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Response**:

    ```json  theme={"dark"}
    {
      "folders": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Product Documentation",
          "description": "Technical guides and product information",
          "documentCount": 0,
          "createdAt": "2024-03-10T10:30:00Z"
        },
        {
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "name": "Technical Support",
          "description": "Troubleshooting guides and error documentation",
          "documentCount": 0,
          "createdAt": "2024-03-10T10:31:00Z"
        }
      ],
      "total": 2
    }
    ```
  </Tab>
</Tabs>

## Step 5: Prepare Your Documents

Before uploading, organize and prepare your documents:

### Supported File Types

<ResponseField name="PDF" type="file">
  Product manuals, guides, reports, brochures - Max size: 50MB - Chunking: Paragraph-based
</ResponseField>

<ResponseField name="TXT" type="file">
  Plain text documentation, notes, logs - Max size: 50MB - Chunking: Paragraph-based
</ResponseField>

<ResponseField name="MD (Markdown)" type="file">
  Technical documentation, README files, wikis - Max size: 50MB - Chunking: Paragraph-based (respects headings)
</ResponseField>

<ResponseField name="DOCX" type="file">
  Word documents, reports, guides - Max size: 50MB - Chunking: Paragraph-based
</ResponseField>

<ResponseField name="CSV" type="file">
  Structured data, product catalogs, FAQs - Max size: 50MB - Chunking: Row-based (each row is a chunk)
</ResponseField>

<ResponseField name="JSON" type="file">
  Structured data, API responses, configurations - Max size: 50MB - Chunking: Whole file (structure preserved)
</ResponseField>

<ResponseField name="LOG" type="file">
  Log files, system outputs - Max size: 50MB - Chunking: Line-based
</ResponseField>

### Document Preparation Tips

<AccordionGroup>
  <Accordion title="Use clear file names">
    ```
    ✅ Good:
    - product-installation-guide-v2.pdf
    - password-reset-faq.md
    - api-authentication-reference.pdf

    ❌ Bad:

    - document1.pdf
    - file.md
    - untitled.pdf

    ```
  </Accordion>

  <Accordion title="Structure content with headings">
    ```markdown  theme={"dark"}
    # Installation Guide

    ## Prerequisites
    Before installing, ensure you have...

    ## Step 1: Download
    Navigate to our downloads page...

    ## Step 2: Install
    Run the installer and follow...
    ```

    Headings help the chunking algorithm create semantic segments.
  </Accordion>

  <Accordion title="Keep documents focused">
    Instead of one 500-page manual, split into topic-specific documents:

    * installation-guide.pdf
    * configuration-guide.pdf
    * troubleshooting-guide.pdf
    * api-reference.pdf

    This improves search relevance.
  </Accordion>

  <Accordion title="Remove unnecessary content">
    * Remove cover pages and table of contents
    * Delete outdated information
    * Remove duplicate content across files
    * Strip unnecessary images from PDFs to reduce size
  </Accordion>
</AccordionGroup>

## Upload Limits

Document uploads are subject to file size and storage limits based on your plan.

* **File size limits** apply per document
* **Batch uploads** supported for multiple files
* **Storage quotas** count only non-deleted documents
* Deleting documents frees up quota for new uploads

<Info>**Need higher limits?** Contact us about Enterprise plans with custom upload limits tailored to your needs.</Info>

### Check Your Usage

<Tabs>
  <Tab title="UI">
    View your current storage usage on the Knowledge Base page at `/knowledge`:

    * **Total uploaded**: Shows your cumulative upload amount
    * **Document count**: Number of active documents
  </Tab>
</Tabs>

## Managing Folders

### Rename a Folder

<Tabs>
  <Tab title="UI">
    1. Click the folder to open it
    2. Click the **Edit** button (pencil icon)
    3. Update name or description
    4. Click **Save**
  </Tab>

  <Tab title="API">
    ```bash  theme={"dark"}
    curl -X PATCH 'https://api.anam.ai/v1/knowledge/groups/FOLDER_ID' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Updated Folder Name",
        "description": "Updated description"
      }'
    ```
  </Tab>
</Tabs>

### Delete a Folder

<Warning>Deleting a folder deletes all documents inside it. This action cannot be undone.</Warning>

<Tabs>
  <Tab title="UI">
    1. Click the folder to open it
    2. Click the **Delete** button (trash icon)
    3. Confirm deletion in the modal
  </Tab>

  <Tab title="API">
    ```bash  theme={"dark"}
    curl -X DELETE 'https://api.anam.ai/v1/knowledge/groups/FOLDER_ID' \
      -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    This performs a soft delete (sets `deleted_at` timestamp). Documents are removed from search immediately.
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with 3-5 folders">
    Don't over-organize initially. Create folders as you need them.

    **Good starting structure**:

    * Product Documentation
    * FAQs
    * Support/Troubleshooting

    Add more specialized folders as your knowledge base grows.
  </Accordion>

  <Accordion title="Use descriptive names">
    Folder names should clearly indicate their content:

    ```
    ✅ Good:
    - API Reference Documentation
    - Customer Billing FAQs
    - Product Installation Guides

    ❌ Too vague:
    - Documents
    - Stuff
    - Files
    ```
  </Accordion>

  <Accordion title="Keep folders focused">
    Each folder should serve a specific purpose:

    ```
    ✅ Good (focused):
    - Product Features
    - Installation Guides
    - Troubleshooting

    ❌ Too broad:
    - Everything
    - All Documents
    - General
    ```
  </Accordion>

  <Accordion title="Plan for growth">
    Choose a structure that scales:

    ```
    Today (10 documents):
    ├── Documentation
    └── FAQs

    Future (100+ documents):
    ├── Product Documentation
    │   ├── Features
    │   ├── Installation
    │   └── API Reference
    ├── Support
    │   ├── Troubleshooting
    │   ├── Common Issues
    │   └── Error Codes
    └── Customer FAQs
        ├── Billing
        ├── Account
        └── Technical
    ```

    Start simple, but use a structure that allows subdivision later.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that your folders are set up, you're ready to upload documents:

<CardGroup cols={2}>
  <Card title="Upload Documents" icon="upload" href="/guides/knowledge/uploading-documents">
    Step-by-step guide to uploading and processing documents
  </Card>

  <Card title="Create Knowledge Tools" icon="wrench" href="/guides/tools/knowledge-tools">
    Enable semantic search with knowledge tools
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/knowledge/introduction">
    Complete API documentation for knowledge base
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/knowledge-base">
    Learn more about how RAG works
  </Card>
</CardGroup>


# Uploading Documents
Source: https://docs.anam.ai/knowledge/uploading-documents

Upload and process documents for semantic search in your knowledge base

## Overview

Once you've created knowledge folders, you can upload documents to make them searchable. This guide covers the upload process, troubleshooting, and best practices for successful document processing.

## Upload Process

Anam uses a secure three-step presigned URL process for all document uploads.

<Info>
  Document uploads are subject to file size limits. **Need higher limits?**
  Contact us about Enterprise plans with custom limits.
</Info>

## How It Works

For security and performance, all document uploads use a presigned URL flow:

<Steps>
  <Step title="Request presigned URL">
    Request an upload URL from Anam:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl -X POST 'https://api.anam.ai/v1/knowledge/groups/FOLDER_ID/documents/presigned-upload' \
        -H 'Authorization: Bearer YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "filename": "large-document.pdf",
          "contentType": "application/pdf",
          "fileSize": 10485760
        }'
      ```

      ```javascript JavaScript theme={"dark"}
      const response = await fetch(
        `https://api.anam.ai/v1/knowledge/groups/${folderId}/documents/presigned-upload`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${apiKey}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            filename: "large-document.pdf",
            contentType: "application/pdf",
            fileSize: file.size,
          }),
        }
      );

      const { uploadUrl, documentId } = await response.json();
      ```

      ```python Python theme={"dark"}
      response = requests.post(
          f'https://api.anam.ai/v1/knowledge/groups/{folder_id}/documents/presigned-upload',
          headers={
              'Authorization': f'Bearer {api_key}',
              'Content-Type': 'application/json'
          },
          json={
              'filename': 'large-document.pdf',
              'contentType': 'application/pdf',
              'fileSize': file_size
          }
      )

      data = response.json()
      upload_url = data['uploadUrl']
      document_id = data['documentId']
      ```
    </CodeGroup>

    **Response**:

    ```json  theme={"dark"}
    {
      "uploadUrl": "https://storage.cloudflare.com/presigned-url-here",
      "documentId": "doc-uuid-123"
    }
    ```
  </Step>

  <Step title="Upload to presigned URL">
    Upload the file directly to cloud storage:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl -X PUT 'PRESIGNED_URL_FROM_STEP_1' \
        -H 'Content-Type: application/pdf' \
        --data-binary '@large-document.pdf'
      ```

      ```javascript JavaScript theme={"dark"}
      const uploadResponse = await fetch(uploadUrl, {
        method: "PUT",
        headers: {
          "Content-Type": "application/pdf",
        },
        body: file,
      });

      if (!uploadResponse.ok) {
        throw new Error("File upload to storage failed");
      }
      ```

      ```python Python theme={"dark"}
      with open('large-document.pdf', 'rb') as f:
          upload_response = requests.put(
              upload_url,
              headers={'Content-Type': 'application/pdf'},
              data=f
          )

      if upload_response.status_code != 200:
          raise Exception('File upload to storage failed')
      ```
    </CodeGroup>

    <Info>
      This step uploads directly to cloud storage, bypassing Anam's API servers for better performance with large files.
    </Info>
  </Step>

  <Step title="Confirm upload">
    Notify Anam that the upload is complete:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl -X POST 'https://api.anam.ai/v1/knowledge/documents/DOCUMENT_ID/confirm-upload' \
        -H 'Authorization: Bearer YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "fileSize": 10485760
        }'
      ```

      ```javascript JavaScript theme={"dark"}
      const confirmResponse = await fetch(
        `https://api.anam.ai/v1/knowledge/documents/${documentId}/confirm-upload`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${apiKey}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            fileSize: file.size,
          }),
        }
      );

      const document = await confirmResponse.json();
      console.log("Upload confirmed, processing started");
      ```

      ```python Python theme={"dark"}
      confirm_response = requests.post(
          f'https://api.anam.ai/v1/knowledge/documents/{document_id}/confirm-upload',
          headers={
              'Authorization': f'Bearer {api_key}',
              'Content-Type': 'application/json'
          },
          json={'fileSize': file_size}
      )

      document = confirm_response.json()
      print('Upload confirmed, processing started')
      ```
    </CodeGroup>

    <Check>
      Processing begins automatically. The document will be ready for search in \~30 seconds.
    </Check>
  </Step>
</Steps>

### Complete Presigned Upload Example

<CodeGroup>
  ```javascript JavaScript theme={"dark"}
  async function uploadLargeDocument(file, folderId, apiKey) {
    try {
      // Step 1: Get presigned URL
      const presignedResponse = await fetch(
        `https://api.anam.ai/v1/knowledge/groups/${folderId}/documents/presigned-upload`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            filename: file.name,
            contentType: file.type,
            fileSize: file.size
          })
        }
      );
      
      if (!presignedResponse.ok) {
        throw new Error('Failed to get presigned URL');
      }
      
      const { uploadUrl, documentId } = await presignedResponse.json();
      console.log('Got presigned URL for document:', documentId);
      
      // Step 2: Upload to storage
      const uploadResponse = await fetch(uploadUrl, {
        method: 'PUT',
        headers: {
          'Content-Type': file.type
        },
        body: file
      });
      
      if (!uploadResponse.ok) {
        throw new Error('Failed to upload file to storage');
      }
      
      console.log('File uploaded to storage');
      
      // Step 3: Confirm upload
      const confirmResponse = await fetch(
        `https://api.anam.ai/v1/knowledge/documents/${documentId}/confirm-upload`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            fileSize: file.size
          })
        }
      );
      
      if (!confirmResponse.ok) {
        throw new Error('Failed to confirm upload');
      }
      
      const document = await confirmResponse.json();
      console.log('Upload complete! Document ID:', document.id);
      console.log('Status:', document.status);
      
      return document;
      
    } catch (error) {
      console.error('Upload error:', error);
      throw error;
    }
  }

  // Usage with file size check
  async function uploadDocument(file, folderId, apiKey) {
  console.log('Using presigned URL upload');
  return await uploadLargeDocument(file, folderId, apiKey);
  }

  ```

  ```python Python theme={"dark"}
  import requests
  import os

  def upload_document(file_path, folder_id, api_key):
      """Upload a document using presigned URL"""

      filename = os.path.basename(file_path)
      file_size = os.path.getsize(file_path)
      content_type = 'application/pdf'  # Adjust based on file type

      try:
          # Step 1: Get presigned URL
          presigned_response = requests.post(
              f'https://api.anam.ai/v1/knowledge/groups/{folder_id}/documents/presigned-upload',
              headers={
                  'Authorization': f'Bearer {api_key}',
                  'Content-Type': 'application/json'
              },
              json={
                  'filename': filename,
                  'contentType': content_type,
                  'fileSize': file_size
              }
          )
          presigned_response.raise_for_status()

          data = presigned_response.json()
          upload_url = data['uploadUrl']
          document_id = data['documentId']

          print(f'Got presigned URL for document: {document_id}')

          # Step 2: Upload to storage
          with open(file_path, 'rb') as f:
              upload_response = requests.put(
                  upload_url,
                  headers={'Content-Type': content_type},
                  data=f
              )
          upload_response.raise_for_status()

          print('File uploaded to storage')

          # Step 3: Confirm upload
          confirm_response = requests.post(
              f'https://api.anam.ai/v1/knowledge/documents/{document_id}/confirm-upload',
              headers={
                  'Authorization': f'Bearer {api_key}',
                  'Content-Type': 'application/json'
              },
              json={'fileSize': file_size}
          )
          confirm_response.raise_for_status()

          document = confirm_response.json()
          print(f'Upload complete! Document ID: {document["id"]}')
          print(f'Status: {document["status"]}')

          return document

      except requests.exceptions.RequestException as e:
          print(f'Upload error: {e}')
          raise

  # Usage with file size check
  def upload_document(file_path, folder_id, api_key):
      """Upload document using the presigned URL method"""

      print('Using presigned URL upload')
      return upload_large_document(file_path, folder_id, api_key)
  ```
</CodeGroup>

## Monitoring Upload Progress

### Check Document Status

After uploading, monitor the document's processing status:

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X GET 'https://api.anam.ai/v1/knowledge/documents/DOCUMENT_ID' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={"dark"}
  async function checkDocumentStatus(documentId, apiKey) {
    const response = await fetch(
      `https://api.anam.ai/v1/knowledge/documents/${documentId}`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
        },
      }
    );

    const document = await response.json();
    return document.status;
  }

  // Poll until READY
  async function waitForProcessing(documentId, apiKey) {
    const maxAttempts = 60; // 60 attempts = 5 minutes max
    let attempts = 0;

    while (attempts < maxAttempts) {
      const status = await checkDocumentStatus(documentId, apiKey);
      console.log(`Status: ${status}`);

      if (status === "READY") {
        console.log("Document is ready for search!");
        return true;
      }

      if (status === "FAILED") {
        throw new Error("Document processing failed");
      }

      // Wait 5 seconds before next check
      await new Promise((resolve) => setTimeout(resolve, 5000));
      attempts++;
    }

    throw new Error("Processing timeout");
  }
  ```

  ```python Python theme={"dark"}
  import time

  def check_document_status(document_id, api_key):
      """Check the processing status of a document"""

      response = requests.get(
          f'https://api.anam.ai/v1/knowledge/documents/{document_id}',
          headers={'Authorization': f'Bearer {api_key}'}
      )
      response.raise_for_status()

      document = response.json()
      return document['status']

  def wait_for_processing(document_id, api_key, max_attempts=60):
      """Poll until document is ready or fails"""

      attempts = 0

      while attempts < max_attempts:
          status = check_document_status(document_id, api_key)
          print(f'Status: {status}')

          if status == 'READY':
              print('Document is ready for search!')
              return True

          if status == 'FAILED':
              raise Exception('Document processing failed')

          # Wait 5 seconds before next check
          time.sleep(5)
          attempts += 1

      raise Exception('Processing timeout')
  ```
</CodeGroup>

**Document statuses**:

* `UPLOADED`: File uploaded, waiting for processing
* `PROCESSING`: Content is being extracted and indexed
* `READY`: Document is searchable
* `FAILED`: Processing failed (check error message)

## Batch Uploads

Upload multiple documents efficiently:

```javascript  theme={"dark"}
async function batchUpload(files, folderId, apiKey) {
  const maxDirectUploadSize = 4 * 1024 * 1024; // 4MB
  const results = [];

  // Process files concurrently (4 at a time)
  const batchSize = 4;
  for (let i = 0; i < files.length; i += batchSize) {
    const batch = files.slice(i, i + batchSize);

    const batchPromises = batch.map(async (file) => {
      try {
        let document;

        if (file.size <= maxDirectUploadSize) {
          document = await uploadSmallDocument(file, folderId, apiKey);
        } else {
          document = await uploadLargeDocument(file, folderId, apiKey);
        }

        console.log(`✓ Uploaded: ${file.name}`);
        return { file: file.name, success: true, documentId: document.id };
      } catch (error) {
        console.error(`✗ Failed: ${file.name}`, error.message);
        return { file: file.name, success: false, error: error.message };
      }
    });

    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
  }

  const successful = results.filter((r) => r.success).length;
  const failed = results.filter((r) => !r.success).length;

  console.log(`\nBatch upload complete:`);
  console.log(`  Successful: ${successful}`);
  console.log(`  Failed: ${failed}`);

  return results;
}
```

<Tip>
  Process documents in batches of 4 for optimal performance. The system handles
  up to 4 documents concurrently.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="File too large">
    **Error**: `File size exceeds limit`

    **Solutions**:

    * Split the document into smaller files
    * Compress images in PDFs
    * Remove unnecessary pages or content
    * Contact us about Enterprise plans with higher file size limits
  </Accordion>

  <Accordion title="Quota exceeded">
    **Error**: `Upload quota exceeded`

    **Solutions**:

    * Delete unused or outdated documents to free up quota
    * Contact us about Enterprise plans with higher storage limits
    * Check current usage: `GET /v1/knowledge/usage`
  </Accordion>

  <Accordion title="Upload fails immediately">
    **Possible causes**:

    * Invalid API key
    * Invalid folder ID
    * Unsupported file type

    **Solutions**:

    1. Verify API key is valid and has proper permissions
    2. Confirm folder ID exists: `GET /v1/knowledge/groups`
    3. Check file extension is supported (PDF, TXT, MD, DOCX, CSV, JSON, LOG)
    4. Review error message in response
  </Accordion>

  <Accordion title="Processing stuck">
    **Status remains PROCESSING for > 5 minutes**

    **Possible causes**:

    * Very large file (40-50MB)
    * Complex PDF with many images
    * Service temporarily slow

    **Solutions**:

    1. Wait up to 10 minutes for large files
    2. Check document status via API
    3. If stuck for >10 minutes, delete and re-upload
    4. Contact support if issue persists
  </Accordion>

  <Accordion title="Processing failed">
    **Status changes to FAILED**

    **Common causes**:

    * Corrupted file
    * Encrypted or password-protected PDF
    * Invalid file format despite correct extension
    * File contains only images (no text)

    **Solutions**:

    1. Check error message in document details
    2. Verify file opens correctly on your computer
    3. Remove password protection from PDFs
    4. Ensure PDFs contain extractable text (not just images)
    5. Try converting to a different supported format
  </Accordion>

  <Accordion title="Presigned URL expires">
    **Error when uploading to presigned URL**

    **Solutions**:

    * Presigned URLs expire after 1 hour
    * Request a new presigned URL if expired
    * Upload the file immediately after receiving the URL
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Always use presigned URL upload">
    ```javascript  theme={"dark"}
    // All uploads use the presigned URL flow for security and consistency
    await presignedUpload(file);
    ```
  </Accordion>

  <Accordion title="Handle errors gracefully">
    ```javascript  theme={"dark"}
    try {
      const document = await uploadDocument(file, folderId, apiKey);

      // Wait for processing
      await waitForProcessing(document.id, apiKey);

      console.log('Document ready!');

    } catch (error) {
      if (error.message.includes('quota exceeded')) {
        // Show quota upgrade prompt
        showQuotaUpgradeDialog();
      } else if (error.message.includes('file too large')) {
        // Suggest file splitting
        showFileTooLargeError();
      } else {
        // Generic error handling
        showErrorNotification(error.message);
      }
    }
    ```
  </Accordion>

  <Accordion title="Show upload progress">
    ```javascript  theme={"dark"}
    async function uploadWithProgress(file, folderId, apiKey, onProgress) {
      // For presigned URL uploads, track progress
      const xhr = new XMLHttpRequest();
      
      return new Promise((resolve, reject) => {
        xhr.upload.addEventListener('progress', (e) => {
          if (e.lengthComputable) {
            const percentComplete = (e.loaded / e.total) * 100;
            onProgress(percentComplete);
          }
        });
        
        xhr.addEventListener('load', () => {
          if (xhr.status === 200) {
            resolve();
          } else {
            reject(new Error('Upload failed'));
          }
        });
        
        xhr.open('PUT', uploadUrl);
        xhr.setRequestHeader('Content-Type', file.type);
        xhr.send(file);
      });
    }
    ```
  </Accordion>

  <Accordion title="Validate before uploading">
    ```javascript  theme={"dark"}
    function validateFile(file) {
      const maxSize = 50 * 1024 * 1024; // 50MB
      const supportedTypes = [
        'application/pdf',
        'text/plain',
        'text/markdown',
        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
        'text/csv',
        'application/json'
      ];
      
      if (file.size > maxSize) {
        throw new Error('File exceeds 50MB limit');
      }
      
      if (!supportedTypes.includes(file.type)) {
        throw new Error('Unsupported file type');
      }
      
      return true;
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Knowledge Tools" icon="wrench" href="/guides/tools/knowledge-tools">
    Enable semantic search with knowledge tools
  </Card>

  <Card title="Knowledge Base Setup" icon="folder" href="/guides/knowledge/setup">
    Organize documents with folders
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/knowledge/introduction">
    Complete API documentation
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/knowledge-base">
    Learn how RAG works
  </Card>
</CardGroup>


# Anam Developer Documentation
Source: https://docs.anam.ai/overview



Get up and running with your first persona in under 5 minutes:

<CodeGroup>
  ```javascript Step 1: Get a session token theme={"dark"}
  // Make this request from your server to keep your API key secure
  const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
    },
    body: JSON.stringify({
      personaConfig: {
        name: "Alex",
        avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
        voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
        llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
        systemPrompt: "You are a helpful customer service representative.",
      },
    }),
  });
  const { sessionToken } = await response.json();
  ```

  ```javascript Step 2: Initialize the client theme={"dark"}
  import { createClient } from "@anam-ai/js-sdk";

  const anamClient = createClient(sessionToken);

  // Stream to any video element
  await anamClient.streamToVideoElement("video-element-id");
  ```

  ```html Step 3: Add to your HTML theme={"dark"}
  <video id="video-element-id" autoplay playsinline></video>
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Tutorial" icon="rocket" href="/quickstart">
    Build your first persona in 5 minutes
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/concepts/personas">
    Understand how personas work
  </Card>

  <Card title="View Examples" icon="code" href="/examples/basic-app">
    See working code examples
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Explore the full API
  </Card>
</CardGroup>


# Usage in Production
Source: https://docs.anam.ai/production

Securely deploy Anam AI in production environments

## Overview

When deploying to production, it's important not to expose your API key publicly. Instead, you should:

1. Exchange your API key for a short-lived session token on the server side
2. Pass this token to the client
3. Initialize the Anam SDK with the session token

Anam AI offers two types of session tokens: **Stateful** and **Ephemeral**.

<Warning>
  **API Change Notice**: Recent API changes mean we now use a `POST` request
  instead of `GET`, and you define your persona configuration at this point in
  the request body. This change improves security by allowing you to configure
  your persona on the server side, preventing sensitive configuration details
  from being exposed to the client.
</Warning>

## Session Token Types

### Stateful Session Tokens

Stateful tokens reference a persona that you've created and configured in the Anam AI Lab, or using the [Anam AI API](/api-reference/introduction). These are referenced by a unique ID.

<CardGroup cols={2}>
  <Card title="Pros" icon="check" color="#22c55e">
    Configuration changes are managed in the Lab interface without needing code
    changes. So this is ideal for personas that don't need to change from
    session to session.
  </Card>

  <Card title="Cons" icon="x" color="#ef4444">
    This approach offers less flexibility for per-user customization.
  </Card>
</CardGroup>

### Ephemeral Session Tokens

Ephemeral tokens allow you to define the persona configuration at runtime.

<CardGroup cols={2}>
  <Card title="Pros" icon="check" color="#22c55e">
    Define your persona configuration at runtime, enabling per session
    customization and fast feedback during development.
  </Card>

  <Card title="Cons" icon="x" color="#ef4444">
    Requires managing persona configuration inside your application.
  </Card>
</CardGroup>

## Getting a Session Token

### Stateful Session Token

From your server, make a request to get a stateful session token, referencing your persona ID:

```javascript Fetching a stateful session token on your server theme={"dark"}
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    personaConfig: {
      id: "<YOUR_PERSONA_ID>",
    },
  }),
});
const data = await response.json();
const sessionToken = data.sessionToken;
```

### Ephemeral Session Token

From your server, make a request to get an ephemeral session token, with your persona configuration:

```javascript Fetching an ephemeral session token on your server theme={"dark"}
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    personaConfig: {
      name: "Cara",
      avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18", // The avatar ID for Cara
      voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b", // The voice ID for Cara
      llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
      systemPrompt:
        "[STYLE] Reply in natural speech without formatting. Add pauses using '...' and very occasionally a disfluency. [PERSONALITY] You are Cara, a helpful assistant.",
    },
  }),
});
const data = await response.json();
const sessionToken = data.sessionToken;
```

## Client Initialization

Once you have a session token from your server, use the `createClient` method to initialize the Anam client:

```javascript HelloWorld.js theme={"dark"}
import { createClient } from "@anam-ai/js-sdk";

const anamClient = createClient("<YOUR_SESSION_TOKEN>");
```

<Note>
  The client exposes the same methods whether initialized with an API key or
  session token.
</Note>

## Understanding a Session

The sequence diagram below shows how a typical session is started.

<Frame>
    <img src="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=e1af3c048119abc5681d3823a3fe4923" alt="Session initialization sequence diagram" data-og-width="1420" width="1420" data-og-height="1260" height="1260" data-path="images/start-session.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=280&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=b6f8b896db056b5239c4fa5618c11606 280w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=560&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=a96a8c9eb47fca8052369f2b4a902016 560w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=840&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=7ba5d3882882f4001d164eca91461b88 840w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=1100&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=c8e148192ba069436bfc2d76b6068b62 1100w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=1650&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=97909954d96d647beef683d4bfdf327b 1650w, https://mintcdn.com/anam/C1_yhmh0z2cLMID5/images/start-session.png?w=2500&fit=max&auto=format&n=C1_yhmh0z2cLMID5&q=85&s=fe44a1bea2846cdd5fc91f0f19d9cb82 2500w" />
</Frame>

## Next Steps

<CardGroup cols={2}>
  <Card title="Talk Commands" icon="message" href="/sdk-reference/talk-commands">
    Learn how to control persona output using talk commands
  </Card>

  <Card title="Audio Control" icon="microphone" href="/sdk-reference/audio-control">
    Control audio input and streaming behavior
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.anam.ai/quickstart

Get your first AI persona running in under 5 minutes

The Anam API provides a simple interface for implementing digital AI personas within your web applications. This guide will walk you through the process of setting up a minimal example of an interactive AI persona. By the end, you'll have a working persona that can have real-time conversations in your web browser.

## Prerequisites

* An Anam API key ([get one here](/api-key))
* A modern web browser with microphone access
* A local web server (we'll show you how)

## Create Your First Persona

<Steps>
  <Step title="Create the HTML structure">
    Create a new file called `index.html` and add this basic structure:

    ```html index.html theme={"dark"}
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Hello Cara</title>
    </head>
    <body>
        <div style="text-align: center; padding: 20px;">
            <h1>Chat with Cara</h1>
            <p>Your AI persona will appear below and start automatically</p>
            <video id="persona-video" autoplay playsinline style="max-width: 100%; border-radius: 8px;"></video>
            <div id="status" style="margin-top: 15px; font-size: 14px; color: #666;">Loading...</div>
        </div>
    </body>
    </html>
    ```
  </Step>

  <Step title="Add the JavaScript">
    Now add the script that will automatically start your persona. Add this `<script>` tag just before the closing `</body>` tag:

    ```javascript  theme={"dark"}
    <script type="module">
        import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

        // Replace with your actual API key
        const API_KEY = "your-api-key-here";

        const videoElement = document.getElementById("persona-video");
        const statusElement = document.getElementById("status");

        async function createSessionToken() {
            const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    Authorization: `Bearer ${API_KEY}`,
                },
                body: JSON.stringify({
                    personaConfig: {
                        name: "Cara",
                        avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
                        voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
                        llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
                        systemPrompt: "You are Cara, a helpful and friendly AI assistant. Keep responses conversational and concise.",
                    },
                }),
            });

            const data = await response.json();
            return data.sessionToken;
        }

        async function startChat() {
            try {
                statusElement.textContent = "Creating session...";

                const sessionToken = await createSessionToken();
                statusElement.textContent = "Connecting...";

                const anamClient = createClient(sessionToken);
                await anamClient.streamToVideoElement("persona-video");

                statusElement.textContent = "Connected! Start speaking to Cara";

            } catch (error) {
                console.error("Failed to start chat:", error);
                statusElement.textContent = "Failed to connect. Check your API key.";
            }
        }

        // Auto-start when page loads
        startChat();
    </script>
    ```
  </Step>

  <Step title="Add your API key">
    Replace `your-api-key-here` with your actual Anam API key in the script.
  </Step>

  <Step title="Complete file example">
    Your final `index.html` file should look like this:

    ```html index.html [expandable] theme={"dark"}
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Hello Cara</title>
    </head>
    <body>
        <div style="text-align: center; padding: 20px;">
            <h1>Chat with Cara</h1>
            <p>Your AI persona will appear below and start automatically</p>
            <video id="persona-video" autoplay playsinline style="max-width: 100%; border-radius: 8px;"></video>
            <div id="status" style="margin-top: 15px; font-size: 14px; color: #666;">Loading...</div>
        </div>

        <script type="module">
            import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

            // Replace with your actual API key
            const API_KEY = "your-api-key-here";

            const videoElement = document.getElementById("persona-video");
            const statusElement = document.getElementById("status");

            async function createSessionToken() {
                const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
                    method: "POST",
                    headers: {
                        "Content-Type": "application/json",
                        Authorization: `Bearer ${API_KEY}`,
                    },
                    body: JSON.stringify({
                        personaConfig: {
                            name: "Cara",
                            avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
                            voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
                            llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
                            systemPrompt: "You are Cara, a helpful and friendly AI assistant. Keep responses conversational and concise.",
                        },
                    }),
                });

                const data = await response.json();
                return data.sessionToken;
            }

            async function startChat() {
                try {
                    statusElement.textContent = "Creating session...";

                    const sessionToken = await createSessionToken();
                    statusElement.textContent = "Connecting...";

                    const anamClient = createClient(sessionToken);
                    await anamClient.streamToVideoElement("persona-video");

                    statusElement.textContent = "Connected! Start speaking to Cara";

                } catch (error) {
                    console.error("Failed to start chat:", error);
                    statusElement.textContent = "Failed to connect. Check your API key.";
                }
            }

            // Auto-start when page loads
            startChat();
        </script>
    </body>
    </html>
    ```
  </Step>

  <Step title="Start a local server">
    To serve your html file, you'll need a local web server. You can use one of
    the following methods depending on which development tools you have installed.

    <CodeGroup>
      <CodeGroup>
        ```bash Node.js theme={"dark"}
        npx http-server -p 8000
        ```

        ```bash Python 3 theme={"dark"}
        python -m http.server 8000
        ```

        ```bash Python 2 theme={"dark"}
        python -m SimpleHTTPServer 8000
        ```

        ```bash PHP theme={"dark"}
        php -S localhost:8000
        ```
      </CodeGroup>
    </CodeGroup>
  </Step>

  <Step title="Open and test">
    1. Navigate to `http://localhost:8000` in your browser
    2. Allow microphone access when prompted
    3. Cara will appear automatically and you can start talking!
    4. When you're done, close the browser tab to end the session.
  </Step>
</Steps>

## What just happened?

* **Obtaining a Session Token**: Your API key was exchanged for a temporary session token that enables the persona connection
* **Establishing a WebRTC Stream**: The Anam SDK established a real-time video/audio connection to display your persona
* **Voice Interaction**: Cara listens to your microphone and responds with natural speech and facial expressions

## What's next?

Now that you've got Cara up and running, here are some exciting directions to explore:

<CardGroup cols={3}>
  <Card title="Customize your persona's appearance and personality" icon="paintbrush" href="concepts/personas">
    Make your persona truly your own by changing their look, voice, and how they
    respond
  </Card>

  <Card title="Build more engaging applications" icon="code" href="examples/basic-app">
    Work through advanced examples that show you how to create richer, more
    interactive experiences
  </Card>

  <Card title="Respond to conversation events" icon="bolt" href="/concepts/events">
    Learn how to react when your persona starts talking, finishes speaking, or
    encounters different situations
  </Card>
</CardGroup>


# Avatar Gallery
Source: https://docs.anam.ai/resources/avatar-gallery

Browse and select from available avatar options for your personas

export const AvatarGrid = ({avatars}) => {
  const [copiedId, setCopiedId] = useState(null);
  const copyToClipboard = async (id, name) => {
    try {
      await navigator.clipboard.writeText(id);
      setCopiedId(id);
      setTimeout(() => {
        setCopiedId(null);
      }, 2000);
    } catch (err) {
      console.error("Failed to copy ID: ", err);
    }
  };
  if (!avatars || avatars.length === 0) {
    return <p className="text-center text-gray-500">No avatars to display.</p>;
  }
  return <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
      {avatars.map(avatar => <div key={avatar.id} className="card block font-normal group relative my-2 ring-2 ring-transparent rounded-2xl bg-white dark:bg-background-dark border border-gray-950/10 dark:border-white/10 overflow-hidden w-full" onClick={() => copyToClipboard(avatar.id, avatar.name)} tabIndex={0} role="button" aria-label={`Select ${avatar.name} avatar and copy ID`} onKeyDown={e => {
    if (e.key === "Enter" || e.key === " ") {
      e.preventDefault();
      copyToClipboard(avatar.id, avatar.name);
    }
  }}>
          <div className="relative">
            <img src={avatar.image || "/placeholder.svg"} alt={`${avatar.name} avatar`} className="w-full object-cover object-center not-prose" />
            <div className="absolute inset-0 flex items-center justify-center bg-black/0 hover:bg-black/5 transition-colors">
              <div className={`
                   bg-white/90 rounded-full p-1.5 shadow-sm hover:opacity-0
                `}>
                {copiedId === avatar.id && <div className="flex items-center justify-center p-3 bg-black/50 rounded-full">
                    <Icon icon="check" size={24} />
                  </div>}
              </div>
            </div>
          </div>
          <div className="p-4 relative">
            <h2 className="not-prose font-semibold text-base text-gray-800 dark:text-white" title={avatar.name}>
              {avatar.name}
            </h2>
            <div className="prose font-normal text-sm leading-6 text-gray-600 dark:text-gray-400">
              {avatar.variant}
            </div>
          </div>
        </div>)}
    </div>;
};

<Note>
  To use an avatar in your application, copy its ID from the table below and
  include it when creating your session token. See the [Usage in
  Production](/production) guide for more information.
</Note>

## Available Avatars

Click on an avatar to copy the avatar ID.

<AvatarGrid
  avatars={[
  {id: '6cc28442-cccd-42a8-b6e4-24b7210a09c5', name: 'Gabriel', variant: 'table', image: 'https://lab.anam.ai/persona_thumbnails/gabriel_table.png'},
  {id: 'edf6fdcb-acab-44b8-b974-ded72665ee26', name: 'Mia', variant: 'studio', image: 'https://lab.anam.ai/persona_thumbnails/mia_studio.png'},
  {id: '19d18eb0-5346-4d50-a77f-26b3723ed79d', name: 'Richard', variant: 'table', image: 'https://lab.anam.ai/persona_thumbnails/richard_table.png'},
  {id: '071b0286-4cce-4808-bee2-e642f1062de3', name: 'Liv', variant: 'home', image: 'https://lab.anam.ai/persona_thumbnails/liv_home.png'},
  {id: '81b70170-2e80-4e4b-a6fb-e04ac110dc4b', name: 'William', variant: 'lean', image: 'https://lab.anam.ai/persona_thumbnails/william_lean.png'},
  {id: 'edcb8f1a-334f-4cdb-871c-5c513db806a7', name: 'Julia', variant: 'sofa', image: 'https://lab.anam.ai/persona_thumbnails/julia_sofa.png'},
  {id: '8a339c9f-0666-46bd-ab27-e90acd0409dc', name: 'Finn', variant: 'lean', image: 'https://lab.anam.ai/persona_thumbnails/finn_lean.png'},
  {id: '27e12daa-50fc-4384-93c2-ebca73f1f78d', name: 'Anne', variant: 'home', image: 'https://lab.anam.ai/persona_thumbnails/anne_home.png'},
  {id: 'ecfb2ddb-80ec-4526-88a7-299a4738957c', name: 'Hunter', variant: 'table', image: 'https://lab.anam.ai/persona_thumbnails/hunter_table.png'},
  {id: 'dc9aa3e1-32f2-499e-9921-ecabac1076fc', name: 'Bella', variant: 'sofa', image: 'https://lab.anam.ai/persona_thumbnails/bella_sofa.png'},
  {id: 'ccf00c0e-7302-455b-ace2-057e0cf58127', name: 'Kevin', variant: 'table', image: 'https://lab.anam.ai/persona_thumbnails/kevin_table.png'},
  {id: 'ae2ea8c1-db28-47e3-b6ea-493e4ed3c554', name: 'Layla', variant: 'home', image: 'https://lab.anam.ai/persona_thumbnails/layla_home.png'},
  {id: '6dbc1e47-7768-403e-878a-94d7fcc3677b', name: 'Sophie', variant: 'sofa', image: 'https://lab.anam.ai/persona_thumbnails/sophie_sofa.png'},

  // original avatars
  {id: 'c1785d08-9825-4ead-89b3-171d3f667c47', name: 'Alister', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/alister_desk.png'},
  {id: '5701b9ca-c474-4b28-b108-4ca81911ca16', name: 'Alister', variant: 'window sofa', image: 'https://lab.anam.ai/persona_thumbnails/alister_windowsofa.png'},
  {id: 'e36f16d8-7ad1-423b-b9c9-70d49f5eaac6', name: 'Alister', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/alister_windowdesk.png'},
  {id: 'bdaaedfa-00f2-417a-8239-8bb89adec682', name: 'Astrid', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/astrid_desk.png'},
  {id: 'e717a556-2d44-4213-96ec-27d0b94dc198', name: 'Astrid', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/astrid_windowdesk.png'},
  {id: '972e0055-4a8a-4ba5-8b77-39bc0dfb6a1c', name: 'Astrid', variant: 'window sofa corner', image: 'https://lab.anam.ai/persona_thumbnails/astrid_windowsofacorner.png'},
  {id: '960f614f-ea88-47c3-9883-f02094f70874', name: 'Cara', variant: 'window sofa', image: 'https://lab.anam.ai/persona_thumbnails/cara_windowsofa.png'},
  {id: '30fa96d0-26c4-4e55-94a0-517025942e18', name: 'Cara', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/cara_desk.png'},
  {id: 'd9ebe82e-2f34-4ff6-9632-16cb73e7de08', name: 'Cara', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/cara_windowdesk.png'},
  {id: '195d733e-58a9-40bb-a049-ac344fa70b7f', name: 'Evelyn', variant: 'window sofa corner', image: 'https://lab.anam.ai/persona_thumbnails/evelyn_windowsofacorner.png'},
  {id: '290ef1d5-9201-40f4-8c88-394a6317f10d', name: 'Evelyn', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/evelyn_desk.png'},
  {id: 'bb4f5306-ffdb-4437-a837-da6fdc23cbff', name: 'Evelyn', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/evelyn_windowdesk.png'},
  {id: 'd73415e3-d624-45a6-a461-0df1580e73d6', name: 'Leo', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/leo_windowdesk.png'},
  {id: '121d5df1-3f3e-4a48-a237-8ff488e9eed8', name: 'Leo', variant: 'window sofa corner', image: 'https://lab.anam.ai/persona_thumbnails/leo_windowsofacorner.png'},
  {id: 'aa5d6abd-416f-4dd4-a123-b5b29bf1644a', name: 'Leo', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/leo_desk.png'},
  {id: '92b91f2a-4159-411f-b092-3e1b8663f6b9', name: 'Pablo', variant: 'window desk', image: 'https://lab.anam.ai/persona_thumbnails/pablo_windowdesk.png'},
  {id: '8dd64886-ce4b-47d5-b837-619660854768', name: 'Pablo', variant: 'desk', image: 'https://lab.anam.ai/persona_thumbnails/pablo_desk.png'},
  {id: '2fbdec6f-86fd-47d6-8bcc-e8a69270e75b', name: 'Pablo', variant: 'window sofa', image: 'https://lab.anam.ai/persona_thumbnails/pablo_windowsofa.png'},

]}
/>


# Frequently Asked Questions
Source: https://docs.anam.ai/resources/faq

Answers to common questions about Anam

### How is usage time calculated and billed?

Usage time starts when you call the `stream()` method and ends when that specific stream closes. The time is tracked in seconds and billed per minute.

### What causes latency and how can I optimize it?

Latency can come from several sources:

* Connection setup time (usually 4-5 seconds, but can be up to 10 seconds)
* LLM processing time
* TTS generation
* Face generation
* Network conditions

To optimize latency:

* Consider using our turnkey solution instead of custom-LLM
* Use the streaming API for custom LLM implementations

### How do I handle multilingual conversations?

Current language support:

* Speech recognition currently struggles outside of English and will often translate non-English speech to English
* TTS supports multiple languages but voice quality may vary
* System prompts can be set to specific languages
* Language handling is primarily controlled via the system prompt
* Auto-language detection is planned for future releases

### Can I interrupt the persona while it's speaking?

Yes, you can interrupt the persona in two ways:

1. When using streaming, user speech will automatically interrupt the current stream
2. Use the `interruptPersona()` method to programmatically stop the persona mid-speech. See the [interrupt command](/sdk-reference/interrupt-command) for more information.

### How do I integrate my own LLM?

See our [custom LLM guide](/concepts/custom-llms) for more information.

### What are the browser compatibility requirements?

The SDK should work well with any recent Chromium-based or Firefox browser. It requires:

* Modern browser with WebRTC support
* Microphone permissions for audio input
* Autoplay capabilities for video/audio
* WebAssembly support

Safari/iOS notes:

* Requires explicit user interaction for audio playback
* May have additional security policy requirements
* WebKit engine has specific autoplay restrictions

### How do I monitor current usage?

Usage tracking options:

* Available in Anam Lab
* API endpoint for usage stats coming soon
* Session logs available in the Anam Lab

### How do I handle connection issues?

Common issues and solutions:

* For "403 Forbidden" errors, verify API key/session token
* If video doesn't appear, check element IDs match exactly
* Connection timeouts may require retry logic
* Session tokens expire and need refresh
* Monitor `CONNECTION_CLOSED` events for network issues


# Migrating
Source: https://docs.anam.ai/resources/migrating-legacy

Guide on how to adopt new Anam features

## Deprecate brainType in favor of llmId

<Warning>
  **Important Update**: The `brainType` parameter has been deprecated and
  replaced with `llmId` to support custom language models. Your existing
  `brainType` values will continue to work as `llmId` for backwards
  compatibility.
</Warning>

### What This Means For You

If you currently use `brainType` in your persona configuration, you should update your code to use `llmId` instead. This change enables support for custom language models while maintaining compatibility with existing brain types.

The benefits of this change are:

* **Custom LLM Support**: Create and use your own language models with Anam personas
* **Server-Side Processing**: Custom LLMs are processed from Anam's servers for improved latency
* **Secure Credential Storage**: API keys for custom LLMs are encrypted at rest
* **Backwards Compatibility**: Your existing brain types work as LLM IDs

### Migration Steps

Simply replace `brainType` with `llmId` in your persona configuration:

```diff  theme={"dark"}
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${ANAM_API_KEY}`,
  },
  body: JSON.stringify({
    personaConfig: {
      avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
      voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
-     brainType: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
+     llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
      systemPrompt: "You are a helpful assistant.",
    },
  }),
});
```

### Available LLM IDs

All existing brain types continue to work as LLM IDs:

| Previous brainType                     | New llmId                              | Description                |
| -------------------------------------- | -------------------------------------- | -------------------------- |
| `0934d97d-0c3a-4f33-91b0-5e136a0ef466` | `0934d97d-0c3a-4f33-91b0-5e136a0ef466` | OpenAI GPT-4 Mini model    |
| `ANAM_LLAMA_v3_3_70B_V1`               | `ANAM_LLAMA_v3_3_70B_V1`               | Llama 3.3 70B model        |
| `CUSTOMER_CLIENT_V1`                   | `CUSTOMER_CLIENT_V1`                   | Client-side LLM processing |

### Custom LLMs

With this change, you can now create custom LLMs and use them with your personas. Learn more about [Custom LLMs](/concepts/custom-llms).

***

## Deprecate GET /session-token

<Warning>
  **Important Update**: Declaring persona configuration on the client side is
  deprecated and has been removed in the latest version of the Anam SDK. You
  should follow the instructions below to migrate to the new POST /session-token
  endpoint and pass the persona config in the request body.
</Warning>

### What This Means For You

If you currently use the GET /session-token endpoint, or use the POST /session-token endpoint with a personaConfig on the client side, you will need to update your code to pass your persona config in the request body. This means you will need to move your persona configuration from your client side to your server side.

The benefits of this change are:

* Allows for persona config to be defined entirely at runtime
* Increased security, don't reveal your Anam config such as persona ID or system prompt to the client
* Improved performance, this is part of a wider initiative to improve connection start times

### Implementation Recommendations

1. Upgrade to the [latest version of the Anam SDK](https://www.npmjs.com/package/@anam-ai/js-sdk).
2. If you currently make a GET request to /session-token, please update this to a POST and pass the personaConfig in this request. This must still be from you server side config, so you may need to pass details from your client side config to your server if you are creating your system prompt dynamically.
3. Update your client side to use the session token only `createClient(sessionToken)`. Optionally you can still pass in client options such as `disableInputAudio` to the client: `createClient(sessionToken, { disableInputAudio: true })`.

For more information on creating sessions, see [here](/concepts/authentication).

### Example migration

The old way:

```typescript  theme={"dark"}
// On the server side
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${ANAM_API_KEY}`,
  },
});
const { sessionToken } = await response.json();
return sessionToken;

// On the client side
const anamClient = createClient(sessionToken, {
  personaId: "<YOUR_PERSONA_ID>",
});
```

The new way:

```typescript  theme={"dark"}
// On the server side
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${ANAM_API_KEY}`,
  },
  body: JSON.stringify({
    personaConfig: {
      personaId: "<YOUR_PERSONA_ID>",
    },
  }),
});

const { sessionToken } = await response.json();
return sessionToken;

// On the client side
const anamClient = createClient(sessionToken);
```

For more in depth examples of how to define your persona config at runtime see our [full implementation example](/examples/full-app).


# Voice Gallery
Source: https://docs.anam.ai/resources/voice-gallery

Browse and select from available voice options for your personas

export const VoiceGrid = ({voices}) => {
  const [copiedId, setCopiedId] = useState(null);
  const [playingId, setPlayingId] = useState(null);
  const audioRefs = useRef({});
  const copyToClipboard = async (id, name) => {
    try {
      await navigator.clipboard.writeText(id);
      setCopiedId(id);
      setTimeout(() => {
        setCopiedId(null);
      }, 2000);
    } catch (err) {
      console.error("Failed to copy ID: ", err);
    }
  };
  const togglePlayback = id => {
    const audioElement = audioRefs.current[id];
    if (!audioElement) return;
    if (playingId === id) {
      audioElement.pause();
      setPlayingId(null);
    } else {
      if (playingId && audioRefs.current[playingId]) {
        audioRefs.current[playingId].pause();
      }
      audioElement.play();
      setPlayingId(id);
      audioElement.onended = () => {
        setPlayingId(null);
      };
    }
  };
  if (!voices || voices.length === 0) {
    return <p className="text-center text-gray-500">No voices to display.</p>;
  }
  return <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
      {voices.map(voice => <div key={voice.id} className="card block font-normal group relative my-2 ring-2 ring-transparent rounded-2xl bg-white dark:bg-background-dark border border-gray-950/10 dark:border-white/10 overflow-hidden w-full">
          <div className="p-4 not-prose">
            <div className="flex justify-between items-center mb-3">
              <h3 className="font-medium text-gray-900">{voice.name}</h3>
              <button onClick={e => copyToClipboard(voice.id, e)} className="rounded-full transition-colors" aria-label={`Copy ${voice.name} voice ID`}>
                {copiedId === voice.id ? <Icon icon="check" size={16} /> : <Icon icon="copy" size={16} />}
              </button>
            </div>
            <div className="flex items-center justify-between mt-4">
              <button onClick={() => togglePlayback(voice.id)} className="flex items-center justify-center w-10 h-10 rounded-full bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors" aria-label={playingId === voice.id ? "Pause voice sample" : "Play voice sample"}>
                {playingId === voice.id ? <Icon icon="pause" size={16} /> : <Icon icon="play" size={16} />}
              </button>
              <div className="text-xs text-gray-500">
                {playingId === voice.id ? "Playing..." : "Click to preview"}
              </div>
            </div>
            <audio ref={el => audioRefs.current[voice.id] = el} src={voice.sampleUrl} preload="none" className="hidden" />
          </div>
        </div>)}
    </div>;
};

<Note>
  To use a voice in your application, copy its ID from the table below and
  include it when creating your session token. See the [Usage in
  Production](/production) guide for more information.
</Note>

## Available Voices

Click on a voice to copy the voice ID.

<VoiceGrid
  voices={[
  {
    id: "b7274f87-8b72-4c5b-bf52-954768b28c75",
    name: "Leo",
    sampleUrl: "https://lab.anam.ai/voice_samples/leo.wav",
  },
  {
    id: "4bdb224b-0342-4986-9831-69a1f059103d",
    name: "Liv",
    sampleUrl: "https://lab.anam.ai/voice_samples/liv.wav",
  },
  {
    id: "6bfbe25a-979d-40f3-a92b-5394170af54b",
    name: "Cara",
    sampleUrl: "https://lab.anam.ai/voice_samples/cara.wav",
  },
  {
    id: "04965b9e-ff4c-4b54-a4dc-fba6e458c760",
    name: "Astrid",
    sampleUrl: "https://lab.anam.ai/voice_samples/astrid.wav",
  },
  {
    id: "c94090ba-7b30-4fe9-9a6d-e4911cef4400",
    name: "Alister",
    sampleUrl: "https://lab.anam.ai/voice_samples/alister.wav",
  },
  {
    id: "95c6316e-85ac-41ae-a0c1-aa5bf3a91f5a",
    name: "Pablo",
    sampleUrl: "https://lab.anam.ai/voice_samples/pablo.wav",
  },
  {
    id: "c0954b69-9a2a-4fe2-8134-4e43be70f066",
    name: "William",
    sampleUrl: "https://lab.anam.ai/voice_samples/william.wav",
  },
  {
    id: "1c6fa8a7-9aa4-4a17-a75e-3e5eb863fccf",
    name: "Sophie",
    sampleUrl: "https://lab.anam.ai/voice_samples/sophie.wav",
  },
  {
    id: "e9104cf7-d163-4f89-b01a-311f2e8943d0",
    name: "Richard",
    sampleUrl: "https://lab.anam.ai/voice_samples/richard.wav",
  },
  {
    id: "df2aec93-4b4e-41f2-8d02-b2d615ce184a",
    name: "Mia",
    sampleUrl: "https://lab.anam.ai/voice_samples/mia.wav",
  },
  {
    id: "f01404e8-d9ab-4aa1-bcba-265776c9ebbc",
    name: "Layla",
    sampleUrl: "https://lab.anam.ai/voice_samples/layla.wav",
  },
  {
    id: "13ba97ac-88e3-454f-8a49-6f9479dd4586",
    name: "Kevin",
    sampleUrl: "https://lab.anam.ai/voice_samples/kevin.wav",
  },
  {
    id: "109ecf2e-93c4-40df-9555-328c4a5f0c97",
    name: "Julia",
    sampleUrl: "https://lab.anam.ai/voice_samples/julia.wav",
  },
  {
    id: "e4531dd3-6e63-4103-ab4a-9bd5b8c8aeed",
    name: "Hunter",
    sampleUrl: "https://lab.anam.ai/voice_samples/hunter.wav",
  },
  {
    id: "8246d9f7-827e-4a5c-8697-644ce860ca02",
    name: "Gabriel",
    sampleUrl: "https://lab.anam.ai/voice_samples/gabriel.wav",
  },
  {
    id: "615ad2e8-c34a-4993-8aa3-36fd4dc3a876",
    name: "Finn",
    sampleUrl: "https://lab.anam.ai/voice_samples/finn.wav",
  },
  {
    id: "7c917e50-c60f-47a2-85a7-78367a8ddc46",
    name: "Bella",
    sampleUrl: "https://lab.anam.ai/voice_samples/bella.wav",
  },
  {
    id: "912ab254-9f18-4a83-bd9e-e9b1176be287",
    name: "Anne",
    sampleUrl: "https://lab.anam.ai/voice_samples/anne.wav",
  },
]}
/>

<Note>
  Localized voices in other languages are available in the [Anam
  Lab](https://lab.anam.ai/).
</Note>


# Audio Control
Source: https://docs.anam.ai/sdk-reference/audio-control

Control audio input and streaming behavior

## Audio Input State

By default, the Anam client starts capturing input audio from the user's microphone when a session starts and stops capturing when the session ends. For certain use cases, you may wish to control the input audio state programmatically.

### Getting the Current State

To check the current input audio state:

```javascript  theme={"dark"}
const audioState: InputAudioState = anamClient.getInputAudioState();
// { isMuted: false } or { isMuted: true }
```

### Mute Audio Input

To mute the input audio:

```javascript  theme={"dark"}
const audioState: InputAudioState = anamClient.muteInputAudio();
// { isMuted: true }
```

<Note>
  If you mute the input audio before starting a stream, the session will start with microphone input disabled.
</Note>

### Unmute Audio Input

To unmute the input audio:

```javascript  theme={"dark"}
const audioState: InputAudioState = anamClient.unmuteInputAudio();
// { isMuted: false }
```

## Custom Input Streams

If you wish to control the microphone input audio capture yourself, you can pass your own `MediaStream` object when starting a stream:

```javascript  theme={"dark"}
anamClient.streamToVideoElement(
  'video-element-id',
  userProvidedMediaStream
);
```

<Note>
  The `userProvidedMediaStream` object must be an instance of `MediaStream` and the user input audio should be the first audio track returned from the `MediaStream.getAudioTracks()` method.
</Note>

<Tip>
  This is the default behavior if you are using `navigator.mediaDevices.getUserMedia()`.
</Tip>


# Basic Usage
Source: https://docs.anam.ai/sdk-reference/basic-usage

Install, setup, and deploy the Anam AI JavaScript SDK

## Installation

Install the SDK in your project using npm:

```bash  theme={"dark"}
npm install @anam-ai/js-sdk
```

## DOM Elements

This quickstart example requires a video element to display the persona:

For this example we would include the following in our HTML:

```html  theme={"dark"}
<video id="video-element-id" autoplay playsinline></video>
```

<Note>
  `autoplay` is used to start the stream as soon as the page loads. The
  `playsinline` attribute prevents the video from being played in fullscreen
  mode on mobile devices.
</Note>

## Basic Usage

It is important to not expose your API key publicly. Instead, you should:

1. Exchange your API key for a short-lived session token on the server side
2. Pass this token to the client
3. Initialize the Anam SDK with the session token

### Step 1: Getting a Session Token

From your server, make a request to get a session token using your API key and persona configuration:

```javascript Step 1: Get a session token theme={"dark"}
// Make this request from your server to keep your API key secure
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
  },
  body: JSON.stringify({
    personaConfig: {
      name: "Alex",
      avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
      voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
      llmId: "0934d97d-0c3a-4f33-91b0-5e136a0ef466",
      systemPrompt: "You are a helpful customer service representative.",
    },
  }),
});
const { sessionToken } = await response.json();
```

### Step 2: Initialize the Client

Once you have a session token, use the `createClient` method to initialize the Anam client:

```javascript Step 2: Initialize the client theme={"dark"}
import { createClient } from "@anam-ai/js-sdk";

const anamClient = createClient(sessionToken);

// Stream to any video element
await anamClient.streamToVideoElement("video-element-id");
```

## Stopping a Stream

To stop an active session, use the `stopStreaming` method. This will end the current session and release the audio and video elements.

```javascript  theme={"dark"}
await anamClient.stopStreaming();
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Talk Commands" icon="message" href="/sdk-reference/talk-commands">
    Learn how to control persona output using talk commands
  </Card>

  <Card title="Audio Control" icon="microphone" href="/sdk-reference/audio-control">
    Control audio input and streaming behavior
  </Card>

  <Card title="User Messages" icon="user" href="/sdk-reference/user-messages">
    Send messages programmatically on behalf of the user
  </Card>
</CardGroup>


# Session Configuration
Source: https://docs.anam.ai/sdk-reference/configuration

Additional configuration options for the Anam client

## Client Configuration

When initializing the Anam client, you can provide various configuration options to customize its behavior.

### Disabling Brains

You can turn off the Anam LLM by setting the `disableBrains` option to `true`. When disabled, the persona will only respond to `talk` commands and won't process voice input:

```typescript  theme={"dark"}
const anamClient = createClient("your-session-token", {
  personaId: "chosen-persona-id",
  disableBrains: true,
});
```

<Note>
  To learn more about how to use your own custom intelligence, see our [Custom
  LLMs](/concepts/custom-llms) guide.
</Note>

## Updating Configuration

You can update the persona configuration after initialization using `setPersonaConfig`:

```typescript  theme={"dark"}
anamClient.setPersonaConfig({
  personaId: "new-persona-id",
});
```

To check the current configuration:

```typescript  theme={"dark"}
const config = anamClient.getPersonaConfig();
```

## Next Steps

<Card title="Listening for Events" icon="bell" href="/sdk-reference/events">
  Session events let you respond to changes in the session state. Learn how you
  can listen for events and trigger custom logic.
</Card>


# Listening for Events
Source: https://docs.anam.ai/sdk-reference/events

Listen to events during Anam AI sessions

## Adding Event Listeners

After initializing the Anam client, you can register event listeners using the `addListener` method:

```typescript  theme={"dark"}
import { AnamEvent } from "@anam-ai/js-sdk/dist/module/types

anamClient.addListener(AnamEvent.CONNECTION_ESTABLISHED, () => {
  console.log('Connection Established');
});

anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
  console.log('Updated Messages:', messages);
});
```

## Available Events

| Event Name                      | Description                                                                                                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTION_ESTABLISHED`        | Called when the direct connection between the browser and the Anam Engine has been established                                                                    |
| `SESSION_READY`                 | Called after the session initialises and all the backend components are ready. Useful for removing loading indicators                                             |
| `CONNECTION_CLOSED`             | Called when the direct connection between the browser and the Anam Engine has been closed                                                                         |
| `VIDEO_PLAY_STARTED`            | Fired when the first frames start playing during video streaming.                                                                                                 |
| `MESSAGE_HISTORY_UPDATED`       | Called with the message history transcription each time the user or persona finishes speaking                                                                     |
| `MESSAGE_STREAM_EVENT_RECEIVED` | For persona speech: Updated with each transcribed chunk as the persona speaks<br />For user speech: Updated with complete transcription once they finish speaking |
| `INPUT_AUDIO_STREAM_STARTED`    | Called with the user's input audio stream when microphone input has been initialized                                                                              |
| `TALK_STREAM_INTERRUPTED`       | Called when the user interrupts a `TalkMessageStream` by speaking. Includes the interrupted stream's `correlationId`                                              |
| `TOOL_CALL`                     | Called when the AI persona invokes a client tool. Includes the tool name and arguments for handling UI actions like navigation or modal displays                  |

## Example Usage

### Loading States

Use connection events to manage loading states:

```typescript  theme={"dark"}
anamClient.addListener(AnamEvent.CONNECTION_ESTABLISHED, () => {
  setIsConnecting(false);
});

anamClient.addListener(AnamEvent.SESSION_READY, () => {
  setIsLoading(false);
});
```

### Message History

Track conversation history:

```typescript  theme={"dark"}
anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
  setConversationHistory(messages);
});
```

### Real-time Transcription

Monitor speech in real-time:

```typescript  theme={"dark"}
anamClient.addListener(AnamEvent.MESSAGE_STREAM_EVENT_RECEIVED, (event) => {
  if (event.role === "persona") {
    updatePersonaSpeech(event.content);
  } else {
    updateUserSpeech(event.content);
  }
});
```

### Client Tool Events

Handle UI actions triggered by the AI persona:

```typescript  theme={"dark"}
anamClient.addListener(AnamEvent.TOOL_CALL, (event) => {
  const { toolName, arguments: args } = event;

  switch (toolName) {
    case "navigate_to_page":
      router.push(`/${args.page}`);
      break;
    case "open_modal":
      openModal(args.modalType, args.data);
      break;
    default:
      console.warn(`Unhandled tool: ${toolName}`);
  }
});
```

## Tool Call Events (Detailed Guide)

Client tools enable your AI persona to trigger events in your client application - like navigating to pages, opening modals, updating UI state, or controlling media playback. When the LLM invokes a client tool during a conversation, the Anam SDK emits a `TOOL_CALL` event that you can handle in your application code.

<Tip>
  For a comprehensive guide on client tools, including how to create them, common use cases, real-world examples, and advanced patterns, see the [Client
  Tools Guide](/guides/tools/client-tools).
</Tip>

### Complete Example

Use the `addListener` method to register a handler for tool call events. The event name is provided by the `AnamEvent` enum, and the payload is typed with `ClientToolEvent`.

```javascript  theme={"dark"}
import { AnamClient, AnamEvent, ClientToolEvent } from "@anam-ai/js-sdk";

const client = new AnamClient({
  sessionToken: "YOUR_SESSION_TOKEN",
});

const handleToolCall = (event: ClientToolEvent) => {
  console.log("Tool call received:", event);

  const { toolName, arguments: args } = event;

  // Handle the tool call based on its name
  switch (toolName) {
    case "navigate_to_page":
      // Example: navigate using your app's router
      router.push(`/${args.page}`);
      break;

    case "open_checkout_modal":
      // Example: open a modal with product data
      openCheckout(args.productId);
      break;

    case "apply_filters":
      // Example: update UI state
      applyProductFilters(args);
      break;

    default:
      console.warn(`Unhandled tool call: ${toolName}`);
  }
};

// Add the listener
client.addListener(AnamEvent.TOOL_CALL, handleToolCall);

// Connect the client to start receiving events
await client.connect();
```

### Event Payload

The `TOOL_CALL` event provides a payload object with the following structure:

<ResponseField name="toolName" type="string">
  The `name` of the client tool that was invoked.
</ResponseField>

<ResponseField name="arguments" type="object">
  An object containing the parameters and their values as extracted by the LLM from the conversation. The structure of this object matches the `parameters` JSON schema you defined for the tool.
</ResponseField>

**Example Payload**:

If you have a tool defined like this:

```json  theme={"dark"}
{
  "type": "client",
  "name": "open_product_page",
  "description": "Opens a product page in the app",
  "parameters": {
    "type": "object",
    "properties": {
      "productId": { "type": "string" },
      "category": { "type": "string" }
    }
  }
}
```

And the user says, "Show me product ABC-123 in the electronics category," the `event` payload would look like this:

```json  theme={"dark"}
{
  "toolName": "open_product_page",
  "arguments": {
    "productId": "ABC-123",
    "category": "electronics"
  }
}
```

### Removing Event Listeners

It's important to clean up listeners to prevent memory leaks, especially in single-page applications. Use the `removeListener` method. This is often done in a cleanup function, such as React's `useEffect` hook.

```javascript  theme={"dark"}
// In a React component
useEffect(() => {
  const handleToolCall = (event: ClientToolEvent) => {
    // ... your logic
  };

  // Add listener when the component mounts
  client.addListener(AnamEvent.TOOL_CALL, handleToolCall);

  // Return a cleanup function to remove the listener when the component unmounts
  return () => {
    client.removeListener(AnamEvent.TOOL_CALL, handleToolCall);
  };
}, [client]); // Rerun effect if the client instance changes
```

### Best Practices

<AccordionGroup>
  <Accordion title="Use a switch statement">
    A `switch` statement is a clean way to handle different tool calls. Always include a `default` case to log unhandled tools.
  </Accordion>

  <Accordion title="Validate arguments">
    Never trust the arguments from a tool call without validation. Even though the LLM tries to provide correct data, it can sometimes make mistakes. Sanitize and validate all inputs before performing actions.

    ```javascript  theme={"dark"}
    case 'navigate_to_page':
      const allowedPages = ['home', 'pricing', 'about'];
      if (allowedPages.includes(args.page)) {
        router.push(`/${args.page}`);
      } else {
        console.error(`Invalid page navigation attempt: ${args.page}`);
      }
      break;
    ```
  </Accordion>

  <Accordion title="Provide user feedback">
    After handling a tool call, provide some form of visual feedback in your UI to confirm the action was performed (e.g., a toast notification, a loading spinner, or the navigation itself).
  </Accordion>

  <Accordion title="Handle potential errors">
    Wrap your tool handling logic in `try...catch` blocks to gracefully handle any errors that occur during execution.
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup cols={2}>
  <Card title="Client Tools Guide" icon="browser" href="/guides/tools/client-tools">
    Complete guide with examples for navigation, modals, UI updates, and more
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/concepts/tools">
    Learn about all tool types: client, webhook, and knowledge tools
  </Card>
</CardGroup>


# Interrupt Command
Source: https://docs.anam.ai/sdk-reference/interrupt-command

Stop the persona from speaking mid-response

## Overview

The `interruptPersona()` method allows you to programmatically stop the persona while it's speaking.

<Note>Requires SDK version 3.4.0 or higher</Note>

## Basic Usage

Stop the persona from speaking immediately:

```javascript  theme={"dark"}
anamClient.interruptPersona();
```

The persona will stop its current speech and be ready to receive new input.

## Important Considerations

<Warning>
  The `interruptPersona()` method only works while the persona is actively speaking.
  Calling it when the persona is not speaking will have no effect but won't throw an error.
</Warning>

The `interruptPersona()` method behavior:

* Immediately stops any ongoing speech from the persona
* The persona remains ready to receive new input after being interrupted

## Use Cases

### User-Initiated Interruption

Allow users to interrupt the persona when they want to ask a different question or change topics:

```javascript  theme={"dark"}
// When user clicks a button or starts speaking
document.getElementById("interrupt-btn").addEventListener("click", async () => {
  await anamClient.interruptPersona();
});
```

<Note>
  Anam's Voice Activity Detection also automatically interrupts the persona when the user starts speaking. However, you can use this function to interrupt the persona at any time or for a more immediate response.
</Note>

### Topic Change Handling

Stop the persona when users navigate to a different section or topic:

```javascript  theme={"dark"}
// When user navigates to a new page or section
async function handleNavigationChange(newSection) {
  // Stop any ongoing explanation
  await anamClient.interruptPersona();
  
  // Send context about the new topic
  await anamClient.sendUserMessage(
    `Note to AI: User navigated to ${newSection}`
  );
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Events" icon="webhook" href="/sdk-reference/events">
    Learn about speech events to track when the persona is speaking
  </Card>

  <Card title="User Messages" icon="message" href="/sdk-reference/user-messages">
    Send messages programmatically after interrupting
  </Card>
</CardGroup>


# Talk Commands
Source: https://docs.anam.ai/sdk-reference/talk-commands

Control persona output using talk commands

## Basic Usage

Sometimes during a persona session, you may wish to force a response from the persona. For example, when the user interacts with an element on the page or when you have disabled the Anam LLM to use your own. To do this, use the `talk` method:

```typescript  theme={"dark"}
await anamClient.talk("Hello, how are you?");
```

This will force the persona to respond with the given text.

<Note>
  To learn more about how to use the `talk` method to enable your own custom
  intelligence, see our [Custom LLMs](/concepts/custom-llms) guide.
</Note>

## Streaming Talk Input

For more advanced use cases, you can stream messages to the persona in multiple chunks. This is particularly useful when streaming output from a custom LLM to reduce latency.

```typescript  theme={"dark"}
const talkMessageStream = anamClient.createTalkMessageStream();

const chunks = ["He", "l", "lo", ", how are you?"];

for (const chunk of chunks) {
  if (talkMessageStream.isActive()) {
    talkMessageStream.streamMessageChunk(
      chunk,
      chunk === chunks[chunks.length - 1]
    );
  }
}
```

<Note>
  One talkMessageStream represents one "turn" in the conversation. Once that
  turn is over, the stream can no longer be used and you must create a new
  `TalkMessageStream`.
</Note>

### End of Speech and Interruptions

A conversation "turn" can end in one of two ways:

1. **End of speech**: When `streamMessageChunk` is called with `endOfSpeech: true` or the `endMessage()` method is called
2. **User interruption**: When the user speaks during the stream, triggering an `AnamEvent.TALK_STREAM_INTERRUPTED` event

In both cases, the `TalkMessageStream` object is closed and no longer usable. You can check if a stream is still active using:

```typescript  theme={"dark"}
if (talkMessageStream.isActive()) {
  // Stream is still active
}
```

## Correlation IDs

For tracking purposes, you can attach a correlation ID to your talk streams by passing the optional `correlationId` parameter to the `createTalkMessageStream` method:

```typescript  theme={"dark"}
const talkMessageStream = anamClient.createTalkMessageStream("unique-id-123");
```

<Note>
  The `correlationId` should be unique for every `TalkMessageStream` instance.
  When a talk stream is interrupted, this ID will be included in the
  `AnamEvent.TALK_STREAM_INTERRUPTED` event.
</Note>

## Next Steps

<Card title="Audio Control" icon="volume" href="/sdk-reference/audio-control">
  Learn how to control Audio Input in your Anam sessions
</Card>


# User Messages
Source: https://docs.anam.ai/sdk-reference/user-messages

Send messages on behalf of the user programmatically

## Overview

The `sendUserMessage()` method allows you to programmatically send text messages on behalf of the user. This is useful for sending contextual information or triggering specific persona responses without actual user input.

<Note>Requires SDK version 3.3.0 or higher</Note>

## Basic Usage

Send a message as if the user typed or spoke it:

```javascript  theme={"dark"}
await anamClient.sendUserMessage("Hello, how can you help me today?");
```

The persona will receive this message and respond as if the user had actually said it.

## Important Considerations

<Warning>
  Messages sent via `sendUserMessage()` are not automatically added to the
  transcript. To maintain an accurate conversation history, you must manually
  add these messages to your transcript display.
</Warning>

The `sendUserMessage()` method differs from regular user messages in that:

* It does not trigger message events that would normally update your UI
* The message is sent directly to the persona without going through the normal message pipeline
* You need to handle transcript updates separately in your application

## Use Cases

### Simulating User Input

```javascript  theme={"dark"}
// Simulate a user greeting when the session starts
await anamClient.sendUserMessage("Hi there!");
```

### Providing Context to the LLM

A powerful use case is providing contextual information about user actions that the LLM can respond to:

```javascript  theme={"dark"}
// Inform the AI about user actions
await anamClient.sendUserMessage(
  "Note to AI: I just clicked the checkout button"
);

// The persona might respond with something like:
// "Thanks for shopping with us today! Let me help you complete your purchase."
```

<Tip>
  When providing context to the LLM, prefix your messages with "Note to AI:" or
  similar to make the intent clear. This helps the LLM understand that it's
  receiving contextual information rather than a direct user question.
</Tip>

### Triggering Specific Flows

```javascript  theme={"dark"}
// Trigger a specific conversation flow
await anamClient.sendUserMessage("I want to learn about your pricing plans");

// Or provide more detailed context
await anamClient.sendUserMessage(
  "Note to AI: User navigated to pricing page and spent 30 seconds reading"
);
```

### Custom Client-Side Transcription

The `sendUserMessage()` method enables you to implement your own client-side speech-to-text transcription. You can capture and transcribe audio using your preferred service, then send the transcribed messages directly:

```javascript  theme={"dark"}
// Example using a custom transcription service
async function handleCustomTranscription(audioStream) {
  // Use your preferred transcription service (e.g., Web Speech API, Whisper, etc.)
  const transcribedText =
    await customTranscriptionService.transcribe(audioStream);

  // Send the transcribed message to the persona
  await anamClient.sendUserMessage(transcribedText);

  // Update your UI transcript
  addMessageToTranscript(transcribedText, "user");
}
```

<Note>
  This approach gives you full control over the transcription process, allowing
  you to use specialized transcription models, handle multiple languages, or
  implement custom preprocessing of the audio before sending it to the persona.
</Note>

## Complete Example

Here's a complete example showing how to use `sendUserMessage()` with proper transcript management:

```javascript  theme={"dark"}
import { createClient } from "@anam-ai/js-sdk";

// Initialize the client
const anamClient = createClient(sessionToken);
await anamClient.streamToVideoElement("video-element-id");

// Function to update your UI transcript
function addMessageToTranscript(message, sender) {
  const transcript = document.getElementById("transcript");
  const messageElement = document.createElement("div");
  messageElement.className = sender === "user" ? "user-message" : "ai-message";
  messageElement.textContent = message;
  transcript.appendChild(messageElement);
}

// Send a message and update the transcript
async function sendUserMessage(message) {
  // Add to transcript manually since sendUserMessage doesn't trigger events
  addMessageToTranscript(message, "user");

  // Send the message to the persona
  await anamClient.sendUserMessage(message);
}

// Example usage
await sendUserMessage("What products do you recommend?");

// Provide context about user actions
await sendUserMessage(
  "Note to AI: User added item to cart with ID product_123"
);
```

## Future Improvements

<Info>
  In future SDK versions, we plan to introduce a dedicated `sendSystemMessage()`
  method that will be better suited for sending contextual information and
  system-level messages to the LLM. This will provide clearer separation between
  user messages and system context.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Events" icon="webhook" href="/sdk-reference/events">
    Learn how to handle message events and build interactive experiences
  </Card>

  <Card title="Interrupt Command" icon="hand" href="/sdk-reference/interrupt-command">
    Stop the persona from speaking mid-response
  </Card>
</CardGroup>


# LiveKit Plugin
Source: https://docs.anam.ai/third-party-integrations/livekit

Integrate Anam's AI avatars into LiveKit agent applications for voice-first, multimodal AI experiences.

The Anam LiveKit plugin enables you to add avatars to your LiveKit agent applications. Combine Anam's avatar technology with any STT, LLM or TTS—including OpenAI Realtime, Gemini Live, or your own custom models—to create engaging AI experiences.

## Demo

See the Anam + LiveKit integration in action with our onboarding assistant demo:

<Frame>
  <a href="https://youtu.be/9mxK5HdHzes">
    ![Anam LiveKit Demo - AI Onboarding Assistant](https://img.youtube.com/vi/9mxK5HdHzes/0.jpg)
  </a>
</Frame>

<Card title="View Demo Source Code" icon="github" href="https://github.com/anam-ai/livekit-demo">
  Full source code for the onboarding assistant demo with Gemini vision and screen share analysis.
</Card>

## Installation

```bash  theme={"dark"}
pip install livekit-plugins-anam
```

## Quick Start

The simplest way to add an Anam avatar to your LiveKit agent:

```python  theme={"dark"}
import os
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import openai, anam

async def entrypoint(ctx: JobContext):
    await ctx.connect()
    
    # Create agent session with OpenAI Realtime
    session = AgentSession(
        llm=openai.realtime.RealtimeModel(voice="alloy"),
    )

    # Configure Anam avatar
    avatar = anam.AvatarSession(
        persona_config=anam.PersonaConfig(
            name="Cara",
            avatarId="a49abb10-9a29-4099-b950-e68534742fb2",
        ),
        api_key=os.getenv("ANAM_API_KEY"),
    )
    
    # Start the avatar and agent
    await avatar.start(session, room=ctx.room)
    await session.start(
        agent=Agent(instructions="You are a helpful assistant."),
        room=ctx.room,
    )
    
    # Generate initial greeting
    session.generate_reply(instructions="Say hello to the user")

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

## Architecture

The Anam LiveKit plugin acts as a visual layer for your AI agent:

```
User Input (Voice/Video)
    ↓
LiveKit Room (Real-time Communication)
    ↓
Your LLM (OpenAI, Gemini, Claude, etc.)
    ↓
Text Response → Anam Avatar (TTS + Video)
    ↓
User sees and hears the avatar
```

<Tip>
  **Bring Your Own LLM**: Anam handles only the visual avatar. You choose the ears, intelligence and voice—whether that's DeepGram, ElevenLabs, Cartesia, OpenAI, Gemini, Claude, or a custom model trained on your data.
</Tip>

## Configuration

### Environment Variables

<Steps>
  <Step title="Get your API credentials">
    You'll need credentials from at least three services:

    | Service             | Where to get it                                      |
    | ------------------- | ---------------------------------------------------- |
    | **Anam**            | [Anam Dashboard](https://dashboard.anam.dev)         |
    | **LiveKit**         | [LiveKit Cloud](https://livekit.io) or self-hosted   |
    | **Other Providers** | DeepGram, ElevenLabs, OpenAI, Google AI Studio, etc. |
  </Step>

  <Step title="Set environment variables">
    Create a `.env` file with your credentials:

    ```bash .env theme={"dark"}
    # Anam credentials
    ANAM_API_KEY=your_anam_api_key
    ANAM_AVATAR_ID=your_avatar_id

    # LiveKit credentials
    LIVEKIT_URL=wss://your-project.livekit.cloud
    LIVEKIT_API_KEY=your_livekit_api_key
    LIVEKIT_API_SECRET=your_livekit_api_secret

    # Other credentials (choose your providers)
    OPENAI_API_KEY=your_openai_api_key
    # or
    GEMINI_API_KEY=your_gemini_api_key
    ```
  </Step>
</Steps>

### PersonaConfig Options

Configure your avatar's identity:

```python  theme={"dark"}
persona_config = anam.PersonaConfig(
    name="Maya",           # Display name for the avatar
    avatarId="uuid-here",  # Avatar appearance ID
)
```

### Choosing an Avatar

<CardGroup cols={2}>
  <Card title="Stock Avatars" icon="users" href="/resources/avatar-gallery">
    Browse ready-to-use avatars in our gallery. Copy the avatar ID directly into your config.
  </Card>

  <Card title="Custom Avatars" icon="wand-magic-sparkles" href="https://lab.anam.ai/avatars">
    Create your own personalized avatar in Anam Lab with custom appearance and style.
  </Card>
</CardGroup>

## Advanced Examples

### Using Gemini with Vision

This example shows how to use Gemini Live for multimodal conversations with screen share analysis:

```python  theme={"dark"}
import os
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.agents.voice import VoiceActivityVideoSampler, room_io
from livekit.plugins import anam, google

async def entrypoint(ctx: JobContext):
    await ctx.connect()
    
    # Gemini Live model with vision capabilities
    llm = google.realtime.RealtimeModel(
        model="gemini-2.0-flash-exp",
        api_key=os.getenv("GEMINI_API_KEY"),
        voice="Aoede",
        instructions="You are a helpful assistant that can see the user's screen.",
    )
    
    # Anam avatar
    avatar = anam.AvatarSession(
        persona_config=anam.PersonaConfig(
            name="Maya",
            avatarId=os.getenv("ANAM_AVATAR_ID"),
        ),
        api_key=os.getenv("ANAM_API_KEY"),
    )
    
    # Agent session with video sampling for screen analysis
    session = AgentSession(
        llm=llm,
        video_sampler=VoiceActivityVideoSampler(
            speaking_fps=0.2,  # 1 frame every 5 sec when speaking
            silent_fps=0.1,    # 1 frame every 10 sec when silent
        ),
    )
    
    await avatar.start(session, room=ctx.room)
    await session.start(
        agent=Agent(instructions="Help the user with what you see on their screen."),
        room=ctx.room,
        room_input_options=room_io.RoomInputOptions(video_enabled=True),
    )

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

### Adding Function Tools

Extend your agent with custom tools that can take actions:

```python  theme={"dark"}
from livekit.agents import function_tool

@function_tool
async def fill_form_field(field_name: str, value: str) -> str:
    """Fill in a form field on the user's screen.
    
    Args:
        field_name: The name of the field to fill
        value: The value to enter
    
    Returns:
        Confirmation message
    """
    # Your implementation here
    await send_command_to_frontend("fill_field", {"field": field_name, "value": value})
    return "Field filled successfully"

# Include tools in your session
session = AgentSession(
    llm=llm,
    tools=[fill_form_field],
)
```

## Running Your Agent

<Tabs>
  <Tab title="Development">
    Use the LiveKit CLI for local development:

    ```bash  theme={"dark"}
    python agent.py dev
    ```

    This connects to your LiveKit server and automatically joins rooms when participants connect.
  </Tab>

  <Tab title="Production">
    For production deployments, run without the `dev` flag:

    ```bash  theme={"dark"}
    python agent.py
    ```

    Deploy using Docker, Kubernetes, or your preferred container platform. See the [LiveKit Agents deployment guide](https://docs.livekit.io/agents/deployment) for details.
  </Tab>
</Tabs>

## Use Cases

The Anam + LiveKit combination is ideal for scenarios requiring voice interaction with visual presence:

<AccordionGroup>
  <Accordion title="Employee Onboarding" icon="id-card">
    Guide new hires through forms and processes with screen share analysis. The AI sees what they see and provides contextual help.
  </Accordion>

  <Accordion title="Educational Tutoring" icon="graduation-cap">
    Help students with homework by seeing their work. The avatar can point out errors and explain concepts visually.
  </Accordion>

  <Accordion title="Technical Support" icon="headset">
    See customer screens and provide step-by-step guidance with a friendly visual presence.
  </Accordion>

  <Accordion title="Healthcare Intake" icon="hospital">
    Assist patients filling out medical forms with a calm, reassuring avatar presence.
  </Accordion>

  <Accordion title="Financial Services" icon="building-columns">
    Guide users through account opening, KYC processes, and complex financial forms.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent won't connect to LiveKit">
    * Verify `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` are correct
    * Check that your LiveKit server is accessible
    * Ensure WebSocket connections aren't blocked by a firewall
    * Test connectivity at [meet.livekit.io](https://meet.livekit.io)
  </Accordion>

  <Accordion title="Avatar not appearing">
    * Verify your `ANAM_API_KEY` is valid
    * Check that `ANAM_AVATAR_ID` matches an existing avatar
    * Review agent logs for Anam connection errors
    * Ensure the avatar session starts before the agent session
  </Accordion>

  <Accordion title="No voice response">
    * Check your LLM API key is valid (OpenAI, Gemini, etc.)
    * Verify microphone permissions in the browser
    * Look for API errors in the agent logs
    * Confirm the agent is receiving audio tracks
  </Accordion>

  <Accordion title="Screen share not detected">
    * Ensure you're sharing the correct tab or window
    * Check browser permissions for screen sharing
    * Look for "Screen share track detected" in agent logs
    * Verify `video_enabled=True` in room input options
  </Accordion>

  <Accordion title="High latency or choppy audio">
    * Check your network connection stability
    * Consider using LiveKit Cloud for optimized routing
    * Reduce video sampling frequency if CPU-bound
    * Monitor your LLM API response times
  </Accordion>
</AccordionGroup>

## API Reference

### AvatarSession

The main class for integrating Anam avatars with LiveKit agents.

```python  theme={"dark"}
avatar = anam.AvatarSession(
    persona_config=anam.PersonaConfig(...),
    api_key="your_api_key",
    api_url="https://api.anam.ai",  # Optional: defaults to production
)
```

<ParamField body="persona_config" type="PersonaConfig" required>
  Configuration for the avatar's identity and appearance.
</ParamField>

<ParamField body="api_key" type="string" required>
  Your Anam API key from the [dashboard](https://dashboard.anam.dev).
</ParamField>

<ParamField body="api_url" default="https://api.anam.ai" type="string">
  Anam API endpoint. Override for staging or self-hosted deployments.
</ParamField>

### PersonaConfig

<ParamField body="name" type="string" required>
  Display name for the avatar. Used in logs and debugging.
</ParamField>

<ParamField body="avatarId" type="string" required>
  UUID of the avatar to use. Get this from the [Avatar Gallery](/resources/avatar-gallery) or [Anam Lab](https://lab.anam.ai/avatars).
</ParamField>

### Methods

#### start()

Starts the avatar session and connects it to the LiveKit room.

```python  theme={"dark"}
await avatar.start(session, room=ctx.room)
```

<ParamField body="session" type="AgentSession" required>
  The LiveKit agent session to connect the avatar to.
</ParamField>

<ParamField body="room" type="rtc.Room" required>
  The LiveKit room instance from the job context.
</ParamField>

## Resources

<CardGroup cols={2}>
  <Card title="LiveKit Documentation" icon="book" href="https://docs.livekit.io">
    Official LiveKit docs for real-time communication
  </Card>

  <Card title="LiveKit Agents Guide" icon="robot" href="https://docs.livekit.io/agents">
    Build AI agents with LiveKit's Python SDK
  </Card>

  <Card title="Avatar Gallery" icon="images" href="/resources/avatar-gallery">
    Browse available stock avatars
  </Card>

  <Card title="Anam Lab" icon="flask" href="https://lab.anam.ai">
    Create custom avatars for your brand
  </Card>
</CardGroup>

## Support

<CardGroup cols={2}>
  <Card title="LiveKit Community" icon="slack" href="https://livekit.io/join-slack">
    Join the LiveKit Slack for community support
  </Card>

  <Card title="Report Issues" icon="github" href="https://github.com/anam-ai/livekit-plugins-anam/issues">
    Report bugs or request features on GitHub
  </Card>
</CardGroup>


# Client Tools and Events
Source: https://docs.anam.ai/tools/client-tools

Enable your AI persona to trigger actions and control your application's user interface

## Overview

Client tools allow your AI persona to trigger events in your client application. When the LLM invokes a client tool, the Anam SDK emits an event that your application can listen for, enabling the persona to:

* Navigate to specific pages or sections
* Open modals, dialogs, or overlays
* Update UI state based on conversation
* Trigger animations or visual effects
* Control media playback
* Submit forms or initiate actions

This creates a seamless voice-driven or chat-driven user experience where the AI can guide users through your application.

<Warning>**Beta Feature**: Tool calling is currently in beta. You may encounter some issues as we continue to improve the feature. Please report any feedback or issues to help us make it better.</Warning>

## How Client Tools Work

<Steps>
  <Step title="User makes a request">
    User: "Show me the pricing page"
  </Step>

  <Step title="LLM decides to call tool">
    The LLM recognizes this requires a client-side action and generates a tool call:

    ```json  theme={"dark"}
    {
      "name": "navigate_to_page",
      "arguments": {
        "page": "pricing"
      }
    }
    ```
  </Step>

  <Step title="SDK emits event">The Anam SDK emits a `TOOL_CALL` event that your application can handle.</Step>

  <Step title="Your app handles the event">
    Your event handler receives the tool call and executes the action:

    ```javascript  theme={"dark"}
    client.addListener(AnamEvent.TOOL_CALL, (event) => {
      if (event.toolName === "navigate_to_page") {
        window.location.href = `/${event.arguments.page}`;
      }
    });
    ```
  </Step>

  <Step title="LLM continues conversation">
    The persona confirms: "I've opened the pricing page for you!"

    <Check>
      The user experiences a seamless interaction between voice/chat and UI.
    </Check>
  </Step>
</Steps>

## Creating Client Tools

### Basic Client Tool Structure

A client tool requires four components:

<ParamField path="type" type="string" required>
  Must be `"client"` for client-side tools
</ParamField>

<ParamField path="name" type="string" required>
  Unique identifier for the tool (snake\_case, 1-64 characters)
</ParamField>

<ParamField path="description" type="string" required>
  Describes when the LLM should use this tool (helps with decision-making)
</ParamField>

<ParamField path="parameters" type="object">
  JSON Schema defining the parameters the tool accepts
</ParamField>

### Example: Page Navigation

```json  theme={"dark"}
{
  "type": "client",
  "name": "navigate_to_page",
  "description": "Navigate to a specific page when user asks to see pricing, features, documentation, or other sections",
  "parameters": {
    "type": "object",
    "properties": {
      "page": {
        "type": "string",
        "description": "The page to navigate to (pricing, features, docs, contact)",
        "enum": ["pricing", "features", "docs", "contact", "dashboard"]
      },
      "section": {
        "type": "string",
        "description": "Optional section anchor to scroll to"
      }
    },
    "required": ["page"]
  }
}
```

### Example: Open Modal

```json  theme={"dark"}
{
  "type": "client",
  "name": "open_modal",
  "description": "Open a modal dialog when user wants to perform an action like checkout, signup, or view details",
  "parameters": {
    "type": "object",
    "properties": {
      "modalType": {
        "type": "string",
        "description": "The type of modal to open",
        "enum": ["checkout", "signup", "login", "contact", "product_details"]
      },
      "data": {
        "type": "object",
        "description": "Additional data to pass to the modal",
        "properties": {
          "productId": { "type": "string" },
          "userId": { "type": "string" }
        }
      }
    },
    "required": ["modalType"]
  }
}
```

### Example: Update UI State

```json  theme={"dark"}
{
  "type": "client",
  "name": "update_filters",
  "description": "Update product filters when user describes what they're looking for",
  "parameters": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string",
        "description": "Product category"
      },
      "priceRange": {
        "type": "object",
        "properties": {
          "min": { "type": "number" },
          "max": { "type": "number" }
        }
      },
      "inStock": {
        "type": "boolean",
        "description": "Only show in-stock items"
      }
    }
  }
}
```

## Handling Tool Events in Your Application

### Setting Up Event Listeners

Use the SDK's `addListener` method to handle tool call events:

```javascript  theme={"dark"}
import { AnamClient, AnamEvent } from "@anam-ai/js-sdk";

const client = new AnamClient({
  sessionToken: "YOUR_SESSION_TOKEN",
});

// Listen for tool calls
client.addListener(AnamEvent.TOOL_CALL, (event) => {
  const { toolName, arguments: args } = event;

  switch (toolName) {
    case "navigate_to_page":
      window.location.href = `/${args.page}`;
      break;
    case "open_modal":
      openModal(args.modalType, args.data);
      break;
    default:
      console.warn(`Unhandled tool: ${toolName}`);
  }
});

// Start the session
await client.streamToVideoElement("video-element-id");
```

<Note>See the complete [SDK Reference](/sdk-reference/events#tool-call-events-detailed-guide) for all available events and methods.</Note>

## Real-World Examples

### E-commerce Shopping Assistant

Create a shopping assistant that can guide users through your product catalog:

```javascript  theme={"dark"}
const tools = [
  {
    type: "client",
    name: "show_product",
    description: "Display a product when user asks about specific items",
    parameters: {
      type: "object",
      properties: {
        productId: { type: "string" },
        productName: { type: "string" },
      },
      required: ["productId"],
    },
  },
  {
    type: "client",
    name: "add_to_cart",
    description: "Add a product to cart when user wants to purchase",
    parameters: {
      type: "object",
      properties: {
        productId: { type: "string" },
        quantity: { type: "number", default: 1 },
      },
      required: ["productId"],
    },
  },
  {
    type: "client",
    name: "apply_filter",
    description: "Filter products when user describes preferences",
    parameters: {
      type: "object",
      properties: {
        category: { type: "string" },
        maxPrice: { type: "number" },
        inStock: { type: "boolean" },
      },
    },
  },
  {
    type: "client",
    name: "open_checkout",
    description: "Open checkout when user is ready to purchase",
    parameters: {
      type: "object",
      properties: {},
    },
  },
];

// Event handler
function handleToolCall(toolName, args) {
  switch (toolName) {
    case "show_product":
      router.push(`/products/${args.productId}`);
      break;

    case "add_to_cart":
      cart.addItem(args.productId, args.quantity);
      showNotification(`Added ${args.quantity}x to cart`);
      break;

    case "apply_filter":
      productList.filter(args);
      break;

    case "open_checkout":
      router.push("/checkout");
      break;
  }
}
```

**Example conversation**:

* User: "Show me wireless headphones under \$100"
* AI: *Calls `apply_filter` with category: "headphones", maxPrice: 100*
* User: "I like the Sony ones"
* AI: *Calls `show_product` with productId: "sony-wh-1000xm4"*
* User: "Add them to my cart"
* AI: *Calls `add_to_cart`* "Added to your cart! Ready to checkout?"

### Customer Support Dashboard

Create a support agent that can navigate your dashboard:

```javascript  theme={"dark"}
const tools = [
  {
    type: "client",
    name: "show_ticket",
    description: "Display a support ticket when user mentions a ticket number",
    parameters: {
      type: "object",
      properties: {
        ticketId: { type: "string" },
      },
      required: ["ticketId"],
    },
  },
  {
    type: "client",
    name: "open_chat",
    description: "Open live chat with a human agent when issue needs escalation",
    parameters: {
      type: "object",
      properties: {
        reason: { type: "string", description: "Why escalating to human" },
      },
    },
  },
  {
    type: "client",
    name: "show_analytics",
    description: "Show analytics dashboard when user asks for metrics or reports",
    parameters: {
      type: "object",
      properties: {
        dateRange: { type: "string", enum: ["today", "week", "month"] },
      },
    },
  },
];
```

### SaaS Application Navigator

```javascript  theme={"dark"}
const tools = [
  {
    type: "client",
    name: "navigate_to_feature",
    description: "Navigate to a specific feature or section of the application",
    parameters: {
      type: "object",
      properties: {
        feature: {
          type: "string",
          enum: ["dashboard", "analytics", "settings", "billing", "team", "integrations"],
        },
      },
      required: ["feature"],
    },
  },
  {
    type: "client",
    name: "create_new",
    description: "Open creation modal for new items (project, user, campaign, etc.)",
    parameters: {
      type: "object",
      properties: {
        itemType: {
          type: "string",
          enum: ["project", "campaign", "user", "report"],
        },
        prefill: {
          type: "object",
          description: "Data to prefill in the creation form",
        },
      },
      required: ["itemType"],
    },
  },
  {
    type: "client",
    name: "run_export",
    description: "Export data when user requests a download",
    parameters: {
      type: "object",
      properties: {
        exportType: { type: "string", enum: ["csv", "pdf", "json"] },
        dataType: { type: "string" },
      },
    },
  },
];
```

## Best Practices

### Provide Clear Descriptions

The description helps the LLM decide when to use the tool:

```javascript  theme={"dark"}
// ✅ Good - Specific about when to use
{
  name: 'open_checkout',
  description: 'Open the checkout page when user explicitly says they want to purchase, buy, checkout, or complete their order'
}

// ❌ Bad - Too vague
{
  name: 'open_checkout',
  description: 'Opens checkout'
}
```

### Use Enums for Constrained Values

When parameters have a limited set of valid values, use enums:

```javascript  theme={"dark"}
{
  parameters: {
    type: 'object',
    properties: {
      page: {
        type: 'string',
        enum: ['home', 'pricing', 'features', 'contact'],
        description: 'The page to navigate to'
      }
    }
  }
}
```

This prevents the LLM from generating invalid values.

### Handle Errors Gracefully

Always validate tool arguments in your event handler:

```javascript  theme={"dark"}
function handleToolCall(toolName, args) {
  try {
    switch (toolName) {
      case "show_product":
        if (!args.productId) {
          console.error("Missing productId");
          return;
        }

        // Validate product exists
        if (!productExists(args.productId)) {
          showNotification("Product not found");
          return;
        }

        router.push(`/products/${args.productId}`);
        break;

      default:
        console.warn("Unknown tool:", toolName);
    }
  } catch (error) {
    console.error("Tool execution error:", error);
    showNotification("Something went wrong");
  }
}
```

### Provide User Feedback

Give immediate feedback when tools execute:

```javascript  theme={"dark"}
case 'add_to_cart':
  cart.addItem(args.productId, args.quantity);

  // Visual feedback
  showNotification(`Added ${args.quantity}x to cart`, 'success');

  // Update cart icon with animation
  cartIcon.classList.add('bounce');
  setTimeout(() => cartIcon.classList.remove('bounce'), 300);
  break;
```

### Test Tool Execution

Use browser console to debug tool calls by logging within your event handler:

```javascript  theme={"dark"}
client.addListener(AnamEvent.TOOL_CALL, (event) => {
  console.group("🔧 Tool Call");
  console.log("Tool:", event.toolName);
  console.log("Arguments:", event.arguments);
  console.log("Timestamp:", new Date().toISOString());
  console.groupEnd();

  handleToolCall(event.toolName, event.arguments);
});
```

## Security Considerations

### Validate All Parameters

Never trust client tool arguments without validation:

```javascript  theme={"dark"}
case 'navigate_to_page':
  // ✅ Validate against whitelist
  const validPages = ['home', 'pricing', 'features', 'contact'];
  if (!validPages.includes(args.page)) {
    console.error('Invalid page:', args.page);
    return;
  }

  window.location.href = `/${args.page}`;
  break;
```

### Avoid Exposing Sensitive Data

Don't include sensitive information in tool parameters:

```javascript  theme={"dark"}
// ❌ Bad - Exposes sensitive data
{
  name: 'show_user_profile',
  parameters: {
    userId: { type: 'string' },
    email: { type: 'string' },
    creditCard: { type: 'string' }  // Never expose this!
  }
}

// ✅ Good - Only IDs, fetch sensitive data server-side
{
  name: 'show_user_profile',
  parameters: {
    userId: { type: 'string' }
  }
}
```

### Rate Limit Tool Calls

Prevent abuse by tracking and limiting tool execution:

```javascript  theme={"dark"}
const toolCallCounts = {};
const MAX_CALLS_PER_MINUTE = 20;

function handleToolCall(toolName, args) {
  // Track calls
  const now = Date.now();
  toolCallCounts[toolName] = toolCallCounts[toolName] || [];
  toolCallCounts[toolName].push(now);

  // Remove old entries
  toolCallCounts[toolName] = toolCallCounts[toolName].filter((time) => now - time < 60000);

  // Check limit
  if (toolCallCounts[toolName].length > MAX_CALLS_PER_MINUTE) {
    console.warn("Too many tool calls");
    return;
  }

  // Execute tool...
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="code" href="/sdk-reference/events#tool-call-events-detailed-guide">
    Complete SDK documentation for tool events
  </Card>

  <Card title="Webhook Tools" icon="webhook" href="/guides/tools/webhook-tools">
    Integrate external APIs with webhook tools
  </Card>

  <Card title="Knowledge Tools" icon="database" href="/guides/tools/knowledge-tools">
    Search documents with RAG-powered tools
  </Card>

  <Card title="Tools API Reference" icon="book" href="/api-reference/tools/introduction">
    Complete API documentation
  </Card>
</CardGroup>


# Getting Started with Tools
Source: https://docs.anam.ai/tools/introduction

Create your first tool and enable function calling in your AI persona

## What You'll Build

In this guide, you'll create a complete AI persona with tool calling capabilities. By the end, you'll have:

* A knowledge base with uploaded documents
* Multiple tools (knowledge, webhook, and client)
* A working persona that can search documents, call APIs, and trigger client actions

<Warning>**Beta Feature**: Tools and Knowledge Base are currently in beta. You may encounter some issues as we continue to improve these features. Please report any feedback or issues to help us make them better.</Warning>

<Info>This guide takes approximately 15 minutes to complete. We'll use both the Anam Lab UI and API for a complete understanding.</Info>

## Prerequisites

Before starting, ensure you have:

* An Anam account (sign up at [anam.ai](https://anam.ai))
* An API key (create one at `/api-keys`)
* Basic familiarity with REST APIs
* (Optional) Node.js or Python for testing

## Step 1: Create a Knowledge Folder

Knowledge folders organize your documents for semantic search. Let's create one for product documentation.

<Tabs>
  <Tab title="UI">
    1. Navigate to the Knowledge Base page at `/knowledge`

    2. Click **Create Folder**

    3. Enter the following details:
       * **Name**: Product Documentation
       * **Description**: Technical guides and product information

    4. Click **Create**

    <Check>
      Your folder is created with a unique ID. Note this ID for later use.
    </Check>
  </Tab>

  <Tab title="API">
    ```bash cURL theme={"dark"}
    curl -X POST 'https://api.anam.ai/v1/knowledge/groups' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Product Documentation",
        "description": "Technical guides and product information"
      }'
    ```

    ```javascript Node.js theme={"dark"}
    const response = await fetch("https://api.anam.ai/v1/knowledge/groups", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Product Documentation",
        description: "Technical guides and product information",
      }),
    });

    const folder = await response.json();
    console.log("Folder ID:", folder.id);
    ```

    ```python Python theme={"dark"}
    import requests

    response = requests.post(
        'https://api.anam.ai/v1/knowledge/groups',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'name': 'Product Documentation',
            'description': 'Technical guides and product information'
        }
    )

    folder = response.json()
    print(f"Folder ID: {folder['id']}")
    ```
  </Tab>
</Tabs>

## Step 2: Upload Documents

Upload documents to make them searchable. We'll use a PDF user guide as an example.

<Tabs>
  <Tab title="UI">
    1. On the Knowledge Base page, click into your **Product Documentation** folder

    2. Click **Upload Documents**

    3. Drag and drop your PDF or click to browse

    4. Click **Upload**

    5. Wait for processing to complete (\~30 seconds)

    <Check>
      The document status changes from PROCESSING to READY. It's now searchable!
    </Check>
  </Tab>

  <Tab title="API">
    All documents uploaded via the API use a secure, three-step signed upload process. This is required for files of all sizes.

    **Step 1: Request a Signed Upload URL**

    ```bash  theme={"dark"}
    curl -X POST 'https://api.anam.ai/v1/knowledge/groups/YOUR_FOLDER_ID/documents/presigned-upload' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "filename": "user-guide.pdf",
        "contentType": "application/pdf",
        "fileSize": 2048000
      }'
    ```

    **Step 2: Upload Your File to the URL**

    ```bash  theme={"dark"}
    curl -X PUT 'SIGNED_URL_FROM_STEP_1' \
      -H 'Content-Type: application/pdf' \
      --data-binary '@user-guide.pdf'
    ```

    **Step 3: Confirm the Upload**

    ```bash  theme={"dark"}
    curl -X POST 'https://api.anam.ai/v1/knowledge/documents/DOCUMENT_ID_FROM_STEP_1/confirm-upload' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "fileSize": 2048000
      }'
    ```

    <Tip>
      For complete, copy-pasteable code examples in different languages, see the dedicated [Document Upload Guide](/knowledge/uploading-documents).
    </Tip>
  </Tab>
</Tabs>

<Warning>Documents must be in READY status before they can be searched. Processing typically takes 30 seconds but may take longer for large files.</Warning>

## Step 3: Create Your First Knowledge Tool

Now create a knowledge tool that searches your uploaded documents.

<Tabs>
  <Tab title="Stateful (Save to Database)">
    Create a tool that can be reused across multiple personas:

    1. Navigate to **Tools** at `/tools`

    2. Click **Create Tool**

    3. Select **Knowledge Tool**

    4. Fill in the details:
       * **Name**: `search_product_docs`
       * **Description**: `Search product documentation when users ask technical questions about features, installation, or usage`
       * **Knowledge Folders**: Select "Product Documentation"

    5. Click **Create Tool**

    <Check>The tool is now saved and can be attached to any persona in your organization.</Check>

    **To attach to a persona**:

    * Go to `/build/{personaId}`
    * In the Tools section, select your newly created tool
    * Save the persona

    When you create sessions with this persona, the tool will automatically be available.
  </Tab>

  <Tab title="Ephemeral (API Only)">
    Define tools inline when creating a session without saving them to the database:

    ```javascript  theme={"dark"}
    const toolConfig = {
      type: "server",
      subtype: "knowledge",
      name: "search_product_docs",
      description: "Search product documentation when users ask technical questions about features, installation, or usage",
      documentFolderIds: ["550e8400-e29b-41d4-a716-446655440000"], // Use the folder ID from Step 1
    };

    // Use this when creating a session token (Step 6)
    ```

    <Tip>
      Ephemeral tools are perfect for dynamic configurations or user-specific knowledge bases that change per session.
    </Tip>
  </Tab>
</Tabs>

## Step 4: Create All Necessary Tools

Before creating a session, you must create all the tools your persona will need via the API or the UI. Each tool will be assigned a unique ID. For this guide, let's assume you've created three tools and have their IDs:

* **Knowledge Tool**: `search_product_docs` (ID: `tool-knowledge-123`)
* **Webhook Tool**: `check_order_status` (ID: `tool-webhook-456`)
* **Client Tool**: `open_product_page` (ID: `tool-client-789`)

<Info>You can create stateful tools via the `POST /v1/tools` endpoint or in the Anam Lab at `/tools`.</Info>

## Step 5: Create a Session with Tools

Now, let's bring it all together by creating an ephemeral persona session that uses the tools we created.

<Steps>
  <Step title="Create session token">
    In the `personaConfig`, provide the `toolIds` array containing the unique IDs of your pre-created tools.

    ```javascript  theme={"dark"}
    const sessionTokenResponse = await fetch("https://api.anam.ai/v1/auth/session-token", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        personaConfig: {
          name: "Product Support Agent",
          avatarId: "YOUR_AVATAR_ID",
          voiceId: "YOUR_VOICE_ID",
          llmId: "YOUR_LLM_ID",
          systemPrompt: `You are a helpful product support agent. You can:
    - Search product documentation to answer technical questions
    - Check order status for customers
    - Open product pages when customers want more details

    Be friendly, concise, and proactive in helping customers.`,
          toolIds: [
            "tool-knowledge-123", // The ID of your knowledge tool
            "tool-webhook-456", // The ID of your webhook tool
            "tool-client-789", // The ID of your client tool
          ],
        },
      }),
    });

    const { sessionToken } = await sessionTokenResponse.json();
    ```
  </Step>

  <Step title="Start engine session">
    ```javascript  theme={"dark"}
    const sessionResponse = await fetch(
      'https://api.anam.ai/v1/engine/session',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${sessionToken}`
        }
      }
    );

    const { ws_url, session_id } = await sessionResponse.json();
    console.log('WebSocket URL:', ws_url);

    ```
  </Step>

  <Step title="Connect via WebSocket">
    ```javascript  theme={"dark"}
    const ws = new WebSocket(ws_url);

    ws.onopen = () => {
    console.log('Connected to Anam engine');
    };

    ws.onmessage = (event) => {
      const message = JSON.parse(event.data);

      // Handle tool execution events
      if (message.type === 'tool_call') {
        console.log('Tool called:', message.toolName);
        console.log('Arguments:', message.arguments);

        // Handle client tool events in your app
        if (message.toolName === 'open_product_page') {
          window.location.href = `/products/${message.arguments.productId}`;
        }
      }
    };
    ```

    <Check>
      Your persona can now search documents, call APIs, and trigger client actions!
    </Check>
  </Step>
</Steps>

## Testing Your Tools

Let's test the complete setup with example conversations:

### Testing Knowledge Tool

**User**: "How do I install the product?"

**Expected flow**:

1. LLM recognizes this as a technical question
2. Invokes `search_product_docs` tool
3. Retrieves relevant chunks from your user guide
4. Responds with accurate installation steps

### Testing Webhook Tool

**User**: "What's the status of my order ORD-12345?"

**Expected flow**:

1. LLM extracts order ID `ORD-12345`
2. Calls `check_order_status` webhook with `orderId: "ORD-12345"`
3. Receives response from your API
4. Tells user the current order status

### Testing Client Tool

**User**: "Show me more details about the premium plan"

**Expected flow**:

1. LLM identifies product name "premium plan"
2. Calls `open_product_page` client tool
3. Your app receives event via WebSocket
4. Navigation happens: `window.location.href = '/products/premium-plan'`

<Tip>Use your browser's developer console to see tool call events in real-time. This helps debug and understand the execution flow.</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Knowledge tool returns no results">
    **Possible causes**:

    * Document still processing (check status)
    * Query doesn't match document content
    * Folder ID incorrect

    **Solutions**:

    1. Wait for document status to be READY
    2. Test query with debug modal (`Ctrl+Shift+K` on knowledge page)
    3. Verify folder ID in tool configuration
  </Accordion>

  <Accordion title="Webhook tool times out">
    **Possible causes**:

    * External API is slow (>60s timeout)
    * Network connectivity issues
    * Invalid endpoint URL

    **Solutions**:

    1. Check endpoint URL is correct
    2. Test endpoint independently with curl
    3. Ensure API returns response within 60 seconds
    4. Check authentication headers are valid
  </Accordion>

  <Accordion title="Client tool event not received">
    **Possible causes**:

    * WebSocket connection not established
    * Event handler not configured
    * Tool name mismatch

    **Solutions**:

    1. Verify WebSocket connection: check `ws.readyState === 1`
    2. Add event listener for `tool_call` message type
    3. Match tool name exactly (case-sensitive)
  </Accordion>
</AccordionGroup>

## Best Practices

### Tool Naming

Use descriptive, action-oriented names:

```typescript  theme={"dark"}
// ✅ Good
search_product_docs;
check_order_status;
open_checkout_page;

// ❌ Bad
search;
api_call;
tool1;
```

### Tool Descriptions

Be specific about when the LLM should use the tool:

```typescript  theme={"dark"}
// ✅ Good
description: "Search product documentation when users ask technical questions about features, installation, troubleshooting, or usage";

// ❌ Bad
description: "Searches documents";
```

### System Prompts

Guide the LLM on how to use tools effectively:

```typescript  theme={"dark"}
systemPrompt: `You are a helpful support agent. You have access to:
- Product documentation (use search_product_docs for technical questions)
- Order tracking system (use check_order_status when users mention order numbers)
- Product pages (use open_product_page when users want to see details)

Always be helpful and proactive. If a user mentions an order number, offer to check its status.`;
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Tool Events" icon="browser" href="/guides/tools/client-tools">
    Learn to handle client tool events in your application
  </Card>

  <Card title="Knowledge Tools Deep Dive" icon="magnifying-glass" href="/guides/tools/knowledge-tools">
    Advanced knowledge tool configuration and optimization
  </Card>

  <Card title="Webhook Tools Guide" icon="webhook" href="/guides/tools/webhook-tools">
    Integrate external APIs with webhook tools
  </Card>

  <Card title="SDK Reference" icon="code" href="/sdk-reference/events#tool-call-events-detailed-guide">
    Complete SDK documentation for tool events
  </Card>
</CardGroup>


# Knowledge Tools and RAG
Source: https://docs.anam.ai/tools/knowledge-tools

Enable semantic search across your documents using Retrieval-Augmented Generation

## Overview

Knowledge tools enable your AI persona to search uploaded documents and provide accurate, source-based answers using Retrieval-Augmented Generation (RAG). Instead of relying only on the LLM's training data, your persona can access your organization's specific documentation, policies, and knowledge base.

This guide covers how to create and optimize knowledge tools for maximum accuracy and relevance.

## Prerequisites

Before creating knowledge tools, you need:

* Knowledge folders created (see [Knowledge Base Setup](/knowledge/setup))
* Documents uploaded and in READY status
* Basic understanding of RAG concepts (see [Knowledge Base Overview](/concepts/knowledge-base))

## Creating a Knowledge Tool

<Tabs>
  <Tab title="Stateful (Database-Saved)">
    Create reusable tools in the Anam Lab that can be attached to multiple personas.

    <Steps>
      <Step title="Create the tool">
        Navigate to `/tools` in the Anam Lab and create your knowledge tool:

        1. Click **Create Tool**

        2. Select **Knowledge Tool**

        3. Fill in the configuration:
           * **Name**: `search_product_docs` (snake\_case)
           * **Description**: Clear description of when to use this tool
           * **Knowledge Folders**: Select one or more folders

        4. Click **Create Tool**

        <Check>
          The tool is now saved with a unique ID and appears in your organization's tool library.
        </Check>
      </Step>

      <Step title="Attach tool to persona">
        Navigate to `/build/{personaId}` and attach the tool:

        1. Scroll to the **Tools** section
        2. Click **Add Tool**
        3. Select `search_product_docs` from the dropdown
        4. Save the persona

        <Check>
          The tool is now attached to this persona. When you create sessions with this persona, the tool will automatically be available.
        </Check>
      </Step>

      <Step title="Use in session">
        Create a session using the persona ID:

        ```javascript  theme={"dark"}
        const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
          method: "POST",
          headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            personaConfig: {
              personaId: "your-persona-id", // Tools loaded automatically
            },
          }),
        });
        ```
      </Step>
    </Steps>

    <Note>
      Stateful tools are ideal when you want to reuse the same tool across multiple personas or manage tools centrally.
    </Note>
  </Tab>
</Tabs>

## How Knowledge Tools Work

When the AI needs information to answer a question, it uses a knowledge tool to search your documents.

<Steps>
  <Step title="User asks a question">
    User: "How do I authenticate API requests?"
  </Step>

  <Step title="AI decides to search">
    The AI determines the question requires information from your documentation and automatically formulates a search query.

    <Info>
      The AI is smart about searching. It looks for the meaning behind the user's question, not just literal keywords.
    </Info>
  </Step>

  <Step title="System finds relevant content">The system searches the folders associated with the tool and retrieves the most relevant snippets from your documents.</Step>

  <Step title="AI generates a response">
    The AI uses the retrieved information to construct an accurate, conversational answer.

    "To authenticate API requests, you'll need to include your API key in the Authorization header like this: `Authorization: Bearer YOUR_API_KEY`. You can get an API key from your dashboard."

    <Check>
      The user receives an answer grounded in your specific documentation.
    </Check>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Knowledge Base Setup" icon="upload" href="/guides/knowledge/setup">
    Create folders and upload documents
  </Card>

  <Card title="Client Tools" icon="browser" href="/guides/tools/client-tools">
    Trigger UI actions with client tools
  </Card>

  <Card title="Webhook Tools" icon="webhook" href="/guides/tools/webhook-tools">
    Integrate external APIs
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/knowledge/introduction">
    Complete API documentation
  </Card>
</CardGroup>


# Webhook Tools
Source: https://docs.anam.ai/tools/webhook-tools

Integrate external APIs and services by calling HTTP endpoints from your AI persona

## Overview

Webhook tools enable your AI persona to call external HTTP endpoints during conversations. This allows integration with any REST API, enabling your persona to:

* Check order or shipment status from your e-commerce system
* Create support tickets in your helpdesk software
* Update CRM records based on conversation context
* Fetch real-time data (weather, stock prices, availability)
* Trigger workflows in external systems
* Send notifications or alerts
* Log conversation events

Webhook tools run server-side, keeping your API credentials secure and allowing the LLM to use response data in its answers.

<Warning>
  **Beta Feature**: Tool calling is currently in beta. You may encounter some issues as we continue to improve the feature. Please report any feedback or issues to help us make it better.

  **Response time requirements**: Webhooks should respond quickly to maintain natural conversation flow:

  * **Ideal**: Under 1 second
  * **Maximum**: 5 seconds
  * **Timeout**: 60 seconds (hard limit)

  For operations taking longer than 5 seconds, use the split pattern: one webhook to start the process, another to check status later.
</Warning>

<Tip>
  Webhooks are perfect for implementing complex agentic workflows. Beyond simple
  data retrieval, use them to orchestrate multi-step processes, integrate with
  third-party services, and build sophisticated AI-driven automation.
</Tip>

## Creating a Webhook Tool

<Tabs>
  <Tab title="Stateful (Database-Saved)">
    Create webhook tools in the Anam Lab that can be reused across personas:

    <Steps>
      <Step title="Create the tool">
        Navigate to `/tools` in the Anam Lab:

        1. Click **Create Tool**
        2. Select **Webhook Tool**
        3. Fill in the configuration:
           * **Name**: `check_order_status` (snake\_case)
           * **Description**: When the LLM should call this webhook
           * **URL**: Your API endpoint
           * **Method**: GET, POST, PUT, PATCH, or DELETE
           * **Headers**: Authentication and content-type headers
           * **Parameters**: JSON Schema for request body
           * **Await Response**: Whether to wait for the response

        <Check>
          The tool is now saved and can be attached to any persona.
        </Check>
      </Step>

      <Step title="Attach to persona">
        Navigate to `/build/{personaId}`:

        1. Scroll to the **Tools** section
        2. Click **Add Tool**
        3. Select your webhook tool from the dropdown
        4. Save the persona
      </Step>

      <Step title="Use in session">
        Create a session with the persona ID:

        ```javascript  theme={"dark"}
        const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
          method: "POST",
          headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            personaConfig: {
              personaId: "your-persona-id",
            },
          }),
        });
        ```
      </Step>
    </Steps>

    <Note>
      Stateful tools are ideal for organization-wide integrations where the same webhook is used by multiple personas.
    </Note>
  </Tab>
</Tabs>

## Tool Configuration

### Required Fields

<ParamField path="type" type="string" required>
  Must be `"server"` for webhook tools
</ParamField>

<ParamField path="subtype" type="string" required>
  Must be `"webhook"` for HTTP endpoint tools
</ParamField>

<ParamField path="name" type="string" required>
  Unique identifier for the tool. Must be 1-64 characters, snake\_case format.

  **Examples**: `check_order_status`, `create_ticket`, `update_crm_contact`
</ParamField>

<ParamField path="description" type="string" required>
  Describes when the LLM should invoke this webhook (1-1024 characters). Be specific about:

  * What triggers the webhook call
  * What data the webhook provides
  * When NOT to use it

  **Example**: `"Check order status when customer mentions an order number or asks about delivery, tracking, or shipping. Use the order ID from the conversation."`
</ParamField>

<ParamField path="url" type="string" required>
  The HTTP endpoint to call. Must be a valid HTTPS URL (HTTP allowed for development).

  **Example**: `https://api.yourcompany.com/v1/orders/status`
</ParamField>

<ParamField path="method" type="string" required>
  HTTP method to use. Supported values: - `GET`: Retrieve data - `POST`: Create
  or query data (most common) - `PUT`: Update entire resource - `PATCH`: Partial
  update - `DELETE`: Remove resource
</ParamField>

### Optional Fields

<ParamField path="headers" type="object">
  HTTP headers to include in the request. Common headers:

  * `Authorization`: API keys or bearer tokens
  * `Content-Type`: Usually `application/json`
  * `X-API-Key`: Alternative auth header
  * Custom headers specific to your API

  **Example**:

  ```json  theme={"dark"}
  {
    "Authorization": "Bearer sk_live_abc123",
    "Content-Type": "application/json",
    "X-Organization-ID": "org_xyz"
  }
  ```
</ParamField>

<ParamField path="parameters" type="object">
  JSON Schema defining the request body structure. The LLM extracts these values from the conversation.

  **Example**:

  ```json  theme={"dark"}
  {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Customer order ID"
      },
      "includeDetails": {
        "type": "boolean",
        "description": "Whether to include detailed tracking info"
      }
    },
    "required": ["orderId"]
  }
  ```
</ParamField>

<ParamField path="awaitResponse" type="boolean" default={true}>
  Whether to wait for the webhook response before continuing:

  * `true` (default): LLM waits for response and uses it in the answer
  * `false`: Fire-and-forget, useful for logging or notifications

  **Timeout**: 60 seconds maximum
</ParamField>

## How Webhook Tools Work

<Steps>
  <Step title="User mentions relevant information">
    User: "What's the status of my order ORD-12345?"
  </Step>

  <Step title="LLM extracts parameters">
    The LLM recognizes this requires the `check_order_status` webhook and extracts parameters:

    ```json  theme={"dark"}
    {
      "toolName": "check_order_status",
      "arguments": {
        "orderId": "ORD-12345"
      }
    }
    ```
  </Step>

  <Step title="Server makes HTTP request">
    Anam's servers call your webhook endpoint:

    ```http  theme={"dark"}
    POST https://api.yourcompany.com/orders/status
    Authorization: Bearer YOUR_API_SECRET
    Content-Type: application/json

    {
      "orderId": "ORD-12345"
    }
    ```

    <Info>
      The request originates from Anam's servers, not the client. Your API credentials stay secure.
    </Info>
  </Step>

  <Step title="Your API responds">
    Your endpoint returns the order data:

    ```json  theme={"dark"}
    {
      "orderId": "ORD-12345",
      "status": "shipped",
      "trackingNumber": "1Z999AA10123456784",
      "estimatedDelivery": "2024-03-15",
      "carrier": "UPS"
    }
    ```
  </Step>

  <Step title="LLM generates response">
    The LLM receives the webhook response and incorporates it into a natural language answer:

    "Your order ORD-12345 has been shipped! It's currently in transit with UPS (tracking number 1Z999AA10123456784) and should arrive by March 15th."

    <Check>
      The user receives real-time, accurate information from your systems.
    </Check>
  </Step>
</Steps>

## Common Use Cases

### E-commerce: Order Status

```json  theme={"dark"}
{
  "type": "server",
  "subtype": "webhook",
  "name": "check_order_status",
  "description": "Check customer order status when they ask about delivery, shipping, or tracking",
  "url": "https://api.yourstore.com/orders/status",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Order ID or order number"
      },
      "email": {
        "type": "string",
        "description": "Customer email for verification"
      }
    },
    "required": ["orderId"]
  },
  "awaitResponse": true
}
```

### Support: Create Ticket

```json  theme={"dark"}
{
  "type": "server",
  "subtype": "webhook",
  "name": "create_support_ticket",
  "description": "Create a support ticket when customer reports a bug, issue, or problem that needs follow-up",
  "url": "https://api.zendesk.com/api/v2/tickets",
  "method": "POST",
  "headers": {
    "Authorization": "Basic BASE64_CREDENTIALS",
    "Content-Type": "application/json"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "subject": {
        "type": "string",
        "description": "Brief summary of the issue"
      },
      "description": {
        "type": "string",
        "description": "Detailed description of the problem"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high", "urgent"],
        "description": "Ticket priority based on severity"
      }
    },
    "required": ["subject", "description"]
  },
  "awaitResponse": true
}
```

### CRM: Update Contact

```json  theme={"dark"}
{
  "type": "server",
  "subtype": "webhook",
  "name": "update_contact_info",
  "description": "Update customer contact information when they provide new email, phone, or address",
  "url": "https://api.salesforce.com/services/data/v55.0/sobjects/Contact",
  "method": "PATCH",
  "headers": {
    "Authorization": "Bearer SALESFORCE_TOKEN",
    "Content-Type": "application/json"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "contactId": {
        "type": "string",
        "description": "Salesforce contact ID"
      },
      "email": {
        "type": "string",
        "description": "New email address"
      },
      "phone": {
        "type": "string",
        "description": "New phone number"
      }
    },
    "required": ["contactId"]
  },
  "awaitResponse": false
}
```

### Real-time Data: Weather

```json  theme={"dark"}
{
  "type": "server",
  "subtype": "webhook",
  "name": "get_weather",
  "description": "Get current weather conditions when user asks about weather for a specific location",
  "url": "https://api.openweathermap.org/data/2.5/weather",
  "method": "GET",
  "headers": {
    "X-API-Key": "YOUR_WEATHER_API_KEY"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      },
      "units": {
        "type": "string",
        "enum": ["metric", "imperial"],
        "description": "Temperature units"
      }
    },
    "required": ["city"]
  },
  "awaitResponse": true
}
```

### Availability Check

```json  theme={"dark"}
{
  "type": "server",
  "subtype": "webhook",
  "name": "check_product_availability",
  "description": "Check if a product is in stock when customer asks about availability",
  "url": "https://api.yourstore.com/inventory/check",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "productId": {
        "type": "string",
        "description": "Product SKU or ID"
      },
      "location": {
        "type": "string",
        "description": "Store location or warehouse"
      }
    },
    "required": ["productId"]
  },
  "awaitResponse": true
}
```

## Best Practices

### Security

<AccordionGroup>
  <Accordion title="Use HTTPS endpoints">
    Always use HTTPS (not HTTP) for production webhooks to encrypt data in transit.

    ```json  theme={"dark"}
    // ✅ Good
    "url": "https://api.yourcompany.com/endpoint"

    // ❌ Bad (except for local development)
    "url": "http://api.yourcompany.com/endpoint"
    ```
  </Accordion>

  <Accordion title="Secure API credentials">
    Never hardcode production credentials in ephemeral tools. Use environment variables or secret management:

    ```javascript  theme={"dark"}
    // ✅ Good - Use environment variables
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET}`
    }

    // ❌ Bad - Hardcoded credentials
    headers: {
      'Authorization': 'Bearer sk_live_abc123xyz_real_key'
    }
    ```

    For stateful tools created in the UI, credentials are stored encrypted in the database.
  </Accordion>

  <Accordion title="Validate webhook responses">
    Your API should validate requests and return appropriate error messages:

    ```json  theme={"dark"}
    // Good error response
    {
      "error": "Order not found",
      "orderId": "ORD-12345",
      "suggestion": "Please check the order number and try again"
    }
    ```

    The LLM will communicate errors naturally to the user.
  </Accordion>

  <Accordion title="Rate limiting">
    Implement rate limiting on your endpoints to prevent abuse:

    * Track requests per API key
    * Return `429 Too Many Requests` when limit exceeded
    * Include `Retry-After` header
  </Accordion>
</AccordionGroup>

### Performance

<AccordionGroup>
  <Accordion title="Keep responses fast">
    Webhooks should respond quickly to maintain conversation flow:

    * **Target**: Under 1 second for best experience
    * **Maximum recommended**: 5 seconds
    * **Hard timeout**: 60 seconds

    Optimization strategies:

    * Use caching for frequently requested data
    * Defer slow operations to background jobs (use split pattern)
    * Return partial data quickly rather than waiting for complete results
    * Database queries should be indexed and optimized
  </Accordion>

  <Accordion title="Use fire-and-forget when appropriate">
    Set `awaitResponse: false` for operations that don't need to return data:

    ```json  theme={"dark"}
    {
      "name": "log_conversation_event",
      "awaitResponse": false // Don't wait, just log it
    }
    ```

    This improves response time since the LLM doesn't wait for confirmation.
  </Accordion>

  <Accordion title="Return only necessary data">
    Keep webhook responses concise. The LLM only needs relevant information:

    ```json  theme={"dark"}
    // ✅ Good - Concise, relevant data
    {
      "status": "shipped",
      "trackingNumber": "1Z999AA10123456784",
      "estimatedDelivery": "2024-03-15"
    }

    // ❌ Too verbose - Unnecessary data
    {
      "orderId": "ORD-12345",
      "customerId": "CUST-789",
      "items": [...100 items],
      "internalNotes": "...",
      "warehouseData": {...},
      // ... lots of irrelevant data
    }
    ```
  </Accordion>
</AccordionGroup>

### Error Handling

<AccordionGroup>
  <Accordion title="Return meaningful error messages">
    Help the LLM understand what went wrong:

    ```json  theme={"dark"}
    // ✅ Good error response
    {
      "error": true,
      "message": "Order ORD-12345 not found in our system",
      "suggestion": "Please verify the order number or contact support at support@company.com"
    }

    // ❌ Bad error response
    {
      "error": "NOT_FOUND"
    }
    ```
  </Accordion>

  <Accordion title="Handle missing parameters gracefully">
    Your API should handle missing or invalid parameters:

    ```json  theme={"dark"}
    {
      "error": true,
      "message": "Missing required parameter: orderId",
      "requiredParameters": ["orderId"],
      "example": {
        "orderId": "ORD-12345"
      }
    }
    ```
  </Accordion>

  <Accordion title="Use appropriate HTTP status codes">
    Return correct status codes for different scenarios:

    * `200 OK`: Success
    * `400 Bad Request`: Invalid parameters
    * `401 Unauthorized`: Invalid API key
    * `404 Not Found`: Resource doesn't exist
    * `429 Too Many Requests`: Rate limit exceeded
    * `500 Internal Server Error`: Server error
  </Accordion>
</AccordionGroup>

## Testing Webhook Tools

### Local Development

For local testing, use tunneling services to expose your localhost:

```bash  theme={"dark"}
# Using ngrok
ngrok http 3000

# Use the ngrok URL in your webhook tool
# Example: https://abc123.ngrok.io/api/orders
```

### Test Mode

Create a test version of your webhook tool:

```json  theme={"dark"}
{
  "name": "check_order_status_test",
  "url": "https://api-staging.yourcompany.com/orders/status",
  "headers": {
    "Authorization": "Bearer TEST_API_KEY"
  }
}
```

### Mock Responses

For development without a backend, use mock API services:

* [Mocky.io](https://www.mocky.io/)
* [JSONPlaceholder](https://jsonplaceholder.typicode.com/)
* [Postman Mock Server](https://www.postman.com/features/mock-api/)

```json  theme={"dark"}
{
  "name": "check_order_status_mock",
  "url": "https://run.mocky.io/v3/your-mock-id",
  "method": "GET"
}
```

### Logging and Debugging

Add logging to your webhook endpoint to debug issues:

```javascript  theme={"dark"}
app.post("/api/orders/status", async (req, res) => {
  console.log("Webhook called:", {
    timestamp: new Date().toISOString(),
    body: req.body,
    headers: req.headers,
    source: "anam",
  });

  try {
    const result = await checkOrderStatus(req.body.orderId);
    console.log("Webhook success:", result);
    res.json(result);
  } catch (error) {
    console.error("Webhook error:", error);
    res.status(500).json({
      error: true,
      message: error.message,
    });
  }
});
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not being called">
    **Possible causes**:

    * Description too vague for LLM to understand when to use it
    * System prompt doesn't mention the webhook capability
    * Missing required parameters in conversation

    **Solutions**:

    1. Make description more specific with trigger words
    2. Update system prompt to mention the webhook
    3. Test with explicit parameter values in conversation
    4. Check server logs to see if request was made
  </Accordion>

  <Accordion title="Webhook timing out">
    **Possible causes**:

    * Endpoint takes >60 seconds to respond
    * Network issues or slow database queries
    * Endpoint not accessible from Anam servers

    **Solutions**:

    1. Optimize endpoint performance
    2. Check endpoint is publicly accessible (not localhost in production)
    3. Verify firewall rules allow Anam's IP range
    4. Use fire-and-forget (`awaitResponse: false`) for slow operations
  </Accordion>

  <Accordion title="Authentication errors">
    **Possible causes**:

    * Incorrect API key or token
    * Expired credentials
    * Wrong authentication header format

    **Solutions**:

    1. Verify credentials are current and valid
    2. Check header format matches API requirements
    3. Test endpoint directly with same credentials using curl/Postman
    4. Check for typos in header names (case-sensitive)
  </Accordion>

  <Accordion title="Incorrect parameter values">
    **Possible causes**:

    * LLM extracting wrong values from conversation
    * Parameter descriptions unclear
    * User providing ambiguous information

    **Solutions**:

    1. Improve parameter descriptions with examples
    2. Update system prompt with parameter extraction guidance
    3. Ask users to confirm values before making webhook call
  </Accordion>
</AccordionGroup>

## Advanced Patterns

### Chaining Multiple Webhooks

The LLM can call multiple webhooks in sequence:

**User**: "Check my order ORD-12345 and create a ticket if there's a problem"

**LLM flow**:

1. Calls `check_order_status` → finds delay
2. Calls `create_support_ticket` → creates ticket
3. Responds: "I checked your order and it's delayed. I've created support ticket #789 to investigate."

### Conditional Webhooks

Use system prompt to guide conditional webhook usage:

```
If the order status is "delayed" or "problem", automatically create a support ticket.
If the user asks about weather and mentions travel, also check flight status.
```

### Dynamic Parameters

Extract multiple pieces of information from complex requests:

```json  theme={"dark"}
{
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string" },
      "action": {
        "type": "string",
        "enum": ["check_status", "cancel", "modify"],
        "description": "What the user wants to do with the order"
      },
      "reason": {
        "type": "string",
        "description": "Reason for cancellation or modification"
      }
    }
  }
}
```

### Long-Running Processes (A Recommended Pattern)

For backend processes that take longer than 5 seconds (like generating a report or running a batch job), the conversation can feel stalled. To keep the interaction fluid, we recommend a "split pattern" where you create two separate webhooks.

This is a design pattern that **you implement on your backend**. You are responsible for creating the two endpoints and managing the state of the job. The Anam agent's role is simply to call the webhooks you provide.

<Steps>
  <Step title="Step 1: Create a 'start' webhook">
    This webhook initiates the long-running process. It should immediately return a unique `jobId` and an estimated completion time.

    ```json  theme={"dark"}
    {
      "name": "start_report_generation",
      "description": "Starts generating a custom report. Returns a job ID.",
      "url": "https://api.example.com/reports/start",
      "awaitResponse": true,
      "parameters": {
        "type": "object",
        "properties": {
          "reportType": { "type": "string" },
          "dateRange": { "type": "string" }
        }
      }
    }
    ```
  </Step>

  <Step title="Step 2: Create a 'check status' webhook">
    This webhook checks the status of the job using the `jobId`. It should return the status and, if complete, the final result (e.g., a download URL).

    ```json  theme={"dark"}
    {
      "name": "check_report_status",
      "description": "Checks the status of a report generation job.",
      "url": "https://api.example.com/reports/status",
      "awaitResponse": true,
      "parameters": {
        "type": "object",
        "properties": {
          "jobId": {
            "type": "string",
            "description": "The job ID returned from start_report_generation"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Step 3: Guide the AI with a system prompt">
    Instruct the AI on how to use this two-step process.

    ```
    When a user asks for a report, first call `start_report_generation`. Inform the user that the report is being generated and tell them the estimated wait time. After waiting, proactively call `check_report_status` to see if it's ready.
    ```
  </Step>
</Steps>

**Example Conversation Flow**:

1. **User**: "Can you generate a sales report for last month?"
2. **AI**:
   * Calls your `start_report_generation` webhook.
   * Your backend starts the job, saves its state (e.g., `status: 'PENDING'`) in a database, and immediately returns `{ "jobId": "job_123", "estimatedTime": "30 seconds" }`.
   * Responds: "I've started generating your sales report. It should be ready in about 30 seconds. I can let you know when it's done."
3. *(AI continues the conversation on other topics...)*
4. **AI (after \~30 seconds)**:
   * Proactively calls your `check_report_status` webhook with `jobId: "job_123"`.
   * Your backend checks the job's state. If it's done, it returns `{ "status": "COMPLETE", "url": "https://.../report.pdf" }`.
   * Responds: "Great news! That sales report you asked for is ready. You can download it here: \[link]."

<Tip>
  This pattern works for any long-running operation: data exports, batch
  processing, AI model inference, video processing, etc. The key is providing
  immediate feedback that the process has started, then checking back later.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Knowledge Tools" icon="database" href="/guides/tools/knowledge-tools">
    Search documents with RAG-powered tools
  </Card>

  <Card title="Client Tools" icon="browser" href="/guides/tools/client-tools">
    Trigger UI actions from your persona
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tools/introduction">
    Complete tools API documentation
  </Card>

  <Card title="Getting Started" icon="rocket" href="/guides/tools/introduction">
    Create your first tool in 5 minutes
  </Card>
</CardGroup>