strands.experimental.bidi.types

Content-related type definitions for bidirectional streaming.

BidiUserContentBlock

A complete text or image block supplied by a user.

BidiContentBlock

A complete text, image, or tool result block.

BidiContentDelta

An audio delta for the live input stream.

BidiUserContentBlockData

Dictionary form of one user content block.

BidiContentBlockData

Dictionary form of one text, image, or tool result block.

BidiContentDeltaData

Dictionary form of an audio delta.

BidiMessage

@dataclass
class BidiMessage()

Defined in: src/strands/experimental/bidi/types/content.py:33

An input message containing ordered content blocks.

Callers must supply at least one block when sending and must not mix tool results with user text or images. Send streaming deltas individually.

Attributes:

• content - Ordered list of complete content blocks.

BidiContentMetadata

class BidiContentMetadata(TypedDict)

Defined in: src/strands/experimental/bidi/types/content.py:46

Streamed content metadata stored under a message’s metadata.custom.bidi.

Attributes:

• kind - Identifies the message as text, reasoning, or a transcript.
• status - Whether the content is pending, complete, or incomplete.

Agent-related type definitions for bidirectional streaming.

This module defines the types used for BidiAgent.

BidiAgentInput

A single user input or list of user content blocks.

Media input types for bidirectional streaming.

AudioDelta

@dataclass
class AudioDelta()

Defined in: src/strands/experimental/bidi/types/media.py:15

Audio samples to append to the live input stream.

Sending a delta does not explicitly end the user’s turn.

Attributes:

• format - Audio format.
• source - Source containing the audio samples.

to_dict

def to_dict() -> _AudioDeltaData

Defined in: src/strands/experimental/bidi/types/media.py:28

Return the dictionary form of this delta.

Protocols for bidirectional input and output streams.

The protocols separate input and output concerns into independent callables with lifecycle methods managed by BidiAgent.

InputStream

@runtime_checkable
class InputStream(Protocol)

Defined in: src/strands/experimental/bidi/types/io.py:18

Callable input stream managed by a bidirectional agent.

An input stream reads one value from a source each time the agent calls it.

start

async def start(agent: "BidiAgent") -> None

Defined in: src/strands/experimental/bidi/types/io.py:24

Start input.

stop

async def stop() -> None

Defined in: src/strands/experimental/bidi/types/io.py:28

Stop input.

__call__

def __call__() -> Awaitable[BidiAgentInput]

Defined in: src/strands/experimental/bidi/types/io.py:32

Read input data from the source.

Returns:

Awaitable that resolves to input content (audio, text, image, etc.)

OutputStream

@runtime_checkable
class OutputStream(Protocol)

Defined in: src/strands/experimental/bidi/types/io.py:42

Callable output stream managed by a bidirectional agent.

An output stream handles one event each time the agent calls it.

start

async def start(agent: "BidiAgent") -> None

Defined in: src/strands/experimental/bidi/types/io.py:48

Start output.

stop

async def stop() -> None

Defined in: src/strands/experimental/bidi/types/io.py:52

Stop output.

__call__

def __call__(event: BidiOutputEvent) -> Awaitable[None]

Defined in: src/strands/experimental/bidi/types/io.py:56

Process output events from the agent.

Arguments:

• event - Output event from the agent (audio, text, tool calls, etc.)

Bidirectional streaming types for real-time audio/text conversations.

Type definitions for bidirectional streaming that extends Strands’ existing streaming capabilities with real-time audio and persistent connection support.

Key features:

• Audio output events with standardized formats
• Barge-in detection and handling
• Connection lifecycle management
• Provider-agnostic event types
• Type-safe discriminated unions with TypedEvent
• JSON-serializable output events (audio stored as base64 strings)

Audio format normalization:

• Supports PCM, WAV, Opus, and MP3 formats
• Describes sample rates in Hz
• Normalizes channel configurations (mono/stereo)
• Abstracts provider-specific encodings
• Audio output stored as base64-encoded strings for JSON compatibility

AudioChannel

Number of audio channels.

• Mono: 1
• Stereo: 2

AudioFormat

Audio encoding format.

Role

Role of a message sender.

• “user”: Messages from the user to the assistant.
• “assistant”: Messages from the assistant to the user.

BidiConnectionStartEvent

class BidiConnectionStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:81

Streaming connection established and ready for interaction.

Arguments:

• connection_id - Unique identifier for this streaming connection.
• model - Model identifier (e.g., “gpt-realtime-2.1”, “gemini-3.8-live”).

__init__

def __init__(connection_id: str, model: str)

Defined in: src/strands/experimental/bidi/types/events.py:89

Initialize connection start event.

connection_id

@property
def connection_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:100

Unique identifier for this streaming connection.

model

@property
def model() -> str

Defined in: src/strands/experimental/bidi/types/events.py:105

Model identifier (e.g., ‘gpt-realtime-2.1’, ‘gemini-3.8-live’).

BidiConnectionRestartEvent

class BidiConnectionRestartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:110

Agent is restarting the model connection.

Emitted on both reconnect paths: reactively after the model reports a timeout, and proactively when the reconnect timer fires ahead of the provider’s limit.

Arguments:

• reason - What triggered the restart (“timeout” reactively, “scheduled” proactively).
• timeout_error - The model’s timeout error on the reactive path; None when scheduled.
• turn_interrupted - True if the restart cut an in-progress or owed turn (the alignment wait could not complete it before the deadline, or a timeout struck mid-turn). The provider replays history as context, so that turn will not be answered on its own — an app can re-prompt or notify the user when this is set.

__init__

def __init__(reason: Literal["timeout", "scheduled"],
             timeout_error: "ConnectionTimeoutError | None" = None,
             turn_interrupted: bool = False)

Defined in: src/strands/experimental/bidi/types/events.py:125

Initialize connection restart event.

reason

@property
def reason() -> str

Defined in: src/strands/experimental/bidi/types/events.py:142

What triggered the restart (“timeout” or “scheduled”).

timeout_error

@property
def timeout_error() -> "ConnectionTimeoutError | None"

Defined in: src/strands/experimental/bidi/types/events.py:147

Connection timeout error on the reactive path; None when scheduled.

turn_interrupted

@property
def turn_interrupted() -> bool

Defined in: src/strands/experimental/bidi/types/events.py:152

True if the restart cut an in-progress or owed turn that will not be answered.

BidiConnectionWarningEvent

class BidiConnectionWarningEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:157

Agent is approaching a proactive reconnect.

Emitted by the proactive reconnect timer before a reconnect; informational only.

Arguments:

• time_left_s - Approximate seconds until the scheduled reconnect.

__init__

def __init__(time_left_s: float)

Defined in: src/strands/experimental/bidi/types/events.py:166

Initialize connection warning event.

time_left_s

@property
def time_left_s() -> float

Defined in: src/strands/experimental/bidi/types/events.py:176

Approximate seconds until the scheduled reconnect.

BidiResponseStartEvent

class BidiResponseStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:181

Start of a model response.

Arguments:

• response_id - Unique identifier for this response (used in BidiResponseStopEvent).

__init__

def __init__(response_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:188

Initialize response start event.

response_id

@property
def response_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:193

Unique identifier for this response.

BidiAudioStartEvent

class BidiAudioStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:198

Beginning of an assistant audio stream, identified by content_id.

__init__

def __init__(content_id: str) -> None

Defined in: src/strands/experimental/bidi/types/events.py:201

Initialize audio start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:206

Identifier shared by this audio stream’s events.

BidiAudioDeltaEvent

class BidiAudioDeltaEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:211

Incremental audio output from the model.

Arguments:

• audio - Base64-encoded audio chunk.
• format - Audio encoding format.
• sample_rate - Number of audio samples per second in Hz.
• channels - Number of audio channels (1=mono, 2=stereo).
• content_id - Unique identifier shared by this audio stream’s events.

__init__

def __init__(audio: str, format: AudioFormat, sample_rate: int,
             channels: AudioChannel, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:222

Initialize audio delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:243

Identifier shared by this audio stream’s events.

audio

@property
def audio() -> str

Defined in: src/strands/experimental/bidi/types/events.py:248

Base64-encoded audio chunk.

format

@property
def format() -> AudioFormat

Defined in: src/strands/experimental/bidi/types/events.py:253

Audio encoding format.

sample_rate

@property
def sample_rate() -> int

Defined in: src/strands/experimental/bidi/types/events.py:258

Number of audio samples per second in Hz.

channels

@property
def channels() -> AudioChannel

Defined in: src/strands/experimental/bidi/types/events.py:263

Number of audio channels (1=mono, 2=stereo).

BidiAudioStopEvent

class BidiAudioStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:268

End of an assistant audio stream, which may still be playing.

__init__

def __init__(content_id: str) -> None

Defined in: src/strands/experimental/bidi/types/events.py:271

Initialize audio stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:276

Identifier shared by this audio stream’s events.

BidiTextStartEvent

class BidiTextStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:281

Beginning of assistant text output, identified by content_id.

__init__

def __init__(content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:284

Initialize text start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:289

Identifier shared by this text block’s events.

BidiTextDeltaEvent

class BidiTextDeltaEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:294

Incremental assistant text output, separate from speech transcripts.

__init__

def __init__(delta: str, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:297

Initialize text delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:302

Identifier shared by this text block’s events.

delta

@property
def delta() -> str

Defined in: src/strands/experimental/bidi/types/events.py:307

Incremental text.

BidiTextStopEvent

class BidiTextStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:312

End of an assistant text stream, before its completed block is emitted.

__init__

def __init__(content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:315

Initialize text stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:320

Identifier shared by this text block’s events.

BidiTextBlockEvent

class BidiTextBlockEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:325

Complete assistant text, emitted after its stop event by the agent.

__init__

def __init__(text: str, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:328

Initialize text block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:333

Identifier shared by this text block’s events.

text

@property
def text() -> str

Defined in: src/strands/experimental/bidi/types/events.py:338

Complete text.

BidiReasoningStartEvent

class BidiReasoningStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:343

Beginning of model-provided reasoning text, identified by content_id.

__init__

def __init__(content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:346

Initialize reasoning start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:351

Identifier shared by this reasoning block’s events.

BidiReasoningDeltaEvent

class BidiReasoningDeltaEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:356

Incremental reasoning text or thought summary exposed by the model.

__init__

def __init__(delta: str, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:359

Initialize reasoning delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:364

Identifier shared by this reasoning block’s events.

delta

@property
def delta() -> str

Defined in: src/strands/experimental/bidi/types/events.py:369

Incremental reasoning text.

BidiReasoningStopEvent

class BidiReasoningStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:374

End of a reasoning stream, before its completed block is emitted.

__init__

def __init__(content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:377

Initialize reasoning stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:382

Identifier shared by this reasoning block’s events.

BidiReasoningBlockEvent

class BidiReasoningBlockEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:387

Complete reasoning text, emitted after its stop event by the agent.

__init__

def __init__(text: str, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:390

Initialize reasoning block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:395

Identifier shared by this reasoning block’s events.

text

@property
def text() -> str

Defined in: src/strands/experimental/bidi/types/events.py:400

Complete reasoning text or thought summary.

BidiTranscriptStartEvent

class BidiTranscriptStartEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:405

Beginning of a user or assistant transcript, before its text arrives.

Arguments:

• role - Who is speaking (“user” or “assistant”).
• content_id - Unique identifier shared by this transcript’s events.

__init__

def __init__(role: Role, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:413

Initialize transcript start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:424

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

Defined in: src/strands/experimental/bidi/types/events.py:429

The role of the speaker.

BidiTranscriptDeltaEvent

class BidiTranscriptDeltaEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:434

Incremental transcription of user or assistant speech.

Arguments:

• delta - The incremental transcript text.
• role - Who is speaking (“user” or “assistant”).
• content_id - Unique identifier shared by this transcript’s events.

__init__

def __init__(delta: str, role: Role, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:443

Initialize transcript delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:455

Identifier shared by this transcript’s events.

delta

@property
def delta() -> str

Defined in: src/strands/experimental/bidi/types/events.py:460

The incremental transcript text.

role

@property
def role() -> Role

Defined in: src/strands/experimental/bidi/types/events.py:465

The role of the message sender.

BidiTranscriptStopEvent

class BidiTranscriptStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:470

End of a transcript stream, before its completed block is emitted.

Arguments:

• role - Who spoke (“user” or “assistant”).
• content_id - Unique identifier shared by this transcript’s events.

__init__

def __init__(role: Role, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:478

Initialize transcript stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:489

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

Defined in: src/strands/experimental/bidi/types/events.py:494

The role of the speaker.

BidiTranscriptBlockEvent

class BidiTranscriptBlockEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:499

Complete transcript, emitted after its stop event by the agent.

Arguments:

• transcript - The final transcript text.
• role - Who spoke (“user” or “assistant”).
• content_id - Unique identifier shared by this transcript’s events.

__init__

def __init__(transcript: str, role: Role, content_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:508

Initialize transcript block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:520

Identifier shared by this transcript’s events.

transcript

@property
def transcript() -> str

Defined in: src/strands/experimental/bidi/types/events.py:525

The final transcript text.

role

@property
def role() -> Role

Defined in: src/strands/experimental/bidi/types/events.py:530

The role of the speaker.

BidiBargeInEvent

class BidiBargeInEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:535

Stop current response generation or playback while the session continues.

Arguments:

• reason - Why response output should stop.

__init__

def __init__(reason: Literal["user_speech", "error"])

Defined in: src/strands/experimental/bidi/types/events.py:542

Initialize barge-in event.

reason

@property
def reason() -> str

Defined in: src/strands/experimental/bidi/types/events.py:552

Why response output should stop.

BidiResponseStopEvent

class BidiResponseStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:557

Response output ended. User transcription may still be pending.

Arguments:

• response_id - ID of the response that ended (matches BidiResponseStartEvent).

__init__

def __init__(response_id: str)

Defined in: src/strands/experimental/bidi/types/events.py:564

Initialize response stop event.

response_id

@property
def response_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:574

Unique identifier for this response.

ModalityUsage

class ModalityUsage(dict)

Defined in: src/strands/experimental/bidi/types/events.py:579

Token usage for a specific modality.

Attributes:

• modality - Type of content.
• input_tokens - Tokens used for this modality’s input.
• output_tokens - Tokens used for this modality’s output.

BidiUsageEvent

class BidiUsageEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:593

Token usage event with modality breakdown for bidirectional streaming.

Tracks token consumption across different modalities (audio, text, images) during bidirectional streaming sessions.

Arguments:

• input_tokens - Total tokens used for all input modalities.
• output_tokens - Total tokens used for all output modalities.
• total_tokens - Sum of input and output tokens.
• modality_details - Optional list of token usage per modality.
• cache_read_input_tokens - Optional tokens read from cache.
• cache_write_input_tokens - Optional tokens written to cache.

__init__

def __init__(input_tokens: int,
             output_tokens: int,
             total_tokens: int,
             modality_details: list[ModalityUsage] | None = None,
             cache_read_input_tokens: int | None = None,
             cache_write_input_tokens: int | None = None)

Defined in: src/strands/experimental/bidi/types/events.py:608

Initialize usage event.

input_tokens

@property
def input_tokens() -> int

Defined in: src/strands/experimental/bidi/types/events.py:633

Total tokens used for all input modalities.

output_tokens

@property
def output_tokens() -> int

Defined in: src/strands/experimental/bidi/types/events.py:638

Total tokens used for all output modalities.

total_tokens

@property
def total_tokens() -> int

Defined in: src/strands/experimental/bidi/types/events.py:643

Sum of input and output tokens.

modality_details

@property
def modality_details() -> list[ModalityUsage]

Defined in: src/strands/experimental/bidi/types/events.py:648

Optional list of token usage per modality.

cache_read_input_tokens

@property
def cache_read_input_tokens() -> int | None

Defined in: src/strands/experimental/bidi/types/events.py:653

Optional tokens read from cache.

cache_write_input_tokens

@property
def cache_write_input_tokens() -> int | None

Defined in: src/strands/experimental/bidi/types/events.py:658

Optional tokens written to cache.

BidiToolUseBlocksEvent

class BidiToolUseBlocksEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:663

A complete group of tool calls requested by the model.

Arguments:

• tool_uses - Tool calls to execute together.

__init__

def __init__(tool_uses: list[ToolUse])

Defined in: src/strands/experimental/bidi/types/events.py:670

Initialize a tool-use group.

tool_uses

@property
def tool_uses() -> list[ToolUse]

Defined in: src/strands/experimental/bidi/types/events.py:675

Tool calls in provider order.

BidiConnectionStopEvent

class BidiConnectionStopEvent(TypedEvent)

Defined in: src/strands/experimental/bidi/types/events.py:680

Streaming connection closed.

Arguments:

• connection_id - Unique identifier for this streaming connection (matches BidiConnectionStartEvent).
• reason - Why the connection was closed.

__init__

def __init__(connection_id: str,
             reason: Literal["client_disconnect", "timeout", "error",
                             "complete", "user_request"])

Defined in: src/strands/experimental/bidi/types/events.py:688

Initialize connection stop event.

connection_id

@property
def connection_id() -> str

Defined in: src/strands/experimental/bidi/types/events.py:703

Unique identifier for this streaming connection.

reason

@property
def reason() -> str

Defined in: src/strands/experimental/bidi/types/events.py:708

Why the connection was closed.

BidiOutputEvent

Union of different bidi output event types.