Your own LLM
Run an agent's voice calls on your own OpenAI-compatible model server. Aethex still runs the call; your server writes the agent's replies.
How it works
Link your server's address and key once, then set an agent's llm_model to custom:<model>. On every turn of that agent's calls, Aethex sends the conversation to your server and speaks its reply.Everything else stays with Aethex: the phone line or WebRTC connection, speech recognition, turn-taking and interruptions, the voice, tools and transcripts. Your server sees the conversation as text and answers with text and tool calls.Your server is never swapped for another model. If it fails or is too slow, that turn goes unanswered; the call never moves to an Aethex model.
Set it up
Two calls: link the endpoint, then point an agent at it.
Link your endpoint
Call
POST /api/v1/llm-credentialswithproviderset tocustom,base_urlset to your server's chat-completions root, andapi_keyset to the key your server expects. Aethex checks the key with your server before storing it, encrypted (see Requirements). Your account has one endpoint: linking another replaces it with no gap.Link the endpointbashcurl -X POST https://api.aethexai.com/api/v1/llm-credentials \ -H "X-API-Key: $AETHEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "custom", "base_url": "https://llm.example.com/v1", "api_key": "your-endpoint-key", "label": "Our model gateway" }'Point an agent at it
Set the agent's
llm_modeltocustom:followed by the model name your server expects. Everything aftercustom:is sent asmodel. An agent can name acustom:model only once your endpoint is linked, and the endpoint cannot be released while an agent still uses it.Use it on an agentbashcurl -X PATCH https://api.aethexai.com/api/v1/agents/$AGENT_ID \ -H "X-API-Key: $AETHEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "llm_model": "custom:acme/support-v2" }'
What your endpoint receives
Each turn of the call is one streamed request:- POST <base_url>/chat/completions, with Authorization: Bearer <api_key>.
- Three headers name the call: X-Aethex-Agent-Id, X-Aethex-Conversation-Id and X-Aethex-Call-Id, each sent when the call has one. Your custom tools receive the same values.
- A standard chat-completions body: model, messages, tools (when the agent has any), temperature, max_completion_tokens, stream: true and stream_options.include_usage: true. No other sampling fields are sent.
POST /v1/chat/completions HTTP/1.1
Host: llm.example.com
Authorization: Bearer your-endpoint-key
X-Aethex-Agent-Id: 3f2b8c1e-...
X-Aethex-Conversation-Id: 9a7d4e20-...
X-Aethex-Call-Id: c51e0b7f-...
Content-Type: application/json
{
"model": "acme/support-v2",
"stream": true,
"stream_options": { "include_usage": true },
"temperature": 0.7,
"max_completion_tokens": 300,
"messages": [
{ "role": "system", "content": "You are on a phone call. ..." },
{ "role": "assistant", "content": "Hello, this is Ada from Acme. How can I help?" },
{ "role": "user", "content": "I'd like to move my appointment to Friday." }
],
"tools": [
{ "type": "function", "function": { "name": "end_call", "parameters": { "...": "..." } } }
]
}What the messages hold
- The system prompt Aethex builds: rules for speaking on a phone call, then your agent's own prompt with its dynamic variables filled in, its tools and its guardrails.
- The conversation so far: what the caller said, as transcribed, and what the agent said.
- Notes from Aethex, sent as `user` messages beginning System note, do not read aloud:. They tell the model what is happening on the call: a tool result arrived late, the caller's speech could not be transcribed, the call is ending and it should say goodbye. Your model should act on them and never say them aloud.
- Interrupted replies. When the caller talks over the agent, the agent's last message keeps the text generated so far, followed by [user interrupted before this response finished]. That is what your server generated, which can be ahead of what the caller actually heard.
Tools
The agent's tools are sent in tools: the built-in ones, such as end_call, transfer_to_number and voicemail_detected, and your own custom tools. When your server returns OpenAI-format tool_calls in the stream, Aethex runs the tool and sends its result on the next request, as a tool message.
tool_calls. Without them the agent cannot hang up, transfer, detect voicemail or run your tools, and a call ends only when the caller hangs up or a call limit is reached.What your endpoint returns
A stream of server-sent events carrying chat.completion.chunk objects and ending with data: [DONE], as OpenAI's streaming API returns.- Timing. The first token must arrive within 5 seconds, and the stream must never go quiet for more than 10 seconds after that. Otherwise Aethex closes the request and the caller hears nothing more for that turn. The next turn tries your server again, and text already spoken is never repeated.
- Errors. Any status other than 2xx ends the turn the same way.
- Repeated failures. After 5 failures across your account's calls, Aethex stops sending requests to your server for 60 seconds; turns in that time go unanswered.
- Redirects are not followed.
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Sure, "}}]}
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Friday works."},"finish_reason":"stop"}]}
data: [DONE]Requirements for base_url
- HTTPS on port 443, to a public hostname or IP address.
- No username or password, query string or fragment, and at most 2,000 characters.
- The root that /chat/completions is added to: https://llm.example.com/v1, not https://llm.example.com/v1/chat/completions.When you link the endpoint, Aethex sends GET <base_url>/models with your key and reads only the status. A 400, 401 or 403 refuses the key. A 404 is accepted, since many servers do not serve /models, so check that calls reach your server after linking.Aethex connects to your server only at public addresses. The hostname is looked up again before every request, so it cannot later be pointed at a private address.
Limits
- Voice calls only. Text chat (POST /agents/{id}/chat) refuses an agent on a custom: model with a 422, and messages that reach such an agent by SMS or WhatsApp go unanswered.
- One endpoint per account. Linking another replaces it.
- No realtime models. A custom: agent always uses Aethex's speech recognition and voice.
