OpenAI Realtime

OpenAI Realtime brings responsive voice conversations to your agents, with support for text and images alongside speech. Users can share context, interrupt a reply, and ask the agent to take action through tools.

Follow the quickstart to build a voice agent that listens, speaks, and calls tools.

Installation

Install the OpenAI Realtime extra:

pip install "strands-agents[bidi-openai]"

For local audio dependencies and device setup, see Audio I/O.

Credentials

Create an OpenAI API key and set it in your environment:

export OPENAI_API_KEY="your-api-key"

OpenAIRealtimeModel reads OPENAI_API_KEY automatically. You can also pass the key directly through api_key. For organization and project options, see the constructor reference.

Configuration

Configure the Realtime model, user transcription, and output voice, then pass the model to BidiAgent:

from strands.bidi.agent import BidiAgent
from strands.bidi.models import OpenAIRealtimeModel

model = OpenAIRealtimeModel(
    model_id="gpt-realtime-2.1",
    transcription_model_id="gpt-transcribe",
    voice="coral",
)
agent = BidiAgent(model=model)

The transcription_model_id argument is required: choose a transcription model for user speech transcripts, or pass None to disable them. The Realtime model processes audio directly, independently of this transcription.

Choose a voice from OpenAI’s voice options. This adapter requires mono PCM at 24 kHz for both audio input and output.

See the OpenAIRealtimeModel API reference for all constructor options.

Session settings

Pass OpenAI’s session settings through params to customize the conversation. The adapter uses server voice activity detection by default. This example allows 800 milliseconds of silence before detecting the end of speech:

from strands.bidi.models import OpenAIRealtimeModel

model = OpenAIRealtimeModel(
    model_id="gpt-realtime-2.1",
    transcription_model_id="gpt-transcribe",
    params={"audio": {"input": {"turn_detection": {"silence_duration_ms": 800}}}},
)

Use OpenAI’s field names inside params. Nested settings merge with the defaults, and params takes precedence over direct options such as voice. Keep turn detection, automatic responses, and interruption enabled; the adapter requires them.

Text output

The model produces speech and its transcript by default. To generate text without audio, set output_modalities through params:

from strands.bidi.models import OpenAIRealtimeModel

model = OpenAIRealtimeModel(
    model_id="gpt-realtime-2.1",
    transcription_model_id=None,
    params={"output_modalities": ["text"]},
)

For a complete terminal conversation using this configuration, see Console I/O.

Connection restarts

OpenAI limits Realtime sessions to 60 minutes. The adapter uses a 50-minute timeout to leave time for reconnection before that limit. By default, BidiAgent schedules a restart after 45 minutes, ahead of this timeout. Each restart opens a new session and replays conversation history, including text, completed transcripts, and tool calls and results.

Set connection.restart_after_s to customize the schedule. The timeout_s option controls the adapter’s timeout and defaults to its maximum of 3000 seconds (50 minutes). Keep the scheduled restart earlier than that timeout to allow time for the transition. See Connection restarts for timing and events.