### Scalable Folder Structure Example

Source: https://anam.ai/docs/personas/knowledge/setup

Plan for future growth by choosing a structure that allows for subdivision. Start simple but anticipate expansion.

```text
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()

Source: https://anam.ai/docs/livekit/configuration

Starts the avatar session and connects it to the LiveKit room.

```APIDOC
## start()

Starts the avatar session and connects it to the LiveKit room.
```
await avatar.start(session, room=ctx.room)

```

### Parameters

* **session** (AgentSession) - Required - The LiveKit agent session to connect the avatar to.
* **room** (rtc.Room) - Required - The LiveKit room instance from the job context.
```

--------------------------------

### Install Optional Display Dependencies

Source: https://anam.ai/docs/python-sdk/installation

Install additional utilities for local video and audio playback.

```bash
pip install anam[display]
```

--------------------------------

### Example System Prompt for Tool Guidance

Source: https://anam.ai/docs/guides/tools/introduction

A system prompt guides the LLM on how to effectively use available tools. It should outline the purpose of each tool and provide context for when to use them.

```javascript
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.`;

```

--------------------------------

### Start the Server

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

Run this command in your terminal to start the Node.js server for the application.

```bash
node server.js
```

--------------------------------

### Verify Anam SDK Installation

Source: https://anam.ai/docs/python-sdk/installation

Check the installed version of the Anam SDK to confirm successful setup.

```python
import anam
print(anam.__version__)
```

--------------------------------

### Install Anam Python SDK with uv

Source: https://anam.ai/docs/llms-full.txt

Alternative installation method using uv. Ensure you have Python 3.10 or higher.

```bash
uv add anam
```

--------------------------------

### Install livekit-plugins-anam

Source: https://anam.ai/docs/livekit/configuration

Install the necessary Anam AI plugin for LiveKit.

```bash
pip install livekit-plugins-anam

```

--------------------------------

### Clone LiveKit Agent Starter and Install Dependencies

Source: https://anam.ai/docs/integrations/livekit/quickstart

Clone the LiveKit Node.js agent starter repository and install its dependencies using pnpm.

```bash
git clone https://github.com/livekit-examples/agent-starter-node.git
cd agent-starter-node
pnpm install
```

--------------------------------

### Install Anam SDK and Chatdio

Source: https://anam.ai/docs/javascript-sdk/examples/custom-tts

Install the necessary packages for Anam SDK and Chatdio, which provides microphone capture utilities.

```bash
npm install @anam-ai/js-sdk chatdio
```

--------------------------------

### Install Anam Python SDK from PyPI

Source: https://anam.ai/docs/llms-full.txt

Use this command to install the Anam Python SDK. Ensure you have Python 3.10 or higher.

```bash
pip install anam
```

--------------------------------

### Install SDK with npm

Source: https://anam.ai/docs/javascript-sdk/reference/basic-usage

Install the Anam AI JavaScript SDK in your project using npm.

```bash
npm install @anam-ai/js-sdk
```

--------------------------------

### Install Anam Plugin

Source: https://anam.ai/docs/integrations/livekit/quickstart

Install the Anam plugin for LiveKit agents using pnpm.

```bash
pnpm add @livekit/agents-plugin-anam
```

--------------------------------

### Install Anam SDK via Package Managers

Source: https://anam.ai/docs/python-sdk/installation

Use pip or uv to install the core Anam SDK package.

```bash
pip install anam
```

```bash
uv add anam
```

--------------------------------

### Create Project Directory and Navigate

Source: https://anam.ai/docs/javascript-sdk/examples/full-app

Sets up the project structure by creating a new directory and changing into it. This is the first step in initializing a new project.

```bash
mkdir anam-production-app
cd anam-production-app
```

--------------------------------

### OpenAPI Specification for Get Tool

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

This OpenAPI 3.1 specification defines the GET /v1/tools/{id} endpoint for retrieving a tool by its ID. It includes request parameters, response schemas, and example data.

```yaml
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
  - name: Engine
paths:
  /v1/tools/{id}:
    get:
      tags:
        - Tools
      summary: get tool
      description: Get a tool by ID
      operationId: getTool
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: Tool ID
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Successfully retrieved tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
              examples:
                default:
                  $ref: '#/components/examples/ToolResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Tool not found
        '500':
          description: Server error
components:
  schemas:
    Tool:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the tool
          example: 00000000-0000-0000-0000-000000000000
        name:
          type: string
          description: Name of the tool
          example: search_knowledge_base
        description:
          type: string
          description: Description of what the tool does
          example: Search the knowledge base for product information
        type:
          type: string
          enum:
            - CLIENT
            - SERVER_RAG
            - SERVER_WEBHOOK
            - SYSTEM
          description: Type of tool
        config:
          type: object
          description: Type-specific configuration
        disableInterruptions:
          type: boolean
          description: When true, interruptions are disabled while this tool is executing
          default: false
        createdAt:
          type: string
          format: date-time
          description: When the tool was created
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the tool was last updated
        usageCount:
          type: integer
          description: Number of personas using this tool
  examples:
    ToolResponse:
      summary: A single tool definition
      value:
        id: 00000000-0000-0000-0000-000000000000
        name: open_calendar
        description: Open the calendar UI in the client app.
        type: CLIENT
        config:
          parameters:
            type: object
            properties:
              date:
                type: string
                description: Date to jump to, in YYYY-MM-DD format.
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: null
        usageCount: 0
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### OpenAPI Specification for Get Session Transcript

Source: https://anam.ai/docs/api-reference/sessions/get-session-transcript

This OpenAPI 3.1.0 specification defines the GET /v1/sessions/{id}/transcript endpoint. It includes details on parameters, responses, and an example of a successful transcript response.

```yaml
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
  - name: Engine
paths:
  /v1/sessions/{id}/transcript:
    get:
      tags:
        - Sessions
      summary: get session transcript
      description: Returns the conversation transcript for a session
      operationId: getSessionTranscript
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          description: Session ID
      responses:
        '200':
          description: Successfully retrieved transcript
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: The session ID
                  personaName:
                    type: string
                    description: Name of the persona in the session
                  startTime:
                    type: string
                    format: date-time
                    description: Session start time
                  endTime:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: Session end time
                  durationMs:
                    type:
                      - integer
                      - 'null'
                    description: Session duration in milliseconds
                  totalMessages:
                    type: integer
                    description: Total number of messages in the transcript
                  transcriptsEnabled:
                    type: boolean
                    description: Whether transcripts were enabled for this session
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum:
                            - user
                            - persona
                        message:
                          type: string
                        timestamp:
                          type:
                            - string
                            - 'null'
                          format: date-time
                        speakingDurationSeconds:
                          type:
                            - number
                            - 'null'
                        wasInterrupted:
                          type: boolean
                          description: Only present for persona messages
              examples:
                default:
                  $ref: '#/components/examples/SessionTranscriptResponse'
        '400':
          description: Bad request - Invalid session ID
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Not Found - Session not found or no transcript available
        '500':
          description: Server error
components:
  examples:
    SessionTranscriptResponse:
      summary: The message log of a completed session
      value:
        sessionId: 00000000-0000-0000-0000-000000000000
        personaName: Cara
        startTime: '2026-04-20T09:00:00.000Z'
        endTime: '2026-04-20T09:12:34.000Z'
        durationMs: 754000
        totalMessages: 6
        transcriptsEnabled: true
        messages:
          - role: persona
            message: Hi! How can I help?
            timestamp: '2026-04-20T09:00:01.000Z'
            speakingDurationSeconds: 1.4
            wasInterrupted: false
          - role: user
            message: Can you tell me a joke?
            timestamp: '2026-04-20T09:00:05.000Z'
            speakingDurationSeconds: 2.1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Create Project Directory

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

Initializes the project directory and navigates into it. Ensure Node.js is installed.

```bash
mkdir my-anam-app
cd my-anam-app

```

--------------------------------

### OpenAPI Specification for Get Avatar

Source: https://anam.ai/docs/api-reference/avatars/get-avatar

This OpenAPI 3.1.0 specification defines the GET /v1/avatars/{id} endpoint, which returns an avatar by ID. It includes request parameters, response schemas, and example responses.

```yaml
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
  - name: Engine
paths:
  /v1/avatars/{id}:
    get:
      tags:
        - Avatars
      summary: get avatar
      description: Returns an avatar by ID
      operationId: getAvatar
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          description: Avatar ID
      responses:
        '200':
          description: Successfully retrieved avatar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Avatar'
              examples:
                default:
                  $ref: '#/components/examples/AvatarResponse'
        '400':
          description: Bad request - Invalid avatar ID
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Not Found - Avatar not found
        '500':
          description: Server error
components:
  schemas:
    Avatar:
      type: object
      description: A face preset that a persona can use as its visual representation.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the avatar.
        displayName:
          type: string
          description: Human-readable name shown in the Lab and share links.
        variantName:
          type: string
          description: >-
            Name of the specific variant (e.g. lighting or pose) within the
            avatar family.
        imageUrl:
          type: string
          format: uri
          description: URL of the still image used as a preview of the avatar.
        landscapeImageUrl:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Preview image cropped exactly as the engine frames landscape
            (1152x768) output. Use this when displaying the avatar at a
            landscape aspect ratio. For avatars with legacy landscape source
            images this is the same as `imageUrl`.
        portraitImageUrl:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Preview image cropped exactly as the engine frames portrait
            (768x1152) output. Use this when starting a session with portrait
            `videoWidth`/`videoHeight`. `null` when the avatar cannot render
            portrait output.
        videoUrl:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Signed URL for a muted idling MP4 preview of the avatar, if one
            exists. The URL expires after 1 hour; re-fetch the avatar to get a
            fresh URL. `null` when the preview is unavailable or still
            generating.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the avatar was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the avatar was last updated.
        createdByOrganizationId:
          type:
            - string
            - 'null'
          description: >-
            ID of the organization that created the avatar, or `null` for stock
            avatars. IDs may be either UUIDs or nanoid-style strings depending
            on when the organization was created.
        availableVersions:
          type: array
          items:
            type: string
          description: >-
            Avatar models this avatar can be used with. Pass one of these values
            as `avatarModel` when creating a persona or starting a session.
        activeVersion:
          type:
            - string
            - 'null'
          description: >-
            Avatar model used by default when no explicit `avatarModel` is
            requested.
  examples:
    AvatarResponse:
      summary: A single avatar resource
      value:
        id: 071b0286-4cce-4808-bee2-e642f1062de3
        displayName: Liv
        variantName: home
        imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png
        videoUrl: https://example.com/avatar-preview.mp4?X-Amz-Signature=...
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:00:00.000Z'
        createdByOrganizationId: null
        availableVersions:
          - cara-3
        activeVersion: cara-3
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Initialize Node.js Project

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

Sets up a new Node.js project with a default package.json file. Requires Node.js and npm to be installed.

```bash
npm init -y

```

--------------------------------

### OpenAPI Specification for Get Knowledge Document

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

This OpenAPI 3.1.0 specification defines the GET /v1/knowledge/documents/{id} endpoint for retrieving a single knowledge document. It includes request parameters, response schemas, and example responses.

```yaml
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
  - name: Engine
paths:
  /v1/knowledge/documents/{id}:
    get:
      tags:
        - Knowledge
      summary: get knowledge document
      description: Get a single document by ID
      operationId: getKnowledgeDocument
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the knowledge document
      responses:
        '200':
          description: Successfully retrieved document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeDocument'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Document not found
        '500':
          description: Server error
components:
  schemas:
    KnowledgeDocument:
      type: object
      description: >-
        A single file uploaded into a knowledge group. Retrieved chunks
        reference it by ID.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the document.
        knowledgeFolderId:
          type: string
          format: uuid
          description: ID of the knowledge group this document belongs to.
        filename:
          type: string
          description: Original filename as uploaded.
        fileType:
          type: string
          description: MIME type or extension-derived file type.
        fileSize:
          type: integer
          description: Size of the file in bytes.
        fileUrl:
          type: string
          format: uri
          description: Internal URL at which the file is stored.
        status:
          type: string
          enum:
            - UPLOADED
            - PROCESSING
            - READY
            - FAILED
          description: Current processing state. Only `READY` documents are searchable.
        errorMessage:
          type:
            - string
            - 'null'
          description: Failure reason when `status` is `FAILED`, otherwise `null`.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the document was uploaded.
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the document record was last updated.
  examples:
    KnowledgeDocumentResponse:
      summary: A single knowledge document
      value:
        id: 00000000-0000-0000-0000-000000000000
        knowledgeFolderId: 00000000-0000-0000-0000-000000000000
        filename: getting-started.pdf
        fileType: application/pdf
        fileSize: 248320
        fileUrl: https://cdn.anam.ai/knowledge/getting-started.pdf
        status: READY
        errorMessage: null
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:01:12.000Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Advanced Example: Gemini with Vision

Source: https://anam.ai/docs/integrations/livekit/configuration

An advanced example demonstrating the use of Gemini Live for multimodal conversations, including screen share analysis. This setup involves configuring the LLM, AvatarSession, and AgentSession with specific samplers and instructions.

```python
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()

    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.",
    )

    avatar = anam.AvatarSession(
        persona_config=anam.PersonaConfig(
            name="Maya",
            avatarId=os.getenv("ANAM_AVATAR_ID"),
            avatarModel="cara-4",
        ),
        api_key=os.getenv("ANAM_API_KEY"),
    )

    session = AgentSession(
        llm=llm,
        video_sampler=VoiceActivityVideoSampler(
            speaking_fps=0.2,
            silent_fps=0.1,
        ),
    )

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

--------------------------------

### Run React Frontend Development Server

Source: https://anam.ai/docs/integrations/livekit/quickstart

Start the React frontend development server using pnpm.

```bash
pnpm dev
```

--------------------------------

### Create Project Directory

Source: https://anam.ai/docs/javascript-sdk/examples/custom-llm

Initializes a new project directory for the custom LLM application.

```bash
mkdir anam-custom-llm-app
cd anam-custom-llm-app
```

--------------------------------

### Register Event Listeners and Tool Call Handlers

Source: https://anam.ai/docs/javascript-sdk/reference/event-types

Register event listeners and tool call handlers before starting the session. This example shows how to listen for the SESSION_READY event and register a tool call handler for 'navigate_to_page'.

```javascript
import { createClient, AnamEvent } from "@anam-ai/js-sdk";

const anamClient = createClient(sessionToken);

anamClient.addListener(AnamEvent.SESSION_READY, (sessionId) => {
  console.log("Session ready:", sessionId);
});

anamClient.registerToolCallHandler("navigate_to_page", {
  onStart: async (payload) => {
    window.location.href = `/${payload.arguments.page}`;
  },
});

await anamClient.streamToVideoElement("persona-video");
```

--------------------------------

### Create React Frontend for LiveKit Agent

Source: https://anam.ai/docs/integrations/livekit/quickstart

Create a new React frontend application using the LiveKit agent starter template and install its dependencies.

```bash
lk app create --template agent-starter-react
cd agent-starter-react
pnpm install
```

--------------------------------

### OpenAPI Specification for Knowledge Document Download

Source: https://anam.ai/docs/api-reference/knowledge/get-knowledge-document-download

This OpenAPI 3.1.0 specification defines the GET endpoint for downloading a knowledge document. It includes parameters, responses, and an example of a successful response with a presigned download URL and filename.

```yaml
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
  - name: Engine
paths:
  /v1/knowledge/documents/{id}/download:
    get:
      tags:
        - Knowledge
      summary: get knowledge document download
      description: Get a presigned download URL for a knowledge document
      operationId: getKnowledgeDocumentDownload
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Unique identifier of the knowledge document
      responses:
        '200':
          description: Successfully generated download URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloadUrl:
                    type: string
                  filename:
                    type: string
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentDownloadResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Document not found
        '500':
          description: Server error
components:
  examples:
    KnowledgeDocumentDownloadResponse:
      summary: A short-lived URL for downloading a knowledge document
      value:
        downloadUrl: >-
          https://cdn.anam.ai/knowledge/00000000-0000-0000-0000-000000000000.pdf?X-Amz-Signature=…
        filename: getting-started.pdf
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Customer Service Guardrails Example

Source: https://anam.ai/docs/personas/llms/prompting-guide

Define rules for a customer service persona to stay on-topic, handle errors gracefully, and maintain a professional tone. Use this to prevent inappropriate responses and guide behavior in sensitive situations.

```text
# Guardrails

Remain within the scope of company products and services; politely decline requests for advice on competitors.
Never share customer data or reveal sensitive account information without proper verification.
Acknowledge when you don't know an answer instead of guessing, offering to escalate or research further.
Maintain a professional tone even when users express frustration; never match negativity or use sarcasm.
If the user requests actions beyond your capabilities (like processing refunds), clearly explain the limitation and offer the appropriate alternative channel.
```

--------------------------------

### Handle Tool Call Started Events

Source: https://anam.ai/docs/embed/widget/events

Listen for the `tool-call-started` event to react to tool invocations. Filter for client-side tools (`toolType: 'client'`) to avoid processing server-side tools. This example shows how to redirect the user if the tool is 'redirect'.

```javascript
const widget = document.querySelector("anam-agent");

widget.addEventListener("anam-agent:tool-call-started", (e) => {
  const { toolName, toolType, arguments: args } = e.detail;

  // Server-side tools (webhook, knowledge) run on Anam's side — ignore them here.
  if (toolType !== "client") return;

  if (toolName === "redirect") {
    window.location.href = args.url;
  }
});
```

--------------------------------

### Get Ephemeral Session Token

Source: https://anam.ai/docs/llms-full.txt

Obtain an ephemeral session token by providing your API key and detailed persona configuration. This token is also valid for 1 hour and is suitable for dynamic persona setups. This endpoint must be called from your server.

```APIDOC
## POST /v1/auth/session-token

### Description
Requests an ephemeral session token with a specific persona configuration. This token is valid for 1 hour. This endpoint must be called from a server.

### Method
POST

### Endpoint
https://api.anam.ai/v1/auth/session-token

### Parameters
#### Request Body
- **personaConfig** (object) - Required - Configuration for the ephemeral persona.
  - **name** (string) - Required - The name of the persona.
  - **avatarId** (string) - Required - The ID of the persona's avatar.
  - **voiceId** (string) - Required - The ID of the persona's voice.
  - **llmId** (string) - Required - The ID of the language model to use.
  - **systemPrompt** (string) - Required - The system prompt defining the persona's behavior.

### Request Example
```json
{
  "personaConfig": {
    "name": "Cara",
    "avatarId": "30fa96d0-26c4-4e55-94a0-517025942e18",
    "voiceId": "6bfbe25a-979d-40f3-a92b-5394170af54b",
    "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
    "systemPrompt": "[STYLE] Reply in natural speech without formatting. Add pauses using '...' and very occasionally a disfluency. [PERSONALITY] You are Cara, a helpful assistant."
  }
}
```

### Headers
- **Content-Type**: application/json
- **Authorization**: Bearer YOUR_API_KEY

### Response
#### Success Response (200)
- **sessionToken** (string) - The obtained session token.

#### Response Example
```json
{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Error Handling
- **401**: Invalid or missing API key.
- **403**: API key does not have permission.
- **429**: Rate limited.
```

--------------------------------

### Install Anam Python SDK with Optional Display Dependencies

Source: https://anam.ai/docs/llms-full.txt

Install the SDK with optional dependencies for local testing, including OpenCV video display and sounddevice audio playback. Requires Python 3.10 or higher.

```bash
pip install anam[display]
```

--------------------------------

### Example System Persona Prompt

Source: https://anam.ai/docs/personas/llms/prompting-guide

This system prompt defines a persona for a technical specialist named Alex, detailing their personality, interaction environment, communication tone, primary goals, and operational guardrails. It's designed to guide LLM behavior in customer support scenarios.

```text
# Personality

You are Alex, a friendly and knowledgeable technical specialist for our company.
You have expertise in all our products and services.
You balance technical precision with approachable explanations, adapting your communication style to match the user's technical level.
You're curious and empathetic, aiming to understand the user's specific needs.

# Environment

You are interacting with a user via a voice and video call directly from our website.
The user is likely seeking guidance on implementing or troubleshooting our products and may have varying technical backgrounds.

# Tone

Your responses are clear, concise, and conversational.
Your output must be plain, unformatted text. For example, write "one hundred million dollars" instead of "$100M".
You incorporate brief affirmations ("Got it," "I see what you're asking") and filler words ("actually," "essentially") to sound human.
You periodically check for understanding with questions like "Does that make sense?" or "Would you like me to explain that differently?"
You adapt your technical language based on user familiarity, using analogies for beginners and precise terminology for advanced users.

# Goal

Your primary goal is to guide users toward successful use of our products. You will:
1. **Classify Intent:** First, identify if the user needs help with features, troubleshooting, or implementation.
2. **Deliver Information:** Provide step-by-step guidance for implementation, a diagnostic sequence for troubleshooting, or a high-level overview for feature questions.
3. **Validate Solution:** Confirm the user understands and that their issue is resolved before ending the conversation.
4. **Connect & Continue:** Suggest related features or next steps that might be helpful.

# Guardrails

Keep responses focused on our products and directly relevant technologies.
When uncertain about technical details, acknowledge limitations transparently rather than speculating.
Respond naturally as a human specialist without referencing being an AI.
Mirror the user's communication style—be brief for direct questions and more detailed for curious users.
```

--------------------------------

### Start Local Web Server with Node.js

Source: https://anam.ai/docs/javascript-sdk/quickstart

Use `http-server` to serve your HTML file locally. This is useful for testing web applications that require a local server environment.

```bash
npx http-server -p 8000
```

--------------------------------

### Verify Anam Python SDK Installation

Source: https://anam.ai/docs/llms-full.txt

Run this Python code to verify the SDK installation by printing the installed version. Requires Python 3.10 or higher.

```python
import anam
print(anam.__version__)
```

--------------------------------

### Configure Client Options

Source: https://anam.ai/docs/javascript-sdk/reference/basic-usage

Initialize the client with optional configuration parameters to customize audio input, voice detection, WebRTC settings, and metrics.

```typescript
import { createClient } from "@anam-ai/js-sdk";

const anamClient = createClient(sessionToken, {
  disableInputAudio: false,      // Set true to disable microphone
  audioDeviceId: "device-id",    // Specify audio input device
  voiceDetection: {
    endOfSpeechSensitivity: 0.5, // 0-1, higher = more sensitive
  },
  iceServers: [],                // Custom ICE/TURN servers for WebRTC
  rtcConfiguration: {            // Full RTCConfiguration passthrough (advanced)
    iceTransportPolicy: "relay", // Force TURN-relay-only on UDP-blocked networks
  },
  metrics: {
    disableClientMetrics: false, // Disable telemetry for air-gapped environments
  },
});
```

--------------------------------

### Get Knowledge Group

Source: https://anam.ai/docs/llms.txt

Get a single RAG group by ID.

```APIDOC
## Get Knowledge Group

### Description
Get a single RAG group by ID.

### Method
GET

### Endpoint
/knowledge/groups/{groupId}

### Parameters
#### Path Parameters
- **groupId** (string) - Required - The ID of the RAG group to retrieve.

### Response
#### Success Response (200)
- **groupId** (string) - The ID of the knowledge group.
- **name** (string) - The name of the knowledge group.
- **createdAt** (string) - The timestamp when the group was created.

#### Response Example
```json
{
  "groupId": "kg_abc123",
  "name": "My Knowledge Group",
  "createdAt": "2023-10-27T11:00:00Z"
}
```
```

--------------------------------

### Complete Example with Transcript Management

Source: https://anam.ai/docs/javascript-sdk/reference/user-messages

Demonstrates initializing the Anam.ai client, sending messages, and manually updating the UI transcript. This ensures an accurate conversation history when using sendUserMessage().

```javascript
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
function sendMessage(message) {
  // Add to transcript manually since sendUserMessage doesn't trigger events
  addMessageToTranscript(message, "user");

  // Send the message to the persona
  anamClient.sendUserMessage(message);
}

// Example usage
sendMessage("What products do you recommend?");

// Provide context about user actions
sendMessage(
  "Note to AI: User added item to cart with ID product_123"
);
```

--------------------------------

### Audio Input Configuration Options

Source: https://anam.ai/docs/javascript-sdk/reference/audio-control

Configure audio input behavior during client initialization.

```APIDOC
## Audio Input Configuration Options

### Description

Configure how the Anam client handles microphone input during initialization.

### Disabling Audio Input

Completely disable microphone input. This is useful for text-only interactions or when providing a custom audio stream.

**Configuration Option:** `disableInputAudio: true`

**Behavior when `disableInputAudio` is `true`:**
- The SDK will not request microphone permissions.
- `muteInputAudio()` and `unmuteInputAudio()` methods will have no effect.
- Any user-provided audio stream will be ignored.

**Request Example:**

```typescript
import { createClient } from '@anam-ai/js-sdk';

const anamClient = createClient(sessionToken, {
  disableInputAudio: true,
});
```

### Specifying an Audio Device

Initialize the client to use a specific microphone.

**Configuration Option:** `audioDeviceId: string`

**Request Example:**

```typescript
const anamClient = createClient(sessionToken, {
  audioDeviceId: 'specific-device-id',
});
```
```

--------------------------------

### Create a Client Tool

Source: https://anam.ai/docs/guides/tools/introduction

Define a client-side tool that can be invoked directly from the client. This example creates a tool to open a product page, requiring a `productId` parameter.

```javascript
const clientTool = await fetch("https://api.anam.ai/v1/tools", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "open_product_page",
    description: "Open a product page when the user wants to see more details about a product",
    type: "CLIENT",
    config: {
      parameters: {
        type: "object",
        properties: {
          productId: {
            type: "string",
            description: "The ID of the product to display",
          },
        },
        required: ["productId"],
      },
    },
  }),
}).then(res => res.json());

```

--------------------------------

### LLM Configuration Example

Source: https://anam.ai/docs/api-reference/llms/get-llm

An example of a single LLM configuration, specifying its ID, display name, description, LLM format, upstream URLs, model name, and other parameters.

```yaml
id: a7cf662c-2ace-4de1-a21e-ef0fbf144bb7
displayName: GPT-4o
description: OpenAI GPT-4o default configuration.
llmFormat: openai
urls:
  - url: https://api.openai.com/v1/chat/completions
modelName: gpt-4o
temperature: 0.7
maxTokens: 1024
deploymentName: null
apiVersion: null
metadata: {}
displayTags:
  - openai
isDefault: true
isGlobal: true
isZdr: false
createdByOrganizationId: null
createdAt: '2026-04-20T10:00:00.000Z'
updatedAt: null
```

--------------------------------

### Get Weather

Source: https://anam.ai/docs/personas/tools/webhook-tools

Get current weather conditions when user asks about weather for a specific location.

```APIDOC
## GET /data/2.5/weather

### Description
Get current weather conditions when user asks about weather for a specific location.

### Method
GET

### Endpoint
https://api.openweathermap.org/data/2.5/weather

### Headers
- X-API-Key (string) - YOUR_WEATHER_API_KEY

### Parameters
#### Query Parameters
- **city** (string) - Required - City name
- **units** (string) - Optional - Temperature units (enum: metric, imperial)
```

--------------------------------

### Create a Knowledge Tool

Source: https://anam.ai/docs/personas/tools/tool-calling-example

Use this to create a reusable knowledge tool for searching product documentation. Ensure you have a valid API key and document folder ID.

```javascript
const knowledgeTool = await fetch("https://api.anam.ai/v1/tools", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "search_product_docs",
    description: "Search product documentation when users ask technical questions about features, installation, or usage",
    type: "SERVER_RAG",
    config: {
      documentFolderIds: ["YOUR_FOLDER_ID"], // From Step 1
    },
  }),
}).then(res => res.json());
```

--------------------------------

### LLM Tool Call Example

Source: https://anam.ai/docs/guides/tools/client-tools

This is an example of a tool call generated by the LLM when it recognizes a client-side action is required.

```json
{
  "name": "navigate_to_page",
  "arguments": {
    "page": "pricing"
  }
}
```

--------------------------------

### Start Local Web Server with PHP

Source: https://anam.ai/docs/javascript-sdk/quickstart

Launch a local web server using PHP's built-in server functionality. This command starts a server on `localhost` at port 8000.

```bash
php -S localhost:8000
```