Skip to main content

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.
  • UI
  • API
  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
Your folder is created with a unique ID. Note this ID for later use.

Step 2: Upload Documents

Upload documents to make them searchable. We’ll use a PDF user guide as an example.
  • UI
  • API
  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)
The document status changes from PROCESSING to READY. It’s now searchable!
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 Your First Knowledge Tool

Now create a knowledge tool that searches your uploaded documents.
  • Stateful (Save to Database)
  • Ephemeral (API Only)
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
The tool is now saved and can be attached to any persona in your organization.
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.

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)
You can create stateful tools via the POST /v1/tools endpoint or in the Anam Lab at /tools.

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

Create session token

In the personaConfig, provide the toolIds array containing the unique IDs of your pre-created tools.
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();
2

Start engine session

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

3

Connect via WebSocket

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}`;
    }
  }
};
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:
  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'
Use your browser’s developer console to see tool call events in real-time. This helps debug and understand the execution flow.

Troubleshooting

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

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