Skip to main content
The API reference covers every field on the agent object. This page covers the parts that need more context than a schema can give: agent fields, model configuration, system prompt structure, tools, and template variables. You can manage agents through the API or through Managed Agents. For working code examples (create, update, delete), see API examples.

​
Agent fields

​
Required fields

​
Common optional fields

​
Models

The models object configures the STT, LLM, and TTS models used by the agent runtime:

​
Finding models

Browse STT and TTS models with the Catalog API: GET https://api.slng.ai/v1/catalog/models lists the catalog and supports service_type, language, and region query parameters, and GET https://api.slng.ai/v1/catalog/models/{model_code} returns a single model’s details, including its voices for TTS models. The Models pages on this site show the same catalog. For LLM options, open your agent in the Dashboard and check the Models tab of the agent editor — it lists the LLMs available for your agent’s language and region combination.

​
Fallbacks and timeouts

​
Writing a system prompt

A system prompt tells the agent who it is, how to talk, and what to do on the call. We recommend splitting it into five sections:
A few things worth calling out:
  • Keep it spoken. The output goes through TTS, so write the way you’d actually talk. No markdown formatting, no numbered lists in the agent’s responses.
  • One question per turn. Stacking questions confuses both the caller and the STT model.
  • Use <wait for response> markers. They make the conversation flow explicit for the LLM.
  • Normalize for speech. Phone numbers, dates, and times should be written out the way you’d say them aloud.

​
Tools

Tools live in your organisation library. You create a draft once, test it, publish an immutable version, and attach that version to one or more agents. New agents use tool_mode: "shared" and reference tools through tool_refs. MCP tools use mcp_refs.
Tool drafts are never attached directly. An attachment always pins a published version, so editing or publishing a new version cannot change a live agent until you upgrade its attachment.

​
Create a Custom Code tool

Custom Code uses Pydantic models for its input and output contract and a handler(input) entry point. The sandbox has no internet access. Add exact pinned Python dependencies when you need packages beyond the runtime.
cURL
The response contains the tool id. Use it for the remaining steps:
cURL
A dependency environment can still be preparing when you build, run, publish, attach, or upgrade a tool. Retry the same request after the Retry-After delay when the API returns 202 or a retryable preparation response.

​
Attach a published tool

Create an agent with the published tool ID and version:
The model sees the published tool schema and decides when to call a model-invoked attachment. You can override its model-facing description or lock declared arguments through argument_overrides. To change attachments on an existing agent:
  1. Download the complete document with GET /v1/agents/{agent_id}/config.
  2. Edit tool_refs or mcp_refs.
  3. Send the complete document with PUT /v1/agents/{agent_id}.
PATCH does not change shared attachments because attachment validation and dependency preparation require the full agent document.

​
Run a tool automatically

Custom Code, API Request, Current Date and Time, and User Phone Number tools can run automatically from system events. Set invocation to system, then provide its triggers and arguments:
Available events are call_start, first_user_message, call_end, tool_succeeded, and tool_failed. Custom Code supports every event except call_end. The other supported system tool types support all five events. For tool outcome events, set source_attachment_id to the attachment that must succeed or fail.

​
Attach an MCP tool

Register an MCP server with POST /v1/agents/mcp-servers, then call its connect endpoint to discover tools and their schema hashes. Attach one discovered tool by pinning the exact hash you reviewed:
MCP attachments are always model-invoked. If the remote schema changes, reconnect the server, review the new schema, and update the attachment hash before the agent can use it.

​
Idle nudges

idle_nudges configures what the runtime should do when the caller goes silent for too long.
If you omit idle_nudges, the backend can apply language-specific defaults when returning the agent configuration.

​
Runtime behavior

Some behavior is built into the agent runtime and worth knowing about when you design a call flow.

​
Turn taking and interruptions

enable_interruptions (default true) controls whether the caller can talk over the agent. When enabled, the runtime applies adaptive interruption handling: brief sounds and backchannels don’t cut the agent off, and if the agent stops for what turns out to be a false interruption, it resumes speaking where it left off. When disabled, the agent finishes what it is saying regardless of caller audio.

​
Noise cancellation

Noise cancellation is always on. The runtime applies it automatically to both phone and web calls — there is nothing to configure.

​
Failure audio

When model warm-up or a fatal model failure prevents the call from proceeding, the caller hears a short localized “technical difficulties” message before the call is hung up, instead of silence. This is on by default; set "failure_audio_enabled": false in the models object to hang up without the message.

​
Idle nudges and tools

Idle nudge timers pause while a tool is executing, so a slow API Request does not trigger an “are you still there?” prompt during a lookup. The timers resume when the tool completes.

​
Human transfer teardown

After a successful transfer, the agent leaves the call and the caller talks to the transfer target directly. The session ends when either remaining party disconnects.

​
Attachment values

An attachment can adapt one published tool for a specific agent without changing the shared version. Use argument_overrides to lock a declared tool argument to one value source:
Use config_overrides only for the fields supported by the attached tool type. For example, an API Request attachment can override its URL, and a Current Date and Time attachment can override its timezone. Custom Code has no config overrides. You can also change the description shown to the model or add a pre-action message:

​
Template variables

Use {{variable_name}} anywhere in the system_prompt or greeting to inject values at runtime. There are two layers:
  1. template_defaults: Default values set on the agent itself. These apply to every call unless overridden.
  2. arguments: Per-call overrides passed when dispatching a call.
In this example, patient_name resolves to “Maria” (from the call arguments) and practice_name resolves to “Greenfield Family Medicine” (from the agent defaults). The API response includes a template_variables field that lists every {{variable}} found in the prompt, along with whether it has a default value. This is useful for validating your templates before dispatching calls. Per-call arguments are limited to 32 keys, with keys up to 64 characters, values up to 1024 characters, and a combined value payload up to 8192 characters.

​
Optional variables

Every template variable is required by default: dispatching a call without a value for it (from arguments or template_defaults) is rejected. Use template_variable_options to mark a variable optional:
template_variable_options maps a variable name to its options — currently required (boolean, default true). An optional variable does not need a default: you can save the agent and dispatch calls without supplying a value. At dispatch, a missing optional variable renders as an empty string in the prompt and greeting, and a non-required system tool argument that references it is skipped instead of failing the tool. Optional variables are not supported in API Request URLs.

​
Runtime variables

Use runtime_variables when the model needs to capture call-scoped values during the conversation and reuse them later in tool configuration. These values:
  • exist only for the active call or web session
  • are set by the model through the built-in set_runtime_variables tool
  • can be referenced in API Request URLs and automatic tool template arguments using the same {{variable_name}} syntax
After the call, the captured values are included in the call detail response as memory_variables: each runtime variable comes back with its value and a status of "set" or "unset", so you can see what the model captured without parsing the transcript.

​
Next steps

API examples

Create, test, update, and delete agents with code.

Dispatching calls

Outbound calls, template variables, and batch dispatch.