config controls its behavior, model, audio, and tools. Set it when you create or update an agent.

The Configuration page in the Playground.

The Advanced page in the Playground.
Instructions and initial message
Useinstructions to define the agent’s role, speaking style, objectives, and limits. A short structure makes the prompt easier to review and maintain:
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, setconfig.initial_message_interruptions:
In the Playground, click Customize on the Introduction row and pick one under Interruptions.
Time zone
Setconfig.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_suppressioncontrols cleanup of incoming audio. Useautofor most calls,maxfor noisy environments, oroffto disable it.keytermshelps 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.
Audio output
Turn settings
Set these fields underconfig.turn:
inactivity_end_call_secs: Seconds of inactivity before the agent says a farewell message and ends the call, from20to240. Defaults to240; cannot benull.inactivity_check_in_secs: Seconds of inactivity before the agent checks in, from5to60. Defaults to8. Set tonullto disable check-ins. When enabled, it must be less thaninactivity_end_call_secs.
Speculative generation
To lower response latency, enableconfig.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:
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 lists each change before it goes live.
Version contents
A version contains a complete configuration snapshot and creation metadata: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 itsconfig, 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.