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

# System Tools

> Built-in tools available to all personas for session control like language switching and turn management

## Overview

System tools are built-in tools that run directly inside the Anam engine. Unlike client, webhook, or knowledge tools which make external calls, system tools execute instantly within the session to control engine behavior.

Every persona can use system tools — you just need to attach them. No external endpoints, no client-side handlers, no additional setup required.

## Available System Tools

### change\_language

Allows the persona to dynamically switch the speech recognition language mid-session based on user requests.

When invoked, the engine updates the transcription pipeline to expect the new language. This is useful for multilingual applications where users may switch languages during a conversation.

**type** `string` *required*

Must be `"system"`

**name** `string` *required*

Must be `"change_language"`

**Tool parameters (set automatically by the LLM):**

**language\_code** `string` *required*

ISO 639-1 language code (e.g., `"fr"`, `"de"`, `"ja"`)

**Supported languages:**

The tool supports 70+ languages, including: `en`, `af`, `ar`, `hy`, `az`, `be`, `bs`, `bg`, `ca`, `zh`, `hr`, `cs`, `da`, `nl`, `et`, `fi`, `fr`, `gl`, `de`, `el`, `he`, `hi`, `hu`, `is`, `id`, `it`, `ja`, `kn`, `kk`, `ko`, `lv`, `lt`, `mk`, `ms`, `mi`, `mr`, `ne`, `no`, `fa`, `pl`, `pt`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `sw`, `sv`, `tl`, `ta`, `th`, `tr`, `uk`, `ur`, `vi`, `cy`.

**Example conversation:**

> **User:** "Can you switch to French? Je préfère parler en français."
>
> **Persona** calls `change_language` with `language_code: "fr"` → speech recognition now expects French input.
>
> **Persona:** "Bien sûr ! Je vous écoute en français maintenant."

> [!WARNING]
>
> This tool only changes the **transcription language** — what the system expects to **hear** from users. For a fully multilingual experience, your persona also needs a multilingual TTS voice and an LLM that supports the target language. See the [Multilingual guide](https://anam.ai/docs/personas/voices/multilingual.md) for more on language configuration.

***

### skip\_turn

Skips the persona's next spoken response so the user has more time to continue speaking. This affects one persona turn only; it does not start a timed pause.

**type** `string` *required*

Must be `"system"`

**name** `string` *required*

Must be `"skip_turn"`

The tool takes no parameters.

**Example conversation:**

> **User:** "Give me a moment, I'm not finished."
>
> **Persona** calls `skip_turn` → does not generate a spoken response for the next persona turn.
>
> The persona continues listening for the user to speak.

> [!NOTE]
>
> The silence breaker remains active after `skip_turn` and follows the configured [`silenceBeforeAutoEndTurnSeconds`](https://anam.ai/docs/personas/session/voice-detection). To stay quiet for a duration requested by the user, use `pause_conversation` instead.

***

### pause\_conversation

Pauses the conversation when the user explicitly asks for more time, such as "give me 40 seconds" or "hold on, I'll be right back." After a brief acknowledgment, the persona skips its next turn and remains quiet for the requested duration.

**type** `string` *required*

Must be `"system"`

**name** `string` *required*

Must be `"pause_conversation"`

**Tool parameters (set automatically by the LLM):**

**duration\_seconds** `number` *required*

How long to pause, in seconds. The persona uses the duration the user requested, or `60` seconds if the user did not provide one. The value must be positive and is capped at `600` seconds.

**Example conversation:**

> **User:** "Can you give me 45 seconds to finish writing this down?"
>
> **Persona** calls `pause_conversation` with `duration_seconds: 45`.
>
> **Persona:** "Sure, take your time — I'll be here." The persona then remains quiet for 45 seconds unless the user speaks first.

> [!TIP]
>
> Tell your persona to use `pause_conversation` only when the user explicitly requests a pause. Use `skip_turn` when the persona only needs to leave its next turn open for the user to continue speaking.

***

### end\_call

Lets the persona end the session gracefully after the user confirms they want to finish the conversation. The tool implements a two-step flow so the call is never closed on a single ambiguous cue.

**type** `string` *required*

Must be `"system"`

**name** `string` *required*

Must be `"end_call"`

The tool takes no parameters.

**How the two-step flow works:**

**1. Persona calls end\_call when the user seems to want to finish**

The engine starts a pending confirmation and instructs the LLM to ask a short yes-or-no confirmation question. The session is not closed yet.

**2. User confirms on the immediate follow-up turn**

The persona calls `end_call` a second time. The engine instructs the LLM to deliver a brief farewell.

**3. Session ends after the farewell**

Once the persona has finished speaking, the engine closes the session with reason `USER_REQUESTED_END`. The end reason and message are written to the session report.

If the next turn happens without a second `end_call` invocation, the pending confirmation expires and the conversation continues normally.

**Example conversation:**

> **User:** "OK, I think that's everything I needed. Thanks!"
>
> **Persona** calls `end_call` → engine returns "Ask the user to confirm whether they want to end the call now."
>
> **Persona:** "Happy to help. Would you like to end the call now?"
>
> **User:** "Yes, please."
>
> **Persona** calls `end_call` again → engine returns "End the call after your brief farewell."
>
> **Persona:** "Thank you, have a great day!" → session closes once the farewell finishes streaming.

> [!NOTE]
>
> `end_call` always runs with interruptions disabled, so the persona's confirmation question and farewell are not cut off if the user speaks at the same time. See [Protecting Tool Turns from Interruptions](https://anam.ai/docs/personas/tools/overview.md#protecting-tool-turns-from-interruptions).

## Adding System Tools to a Persona

System tools are already available to every organization — you don't need to create them. Just fetch the tool IDs and attach them to your persona or session.

### Step 1: Fetch System Tool IDs

Use the tools API to find the system tools available to your account:

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

The response includes the tool IDs you'll need:

```json theme={"system"}
{
  "tools": [
    {
      "id": "system-tool-uuid-1",
      "type": "system",
      "name": "change_language",
      ...
    },
    {
      "id": "system-tool-uuid-2",
      "type": "system",
      "name": "skip_turn",
      ...
    },
    {
      "id": "system-tool-uuid-3",
      "type": "system",
      "name": "pause_conversation",
      ...
    }
  ]
}
```

### Step 2: Attach to a Session or Persona

Use the tool IDs in the `toolIds` array when creating a session token:

```javascript theme={"system"}
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
  },
  body: JSON.stringify({
    personaConfig: {
      name: "Multilingual Assistant",
      avatarId: "avatar-uuid",
      avatarModel: "cara-4",
      voiceId: "voice-uuid",
      llmId: "llm-uuid",
      systemPrompt:
        "You are a helpful assistant. If the user asks to switch languages, use change_language. If the user needs another turn to continue speaking, use skip_turn. If the user explicitly requests a pause, use pause_conversation.",
      toolIds: [
        "system-tool-uuid-1",
        "system-tool-uuid-2",
        "system-tool-uuid-3",
      ],
    },
  }),
});
```

Or attach them to an existing persona:

```http theme={"system"}
PUT /v1/personas/{personaId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "toolIds": ["system-tool-uuid-1", "system-tool-uuid-2", "other-tool-id"]
}
```

> [!NOTE]
>
> System tools are pre-provisioned for all organizations. You only need to fetch the IDs once — they remain the same across sessions.

## How System Tools Differ from Other Tools

| | System Tools | Client Tools | Webhook Tools | Knowledge Tools |
| - | - | - | - | - |
| **Runs where** | Inside the engine | In your client app | External HTTP endpoint | Engine-side RAG search |
| **Latency** | Near-instant | Depends on client | Network dependent | Depends on corpus size |
| **Setup needed** | Just `type` + `name` | Client-side handler | URL + endpoint | Document upload |
| **Use case** | Session control | UI actions | External APIs | Document search |

## Next Steps

> [card] [Multilingual Support](https://anam.ai/docs/personas/voices/multilingual.md)
>
> Learn more about configuring languages for your personas

> [card] [Tools Overview](https://anam.ai/docs/personas/tools/overview.md)
>
> Explore all tool types available in Anam


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