Realtime transport

Use this page to decide how realtime agents fit into your Python application.

!!! note "Python SDK boundary"

The Python SDK does **not** include a browser WebRTC transport. This page is only about Python SDK transport choices: server-side WebSockets and SIP attach flows. Browser WebRTC is a separate platform topic, documented in the official [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) guide.

Decision guide

Goal	Start with	Why
Build a server-managed realtime app	Quickstart	The default Python path is a server-side WebSocket session managed by RealtimeRunner.
Understand which transport and deployment shape to choose	This page	Use this before you commit to a transport or deployment shape.
Attach agents to phone or SIP calls	Realtime guide and examples/realtime/twilio_sip	The repo ships a SIP attach flow driven by call_id.

Server-side WebSocket is the default Python path

RealtimeRunner uses OpenAIRealtimeWebSocketModel unless you pass a custom RealtimeModel.

That means the standard Python topology looks like this:

1. Your Python service creates a RealtimeRunner.
2. await runner.run() returns a RealtimeSession.
3. Enter the RealtimeSession as an async context manager, then send text, structured messages, or audio.
4. Consume RealtimeSessionEvent items and forward audio or transcripts to your application.

This is the topology used by the core demo app, the CLI example, and the Twilio Media Streams example:

• examples/realtime/app
• examples/realtime/cli
• examples/realtime/twilio

Use this path when your server owns the audio pipeline, tool execution, approval flow, and history handling.

Low-level WebSocket tuning

Pass transport_config to OpenAIRealtimeWebSocketModel when you need to tune the underlying server-side WebSocket connection:

from agents.realtime import (
    OpenAIRealtimeWebSocketModel,
    RealtimeAgent,
    RealtimeRunner,
)

agent = RealtimeAgent(name="Assistant")
model = OpenAIRealtimeWebSocketModel(
    transport_config={
        "ping_interval": 20.0,
        "ping_timeout": 60.0,
        "handshake_timeout": 30.0,
        "max_size": 8 * 1024 * 1024,
    }
)
runner = RealtimeRunner(starting_agent=agent, model=model)

The supported options are:

• ping_interval: Seconds between client keepalive pings. Set None to disable pings.
• ping_timeout: Seconds to wait for a pong before disconnecting. Set None to tolerate delayed pongs without a heartbeat timeout.
• handshake_timeout: Seconds to wait for the initial connection handshake.
• max_size: Maximum incoming WebSocket message size in bytes. The SDK default is None, which leaves incoming message size unlimited; set an explicit limit when you need to bound per-message memory usage.

These settings configure the client connection rather than the Realtime API session. Continue to use RealtimeModelConfig for endpoint, authentication, call attachment, and playback settings.

SIP attach is the telephony path

For the telephony flow documented in this repository, the Python SDK attaches to an existing realtime call via call_id.

This topology looks like:

1. OpenAI sends your service a webhook such as realtime.call.incoming.
2. Your service accepts the call through the Realtime Calls API.
3. Your Python service starts a RealtimeRunner(..., model=OpenAIRealtimeSIPModel()).
4. The session connects with model_config={"call_id": ...} and then processes events like any other realtime session.

This is the topology shown in examples/realtime/twilio_sip.

The broader Realtime API also uses call_id for some server-side control patterns, but this repository's shipped attach example is SIP.

Browser WebRTC is outside this SDK

If your app's primary client is a browser using Realtime WebRTC:

• Treat it as outside the scope of the Python SDK docs in this repository.
• Use the official Realtime API with WebRTC and Realtime conversations docs for the client-side flow and event model.
• Use the official Realtime server-side controls guide if, in addition to a browser WebRTC client, you need a sideband server connection.
• Do not expect this repository to provide a browser-side RTCPeerConnection abstraction or a ready-made browser WebRTC sample.

This repository also does not currently ship a browser WebRTC plus Python sideband example.

Custom endpoints and attach points

The transport configuration surface in [RealtimeModelConfig][agents.realtime.model.RealtimeModelConfig] lets you customize the default transport behavior:

• url: Override the WebSocket endpoint
• headers: Provide explicit headers such as Azure auth headers
• api_key: Pass an API key directly or via callback
• call_id: Attach to an existing realtime call. In this repository, the documented example is SIP.
• playback_tracker: Report actual playback progress for interruption handling

See the Realtime agents guide for the detailed lifecycle and capability surface once you've chosen a topology.