Welcome to Anam

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

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.

This guide takes approximately 15 minutes to complete. We’ll use both the Anam Lab UI and API for a complete understanding.

Prerequisites

Before starting, ensure you have:

An Anam account (sign up at 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.

Navigate to the Knowledge Base page at /knowledge
Click Create Folder
Enter the following details:
- Name: Product Documentation
- Description: Technical guides and product information
Click Create

Your folder is created with a unique ID. Note this ID for later use.

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

Step 2: Upload Documents

Upload documents to make them searchable. We’ll use a PDF user guide as an example.

On the Knowledge Base page, click into your Product Documentation folder
Click Upload Documents
Drag and drop your PDF or click to browse
Click Upload
Wait for processing to complete (~30 seconds)

The document status changes from PROCESSING to READY. It’s now searchable!

All documents uploaded via the API use a secure, three-step signed upload process:Step 1: Request a Signed Upload URL

const uploadResponse = await fetch(
  `https://api.anam.ai/v1/knowledge/groups/${YOUR_FOLDER_ID}/documents/presigned-upload`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filename: "user-guide.pdf",
      contentType: "application/pdf",
      fileSize: 2048000,
    }),
  }
);

const { uploadUrl, documentId } = await uploadResponse.json();

Step 2: Upload Your File to the URL

const file = document.querySelector('input[type="file"]').files[0]; // Your File object
await fetch(uploadUrl, {
  method: "PUT",
  headers: {
    "Content-Type": file.type,
  },
  body: file,
});

Step 3: Confirm the Upload

await fetch(
  `https://api.anam.ai/v1/knowledge/documents/${documentId}/confirm-upload`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fileSize: 2048000,
    }),
  }
);

For complete, copy-pasteable code examples in different languages, see the dedicated Document Upload Guide.

Documents must be in READY status before they can be searched. Processing typically takes 30 seconds but may take longer for large files.

Step 3: Create a Session with Tools

Ephemeral personas support two ways to configure tools at runtime:

Reference pre-created tools using toolIds - Best for reusing tools across different sessions or personas
Define tools inline using tools array - Best for session-specific or dynamic tool configurations

Using toolIds (Reusable)
Inline tools (Dynamic)

First, create reusable tools via the API. These can be used across multiple sessions and personas.

Create a Knowledge Tool

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());

Create a Webhook Tool

const webhookTool = await fetch("https://api.anam.ai/v1/tools", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "check_order_status",
    description: "Check the status of a customer order when they provide an order ID",
    type: "SERVER_WEBHOOK",
    config: {
      url: "https://your-api.com/orders/status",
      method: "POST",
      headers: {
        "X-API-Key": "your-api-key",
      },
    },
  }),
}).then(res => res.json());

Create a Client Tool

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());

Reference tools by ID in session

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: [
        knowledgeTool.id,
        webhookTool.id,
        clientTool.id,
      ],
    },
  }),
});

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

This approach lets you manage tools centrally and reuse them across multiple sessions and personas.

Define the complete tool configuration directly in the session token request:

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.`,
      tools: [
        // Knowledge Tool - searches your uploaded documents
        {
          type: "server",
          subtype: "knowledge",
          name: "search_product_docs",
          description: "Search product documentation when users ask technical questions about features, installation, or usage",
          documentFolderIds: ["YOUR_FOLDER_ID"], // Folder ID from Step 1
        },
        // Webhook Tool - calls your external API
        {
          type: "server",
          subtype: "webhook",
          name: "check_order_status",
          description: "Check the status of a customer order when they provide an order ID",
          url: "https://your-api.com/orders/status",
          method: "POST",
          headers: {
            "X-API-Key": "your-api-key",
          },
          parameters: {
            type: "object",
            properties: {
              orderId: {
                type: "string",
                description: "The order ID to check",
              },
            },
            required: ["orderId"],
          },
        },
        // Client Tool - triggers events in your app
        {
          type: "client",
          name: "open_product_page",
          description: "Open a product page when the user wants to see more details about a product",
          parameters: {
            type: "object",
            properties: {
              productId: {
                type: "string",
                description: "The ID of the product to display",
              },
            },
            required: ["productId"],
          },
        },
      ],
    },
  }),
});

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

Inline tools are perfect for dynamic configurations, user-specific parameters, or when tool behavior needs to change per session.

Step 4: Initialize SDK and Handle Events

Initialize SDK client

import { AnamClient, AnamEvent } from '@anam-ai/js-sdk';

const client = new AnamClient({
sessionToken: sessionToken,
});

console.log('Anam client initialized');

Set up event listeners

// Register a handler for the client tool
client.registerToolCallHandler('open_product_page', {
  onStart: async (payload) => {
    console.log('Tool called:', payload.toolName);
    console.log('Arguments:', payload.arguments);
    window.location.href = `/products/${payload.arguments.productId}`;
    return `Opened product ${payload.arguments.productId}`;
  },
});

// Register handlers for the webhook and knowledge tools

client.registerToolCallHandler('check_order_status', {
  onComplete: async (payload) => {
    const { toolName, result, executionTime } = payload;
    console.log(`Tool ${toolName} completed in ${executionTime}ms:`, result);
  }
})

client.registerToolCallHandler('search_product_docs', {
  onComplete: async (payload) => {
    const { toolName, result, executionTime } = payload;
    console.log(`Tool ${toolName} completed in ${executionTime}ms:`, result);
  }
})

// alternatively you can use the emitted events to register generic handlers
// client.addListener(AnamEvent.TOOL_CALL_COMPLETED, (event) => {
//   console.log(`Tool completed: ${event.toolName} in ${event.executionTime}ms`);
// })


// Handle session ready
client.addListener(AnamEvent.SESSION_READY, () => {
  console.log('Session ready - persona is active');
});

// Connect and start streaming
await client.streamToVideoElement('persona-video');

Your persona can now search documents, call APIs, and trigger client actions!

Testing Your Tools

Let’s test the complete setup with example conversations:

Testing Knowledge Tool

User: “How do I install the product?” Expected flow:

LLM recognizes this as a technical question
Invokes search_product_docs tool
Retrieves relevant chunks from your user guide
Responds with accurate installation steps

Testing Webhook Tool

User: “What’s the status of my order ORD-12345?” Expected flow:

LLM extracts order ID ORD-12345
Calls check_order_status webhook with orderId: "ORD-12345"
Receives response from your API
Tells user the current order status

Testing Client Tool

User: “Show me more details about the premium plan” Expected flow:

LLM identifies product name “premium plan”
Calls open_product_page client tool
SDK triggers the registered open_product_page handler
Navigation happens: window.location.href = '/products/premium-plan'

Use your browser’s developer console to see tool call events in real-time. This helps debug and understand the execution flow.

Troubleshooting

Knowledge tool returns no results

Possible causes:

Document still processing (check status)
Query doesn’t match document content
Folder ID incorrect

Solutions:

Wait for document status to be READY
Verify lifecycle events are firing i.e. TOOL_CALL_STARTED, TOOL_CALL_COMPLETED and TOOL_CALL_FAILED events.
Verify expected documents are being read see ToolCallCompletedPayload.documentsAccessed
Verify folder ID in tool configuration

Webhook tool times out

Possible causes:

External API is slow (>60s timeout)
Network connectivity issues
Invalid endpoint URL

Solutions:

Check endpoint URL is correct
Test endpoint independently with curl
Ensure API returns response within 60 seconds
Check authentication headers are valid
Verify lifecycle events are firing i.e. TOOL_CALL_STARTED, TOOL_CALL_COMPLETED and TOOL_CALL_FAILED events.

Client tool event not received

Possible causes:

SDK client not properly initialized
Event listener not registered before session starts
Tool name mismatch

Solutions:

Verify SDK client is initialized with valid session token
Register handler using client.registerToolCallHandler(toolName, handler) before calling streamToVideoElement
Match tool name exactly in your handler (case-sensitive)
Check browser console for any SDK initialization errors

Best Practices

Tool Naming

Use descriptive, action-oriented names:

// ✅ 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:

// ✅ 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:

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

Client Tool Events

Learn to handle client tool events in your application

Knowledge Tools Deep Dive

Advanced knowledge tool configuration and optimization

Webhook Tools Guide

Integrate external APIs with webhook tools

SDK Reference

Complete SDK documentation for tool events

Getting Started

Core Concepts

Anam Widget

Tools

Knowledge

Examples

SDK Reference

Resources

Third-Party Integrations

Community

Getting Started with Tools

What You’ll Build

Prerequisites

Step 1: Create a Knowledge Folder

Step 2: Upload Documents

Step 3: Create a Session with Tools

Step 4: Initialize SDK and Handle Events

Testing Your Tools

Testing Knowledge Tool

Testing Webhook Tool

Testing Client Tool

Troubleshooting

Best Practices

Tool Naming

Tool Descriptions

System Prompts

Next Steps

Client Tool Events

Knowledge Tools Deep Dive

Webhook Tools Guide

SDK Reference

Getting Started

Core Concepts

Anam Widget

Tools

Knowledge

Examples

SDK Reference

Resources

Third-Party Integrations

Community

​What You’ll Build

​Prerequisites

​Step 1: Create a Knowledge Folder

​Step 2: Upload Documents

​Step 3: Create a Session with Tools

​Step 4: Initialize SDK and Handle Events

​Testing Your Tools

​Testing Knowledge Tool

​Testing Webhook Tool

​Testing Client Tool

​Troubleshooting

​Best Practices

​Tool Naming

​Tool Descriptions

​System Prompts

​Next Steps

Client Tool Events

Knowledge Tools Deep Dive

Webhook Tools Guide

SDK Reference

What You’ll Build

Prerequisites

Step 1: Create a Knowledge Folder

Step 2: Upload Documents

Step 3: Create a Session with Tools

Step 4: Initialize SDK and Handle Events

Testing Your Tools

Testing Knowledge Tool

Testing Webhook Tool

Testing Client Tool

Troubleshooting

Best Practices

Tool Naming

Tool Descriptions

System Prompts

Next Steps