Agent configuration - Cartesia Docs

An agent’s config controls its behavior, model, audio, and tools. Set it when you create an agent. To change it, send only the fields you want to update with PATCH /v1/agents/{agent_id}.

Agent configuration page in the Playground showing instructions, welcome message, voice, and LLM settings — The same settings in the Playground: instructions, welcome message, voice, and LLM.

{
  "name": "Acme Support",
  "config": {
    "instructions": "You are Acme's support agent. Help callers with orders and returns. Be warm and concise.",
    "initial_message": "Hi, thanks for calling Acme. How can I help?",
    "timezone": "America/Los_Angeles",
    "model": { "id": "gpt-5.4-mini" },
    "language": { "primary": "en" },
    "audio": {
      "input": {
        "noise_suppression": "auto",
        "keyterms": ["Acme", "ProGrip"]
      },
      "output": {
        "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        "speed": 1.0
      }
    },
    "tools": [{ "id": "agent_tool_5RkP2wZmQ8xTnLc4vB7dHy" }],
    "system_tools": {
      "end_call": {
        "description": null,
        "pre_tool_speech": "force"
      }
    }
  }
}

Instructions and greeting

Use instructions to define the agent’s role, speaking style, objectives, and limits. A short structure makes the prompt easier to review and maintain:

# Identity and personality
You are Acme's friendly and concise support agent.

# Speaking rules
Use short sentences. Ask one question at a time.

# Objectives
Help callers check orders and start returns.

# Guardrails
Never invent order details. Ask for an order number before using the lookup tool.

initial_message 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 welcome message uses the values available when the call starts. Updates do not rewrite earlier messages in the conversation. Use Variables in the Playground to save samples for test calls, or set config.dynamic_variable_placeholders through the API. Production calls never use saved samples.

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, choose the time zone under Settings.

Model

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

Language

language.primary sets the language used for speech recognition, agent responses, and speech synthesis. Use a supported ISO 639-1 code such as en, es, or de.

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

Field	Description
`voice_id`	Voice used for agent speech. Required.
`speed`	Speech speed from `0.6` to `1.5`. `null` uses the voice default.
`volume`	Speech volume from `0.5` to `2`. `null` uses the default.
`emotion`	Emotion supported by the selected voice, such as `calm`, `happy`, or `sad`.
`pronunciation_dictionary_id`	Pronunciation dictionary used when the agent speaks.
`background_sound`	Ambient audio with a `file_id` and volume from `0` to `2`. `null` disables it.

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, and transferring to a phone number. See Tools for how each kind works and how to configure it. Every effective configuration change creates an immutable version.

​Instructions and greeting

​Time zone

​Model

​Language

​Audio input

​Audio output

​Tools