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

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

The silence breaker remains active after skip_turn and follows the configured silenceBeforeAutoEndTurnSeconds. 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.

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.

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.

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:

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:

{
  "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:

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:

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

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

Multilingual Support

Learn more about configuring languages for your personas

Tools Overview

Explore all tool types available in Anam