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

User input accepted by BidiAgent.send() and returned by input streams.

Supported forms:

• Text: a string, TextBlock, or a dictionary with a text key.
• Image: ImageBlock or a dictionary with an image key.
• Streaming audio: AudioDelta or a dictionary with an audio_delta key.
• Grouped content: a nonempty list of strings, text/image blocks, or their dictionary forms.

A list forms one user message and preserves block order. Send audio deltas individually, outside these lists.

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.run().

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:73

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:81

Initialize connection start event.

connection_id

@property
def connection_id() -> str

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

Unique identifier for this streaming connection.

model

@property
def model() -> str

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

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

BidiConnectionRestartEvent

class BidiConnectionRestartEvent(TypedEvent)

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

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. Recovery depends on the provider’s replay or resumption support; the application may need to re-prompt or notify the user.

__init__

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

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

Initialize connection restart event.

reason

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

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

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

timeout_error

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

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

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:143

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:148

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:157

Initialize connection warning event.

time_left_s

@property
def time_left_s() -> float

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

Approximate seconds until the scheduled restart.

BidiResponseStartEvent

class BidiResponseStartEvent(TypedEvent)

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

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:179

Initialize response start event.

response_id

@property
def response_id() -> str

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

Unique identifier for this response.

BidiAudioStartEvent

class BidiAudioStartEvent(TypedEvent)

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

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:192

Initialize audio start event.

content_id

@property
def content_id() -> str

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

Identifier shared by this audio stream’s events.

BidiAudioDeltaEvent

class BidiAudioDeltaEvent(TypedEvent)

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

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:213

Initialize audio delta event.

content_id

@property
def content_id() -> str

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

Identifier shared by this audio stream’s events.

audio

@property
def audio() -> str

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

Base64-encoded audio chunk.

format

@property
def format() -> AudioFormat

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

Audio encoding format.

sample_rate

@property
def sample_rate() -> int

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

Number of audio samples per second in Hz.

channels

@property
def channels() -> AudioChannel

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

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

BidiAudioStopEvent

class BidiAudioStopEvent(TypedEvent)

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

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:262

Initialize audio stop event.

content_id

@property
def content_id() -> str

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

Identifier shared by this audio stream’s events.

BidiTextStartEvent

class BidiTextStartEvent(TypedEvent)

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

Beginning of assistant text output, identified by content_id.

__init__

def __init__(content_id: str)

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

Initialize text start event.

content_id

@property
def content_id() -> str

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

Identifier shared by this text block’s events.

BidiTextDeltaEvent

class BidiTextDeltaEvent(TypedEvent)

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

Incremental assistant text output, separate from speech transcripts.

__init__

def __init__(delta: str, content_id: str)

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

Initialize text delta event.

content_id

@property
def content_id() -> str

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

Identifier shared by this text block’s events.

delta

@property
def delta() -> str

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

Incremental text.

BidiTextStopEvent

class BidiTextStopEvent(TypedEvent)

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

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:306

Initialize text stop event.

content_id

@property
def content_id() -> str

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

Identifier shared by this text block’s events.

BidiTextBlockEvent

class BidiTextBlockEvent(TypedEvent)

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

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:319

Initialize text block event.

content_id

@property
def content_id() -> str

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

Identifier shared by this text block’s events.

text

@property
def text() -> str

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

Complete text.

BidiReasoningStartEvent

class BidiReasoningStartEvent(TypedEvent)

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

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

__init__

def __init__(content_id: str)

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

Initialize reasoning start event.

content_id

@property
def content_id() -> str

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

Identifier shared by this reasoning block’s events.

BidiReasoningDeltaEvent

class BidiReasoningDeltaEvent(TypedEvent)

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

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:350

Initialize reasoning delta event.

content_id

@property
def content_id() -> str

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

Identifier shared by this reasoning block’s events.

delta

@property
def delta() -> str

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

Incremental reasoning text.

BidiReasoningStopEvent

class BidiReasoningStopEvent(TypedEvent)

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

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:368

Initialize reasoning stop event.

content_id

@property
def content_id() -> str

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

Identifier shared by this reasoning block’s events.

BidiReasoningBlockEvent

class BidiReasoningBlockEvent(TypedEvent)

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

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:381

Initialize reasoning block event.

content_id

@property
def content_id() -> str

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

Identifier shared by this reasoning block’s events.

text

@property
def text() -> str

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

Complete reasoning text or thought summary.

BidiTranscriptStartEvent

class BidiTranscriptStartEvent(TypedEvent)

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

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:404

Initialize transcript start event.

content_id

@property
def content_id() -> str

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

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

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

The role of the speaker.

BidiTranscriptDeltaEvent

class BidiTranscriptDeltaEvent(TypedEvent)

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

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:434

Initialize transcript delta event.

content_id

@property
def content_id() -> str

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

Identifier shared by this transcript’s events.

delta

@property
def delta() -> str

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

The incremental transcript text.

role

@property
def role() -> Role

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

The role of the message sender.

BidiTranscriptStopEvent

class BidiTranscriptStopEvent(TypedEvent)

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

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:469

Initialize transcript stop event.

content_id

@property
def content_id() -> str

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

Identifier shared by this transcript’s events.

role

@property
def role() -> Role

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

The role of the speaker.

BidiTranscriptBlockEvent

class BidiTranscriptBlockEvent(TypedEvent)

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

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:499

Initialize transcript block event.

content_id

@property
def content_id() -> str

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

Identifier shared by this transcript’s events.

transcript

@property
def transcript() -> str

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

The final transcript text.

role

@property
def role() -> Role

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

The role of the speaker.

BidiBargeInEvent

class BidiBargeInEvent(TypedEvent)

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

Stop current response generation or playback while the session continues.

__init__

def __init__() -> None

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

Initialize barge-in event.

BidiResponseStopEvent

class BidiResponseStopEvent(TypedEvent)

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

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:541

Initialize response stop event.

response_id

@property
def response_id() -> str

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

Unique identifier for this response.

TokenDetails

class TokenDetails(TypedDict)

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

Token counts by category for the input or output side of a usage event.

All fields are optional. Categories may overlap or be incomplete, so their sum is not necessarily the event’s input or output token count.

Attributes:

• text - Text tokens.
• audio - Audio tokens.
• image - Image tokens.
• video - Video tokens.
• cache_read - Input tokens read from cache.
• reasoning - Output reasoning or thought tokens reported by the provider.

BidiUsageEvent

class BidiUsageEvent(TypedEvent)

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

Additional model token usage with optional input and output breakdowns.

Each event contributes new usage to the conversation’s running totals. Its counts may cover part of a response or a complete model generation.

Detail maps use names such as audio, text, image, cache_read, and reasoning. Providers may omit details or report overlapping counts, so use the reported totals rather than summing the breakdowns.

Arguments:

• input_tokens - Input tokens accounted for by this event.
• output_tokens - Output tokens accounted for by this event.
• total_tokens - Total tokens accounted for by this event.
• input_token_details - Optional input token counts by category for this event.
• output_token_details - Optional output token counts by category for this event.

__init__

def __init__(input_tokens: int,
             output_tokens: int,
             total_tokens: int,
             input_token_details: TokenDetails | None = None,
             output_token_details: TokenDetails | None = None) -> None

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

Initialize usage event.

input_tokens

@property
def input_tokens() -> int

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

Input tokens accounted for by this event.

output_tokens

@property
def output_tokens() -> int

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

Output tokens accounted for by this event.

total_tokens

@property
def total_tokens() -> int

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

Total tokens accounted for by this event.

input_token_details

@property
def input_token_details() -> TokenDetails

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

Input token counts by category, empty when unreported.

output_token_details

@property
def output_token_details() -> TokenDetails

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

Output token counts by category, empty when unreported.

BidiToolUseBlocksEvent

class BidiToolUseBlocksEvent(TypedEvent)

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

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:651

Initialize a tool-use group.

tool_uses

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

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

Tool calls in provider order.

BidiConnectionStopEvent

class BidiConnectionStopEvent(TypedEvent)

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

Streaming connection stop notification, which may precede resource cleanup.

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:669

Initialize connection stop event.

connection_id

@property
def connection_id() -> str

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

Unique identifier for this streaming connection.

reason

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

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

Why the connection was closed.

BidiOutputEvent

Union of different bidi output event types.