Delegation

Delegation splits a conversation between two models: a frontend model that talks to the caller, and a backend model that does the work. The frontend keeps the caller company — fast, cheap, low latency — while the backend looks things up and runs tools. This matters most on GPT-Live speech-to-speech conversations, where the frontend model cannot call tools at all. Without delegation such an assistant can hold a conversation but can never look anything up or act on the caller’s behalf, which is why delegation is enabled by default.

Beta. Configure delegation with delegation_settings on the assistant.

How a delegation is raised

The two conversation paths differ only in how the frontend asks for help. GPT-Live (speech-to-speech). The frontend model has no tools. When it needs work done it raises a delegation and waits — so the backend’s answer streams back sentence by sentence, and the model speaks it as it arrives. The frontend prompt is deliberately small; the business rules belong on the backend. Chat completion (STT → LLM → TTS). The frontend is stripped down to a single delegate tool. Calling it hands the work over and returns immediately, so the conversation carries on while the backend works:

Caller: Can you check the status of my order? Assistant: Sure, let me take a look. (calls delegate, keeps talking) (backend looks up the order) Assistant: It shipped Tuesday and should arrive Thursday.

Either way the result is injected back as context, not spoken verbatim by the backend.

Configure it

curl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_settings": {
      "enabled": true,
      "mode": "telnyx",
      "model": "openai/gpt-4o",
      "instructions": "You have access to the order system. Always confirm the order number before answering.",
      "speak_results": true
    }
  }'

Field	Default	Description
`enabled`	`true`	Whether the assistant delegates work to a backend model.
`mode`	`"telnyx"`	Who answers a delegation — see Choosing a mode.
`model`	platform default	The backend model. Must be a model available for AI Assistants.
`llm_api_key_ref`	—	Integration secret holding the API key for `model`.
`instructions`	—	Extra instructions for the backend, in addition to the assistant’s own.
`speak_results`	`true`	Whether the backend’s answer is spoken to the caller.
`external_llm`	—	Run the backend on your own OpenAI-compatible endpoint.

{"enabled": true} on its own is a valid configuration: with no model, the backend runs on the platform default.

delegation_settings does not accept a raw api_key, and neither does its nested external_llm. Passing one is rejected, not ignored — a plaintext credential in the assistant payload is a leak, and silently falling back to a different key would hide the misconfiguration. Reference an integration secret with llm_api_key_ref (or external_llm.llm_api_key_ref) instead.

Spoken results versus silent context

speak_results decides what happens to the backend’s answer:

true (default) — the result is appended as commentary and paraphrased aloud. Use this when the caller is waiting on the answer.
false — the result is kept as silent context that informs later answers without being read out. Use this when the backend is enriching what the assistant knows rather than answering a direct question.

Writing backend instructions

instructions are added to the assistant’s own instructions for the backend model only. Put the business rules, lookup procedures and tool guidance here — the frontend model does not need them, and on GPT-Live it has a small context window that is better spent on holding a natural conversation.

Choosing a mode

`telnyx` — Telnyx runs the backend

The default. Telnyx runs the backend model with the assistant’s own tools, MCP servers and observability, so a delegation can do anything the assistant could do. Validation happens when you save the assistant: an unavailable model, or an llm_api_key_ref that does not resolve, is rejected there rather than surfacing mid-call as an assistant that talks but can never look anything up.

On GPT-Live, an OpenAI backend model is handed to OpenAI’s own delegation at session start and runs there, calling back into Telnyx for the assistant’s tools. MCP servers are not available on that path.

`client` — you answer the delegation

Set mode: "client" and Telnyx relays each delegation to your own server over the WebSocket configured in websocket_settings. Use this when the answer has to come from a system that cannot be reached as a Telnyx tool — an internal service behind your own auth, a model you host, a human in the loop. Telnyx sends:

{
  "type": "session.delegation.created",
  "delegation": {
    "id": "5b1d9e02-4c77-4f3a-8a2e-1c6f0b9d7a54",
    "request": "Check the status of order 40192.",
    "instructions": "You have access to the order system."
  }
}

You answer with the same id:

{
  "type": "session.delegation.completed",
  "delegation": {
    "id": "5b1d9e02-4c77-4f3a-8a2e-1c6f0b9d7a54",
    "output": "Order 40192 shipped on Tuesday and is due to arrive Thursday."
  }
}

Things to know about client mode:

It requires an active event-stream socket. If none is connected when a delegation is raised, the delegation is refused: the assistant tells the caller it cannot look things up right now and carries on from what it already knows. It never leaves the caller waiting in silence.
The answer is text only. The event stream offers your server no tool vocabulary, so output is plain text that gets injected as context.
An empty answer is a failure, not a quiet success. The assistant has already told the caller it is checking, so an output that is blank after trimming is rejected rather than producing dead air.
request is null on GPT-Live. The live model raises a delegation with no text of its own, so you work from the conversation events the socket is already streaming you.
Answer promptly. A delegation that is not answered in time falls back the same way an unavailable socket does.

Model requirements

GPT-Live conversations are selected by the assistant’s model and voice:

Setting	Requirement
`model`	The model family must start with `gpt-live` (for example `openai/gpt-live-...`).
`voice_settings.voice`	Must be prefixed `OpenAILive.`

The two have to be paired. An assistant with a GPT-Live model and a non-live voice — or the reverse — is rejected when you save it, rather than failing when a call arrives. Conversation flows are not supported on the GPT-Live route. The backend model in delegation_settings.model has no such restriction: it is an ordinary text model, and it is where tool use actually happens.

Next steps

Conversation event stream — the WebSocket that mode: "client" delegations travel over
Tools library — the tools a telnyx-mode backend can call
Custom LLM — running a model on your own endpoint with external_llm

Guides

Missions

AI Insights

Assistants API

Missions API

Conversations API

For AI Agents

How a delegation is raised

Configure it

Spoken results versus silent context

Writing backend instructions

Choosing a mode

`telnyx` — Telnyx runs the backend

`client` — you answer the delegation

Model requirements

Next steps

​How a delegation is raised

​Configure it

​Spoken results versus silent context

​Writing backend instructions

​Choosing a mode

​telnyx — Telnyx runs the backend

​client — you answer the delegation

​Model requirements

​Next steps

How a delegation is raised

Configure it

Spoken results versus silent context

Writing backend instructions

Choosing a mode

`telnyx` — Telnyx runs the backend

`client` — you answer the delegation

Model requirements

Next steps