> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools and Function Calling

> 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 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 agentic, capable of taking actions to help users accomplish their goals.

## How Tool Calling Works

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

**1. User speaks or types**

The user makes a request: "What's the status of my order 12345?"

**2. LLM analyzes intent**

The persona's LLM analyzes the request and determines it needs external information to respond accurately.

**3. Tool invocation**

The LLM selects the appropriate tool and generates a structured function call:

```json theme={"system"}
{
  "name": "check_order_status",
  "arguments": {
    "orderId": "12345"
  }
}
```

**4. Tool execution**

The system executes the tool based on its type:

* **Client tools**: The SDK triggers your registered handler. If `awaitResult` is `true`, the return value from `onStart` (or error message if it throws) is sent back to the engine as the tool result.
* **Knowledge tools**: Semantic search performed on your documents
* **Webhook tools**: HTTP request sent to your API endpoint
* **System tools**: Executed instantly inside the engine

**5. Response integration**

The tool result is returned to the LLM, which incorporates it into a natural language response.

> [!TIP]
>
> The user hears a complete, informed answer without knowing the technical orchestration behind the scenes.

## Multi-utterance persona turns

A persona can speak, call a tool, and then continue speaking after the tool returns without starting a new logical turn. Anam represents each spoken part as an utterance while keeping the complete response as one persona message.

The JavaScript SDK `v4.25.0` and Python SDK `v0.11.0` expose these boundaries in streamed events and completed message history. The existing message `content` remains the full concatenated response, so integrations that do not use utterances continue to work unchanged. See the [JavaScript event reference](https://anam.ai/docs/javascript-sdk/reference/events.md#multi-utterance-persona-turns) or [Python quickstart](https://anam.ai/docs/python-sdk/quickstart.md#multi-utterance-persona-turns) for examples.

> [!NOTE]
>
> Multi-utterance turns require an LLM that supports interleaved tool calling: text before and after a tool call in one turn. Anam-provided LLMs hosted by OpenAI or Azure support this behavior; LLMs hosted by Groq do not.

## Tool Types

Anam supports four 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={"system"}
{
  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']
  },
  awaitResult: true,
  toolTimeoutSeconds: 10
}
```

> [!TIP]
>
> Client tools work well for creating voice-driven user experiences
> where the AI can guide users through your application. Set `awaitResult: true` on the tool definition if you want the return value from your handler to be sent back to the LLM. Use `toolTimeoutSeconds` to control how long the engine waits for a result (default: 10s, max: 600s).

### 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={"system"}
{
  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']
}
```

> [!NOTE]
>
> Folder IDs are UUIDs. Find them in the **Knowledge** card on the [Prompt tab
> in Anam Lab](https://lab.anam.ai/build?tab=prompt), or in the API response
> when you create a folder.

Knowledge tools handle search automatically:

* 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](https://anam.ai/docs/personas/knowledge/overview.md).

### Webhook Tools

Webhook tools call external HTTP endpoints, allowing your persona to integrate with any API. This enables your persona to interact with external systems and perform 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={"system"}
{
  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.

### System Tools

System tools are built-in tools that execute directly inside the Anam engine for instant session control. Unlike other tool types, they require no external endpoints or client-side handlers — just specify the `type` and `name`.

**Available system tools**:

* `change_language` — Dynamically switch the speech recognition language mid-session
* `skip_turn` — Skip the next persona response so the user can continue speaking
* `pause_conversation` — Stay quiet for a duration explicitly requested by the user
* `end_call` — End the session gracefully after the user confirms they want to finish

System tools are pre-provisioned for all organizations. Fetch the tool IDs via the API and attach them using `toolIds`:

```bash theme={"system"}
curl -X GET 'https://api.anam.ai/v1/tools' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

> [!TIP]
>
> See the [System Tools guide](https://anam.ai/docs/personas/tools/system-tools.md) for detailed usage, supported languages, and configuration examples.

## Protecting Tool Turns from Interruptions

By default, the user can interrupt the persona at any point, including while a tool is executing or while the persona is reading the tool result back. For tools that drive a multi-step action — for example, navigating to a new page, submitting a form, or playing back a confirmation — an interruption part way through can leave the conversation out of sync with what your application just did.

Set `disableInterruptions` to `true` on a tool definition to suppress interruptions for the duration of that tool's turn:

```typescript theme={"system"}
{
  type: 'server',
  subtype: 'webhook',
  name: 'submit_order',
  description: 'Submit the customer order once they have confirmed the items',
  url: 'https://api.example.com/orders',
  method: 'POST',
  awaitResponse: true,
  disableInterruptions: true,
}
```

The flag applies to all tool types: `client`, `server` (knowledge and webhook), and `system`. It defaults to `false`, which preserves the existing interrupt-anytime behavior.

> [!NOTE]
>
> `disableInterruptions` only takes effect when there is a turn to protect. Set `awaitResult: true` on client tools and `awaitResponse: true` on webhook tools — fire-and-forget tools return control to the LLM immediately, so the flag has nothing to guard.

When creating tools via the API, pass `disableInterruptions` alongside the other tool fields:

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

{
  "type": "SERVER_WEBHOOK",
  "name": "submit_order",
  "description": "Submit the customer order once they have confirmed the items",
  "disableInterruptions": true,
  "config": {
    "url": "https://api.example.com/orders",
    "method": "POST",
    "awaitResponse": true
  }
}
```

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

**1. Create tools**

Create tools on the [Tools tab in Anam Lab](https://lab.anam.ai/build?tab=tools) or via the API. Each tool gets a persistent ID.

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

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

Saved tools use the tool type — `CLIENT`, `SERVER_RAG`, `SERVER_WEBHOOK` or `SYSTEM` — with the type-specific settings nested under `config`. The `type` and `subtype` pair shown elsewhere on this page describes inline session tools, which are a different shape.

Response includes the tool ID:

```json theme={"system"}
{
  "id": "tool-uuid-123",
  "name": "search_docs",
  ...
}
```

**2. 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={"system"}
PUT /v1/personas/{personaId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "toolIds": ["tool-uuid-123", "tool-uuid-456"]
}
```

**3. Use persona in session**

When you create a session with this persona, all attached tools are automatically loaded:

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

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

> [!TIP]
>
> The persona's tools are available during the session without needing to specify them again.

### Ephemeral Personas (Session-Only)

For ephemeral personas defined at session creation time, attach tools by their IDs in the `toolIds` array:

```http theme={"system"}
POST /v1/auth/session-token
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "personaConfig": {
    "name": "Support Agent",
    "avatarId": "avatar-uuid",
    "avatarModel": "cara-4",
    "voiceId": "voice-uuid",
    "llmId": "llm-uuid",
    "systemPrompt": "You are a helpful support agent...",
    "toolIds": ["tool-uuid-123", "tool-uuid-456"]
  }
}
```

> [!NOTE]
>
> Tools must be created first via the API or UI before they can be attached to ephemeral personas. The `toolIds` array references existing tool IDs.

## Handling Tool Events

For client tools, use `registerToolCallHandler` to define per-tool handlers, this will automatically emit `completed` or `failed` events when the handler completes.

```typescript theme={"system"}
import { AnamClient } from '@anam-ai/js-sdk';

const client = new AnamClient(sessionToken);

const cancelCheckoutHandler = client.registerToolCallHandler('open_checkout', {
  onStart: async (payload) => {
    window.location.href = `/checkout/${payload.arguments.productId}`;
    return `Opened checkout for product ${payload.arguments.productId}`;
  },
  onComplete: async(payload) => {
    console.log(`tool call completed ${payload.toolName}`)
  },
  onFail: async(payload) => {
    console.log(`tool call failed ${payload.toolName}`)
  }
});

// you can also register partial handlers
const cancelRegisterHandler = client.registerToolCallHandler('show_notification', {
  onStart: async (payload) => {
    showNotification(payload.arguments.message);
    return 'Notification shown';
  },
});
```

You can also listen for tool call lifecycle events for logging or analytics:

```typescript theme={"system"}
import { AnamEvent } from '@anam-ai/js-sdk';

client.addListener(AnamEvent.TOOL_CALL_STARTED, (event) => {
  console.log('Tool started:', event.toolName, event.arguments);
});

client.addListener(AnamEvent.TOOL_CALL_COMPLETED, (event) => {
  console.log('Tool completed:', event.toolName, `${event.executionTime}ms`);
});
```

> [!WARNING]
>
> Register handlers and event listeners before calling `streamToVideoElement()` to ensure you don't miss any events.

## Tool Design Best Practices

### Write Clear Descriptions

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

```typescript Good theme={"system"}
{
  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={"system"}
{
  name: 'check_order_status',
  description: 'Checks orders'
}
```

### 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={"system"}
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.

### Organize Knowledge by Domain

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

```typescript theme={"system"}
// 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 calls per turn**:

* Maximum 10 tool calls during one LLM turn
* Maximum 5 consecutive calls to the same tool with identical arguments; calling a different tool or changing the arguments resets this counter

When either limit is reached, Anam ends the current turn. These safeguards prevent repeated tool calls from stalling the session or creating a runaway loop.

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

> [card] [Cookbook: Client-Side Tools](https://anam.ai/cookbook/client-side-tools)
>
> Build a multi-page app where the avatar navigates users with voice commands

> [card] [Getting Started with Tools](https://anam.ai/docs/personas/tools/tool-calling-example.md)
>
> Create your first tool in 15 minutes

> [card] [Knowledge Base Setup](https://anam.ai/docs/personas/knowledge/overview.md)
>
> Upload documents and configure RAG search

> [card] [Webhook Tools](https://anam.ai/docs/personas/tools/webhook-tools.md)
>
> Integrate external APIs with webhook tools

> [card] [System Tools](https://anam.ai/docs/personas/tools/system-tools.md)
>
> Built-in tools for language switching and turn management


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.