Sign in
Agents

Update agent conversation and voice settings

Changed on

Update the conversation and voice configuration of a specific agent.

Updatable fields (partial update — only the fields you send are changed):
- `prompt_instructions`: the custom instructions driving the agent behaviour
- `first_message`: the message the agent says when the conversation starts
- `ai_provider`: public voice model selector, including `zeta` for GPT Live 1
- `selected_voice`: compatible voice ID; the provider is validated from the voice
- `default_language` and `supported_languages`: language configuration
- `conversation_style`: tone, formality, response length and pace
- `live_conversation_settings`: GPT Live backchannels, pauses and reference
  pronunciations. Within this object, omitting or nulling `pronunciations`
  keeps the agent's current list; sending an empty list clears it
- `live_reasoning_effort`: GPT Live delegated backend, low/medium/high; null follows medium
- `reasoning_effort`: Grok only, none/high; null follows the platform default
- `gemini_backend`: Gemini only, vertex_ai/google_ai_studio; null follows the platform default

Effort preferences and the Gemini backend remain stored but inactive when another model is selected.
Read `/agents/models` for supported effort levels and the effective backend model.

Sending an explicit `null` clears nullable configuration fields. A blank
string clears only `prompt_instructions` and `first_message`; blank model,
voice, language, style or Live settings values are rejected. Omitting a
field leaves it untouched. An empty body is rejected with 400.

Phone routing, caller IDs, and agent type remain internal lifecycle settings.
Voice/model writes use the same provider compatibility and GPT Live rollout
checks as the dashboard.

Unknown fields are rejected with 400, so a typo (or an attempt to change a
read-only field) never looks like a successful update.

The agent must belong to your organization. Attempting to update an agent
from another organization will return 404.

Authentication:
- API key with READ_WRITE permission, or
- OAuth access token granted the `agents:write` scope
patch/agents/{agent_id}

Request

  • Base URL: https://api.yourang.ai/v1
  • URL: https://api.yourang.ai/v1/agents/{agent_id}
  • Auth: API Key (a scheme the document does not define)

Path parameters

agent_idstring uuid required

Request body

prompt_instructionsstring nullable

Custom prompt instructions driving the agent's behaviour during a call. Send null to clear them and fall back to the default prompt.

first_messagestring nullable

Initial message the agent says when the conversation starts. Send null to clear it (the agent opens the conversation on its own).

ai_providerstring nullable

Voice model selector, such as 'base' (OpenAI), 'beta' (Gemini), or 'zeta' (GPT Live 1). Availability is validated by the service.

selected_voicestring uuid nullable

ID of the voice to use; its provider is validated automatically.

default_languagestring nullable

ISO 639-1 default language for the agent.

supported_languagesstring[] nullable

ISO 639-1 languages supported by the agent.

live_reasoning_effort'low' | 'medium' | 'high' nullable

GPT Live delegated reasoning. Omit to preserve; null resets to medium. Inactive on other models.

reasoning_effort'none' | 'high' nullable

Grok reasoning. Omit to preserve; null follows the platform default. Inactive on other models.

gemini_backend'vertex_ai' | 'google_ai_studio' nullable

Gemini Live backend: 'vertex_ai' (EU-resident, best phone transcription, platform default) or 'google_ai_studio' (gemini-3.8-live, newest model). Omit to preserve; null follows the platform default. Inactive on other models.

Example request

{
  "ai_provider": "zeta",
  "conversation_style": {
    "custom_note": "",
    "formality": "balanced",
    "pace": "natural",
    "response_length": "concise",
    "tone": "warm"
  },
  "default_language": "it",
  "first_message": "Hello! How can I help you today?",
  "live_conversation_settings": {
    "backchannels": "natural",
    "pauses": "patient"
  },
  "prompt_instructions": "You are the reception assistant. Be polite and concise. Help guests with check-in, check-out and general inquiries.",
  "selected_voice": "770e9611-49d6-3f6c-9386-688776611112",
  "supported_languages": [
    "it",
    "en"
  ]
}

Response

Successfully updated the agent

okboolean required

Example response

{
  "data": {
    "voice": {
      "ai_provider": "base",
      "custom_name": "Marco",
      "description": "Una voce equilibrata e versatile adatta alla maggior parte delle applicazioni",
      "file": {
        "content_size": 1024,
        "content_type": "audio/mpeg",
        "file_name": "voice.mp3",
        "id": "aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f",
        "url": "https://s3.example.com/some-generated-id/logo.png"
      },
      "id": "aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f",
      "language": "it",
      "recommended_for": []
    }
  }
}

Changes

  • 7b18ba00cfb7Revision changes
    • ○

      added the new optional request property

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

  • c3b6133647f1Revision changes
    • ○

      added the new optional request property //

    • ○

      added the optional property //// to the response with the status

    • ○

      added the optional property //// to the response with the status

    • ○

      added the optional property //// to the response with the status