Create an agent
create_agentSave an agent for calls, texts, and email replies.
A handover contact's phone number is hidden from the call agent. Saving an agent does not change any phone number's routing. Returns the saved agent record 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": {
"name": "<name>",
"system_prompt": "<system_prompt>"
},
"name": "create_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | 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. | |
| 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. | |
| 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 | Yes | 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 | Up to ten ``{contact_id, note}`` entries for people a call can be handed over to. ``contact_id`` is an ID from ``list_contacts``, ``lookup_contact`` or ``create_contact`` (a UUID or ``member:<user_id>``); the contact needs a phone number. ``note`` (1 to 200 characters) says when the agent hands over to that person, such as ``billing questions``. | |
| 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 | |||