Skip to main content
An agent’s config controls its behavior, model, audio, and tools. Set it when you create or update an agent.
In the Playground, Configuration holds the system prompt, introduction, model, voice, and language.
Agent configuration page in the Playground showing the system prompt, introduction, model, voice, and language

The Configuration page in the Playground.

Advanced holds settings such as noise suppression, silence timeouts, and time zone. Some fields are API only.
Advanced page in the Playground showing the Conversation and Speech settings

The Advanced page in the Playground.

Instructions and initial message

Use instructions to define the agent’s role, speaking style, objectives, and limits. A short structure makes the prompt easier to review and maintain:
The initial message, initial_message (Introduction in the Playground), is what the agent says when the call begins. Set it to null to wait for the caller to speak first. Both fields accept dynamic variables, such as {{customer_name}}. The agent’s instructions use the latest values each time the model responds. The initial message uses the values available when the call starts. Updates do not rewrite earlier messages in the conversation. Click Vars in the Playground header to set sample values for preview calls, or set config.dynamic_variable_placeholders through the API. Production calls never use saved samples.

Initial message interruptions

To play the initial message in full, for example to read a recording notice or disclaimer, set config.initial_message_interruptions: In the Playground, click Customize on the Introduction row and pick one under Interruptions.

Time zone

Set config.timezone to an IANA time zone, such as America/Los_Angeles, to control {{system__time}}. It defaults to UTC. In the Playground, set Time zone on the Advanced page.

Model

model.id selects the LLM that generates the agent’s responses. model.temperature and model.max_output_tokens tune its output. See Managed LLMs for the available models and settings.

Language

language.primary sets the language each call starts in. Use a supported language or locale such as en, or en-GB for a regional accent. Configure language.additional to allow the agent to switch between the configured languages when the caller asks. Otherwise, calls stay in the primary language. Use language.presets to give a language or locale its own voice_id, normalization, or both. A preset applies only when the agent speaks that exact language or locale, including the primary language.
normalization controls how the agent reads numbers, dates, times, and currency aloud. Set it to a supported locale to use that locale’s text normalization conventions. Leave it unset to use the conventions of the language the agent is speaking. Unlike the TTS API, it doesn’t accept auto, off, or a bare language code such as en. In this example, the agent uses <spanish_voice_id> for Mexican Spanish and its default voice for the other languages. In US English and Hindi, it reads rupee amounts and dates as Indian English does, so ₹1,25,000 becomes “one lakh twenty-five thousand rupees”. When you update the agent, the presets map you send replaces the saved one, so include every preset you want to keep. See language configuration in Create Agent for details.

Audio input

  • noise_suppression controls cleanup of incoming audio. Use auto for most calls, max for noisy environments, or off to disable it.
  • keyterms helps Ink recognize names and domain-specific phrases. See Improve transcription with keyterms. Keyterms affect recognition; a pronunciation dictionary changes how the agent speaks a word.
Dynamic variables in keyterms use the values available at startup; later assignments do not update them.

Audio output

Turn settings

Set these fields under config.turn:
  • inactivity_end_call_secs: Seconds of inactivity before the agent says a farewell message and ends the call, from 20 to 240. Defaults to 240; cannot be null.
  • inactivity_check_in_secs: Seconds of inactivity before the agent checks in, from 5 to 60. Defaults to 8. Set to null to disable check-ins. When enabled, it must be less than inactivity_end_call_secs.

Speculative generation

To lower response latency, enable config.speculative_generation. When enabled, the LLM starts generating a response when the speech-to-text model predicts the caller has finished speaking and emits an eager end-of-turn event. The agent does not speak or execute tools until the model confirms the turn has ended. If the caller resumes speaking, the agent cancels the speculative response. Discarded responses still consume LLM tokens, so enabling this setting can increase LLM costs. The setting defaults to true for new agents. To disable it, set AGENT_ID and CARTESIA_API_KEY, then update the agent:
Set the value to true to enable it again. Omitting the field from an update preserves the agent’s current setting.

Tools

tools lists the shared webhook and client tools the agent can invoke, by ID. system_tools enables the built-in actions: ending the call, sending DTMF tones, skipping a turn, detecting voicemail, and transferring the call to a phone number or SIP URI. See Tools for how each kind works and how to configure it.

Versions

When you change an agent’s configuration in a way that affects behavior, Cartesia saves a full config snapshot as a version. New calls use the latest version. A call already in progress stays on the version it started with. API updates take effect when they succeed. In the Playground, edits stay in a draft until you click Publish, which lists each change for review. Preview runs the draft in your browser, except for speed, pronunciation dictionary, silence timeouts, and time zone, which take effect after you publish. Phone calls always use the published version.
Publish dialog in the Playground listing the changes in the draft

Publish lists each change before it goes live.

Version contents

A version contains a complete configuration snapshot and creation metadata:
To label a new version, set version_description when you update the agent. The version record returns this label as description. Metadata-only updates, such as changing the agent’s name, do not create versions, and version_description is not allowed on them.

Browse version history

GET /v1/agents/{agent_id}/versions lists versions from newest to oldest. GET /v1/agents/{agent_id}/versions/{version_id} returns one version with its complete configuration.

Restore a version

To restore a version, read its config, then send it through PATCH /v1/agents/{agent_id}. That creates a new version instead of rewriting history. Cartesia validates the configuration again. If it references a deleted resource or a model that is no longer offered, replace that reference before restoring it.

Referenced resources

Versions store tool and voice IDs, not copies of those resources. Editing a tool affects every agent that references it without creating an agent version. To avoid changing the behavior of earlier versions, create a new tool and attach it instead.