Skip to main content
A voice AI agent answers or places real phone calls and carries the conversation end to end — greeting the caller, understanding speech, deciding what to do next, speaking back, and calling your tools when it needs data or an action. Build it once and it handles inbound calls to your numbers, outbound outreach you dispatch from the API, and live handoff to a human when the conversation needs one. This page introduces the concept and the pieces a voice agent is made of, then walks each path the agent takes — inbound, outbound, and handoff — so you can build a mental model of where the agent fits in the stack before you wire anything. Everything it references ships in the product today.

​
What a voice agent is

A voice agent is a regular Orbit agent whose channel of work is the phone. On create you attach a system prompt, optional knowledge bases, and the tools it may call; the runtime takes it from there. There is no separate “voice SDK” to wire — the phone call lands on the Orbit voice pillar and the agent answers it. What changes for voice is timing. The caller hears delays, so every turn has to complete in well under a second of speaking time and the agent must handle being interrupted. The Orbit voice runtime manages barge-in and turn-taking for you; your prompt and tools stay the same as for a text agent.

​
The four-stage pipeline

Each spoken turn passes through a managed media pipeline:
Each stage runs in a different place, and knowing which is which tells you where to tune:
  • Speech-to-text and text-to-speech run on production-grade speech providers Orbit operates for you — you never provision a speech service or a separate AI vendor yourself. Language and voice follow the agent’s configuration (see the Voice quickstart for the GA locales).
  • Agent reasoning runs on the same runtime that powers text agents, so conversation flows, memory, and tool calls behave the way you already know.
The runtime sits between the two: it keeps turn-taking under half a second of dead air, detects a caller talking over the agent’s reply, and stops playback mid-sentence so the new utterance takes over. That barge-in support is platform-managed — there is nothing to configure, and your prompt never has to handle it. The split of control: you own the system prompt, the knowledge bases, the tool set, the first greeting, and the model choice (pick latency-appropriate models in model selection). The platform owns the media path, speech vendors, turn-taking, and interruption handling. The call itself — from ringing to hangup — follows a deterministic state machine: queued → initiated → ringing → answered → completed or a failure outcome (failed, no-answer, busy, cancelled). Every webhook you receive maps to one of those transitions. Read Voice call lifecycle once and every event payload will make sense.

​
Inbound: the agent answers your number

For inbound, you route a phone number you own to the agent. Every caller to that number is greeted and served by the agent. The walkthrough, end to end:
  1. Claim a number. Grab a trial number from the dashboard (Numbers → Buy → Use a trial number) or buy a dedicated DID when you’re ready to leave the trial pool.
  2. Attach the agent. Open the number, set Inbound routing to AI agent, and pick the agent.
  3. Call it. Dial the number from any phone. You should hear the agent’s greeting within about two seconds of pickup.
  4. Watch the conversation. Open Agents → Live in the dashboard while the call is still running — the transcript streams in turn by turn, and you can whisper a one-way note to the agent mid-call. The Live monitor page covers that surface.
The full copy-paste version of those steps is the Voice quickstart.

​
Outbound: the agent dials

For outbound, you request a call over POST /voice/calls and set agent_id on the body — that field is what turns a plain dial into an agent call:
from must be a number on your account; omit it and Orbit picks a sensible default. A successful initiation returns 201 with the call id immediately — the dial is placed in the background, and you follow the call over the call.* webhooks. The request schema, response, and full error matrix live in Outbound calls with an AI voice agent. Compliance pre-flight runs before anything rings. The dial is attempted only after the recipient passes your tenant’s own gates — tenant quiet-hours windows, your do-not-call and cross-channel suppression lists, and AI-voice consent on file for the destination. A rejected call is never billed, and the 4xx codes in that error matrix tell you which gate rejected it. All of these controls are yours — configure them under compliance; the one exception you cannot toggle is the federal US TCPA dialing-window guard, which the platform enforces for everyone. Pick the dialer path when the list grows. Per-call API dials are for ad-hoc, one-off outreach. Once you’re dialing more than a handful of recipients, run a dialer campaign instead: the campaign paces the dials against your calling window, applies the same compliance gates per number, and closes the loop with dialer dispositions so no-answer, voicemail, and completed calls all land on one report.

​
Human handoff when the conversation needs one

A voice agent is not a dead end. A call reaches a human two ways:
  • The agent escalates. The runtime gives the in-call agent a warm transfer tool it can invoke mid-conversation — when the request is outside its knowledge, when its confidence or policy says a person should take over, or when it was prompted to escalate on a keyword.
  • The caller requests it. When a caller asks for a person, the agent announces the transfer and hands off.
Either way the transfer is warm: the caller is bridged into a named human queue and stays connected, and the receiving person gets a screen-pop with a summary of the call — sentiment, key topics, and anything the agent already collected — so the caller never has to repeat themselves. You choose the queue each agent escalates into, so “billing” and “support” can land in different queues from the same agent. The target allowlist is the second control plane: an agent can only hand off to the destinations you explicitly list on its configuration — no allowlist, no handoff. Set those targets in handoff targets. The reverse trip is covered too: once the human resolves the exception, hand the call back to the agent with the full conversation intact.

​
Where to go next

Walk this chain in order — each step hands the next one a working setup:
  1. Voice quickstart — claim a number, attach an agent, place your first call in minutes.
  2. Creating agents — prompt, tools, and knowledge bases behind a working agent.
  3. Voice eval runs — test the agent against recorded and simulated speech before pointing a real number at it, with guardrail effectiveness alongside.
Then, in production: When you’re past the introduction, the AI agents overview page indexes everything else the agent runtime can do; the voice-specific state machine lives under Voice call lifecycle. If the /agents dashboard itself is new to you, the Agents workspace map walks its cards, tabs, and routes.