Agents

An agent is the core configuration object in Aethex. It holds the voice, language, system prompt, and behaviour settings the pipeline uses on every call.

Quickstart

Create your first agent with a single POST /agents call:

create_agent.py

python

import os, requests

resp = requests.post(
    "https://api.aethexai.com/api/v1/agents",
    headers={"X-API-Key": os.environ["AETHEX_API_KEY"]},
    json={
        "name": "Acme Storage Support",
        "system_prompt": "You are Maya, a friendly support agent for Acme Storage. Help with bookings, payments, and unit availability. Keep replies short.",
        "first_message": "Hi, thanks for calling Acme Storage. This is Maya. How can I help?",
        "voice_id": "Femi",
        "language": "english",
    },
)
agent = resp.json()
print(f"Created agent: {agent['id']}")

Save the returned id — you will use it to assign a phone number, trigger calls, and manage the agent.

How agents handle calls

Once created, an agent can handle calls three ways:

Inbound. Assign the agent to a registered phone number. All inbound calls to that number route to the agent.
Outbound. Trigger calls via POST /calls/trigger with agent_id and a to_number.
WebRTC. Start a browser or mobile session via the WebRTC calls flow — no phone number needed.

Agents can also use tools to call your own HTTPS endpoints mid-call, and pull grounded answers from a knowledge base you upload.

Core fields

namestringrequired
Human-readable name. Used in dashboards and logs.
system_promptstringrequired
The instruction set the LLM receives before every call. Sets persona, tone, and call flow.
voice_idstringrequired
Voice to use for TTS. Must match the agent's language. Use GET /voices to browse the catalog.
first_messagestringoptional
Optional opening line the agent speaks as soon as the call connects. If omitted, the agent waits for the caller to speak first.
languagestringrequired
Language the agent speaks and understands. Affects STT, TTS, and LLM response language.
dialect_stylestringoptional
Optional regional dialect variant. Available values depend on the language.

Writing the system prompt

The system prompt is the single most important field on an agent. Include:

Role and persona. Who the agent is, what company it represents, and what it is called.
Tone and style. How formal, how concise, and what vocabulary to use.
Don'ts. What the agent should never say or do (competitor mentions, pricing speculation, legal advice).
Tool instructions. When and how to invoke each tool. For example: "Call lookup_order when the user mentions an order number."

See the Quickstart for an example prompt that walks through all four elements.

Behaviour settings

These fields tune the LLM and call-handling behaviour:

temperaturenumberoptional
LLM sampling temperature (0–2). Lower values make responses more predictable. Defaults to 0.7. OpenAI's reasoning models (the o-series and the gpt-5 family) take no temperature, so it is ignored for them.
max_tokensintegeroptional
Maximum tokens in a single LLM response. Controls verbosity. Defaults to 300.
max_duration_secondsintegeroptional
Hard call duration cap in seconds (30–3,600). The agent hangs up after this limit regardless of conversation state.
transfer_phone_numberstringoptional
Destination number for the transfer_to_number built-in tool. Required to enable transfers.
transfer_modestringoptional
warm (default): the agent briefs the person it transfers to, then leaves the call. conference: it stays on the call without speaking, and the rest of the call is recorded and transcribed (the person's words appear as human_agent turns), as far as the agent's recording and transcription settings allow. Conference needs a SIP call and an outbound trunk for the transfer; Twilio and Teams calls transfer as warm.
keypad_capture_enabledbooleanoptional
Capture touch-tone keypad (DTMF) digits on phone calls: when a caller keys in a card or reference number, the agent reads the digits exactly instead of transcribing them from speech, and reads them back to confirm. On by default; set to false to disable. Twilio and SIP only, since browser calls have no keypad.

Note

Temperature affects naturalness vs predictability. For scripted customer-service agents, 0.3–0.5 is a good starting point.

Lifecycle

Update

PATCH/agents/{id}

PATCH any field at any time. Changes take effect on the next call — mid-call sessions are unaffected.

Delete

DELETE/agents/{id}

Deletes the agent and unlinks it from any registered phone numbers. Active calls complete normally.