Skip to main content
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 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.
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. Supply cors_origins when you deploy behind a browser client that runs on a different domain.
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.

​
Serve voice endpoints from run_fastapi

Keep your existing REST endpoints and add realtime voice routes with one flag:
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:
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:
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.

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