Build a voice agent

Build an agent that listens and talks in real time. This guide walks through a bidirectional streaming agent end to end: audio input and output, streaming events, tool calls mid-conversation, and the model providers that support it.

After completing this guide, you can build voice assistants, interactive chatbots, multi-modal applications, and integrate bidirectional streaming with web servers or custom I/O streams.

Prerequisites

Before starting, ensure you have:

• Python 3.10+ installed (3.12+ required for Nova Sonic)
• Audio hardware (microphone and speakers) for voice conversations
• Model provider credentials configured (AWS, OpenAI, or Google)

Install the SDK

Install the SDK with bidirectional streaming support:

For All Providers

To install support for all bidirectional streaming providers:

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

This includes all three providers (Nova Sonic, OpenAI, and Gemini Live), ConsoleIO, and microphone audio processing. Local microphone and speaker I/O with AudioIO also requires PortAudio and the bidi-pyaudio extra. See Platform-Specific Audio Setup.

For Specific Providers

You can also install support for specific providers:

Amazon Bedrock Nova Sonic

# With local microphone and speaker I/O
pip install "strands-agents[bidi,bidi-io,bidi-pyaudio]"

# With terminal text I/O
pip install "strands-agents[bidi,bidi-io]"

OpenAI Realtime API

# With local audio I/O
pip install "strands-agents[bidi-io,bidi-openai,bidi-pyaudio]"

# With terminal text I/O
pip install "strands-agents[bidi-io,bidi-openai]"

Google Gemini Live

# With local audio I/O
pip install "strands-agents[bidi-google,bidi-io,bidi-pyaudio]"

# With terminal text I/O
pip install "strands-agents[bidi-google,bidi-io]"

Server-Side Deployments

The bidi-pyaudio extra provides PyAudio for direct microphone and speaker access. The bidi-io extra provides terminal text input and transcript rendering. For server deployments where clients handle audio I/O, omit bidi-pyaudio and implement custom handlers using the InputStream and OutputStream protocols. See I/O Streams for details.

Platform-Specific Audio Setup

AudioIO depends on PyAudio, which requires the PortAudio system library. Install PortAudio first, then install the bidi-pyaudio extra alongside bidi-all.

macOS

brew install portaudio
pip install "strands-agents[bidi-all,bidi-pyaudio]"

Linux (Ubuntu/Debian)

sudo apt-get install portaudio19-dev python3-pyaudio
pip install "strands-agents[bidi-all,bidi-pyaudio]"

Windows

PyAudio typically installs without additional dependencies.

pip install "strands-agents[bidi-all,bidi-pyaudio]"

Configuring Credentials

Bidirectional streaming supports multiple model providers. Choose one based on your needs:

Amazon Bedrock Nova Sonic

Nova Sonic is Amazon’s bidirectional streaming model. Configure AWS credentials:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

Enable Nova Sonic model access in the Amazon Bedrock console.

OpenAI Realtime API

For OpenAI’s Realtime API, set your API key:

export OPENAI_API_KEY=your_api_key

Google Gemini Live

For Gemini Live API, set your API key:

export GOOGLE_API_KEY=your_api_key

Your First Voice Conversation

Now let’s create a simple voice-enabled agent that can have real-time conversations:

import asyncio
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel

# Create a bidirectional streaming model
model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")

# Create the agent
agent = BidiAgent(
    model=model,
    system_prompt="You are a helpful voice assistant. Keep responses concise and natural."
)

# Setup audio I/O for microphone and speakers
audio_io = AudioIO()

# Run the conversation
async def main():
    await agent.run(
        inputs=[audio_io.input()],
        outputs=[audio_io.output()]
    )

asyncio.run(main())

You now have a voice-enabled agent that can:

• Listen to your voice through the microphone
• Process speech in real time
• Respond with natural voice output
• Display live user and assistant transcripts
• Handle barge-ins when you start speaking

Stopping the Conversation

The run() method runs indefinitely. See Controlling Conversation Lifecycle for proper ways to stop conversations.

Live Transcripts

AudioIO.output() displays user and assistant transcripts while audio plays through the speakers. User speech appears in shaded > blocks and assistant speech appears as plain text.

Controlling Conversation Lifecycle

The run() method runs indefinitely by default. The simplest way to stop conversations is using Ctrl+C:

import asyncio
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel

async def main():
    model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
    agent = BidiAgent(model=model)
    audio_io = AudioIO()

    try:
        # Runs indefinitely until interrupted
        await agent.run(
            inputs=[audio_io.input()],
            outputs=[audio_io.output()]
        )
    except asyncio.CancelledError:
        print("\nConversation cancelled by user")
    finally:
        # stop() should only be called after run() exits
        await agent.stop()

asyncio.run(main())

Important: Call stop() After Exiting Loops

Always call agent.stop() after exiting the run() or receive() loop, never during. Calling stop() while still receiving events can cause errors.

Adding Tools to Your Agent

Just like standard Strands agents, bidirectional agents can use tools during conversations:

import asyncio
from strands import tool
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel
from strands.vended_tools import notebook

# Define a custom tool
@tool
def get_weather(location: str) -> str:
    """
    Get the current weather for a location.

    Args:
        location: City name or location

    Returns:
        Weather information
    """
    # In a real application, call a weather API
    return f"The weather in {location} is sunny and 72°F"

# Create agent with tools
model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
agent = BidiAgent(
    model=model,
    tools=[notebook, get_weather],
    system_prompt="You are a helpful assistant with access to tools."
)

audio_io = AudioIO()

async def main():
    await agent.run(
        inputs=[audio_io.input()],
        outputs=[audio_io.output()]
    )

asyncio.run(main())

You can now ask questions like:

• “What time is it?”
• “Calculate 25 times 48”
• “What’s the weather in San Francisco?”

The agent automatically determines when to use tools and executes them concurrently without blocking the conversation.

Model Providers

Strands supports three bidirectional streaming providers:

• Nova Sonic - Amazon’s bidirectional streaming model via AWS Bedrock
• OpenAI Realtime - OpenAI’s Realtime API for voice conversations\
• Gemini Live - Google’s multimodal streaming API

Each provider has different features, timeout limits, and audio quality. See the individual provider documentation for detailed configuration options.

Configuring Audio Settings

Choose supported audio settings on the model and device buffering on the I/O stream:

import asyncio

from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import GoogleGeminiLiveModel

# Configure model audio settings
model = GoogleGeminiLiveModel(
    model_id="gemini-3.8-live",
    audio={"input": {"sample_rate": 48000}},
    voice="Puck",
)

# Configure I/O buffer settings
audio_io = AudioIO(
    input_buffer_size=10,           # Max input queue size
    output_buffer_size=20,          # Max output queue size
    input_frames_per_buffer=512,   # Input chunk size
    output_frames_per_buffer=512   # Output chunk size
)

agent = BidiAgent(model=model)

async def main():
    await agent.run(
        inputs=[audio_io.input()],
        outputs=[audio_io.output()]
    )

asyncio.run(main())

AudioIO reads the model’s resolved input and output formats through get_audio_config(). You do not need to repeat rates or channel counts on the I/O stream.

Handling Barge-in

Bidirectional agents automatically handle barge-ins when users start speaking:

import asyncio
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel
from strands.bidi.types import BidiBargeInEvent

model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
agent = BidiAgent(model=model)
audio_io = AudioIO()

async def main():
    await agent.start()

    # Start receiving events
    async for event in agent.receive():
        if isinstance(event, BidiBargeInEvent):
            print(f"Barge-in: {event.reason}")
            # Audio output automatically cleared
            # Model stops generating
            # Ready for new input

asyncio.run(main())

Barge-ins are detected via voice activity detection (VAD) and handled automatically:

1. User starts speaking
2. Model stops generating
3. Audio output buffer cleared
4. Model ready for new input

Manual Start and Stop

If you need more control over the agent lifecycle, you can manually call start() and stop():

import asyncio
from strands.bidi.agent import BidiAgent
from strands.bidi.models import BedrockNovaSonicModel
from strands.bidi.types import BidiResponseStopEvent

async def main():
    model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
    agent = BidiAgent(model=model)

    # Manually start the agent
    await agent.start()

    try:
        await agent.send("What is Python?")

        async for event in agent.receive():
            if isinstance(event, BidiResponseStopEvent):
                break
    finally:
        # Always stop after exiting receive loop
        await agent.stop()

asyncio.run(main())

See Controlling Conversation Lifecycle for more patterns and best practices.

Graceful Shutdown

To let users end a conversation by voice, define a tool that calls agent.cancel():

import asyncio
from strands import LocalAgent, ToolContext, tool
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel


@tool(context=True)
def end_conversation(tool_context: ToolContext[LocalAgent]) -> str:
    """End the conversation when the user asks to stop."""
    tool_context.agent.cancel()
    return "Ending conversation"


model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
agent = BidiAgent(
    model=model,
    tools=[end_conversation],
    system_prompt="You are a helpful assistant.",
)

audio_io = AudioIO()

async def main():
    await agent.run(
        inputs=[audio_io.input()],
        outputs=[audio_io.output()]
    )
    # run() returns after the agent calls end_conversation.

asyncio.run(main())

Bidi checks for cancellation after a tool group completes and its results are recorded. Requests from other contexts remain pending until that checkpoint.

Debug Logs

To enable debug logs in your agent, configure the strands logger:

import asyncio
import logging
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel

# Enable debug logs
logging.getLogger("strands").setLevel(logging.DEBUG)
logging.basicConfig(
    format="%(levelname)s | %(name)s | %(message)s",
    handlers=[logging.StreamHandler()]
)

model = BedrockNovaSonicModel(model_id="amazon.nova-2-sonic-v1:0")
agent = BidiAgent(model=model)
audio_io = AudioIO()

async def main():
    await agent.run(
        inputs=[audio_io.input()],
        outputs=[audio_io.output()]
    )

asyncio.run(main())

Debug logs show:

• Connection lifecycle events
• Audio buffer operations
• Tool execution details
• Event processing flow

Common Issues

Audio Feedback Loop in a Python Console

Over open speakers, the agent’s own playback can feed back into the microphone and trigger a barge-in. Either use a headset, or enable microphone audio processing to cancel the echo:

pip install "strands-agents[bidi,bidi-pyaudio,bidi-aec]"

audio_io = AudioIO(audio_processor=True)

See Audio Processing for the available options.

No Audio Output

If you don’t hear audio:

# List available audio devices
import pyaudio
p = pyaudio.PyAudio()
for i in range(p.get_device_count()):
    info = p.get_device_info_by_index(i)
    print(f"{i}: {info['name']}")

# Specify output device explicitly
audio_io = AudioIO(output_device_index=2)

Microphone Not Working

If the agent doesn’t respond to speech:

# Specify input device explicitly
audio_io = AudioIO(input_device_index=1)

# Check system permissions (macOS)
# System Preferences → Security & Privacy → Microphone

Connection Restarts

Each provider caps how long a single connection stays open. Rather than wait for that limit, BidiAgent restarts the connection proactively: a timer fires ahead of the cap, the agent replays the conversation history into a fresh connection, and it emits a BidiConnectionRestartEvent with reason="scheduled". If a connection times out first, the agent restarts reactively and emits the same event with reason="timeout". Treat both as informational, not errors:

from strands.bidi.types import BidiConnectionRestartEvent

async for event in agent.receive():
    if isinstance(event, BidiConnectionRestartEvent):
        print(f"Restarting (reason={event.reason})")
        if event.turn_interrupted:
            print("The in-progress turn was cut short; consider re-prompting.")
        continue

Providers declare restart timing through ConnectionConfig. Tune it, or opt out of automatic restart with the model’s connection argument:

from strands.bidi.models import BedrockNovaSonicModel

# Restart 60s earlier than the provider default
model = BedrockNovaSonicModel(
    model_id="amazon.nova-2-sonic-v1:0",
    connection={"restart_after_s": 360},
)

For longer sessions on a single connection, OpenAI Realtime allows a larger connection window than Nova Sonic.

Next Steps

• Agent - Deep dive into BidiAgent configuration and lifecycle
• Events - Complete guide to bidirectional streaming events
• I/O Streams - Understanding and customizing input and output streams
• Model Providers:
  • Nova Sonic - Amazon Bedrock’s bidirectional streaming model
  • OpenAI Realtime - OpenAI’s Realtime API
  • Gemini Live - Google’s Gemini Live API
• Python API Reference - Complete API documentation

Tags

bidi-streaming12quickstart7