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

<ParamField path="type" type="string" required>
  Must be `"system"`
</ParamField>

<ParamField path="name" type="string" required>
  Must be `"change_language"`
</ParamField>

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

<ParamField path="language_code" type="string" required>
  ISO 639-1 language code (e.g., `"fr"`, `"de"`, `"ja"`)
</ParamField>

**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](/docs/personas/voices/multilingual) for more on language configuration.
</Warning>

***

### skip\_turn

Allows the persona to skip generating a spoken response and wait silently for the user to continue speaking. This is useful when the persona determines that no verbal response is needed — for example, when the user is in the middle of a thought or when silence is the most natural response.

<ParamField path="type" type="string" required>
  Must be `"system"`
</ParamField>

<ParamField path="name" type="string" required>
  Must be `"skip_turn"`
</ParamField>

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

<ParamField path="timeout_seconds" type="number">
  How long to wait in seconds before prompting the user again. Defaults to `30`. Must be a positive number.
</ParamField>

**Example conversation:**

> **User:** "Hold on, let me think about this..."
>
> **Persona** calls `skip_turn` with `timeout_seconds: 30` → stays silent for up to 30 seconds.
>
> The persona waits quietly until the user speaks again or the timeout elapses.

<Tip>
  The `skip_turn` tool helps create more natural conversation flow by preventing the persona from filling every pause with speech. Consider adding guidance in your system prompt about when the persona should use this tool.
</Tip>

***

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

<ParamField path="type" type="string" required>
  Must be `"system"`
</ParamField>

<ParamField path="name" type="string" required>
  Must be `"end_call"`
</ParamField>

The tool takes no parameters.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/docs/personas/tools/overview#protecting-tool-turns-from-interruptions).
</Note>

## 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",
      ...
    }
  ]
}
```

### 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 the change_language tool. If the user needs time to think, use the skip_turn tool to wait silently.",
      toolIds: ["system-tool-uuid-1", "system-tool-uuid-2"],
    },
  }),
});
```

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"]
}
```

<Info>
  System tools are pre-provisioned for all organizations. You only need to fetch the IDs once — they remain the same across sessions.
</Info>

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

<CardGroup cols={2}>
  <Card title="Multilingual Support" icon="globe" href="/docs/personas/voices/multilingual">
    Learn more about configuring languages for your personas
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/docs/personas/tools/overview">
    Explore all tool types available in Anam
  </Card>
</CardGroup>