Agents

Display name for the agent.

LLM system prompt that defines the agent's persona and behavior.

Voice to use for TTS. Must be a valid voice ID from GET /voices.

Optional prompt for text conversations. WhatsApp messages, SMS and the chat API use it in place of system_prompt. Calls, WhatsApp calls included, always use system_prompt. Leave it out to use system_prompt everywhere.

Greeting the agent says when a call connects. If omitted the agent waits for the user to speak first.

Language for STT and TTS (e.g. english, french). Default: english.

Dialect style override (e.g. formal, local). Provider-specific.

Arbitrary key-value pairs stored with the agent.

LLM model ID — a public catalog name from GET /api/v1/models (for example claude-sonnet-4-6, gpt-4o, or aethex-default). Omit it or send an empty string to use the platform default. Responses always echo the public catalog name; the internal provider routing behind it is never exposed.

Sampling temperature (0.0–2.0). Lower values produce more deterministic responses. Ignored for OpenAI's reasoning models (the o-series and the gpt-5 family), which take no temperature.

Maximum tokens per LLM response, an integer from 1 to 8192. Omit or send null for the platform default (configurable via AETHEX_LLM_MAX_COMPLETION_TOKENS, 512 unless the deployment overrides it).

Maximum LLM context window for this agent (1024–262144 tokens). Null uses the platform default.

LLM frequency penalty between -2.0 and 2.0. Omitting or sending null falls back to the Aethex platform default of 0.4 (not a provider-native default).

LLM presence penalty between -2.0 and 2.0. Omitting or sending null falls back to the Aethex platform default of 0.9 (not a provider-native default).

Hard cap on call duration in seconds (30–3,600). Call ends automatically when reached.

End the call if the user is silent for this many seconds. Null disables.

Hang up when the caller begins their Nth user turn, where N is this value (1–1000); that turn is not answered. Null inherits the platform default (no turn cap).

Drop older turns once the conversation grows long. Null inherits the platform default; the platform overrides false on models it serves itself.

Turn count that triggers truncation (1–200) — not the number of turns retained. Null inherits the platform default.

Which of your text messages this agent may send, by id. Omit or send [] for every active message. Past about 8 choices an agent picks between them less reliably — advice, not a limit.

How many times one call may send the same message (1–30). Null inherits the default of 2. The call's own ceiling still bounds the total.

Allow the caller to interrupt the agent mid-response (default: true).

How long, in seconds, the caller must keep talking over the agent before it stops to listen, from 0 to 3. A shorter sound, such as a cough or a quick "mm-hmm", no longer cuts the agent off, and the agent does not respond to it. While the agent is silent, speech starts the caller's turn at once; on some models a reply that is about to play is protected the same way, so a short sound just before it does not cancel it. Null uses the platform default of 0.6; 0 stops the agent at the first speech it hears. A change applies from the agent's next call.

How aggressively the agent claims its turn: patient, normal, or eager. Null uses the platform default.

Whether the agent may end the call itself (default: true).

Phrases the caller may say to end the call. When the agent hears any of them, it says a brief goodbye and ends the call.

When to end calls: auto_detect (LLM intent + phrases) or phrases_only (default: auto_detect). phrases_only is advisory — it steers the agent toward ending on your end_call_phrases, but the model may still end on a clear conversation conclusion.

Detect when the call has gone to voicemail (default: false).

Message to leave when voicemail is detected. Requires voicemail_detection_enabled=true.

What to do on voicemail: leave_message or hangup (default: leave_message).

Play a holding message at the start of inbound calls before the agent picks up (default: false).

Lobby greeting text, up to 120 characters.

Lobby background audio: none, ambient, or instrumental (default: ambient).

Maximum lobby wait in seconds (0–60, default: 45).

Whether to record the call audio (default: true).

Whether to store the conversation transcript (default: true).

When on, anyone can start a call with this agent from a browser or app using only its id, with no API key or proxy. Off by default. You are billed for public calls as usual, and platform limits cap abuse. Use allowed_origins to restrict which websites may embed it.

Optional list of website hostnames allowed to embed a public agent in a browser, for example example.com or app.example.com. Leave empty to allow any origin. Applies to browsers only, since native apps and servers send no origin. Has no effect unless public_access is on.

Block off-topic responses (default: true).

Block unsafe content (default: false).

Custom natural-language rules: list of { name, prompt, is_enabled } objects.

How strictly the agent follows its system prompt: strict, medium, or loose (default: strict).

Whether the agent accepts keypad (touch-tone) input on phone calls, so a caller can key in a reference or card number instead of saying it. On by default. No effect on browser agents, which have no keypad.

Seconds of user silence before the agent checks in (1.0–600.0). Defaults to 15 seconds when unset.

Maximum idle check-ins before the agent sends a goodbye and hangs up (>= 0). Use 0 for unlimited check-ins (agent never hangs up on silence alone).

Seconds before the agent plays a filler/holding line while it waits for the LLM (1.0–300.0). Null disables.

Filler text spoken when the soft timeout fires.

If true, the soft-timeout message is generated by the LLM instead of using soft_timeout_message verbatim (default: false).

Minimum sentences per response (>= 0). Defaults to 2 when unset.

Maximum sentences per response (>= 0). Must be >= response_min_sentences. Defaults to 3 when unset.

Number of knowledge-base chunks to retrieve per turn (1–20). Null uses the platform default of 6, chosen to improve recall for policies split across adjacent chunks while the voice pipeline still caps local prompt injection to the served context window.

Minimum vector or keyword similarity score for retrieved chunks (0.0–1.0). Null uses the platform default of 0.1; set 0.0 to disable the floor.

E.164 number to transfer the call to when the agent triggers a transfer.

Up to five numbers in E.164, dialled in order: a warm transfer rolls to the next one when a leg goes unanswered or unavailable. When set it takes precedence over transfer_phone_number; send [] to go back to the single-number behaviour.

What the agent does once the person it transfers to picks up. warm (the default): it briefs them privately, then leaves the call. conference: it briefs them, then stays on the call without speaking — the rest of the call is recorded and transcribed, the person's words as human_agent turns, as far as the agent's recording_enabled and transcription_enabled allow. Conference needs the call to stay on the Aethex SIP bridge: SIP calls only, and an outbound trunk the transfer can dial through. On Twilio and Teams calls the agent transfers as warm.

The SIP trunk this agent dials out through. Must be one of your active outbound trunks; omit it to use the workspace default, and send "" to clear an existing choice. A trunk linked to the specific number still wins over this.

The number this agent's text messages go out from, as a phone-number id. It must be one of your active numbers with sms_sender on; 404 if it is not yours, 422 if it does not send. Omit it (or send "") and the agent uses the number carrying sms_sender_default, which is what every agent does until you set one. Checked again on every call, so a number you later release falls back to the default rather than sending from a line you no longer hold.

Default values for {{variable}} placeholders interpolated into the system prompt at call start. Inbound calls and messages have nobody to supply values, so every placeholder needs a default here or must be a built-in (system__channel, system__caller_id, …). The response's read-only unfilled_variables lists the placeholders that have neither (a blank "" default counts as none). No call or message is ever refused over one: the agent answers with [name: not provided] in its place, and the agent's webhook_url gets agent.prompt_variables.unfilled. An agent with any cannot be mapped to a WhatsApp number or a number that answers texts (422 unfilled_prompt_variables, with variables).

HTTPS URL (port 443) that receives a signed call.ended report after each call ends, with the call status and transcript. The recording arrives separately via a recording.ready event once the audio finishes uploading. Signed with your tenant webhook secret via the X-Aethex-Signature header.

UUID of the agent to duplicate.

UUID of the agent.

Tool name used in the LLM function call (snake_case, no spaces).

Human-readable description of what the tool does. The LLM uses this to decide when to call it.

Tool type — function for HTTP callbacks. Default: function.

JSON Schema object describing the tool's parameters.

Alias for parameters_schema.

HTTPS URL (port 443) the platform calls when the agent invokes this tool. Must be a publicly resolvable hostname or public IP literal (no localhost, no private/internal IPs, no embedded credentials, no URL fragments). Enforced at API-validation time when the tool is created — the request is rejected if the host cannot be resolved or resolves to a non-public address (or the URL is not on port 443).

Additional HTTP headers to send with the tool request (e.g. {"Authorization": "Bearer token"}).

HTTP method used to dispatch the tool. POST (default): LLM arguments and contextual IDs go in the JSON request body. GET: arguments go in the URL query string (non-scalar values JSON-encoded); contextual IDs are forwarded as X-Aethex-Agent-Id, X-Aethex-Conversation-Id, and X-Aethex-Call-Id headers; no body is sent. Operator-pinned query parameters in the endpoint URL are always authoritative — if the LLM supplies an argument with the same key it is silently dropped. Only POST and GET are accepted. Type note (GET only): scalars are stringified directly, so string "true" and boolean true both arrive as flag=true — indistinguishable on the receiving end. null arrives as the literal string "null".

UUID of the agent.

Document file to upload (PDF, DOCX, TXT, MD).

Plain-text content to add as a virtual document instead of a file.

Filename to assign to the virtual text document.

UUID of the agent.

Signed upload token returned by POST /uploads/presign. Opaque string, 8–8192 characters.

Language hint for text extraction.

Override for the document filename.

UUID of the agent.

UUID of the document to reprocess.

UUID of the agent.

Free-text query to run against the knowledge base.

Number of chunks to return. Omit to use the agent's rag_top_k override or the platform default of 6.

Minimum relevance score. Omit to use the agent's rag_min_score override or the platform default of 0.1.