> ## 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.

# Deployment

> Run the realtime FastAPI bridge, serve the bundled web client, and connect Twilio phone calls.

Use this guide once your agent is ready and you want to host a realtime bridge or connect phone infrastructure. It builds on the [Overview](./overview) and assumes your agents are ready for deployment.

## Host the FastAPI bridge

`run_realtime` starts a FastAPI app that proxies between your Agency Swarm agents and a supported realtime provider (OpenAI or xAI). The helper already converts your agency to the realtime runtime, exposes a `/realtime` websocket, and streams events back to callers.

```python theme={null}
from agency_swarm import Agency
from agency_swarm.integrations import run_realtime
from voice_agent import voice_agent

agency = Agency(voice_agent)

run_realtime(
    agency=agency,
    provider="openai",
    model="gpt-realtime-2",
    host="0.0.0.0",
    port=8000,
    turn_detection={"type": "server_vad"},
)
```

```bash theme={null}
python app.py
```

The server prints every incoming websocket connection. Set `voice=` to pick the voice for the whole call, or leave it out to use the entry agent's voice—see [one voice per call](./overview#one-voice-per-call). Supply `cors_origins` when you deploy behind a browser client that runs on a different domain.

<Tip>
  `run_realtime(..., return_app=True)` returns the FastAPI `app` object if you want to mount it inside an existing application rather than start a dedicated Uvicorn process.
</Tip>

## Serve voice endpoints from `run_fastapi`

Keep your existing REST endpoints and add realtime voice routes with one flag:

```python theme={null}
run_fastapi(
    agencies={"support": create_agency},
    enable_realtime=True,
    realtime_options={
        "model": "gpt-realtime-2",
        "turn_detection": {"type": "server_vad", "interrupt_response": True},
    },
    enable_logging=True,
)
```

`enable_realtime=True` mounts `/support/realtime` alongside the normal JSON endpoints. Pass `realtime_options` when you want to override model settings (they map directly to `run_realtime` keyword arguments). Authentication and logging apply to the new websocket route automatically.

For xAI sessions:

```python theme={null}
run_realtime(
    agency=agency,
    provider="xai",
    model="grok-voice-think-fast-1.0",
)
```

Agency Swarm adds the selected xAI model to the realtime websocket URL as `?model=<model>` because xAI selects voice models from the connection query string.

## Serve the packaged browser client

A ready-made WebAudio frontend ships with the library. Launch it with your own agency in one call:

```python theme={null}
from agency_swarm.ui.demos.realtime import RealtimeDemoLauncher

RealtimeDemoLauncher.start(agency, model="gpt-realtime-2", voice="marin")
```

This mounts the frontend and websocket bridge under the same process—ideal for internal demos or QA. For a runnable script, see [`examples/interactive/realtime/demo.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/realtime/demo.py).

## Twilio phone calls

Pass a Twilio number to `run_realtime` to expose a media-stream bridge. The helper exposes `/incoming-call` (returns TwiML) and `/twilio/media-stream` for bidirectional audio.

```python theme={null}
run_realtime(
    agency=agency,
    model="gpt-realtime-2",
    twilio_number="+15551234567",
    twilio_audio_format="g711_ulaw",
    twilio_greeting="Connecting you to the assistant.",
)
```

Deployment checklist:

1. Start the server and expose it publicly, e.g. `ngrok http 8000`.
2. In the Twilio Console, set your phone number’s voice webhook to `https://<public-host>/incoming-call`.
3. Call the number—the helper streams audio in both directions and reuses your existing tools and handoffs.

For a lower-level implementation (custom playback tracking, fine-grained buffering), see the [Twilio demo README](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/ui/demos/realtime/twilio/README.md).

<Note>
  Store your Twilio account SID and auth token in a local `.env`, export them before launching the demo, and keep `OPENAI_API_KEY` alongside them. The packaged server reads standard environment variables; no credentials live in source control.
</Note>