Update an agent
update_agentUpdate selected fields on a saved workspace agent.
Omitted fields retain their values. Repeating the same update gives the same result. Changing only language or voice preserves the other value. A field cannot be both set and cleared in the same request. Removing a greeting makes an inbound agent wait for the caller. Other resets restore workspace defaults; the handover limit resets to 1800 seconds. Existing calls keep their starting settings; changes affect later calls and texts. Returns the updated agent or an error.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"agent_id": "<agent_id>"
},
"name": "update_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Agent display name. | |
| tools | No | Names of the tools the agent may use during a call or reply. Omitted: every tool the workspace's channels support. An empty list: none. | |
| status | No | ``paused`` stops the agent answering; ``live`` turns it back on. | |
| agent_id | Yes | Saved agent ID, from ``list_agents`` or ``create_agent``. | |
| language | No | Language the agent speaks, as an ISO 639-1 code such as ``es``. Omitted: English. | |
| voice_id | No | Text-to-speech voice ID from the voice provider that serves the call, such as an ElevenLabs voice ID. Omitted: the workspace's default voice. | |
| llm_model | No | Model ID of the calling agent. Optional. Recorded for analytics only. | |
| http_tools | No | Up to ten customer APIs the agent may call during calls, texts and email. Each entry: ``name`` (letters, digits, _), ``description`` (read by the model), ``url`` (public https), optional ``parameters`` (JSON Schema, type object), ``headers`` (static, stored encrypted, returned as names only), ``timeout_seconds`` (1 to 10, default 5) and ``wait_message`` (said on a call while waiting). The list replaces the saved one; an empty list removes it. On update, an entry without ``headers`` keeps the saved headers of the same name while the url keeps its host; a url on a new host needs ``headers`` again. The first save returns ``http_tool_secret`` once; requests carry ``X-Hail-Signature`` signed with it. | |
| sms_enabled | No | Whether this agent answers texts on numbers whose texts route to it. | |
| clear_fields | No | Settings to reset to the workspace default. Omitted: nothing is reset. | |
| ai_disclosure | No | Speak the AI disclosure line first on every call. | |
| email_enabled | No | Whether this agent replies to mail on addresses routed to it. | |
| first_message | No | Greeting spoken after the AI disclosure. Without one, an inbound agent waits for the caller. | |
| system_prompt | No | Instructions that define the agent's behavior on calls, texts and email replies. | |
| voice_enabled | No | Whether this agent answers calls on numbers whose calls route to it. | |
| handover_contacts | No | Replaces the whole handover list; an empty list removes it. Up to ten ``{contact_id, note}`` entries, with ``contact_id`` from ``list_contacts``, ``lookup_contact`` or ``create_contact`` and a ``note`` of 1 to 200 characters. | |
| recording_enabled | No | Recording for this agent's calls. ``true`` or ``false`` overrides the workspace setting. | |
| ai_disclosure_line | No | Custom AI disclosure line replacing the workspace line. ``{org}`` expands to the organization name. | |
| max_duration_seconds | No | Longest a call with this agent may last, in seconds, counted from pickup. At the limit the agent says goodbye and hangs up. Omitted: the workspace's call limit. | |
| handover_max_duration_seconds | No | Longest a call may last after a handover contact answers, in seconds, counted from that answer. Omitted: 1800 (30 minutes). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||