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?",
    "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.

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 the agent listens and speaks in, as an ISO 639-1 code such as en, es, or fr. Set it to null to detect the caller’s language automatically.

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.

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

​Model

​Language

​Audio input

​Audio output

​Tools