Update Agent
Update an agent's deployment binding and/or its A2A exposure flags. See PATCH /agents/{agent_id}/stage/agent for the Versioned-surface settings (system prompt, LLM provider binding, conversation storage, evaluation, widget, and custom-variable settings), and PATCH /agents/{agent_id}/stage/voice for voice pipeline settings.
Authorization
OAuth2AuthorizationCodeBearer In: header
Path Parameters
uuidQuery Parameters
trueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
deployment_id, a2a_open, and a2a_discoverable - the non-Versioned subset of what this schema used to carry in one call. Every field is independently optional so any subset can be sent alone; an explicit null deployment_id unbinds the agent, while an omitted one leaves the binding untouched (callers distinguish the two via model_fields_set). At least one is expected but that is left to the route to enforce, matching the rest of this file's patch schemas.
Every other field this schema used to declare (system_prompt, first_message, llm_provider_id, conversation_storage_enabled, evaluation settings, widget settings, custom_variables) moved to AgentStagePatchIn below, served from PATCH /agents/{agent_id}/stage/agent - those are the Versioned-surface fields a future Publish step snapshots, while deployment_id/a2a_open/a2a_discoverable are not part of that surface and stay on this original route.
voice moved to its own dedicated PATCH /agents/{agent_id}/stage/voice
route (AgentVoicePatchIn accepted directly as that endpoint's body,
rather than nested under a voice key) - it carries the agent's entire
voice configuration and warrants its own endpoint rather than sharing
this one, matching every other Versioned-surface field's move above.
extra="forbid" so a client still sending a since-relocated field here (e.g. system_prompt, voice) gets a clear 422 instead of a silent no-op.
Response Body
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6", "llm_provider_id": "01f100ab-eef6-496a-9799-f8fbf49c6288", "llm_model": "string", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "event_org_id": "38381290-8ff7-413c-a0d2-e750a21c5122", "system_prompt": "string", "first_message": "string", "a2a_open": true, "a2a_discoverable": true, "conversation_storage_enabled": true, "voice": { "pipeline_mode": "string", "language": "string", "silence_end_call_timeout_secs": 0, "cascade": { "stt_provider_id": "d4a67d44-bb59-4313-9013-67e80ee06719", "stt_model": "string", "tts_provider_id": "548bbff5-1048-4ad8-a0df-cd333e015434", "tts_model": "string", "tts_voice_id": "11bfaa1c-5a0e-4a01-aa9f-9c79a298dae1", "enable_interruptions": true, "min_words_before_interruption": 0, "vad_confidence": 0, "vad_start_secs": 0, "vad_stop_secs": 0, "vad_min_volume": 0, "turn_model": "string", "eagerness": "string", "turn_timeout_secs": 0, "asr_keywords": [ "string" ], "filter_background_speech": true, "input_audio_format": "string", "interruption_ignore_terms": [ "string" ], "transcribe_on_disabled_interruptions": true }, "s2s": { "realtime_provider_id": "15347105-df5d-4c64-b3e4-5148a8ebb81c", "realtime_model": "string", "decision_provider_id": "c9798dc0-90d8-4341-8778-6ff2649d592b", "decision_model": "string", "voice_id": "2235c634-e4db-4ad6-aa15-066fb69b1c8f", "turn_detection_type": "string", "turn_threshold": 0, "prefix_padding_ms": 0, "silence_duration_ms": 0, "eagerness": "string" } }, "has_workflow": false, "state_schema": {}, "evaluation_enabled": true, "extraction_field_defs": [ { "name": "string", "type": "string", "description": "string", "enum_values": [ "string" ] } ], "evaluation_criteria_defs": [ { "name": "string", "description": "string" } ], "pii_redaction_enabled": true, "widget_enabled": true, "widget_public": true, "widget_embed_key": "string", "widget_accent_color": "string", "widget_orb_color_1": "string", "widget_orb_color_2": "string", "widget_allowed_domains": [ "string" ], "widget_placement": "string", "widget_style_overrides": { "property1": "string", "property2": "string" }, "custom_variables": { "property1": "string", "property2": "string" }, "max_conversation_duration_seconds": 0, "max_duration_message": "string", "conversation_retention_days": 0, "workflow_run_io_retention": 30, "recording_enabled": true, "audio_retention_days": 0, "client_events": [ "string" ], "chat_mode_enabled": true, "dtmf_enabled": true, "visitor_thread_window_minutes": 0, "visitor_memory_enabled": true, "visitor_memory_scope": "string", "visitor_memory_days": 0, "visitor_memory_include_soft_links": true, "emotion_enabled": false, "emotion_engine": "string", "attachments_enabled": false, "vision_mode": "auto", "attachment_retention": "conversation", "vision_analysis_provider_id": "38a9be8b-83a5-41fc-b444-d5d6911c3198", "vision_analysis_model": "string", "vision_analysis_instructions": "string", "max_attachments_per_message": 5, "max_attachments_per_conversation": 20, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "can_modify": false, "run": { "token": "string", "run_id": "string", "expires_at": "2019-08-24T14:15:22Z", "deadline_at": "2019-08-24T14:15:22Z" }}{ "detail": "string", "code": "string"}{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ]}