strands.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/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/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/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/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/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/bidi/types/io.py:24

Start input.

stop

async def stop() -> None

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

Stop input.

__call__

def __call__() -> Awaitable[BidiAgentInput]

Defined in: src/strands/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/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/bidi/types/io.py:48

Start output.

stop

async def stop() -> None

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

Stop output.

__call__

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

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

Process output events from the agent.

Arguments:

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

Output event types for bidirectional streaming.

Defines the provider-agnostic events produced by bidirectional models and BidiAgent: connection lifecycle (start, restart, warning, stop), response start and stop, audio, text, reasoning, and transcript streams (start, delta, stop, and the completed block), barge-in, token usage, and tool-use groups. Also defines the AudioChannel, AudioFormat, and Role literals and the BidiOutputEvent union.

AudioChannel

Number of audio channels.

• Mono: 1
• Stereo: 2

AudioFormat

Audio encoding format of model audio output and AudioStreamConfig.

Distinct from strands.types.media.AudioFormat, the wider set of formats that types AudioDelta.format on audio input.

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/bidi/types/events.py:71

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/bidi/types/events.py:79

Initialize connection start event.

connection_id

@property
def connection_id() -> str

Defined in: src/strands/bidi/types/events.py:90

Unique identifier for this streaming connection.

model

@property
def model() -> str

Defined in: src/strands/bidi/types/events.py:95

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

BidiConnectionRestartEvent

class BidiConnectionRestartEvent(TypedEvent)

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

Agent is restarting the model connection.

Emitted on both restart paths: reactively after the model reports a timeout, and proactively when the restart 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 off an in-progress assistant response or a user turn that had not been answered yet. The new connection receives the history as context, so that turn is not 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/bidi/types/events.py:115

Initialize connection restart event.

reason

@property
def reason() -> Literal["timeout", "scheduled"]

Defined in: src/strands/bidi/types/events.py:132

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

timeout_error

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

Defined in: src/strands/bidi/types/events.py:137

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

turn_interrupted

@property
def turn_interrupted() -> bool

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

True if the restart cut off an in-progress response or an unanswered user turn.

BidiConnectionWarningEvent

class BidiConnectionWarningEvent(TypedEvent)

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

Agent is approaching a proactive restart.

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

Arguments:

• time_left_s - Approximate seconds until the scheduled restart.

__init__

def __init__(time_left_s: float)

Defined in: src/strands/bidi/types/events.py:156

Initialize connection warning event.

time_left_s

@property
def time_left_s() -> float

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

Approximate seconds until the scheduled restart.

BidiResponseStartEvent

class BidiResponseStartEvent(TypedEvent)

Defined in: src/strands/bidi/types/events.py:171

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/bidi/types/events.py:178

Initialize response start event.

response_id

@property
def response_id() -> str

Defined in: src/strands/bidi/types/events.py:183

Unique identifier for this response.

BidiAudioStartEvent

class BidiAudioStartEvent(TypedEvent)

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

Beginning of an assistant audio stream, identified by content_id.

__init__

def __init__(content_id: str) -> None

Defined in: src/strands/bidi/types/events.py:191

Initialize audio start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:196

Identifier shared by this audio stream’s events.

BidiAudioDeltaEvent

class BidiAudioDeltaEvent(TypedEvent)

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

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/bidi/types/events.py:212

Initialize audio delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:233

Identifier shared by this audio stream’s events.

audio

@property
def audio() -> str

Defined in: src/strands/bidi/types/events.py:238

Base64-encoded audio chunk.

format

@property
def format() -> AudioFormat

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

Audio encoding format.

sample_rate

@property
def sample_rate() -> int

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

Number of audio samples per second in Hz.

channels

@property
def channels() -> AudioChannel

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

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

BidiAudioStopEvent

class BidiAudioStopEvent(TypedEvent)

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

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

__init__

def __init__(content_id: str) -> None

Defined in: src/strands/bidi/types/events.py:261

Initialize audio stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:266

Identifier shared by this audio stream’s events.

BidiTextStartEvent

class BidiTextStartEvent(TypedEvent)

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

Beginning of assistant text output, identified by content_id.

__init__

def __init__(content_id: str)

Defined in: src/strands/bidi/types/events.py:274

Initialize text start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:279

Identifier shared by this text block’s events.

BidiTextDeltaEvent

class BidiTextDeltaEvent(TypedEvent)

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

Incremental assistant text output, separate from speech transcripts.

__init__

def __init__(delta: str, content_id: str)

Defined in: src/strands/bidi/types/events.py:287

Initialize text delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:292

Identifier shared by this text block’s events.

delta

@property
def delta() -> str

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

Incremental text.

BidiTextStopEvent

class BidiTextStopEvent(TypedEvent)

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

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

__init__

def __init__(content_id: str)

Defined in: src/strands/bidi/types/events.py:305

Initialize text stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:310

Identifier shared by this text block’s events.

BidiTextBlockEvent

class BidiTextBlockEvent(TypedEvent)

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

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

__init__

def __init__(text: str, content_id: str)

Defined in: src/strands/bidi/types/events.py:318

Initialize text block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:323

Identifier shared by this text block’s events.

text

@property
def text() -> str

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

Complete text.

BidiReasoningStartEvent

class BidiReasoningStartEvent(TypedEvent)

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

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

__init__

def __init__(content_id: str)

Defined in: src/strands/bidi/types/events.py:336

Initialize reasoning start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:341

Identifier shared by this reasoning block’s events.

BidiReasoningDeltaEvent

class BidiReasoningDeltaEvent(TypedEvent)

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

Incremental reasoning text or thought summary exposed by the model.

__init__

def __init__(delta: str, content_id: str)

Defined in: src/strands/bidi/types/events.py:349

Initialize reasoning delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:354

Identifier shared by this reasoning block’s events.

delta

@property
def delta() -> str

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

Incremental reasoning text.

BidiReasoningStopEvent

class BidiReasoningStopEvent(TypedEvent)

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

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

__init__

def __init__(content_id: str)

Defined in: src/strands/bidi/types/events.py:367

Initialize reasoning stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:372

Identifier shared by this reasoning block’s events.

BidiReasoningBlockEvent

class BidiReasoningBlockEvent(TypedEvent)

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

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

__init__

def __init__(text: str, content_id: str)

Defined in: src/strands/bidi/types/events.py:380

Initialize reasoning block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:385

Identifier shared by this reasoning block’s events.

text

@property
def text() -> str

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

Complete reasoning text or thought summary.

BidiTranscriptStartEvent

class BidiTranscriptStartEvent(TypedEvent)

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

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/bidi/types/events.py:403

Initialize transcript start event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:414

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

Defined in: src/strands/bidi/types/events.py:419

The role of the speaker.

BidiTranscriptDeltaEvent

class BidiTranscriptDeltaEvent(TypedEvent)

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

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/bidi/types/events.py:433

Initialize transcript delta event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:445

Identifier shared by this transcript’s events.

delta

@property
def delta() -> str

Defined in: src/strands/bidi/types/events.py:450

The incremental transcript text.

role

@property
def role() -> Role

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

The role of the message sender.

BidiTranscriptStopEvent

class BidiTranscriptStopEvent(TypedEvent)

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

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/bidi/types/events.py:468

Initialize transcript stop event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:479

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

Defined in: src/strands/bidi/types/events.py:484

The role of the speaker.

BidiTranscriptBlockEvent

class BidiTranscriptBlockEvent(TypedEvent)

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

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/bidi/types/events.py:498

Initialize transcript block event.

content_id

@property
def content_id() -> str

Defined in: src/strands/bidi/types/events.py:510

Identifier shared by this transcript’s events.

transcript

@property
def transcript() -> str

Defined in: src/strands/bidi/types/events.py:515

The final transcript text.

role

@property
def role() -> Role

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

The role of the speaker.

BidiBargeInEvent

class BidiBargeInEvent(TypedEvent)

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

Stop current response generation or playback while the session continues.

__init__

def __init__() -> None

Defined in: src/strands/bidi/types/events.py:528

Initialize barge-in event.

BidiResponseStopEvent

class BidiResponseStopEvent(TypedEvent)

Defined in: src/strands/bidi/types/events.py:533

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/bidi/types/events.py:540

Initialize response stop event.

response_id

@property
def response_id() -> str

Defined in: src/strands/bidi/types/events.py:550

Unique identifier for this response.

ModalityUsage

class ModalityUsage(dict)

Defined in: src/strands/bidi/types/events.py:555

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/bidi/types/events.py:569

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/bidi/types/events.py:584

Initialize usage event.

input_tokens

@property
def input_tokens() -> int

Defined in: src/strands/bidi/types/events.py:609

Total tokens used for all input modalities.

output_tokens

@property
def output_tokens() -> int

Defined in: src/strands/bidi/types/events.py:614

Total tokens used for all output modalities.

total_tokens

@property
def total_tokens() -> int

Defined in: src/strands/bidi/types/events.py:619

Sum of input and output tokens.

modality_details

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

Defined in: src/strands/bidi/types/events.py:624

Optional list of token usage per modality.

cache_read_input_tokens

@property
def cache_read_input_tokens() -> int | None

Defined in: src/strands/bidi/types/events.py:629

Optional tokens read from cache.

cache_write_input_tokens

@property
def cache_write_input_tokens() -> int | None

Defined in: src/strands/bidi/types/events.py:634

Optional tokens written to cache.

BidiToolUseBlocksEvent

class BidiToolUseBlocksEvent(TypedEvent)

Defined in: src/strands/bidi/types/events.py:639

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/bidi/types/events.py:646

Initialize a tool-use group.

tool_uses

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

Defined in: src/strands/bidi/types/events.py:651

Tool calls in provider order.

BidiConnectionStopEvent

class BidiConnectionStopEvent(TypedEvent)

Defined in: src/strands/bidi/types/events.py:656

Streaming connection closed.

Arguments:

• connection_id - Unique identifier for this streaming connection (matches BidiConnectionStartEvent).
• reason - Why the connection was closed. "user_request" after agent.cancel() takes effect.

__init__

def __init__(connection_id: str, reason: Literal["user_request"])

Defined in: src/strands/bidi/types/events.py:664

Initialize connection stop event.

connection_id

@property
def connection_id() -> str

Defined in: src/strands/bidi/types/events.py:679

Unique identifier for this streaming connection.

reason

@property
def reason() -> Literal["user_request"]

Defined in: src/strands/bidi/types/events.py:684

Why the connection was closed.

BidiOutputEvent

Union of different bidi output event types.