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
-
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.
Step 2: Upload Documents
Upload documents to make them searchable. We’ll use a PDF user guide as an example.- UI
- API
- 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!
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:To attach to a persona:
-
Navigate to Tools at
/tools - Click Create Tool
- Select Knowledge Tool
-
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”
- Name:
- Click Create Tool
The tool is now saved and can be attached to any persona in your organization.
- Go to
/build/{personaId} - In the Tools section, select your newly created tool
- Save the persona
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.2
Start engine session
3
Connect via WebSocket
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_docstool - 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_statuswebhook withorderId: "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_pageclient tool - Your app receives event via WebSocket
- 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
Knowledge tool returns no results
Possible causes:
- Document still processing (check status)
- Query doesn’t match document content
- Folder ID incorrect
- Wait for document status to be READY
- Test query with debug modal (
Ctrl+Shift+Kon knowledge page) - Verify folder ID in tool configuration
Webhook tool times out
Webhook tool times out
Possible causes:
- External API is slow (>60s timeout)
- Network connectivity issues
- Invalid endpoint URL
- Check endpoint URL is correct
- Test endpoint independently with curl
- Ensure API returns response within 60 seconds
- Check authentication headers are valid
Client tool event not received
Client tool event not received
Possible causes:
- WebSocket connection not established
- Event handler not configured
- Tool name mismatch
- Verify WebSocket connection: check
ws.readyState === 1 - Add event listener for
tool_callmessage type - Match tool name exactly (case-sensitive)

