> ## Documentation Index
> Fetch the complete documentation index at: https://agency-swarm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Design voice-first assistants with the same Agency Swarm agents you already use.

Agency Swarm reuses your existing `Agent` definitions for voice. This page shows how to adapt agents for spoken conversations; deployment lives on the dedicated [Deployment](./deployment) guide.

## What you can build

* **Phone receptionist** — answers calls, routes to specialists, captures caller details.
* **Live support triage** — gathers context, lets callers interrupt, and escalates to a human or another agent.
* **Language coach** — listens, corrects pronunciation, and keeps the dialogue short and encouraging.

## Prerequisites

* Access to a supported realtime provider:
  * OpenAI (`gpt-realtime-2` by default, or the cheaper `gpt-realtime-mini`)
  * xAI (`grok-voice-think-fast-1.0`; legacy `grok-voice-fast-1.0` remains available for older deployments)
* The standard install—no extras needed:

```bash theme={null}
pip install agency-swarm
```

## Define your agent (same API)

You keep using the standard `Agent` class—voice agents are regular agents with the same tools, handoffs, and instructions.

```python theme={null}
from agency_swarm import Agent, function_tool

@function_tool
def lookup_order(order_id: str) -> str:
    """Return a short order status by ID."""
    return f"Order {order_id} has shipped and will arrive soon."

voice_agent = Agent(
    name="Voice Concierge",
    instructions=(
        "You are a friendly concierge. Answer in one or two sentences and offer to look up order "
        "details when the caller mentions a number."
    ),
    tools=[lookup_order],
    voice="marin",
)
```

<Tip>
  Keep using the same agent definitions—add `voice=` only when you care about the spoken persona.
</Tip>

Set `voice` to any supported realtime token:

* OpenAI voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `marin`, `sage`, `shimmer`, `verse`
* xAI voices: `ara`, `eve`, `leo`, `rex`, `sal`

## One voice per call

<Warning>
  **A call uses a single voice from start to finish.** Once the model has spoken, the realtime API refuses to switch voices—OpenAI answers with a `cannot_update_voice` error. Agency Swarm therefore picks the voice as the call starts and keeps it, even when the call hands off to another agent.
</Warning>

The voice comes from the first place that sets one:

1. The `voice=` you pass to `run_realtime()` or the demo launcher.
2. The `voice=` on your **entry agent**—the agent that answers the call.
3. The provider's own default when neither is set.

A `voice=` on any other agent is not used for that call. It is still worth setting: that agent uses its own voice whenever it is the one answering.

If you want variety without picking voices by hand, build the agency with `randomize_agent_voices=True`. Every agent without an explicit voice gets a deterministic random pick from the provider's list, and the entry agent's pick becomes the voice for the call. Pass `voice_random_seed=` to keep the picks stable between runs.

## Add handoffs (optional)

Handoffs work exactly as they do in text mode. Register your flows once and they will carry over to voice sessions.

```python theme={null}
from agency_swarm import Agency, Agent, Handoff

billing = Agent(name="Billing", instructions="Handle billing questions briefly.")
faq = Agent(name="FAQ", instructions="Answer frequently asked questions.")

concierge = Agent(
    name="Concierge",
    instructions="Greet the caller, collect intent, then hand off when a specialist is needed.",
    voice="marin",
)

agency = Agency(
    concierge,
    communication_flows=[
        (concierge > billing, Handoff),
        (concierge > faq, Handoff),
    ],
)
```

When the concierge hands off, the specialist takes over the conversation with its own instructions and tools. The caller keeps hearing the concierge's `marin` voice for the rest of the call, so give the specialists a different name or greeting if you want the switch to be obvious.

## Next steps

* Try the [realtime browser demo](https://github.com/VRSEN/agency-swarm/tree/main/examples/interactive/realtime)
* [Deploy your agents](./deployment) for phone calls using Twilio.
* Review OpenAI’s realtime [Quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/) and [Guide](https://openai.github.io/openai-agents-python/realtime/guide/) for protocol details—Agency Swarm builds on those primitives.