System Tools

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

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.

type

string

required

Must be "system"

name

string

required

Must be "skip_turn"

Tool parameters (set automatically by the LLM):

timeout_seconds

number

How long to wait in seconds before prompting the user again. Defaults to 30. Must be a positive number.

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.

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.

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:

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.

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.

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

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

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

Introduction

Personas

Security & Network

Resources

System Tools

Overview

Available System Tools

change_language

skip_turn

end_call

Adding System Tools to a Persona

Step 1: Fetch System Tool IDs

Step 2: Attach to a Session or Persona

How System Tools Differ from Other Tools

Next Steps

Multilingual Support

Tools Overview

Introduction

Personas

Security & Network

Resources

Documentation Index

​Overview

​Available System Tools

​change_language

​skip_turn

​end_call

​Adding System Tools to a Persona

​Step 1: Fetch System Tool IDs

​Step 2: Attach to a Session or Persona

​How System Tools Differ from Other Tools

​Next Steps

Multilingual Support

Tools Overview

Overview

Available System Tools

change_language

skip_turn

end_call

Adding System Tools to a Persona

Step 1: Fetch System Tool IDs

Step 2: Attach to a Session or Persona

How System Tools Differ from Other Tools

Next Steps