Stream Events

Use stream events to react to a conversation as it unfolds. BidiAgent emits events that carry new content or signal a change in state. An event can deliver an audio chunk, add text to a transcript, mark the start or end of a response, or report a tool result.

Your application consumes these events to play audio, display text, and track ongoing work. A single response can produce many events, while user transcripts and background tool results can arrive independently. All of them flow through the same event stream.

Consume events

Read events with agent.receive() after starting the agent. To forward events to output streams, use agent.run(), which manages the agent lifecycle and sends each event to every configured output stream.

Use isinstance() to access typed properties, or check the type string and read dictionary fields. The example below demonstrates both styles by sending a text prompt and printing completed transcripts until the first model response ends:

Typed events
Dictionary access

import asyncio

from strands.bidi.agent import BidiAgent
from strands.bidi.types import (
    BidiResponseStopEvent,
    BidiTranscriptBlockEvent,
)


async def main() -> None:
    async with BidiAgent() as agent:
        await agent.send("Say hello in one sentence.")

        async for event in agent.receive():
            if isinstance(event, BidiTranscriptBlockEvent):
                print(f"{event.role}: {event.transcript}")
            elif isinstance(event, BidiResponseStopEvent):
                break


asyncio.run(main())

import asyncio

from strands.bidi.agent import BidiAgent


async def main() -> None:
    async with BidiAgent() as agent:
        await agent.send("Say hello in one sentence.")

        async for event in agent.receive():
            event_type = event.get("type")
            if event_type == "bidi_transcript_block":
                print(f"{event['role']}: {event['transcript']}")
            elif event_type == "bidi_response_stop":
                break


asyncio.run(main())

Event families

Model adapters emit connection starts, response boundaries, content streams, barge-in signals, tool requests, and usage reports. The agent adds completed blocks, tool results, restart notifications, and connection stops.

Provider support and configuration determine which events appear. See the event API reference for complete class definitions and fields.

Connections

Use connection events to track when the model is ready, a restart is approaching, or the agent is shutting down.

Event	Meaning
`BidiConnectionStartEvent`	The model connection is ready. Includes its `connection_id` and `model`.
`BidiConnectionWarningEvent`	A scheduled restart is approaching. `time_left_s` estimates the time remaining.
`BidiConnectionRestartEvent`	The agent is replacing the connection. `reason` identifies a scheduled restart or timeout.
`BidiConnectionStopEvent`	The agent is shutting down. Includes `connection_id`.

Responses

Use response events to track a model response to user input, conceptually similar to a single Agent invocation. Match the start and stop events by response_id.

Event	Meaning
`BidiResponseStartEvent`	A model response begins.
`BidiResponseStopEvent`	The response’s output ends. Buffered audio may still be playing.

Background tool execution can continue after response stop, and tool results can trigger a follow-up model response.

Audio

Use audio events to play the assistant’s speech. Events for one audio stream share a content_id.

Event	Meaning
`BidiAudioStartEvent`	An audio stream begins.
`BidiAudioDeltaEvent`	The next audio chunk is in `audio`, encoded as base64.
`BidiAudioStopEvent`	The audio stream ends.

Each delta also includes the audio format, sample_rate, and channels. Buffered audio may still be playing when BidiAudioStopEvent arrives. See AudioIO for playback handling.

Transcripts

Use transcript events to display user or assistant speech as text. Each event includes the speaker’s role ("user" or "assistant") and the stream’s content_id.

Event	Meaning
`BidiTranscriptStartEvent`	A transcript stream begins.
`BidiTranscriptDeltaEvent`	The next transcript fragment is in `delta`.
`BidiTranscriptStopEvent`	The transcript stream ends.
`BidiTranscriptBlockEvent`	The complete transcript is in `transcript`.

Text

Use text events for written assistant output. Events for one text stream share a content_id.

Event	Meaning
`BidiTextStartEvent`	A text stream begins.
`BidiTextDeltaEvent`	The next text fragment is in `delta`.
`BidiTextStopEvent`	The text stream ends.
`BidiTextBlockEvent`	The complete text is in `text`.

Reasoning

Use reasoning events for reasoning text or thought summaries exposed by the model. Events for one reasoning stream share a content_id.

Event	Meaning
`BidiReasoningStartEvent`	A reasoning stream begins.
`BidiReasoningDeltaEvent`	The next reasoning fragment is in `delta`.
`BidiReasoningStopEvent`	The reasoning stream ends.
`BidiReasoningBlockEvent`	The complete reasoning is in `text`.

Tools

Use tool events to track requests, intermediate output, and completed results.

Event	Meaning
`BidiToolUseBlocksEvent`	The model requests a group of tool calls in `tool_uses`. Each call includes `toolUseId`, `name`, and `input`.
`ToolStreamEvent`	A running tool yields intermediate output. `tool_stream_event` contains `tool_use` and `data`.
`ToolResultEvent`	A tool finishes. `tool_result` contains its `toolUseId`, `status`, and result `content`.
`ToolResultMessageEvent`	The agent records all results from a tool group in a history `message`.

Barge-in

BidiBargeInEvent signals an interruption to model output, whether audio, text, or other content. It carries no fields beyond type. See Barge-in for responding to interrupted output.

Usage

Use BidiUsageEvent to track token usage during a conversation. Each event reports additional input_tokens, output_tokens, and total_tokens; sum these counts to track conversation totals.

Optional input_token_details and output_token_details provide breakdowns by modality, cache, or reasoning, depending on the provider. See Tracking token usage for an example.

Event ordering

Follow these ordering rules when consuming events or implementing a custom model. The diagram illustrates an audio response with an assistant transcript and a separate user transcript.

User transcripts have their own lifecycle and can start or finish before, during, or after an assistant response. Aligned rows do not imply timing, and a transcript start does not mark the exact moment speech began. Process assistant audio and tool requests without waiting for a completed user transcript.

Connection starts. BidiConnectionStartEvent precedes output from that model connection. Track the connection by connection_id. A connection can contain multiple responses.
Response starts. BidiResponseStartEvent precedes the response’s assistant content and tool requests. Match response start and stop by response_id.
Content streams. Each stream emits a start, zero or more deltas, and a stop. Text, reasoning, and other streams can interleave with the audio and transcripts shown, and streams can finish in a different order from their starts. Track each stream by its content_id, unique within the connection. A response can contain multiple streams and tool groups.
Completed blocks follow. The agent emits each completed block after its content stop, such as BidiTextBlockEvent after BidiTextStopEvent. Custom models supply start, delta, and stop events; the agent assembles the block. Audio has no completed block event.
Usage is reported. BidiUsageEvent provides token counts before response stop.
Response stops. BidiResponseStopEvent follows all assistant content stops and completed blocks in that response. User transcripts and background tool results are independent of this boundary.
Connection stops. BidiConnectionStopEvent signals the end of the conversation; the event iterator then ends.

Use deltas for live updates. A completed block contains the full text for its stream, so replace the displayed partial text when it arrives. See Messages for how this content becomes conversation history.

The model’s events stay in order, but background tool results and restart notifications can appear between them, even between a content stop and its block. Correlate events by their identifiers rather than adjacency.

A stop, connection failure, or forced restart can leave content or a response unfinished. Clean up application state without requiring a final content stop, block, or response stop event.

Tool execution

Track tool calls by toolUseId; results can arrive out of order or during another response. In this example, the tool group finishes after the response that requested it:

Request the group. BidiToolUseBlocksEvent contains complete calls in provider order. The agent starts them concurrently.
Receive tool output. Tools can emit intermediate output through ToolStreamEvent. Each ToolResultEvent arrives as a tool finishes.
Record the results. After all calls finish, ToolResultMessageEvent exposes their results in request order. It confirms the history update, not delivery to the model.

Tool errors reported through ToolResultEvent use status: "error". Failures that escape the tool runner raise from receive().

Barge-in

Use BidiBargeInEvent to stop presenting the current model output while the conversation and any background tools continue. The example below shows interrupted audio, but the same signal applies to text and other output:

Clear buffered audio as soon as the event arrives so playback stops promptly. AudioIO.output() does this automatically; a custom output stream must clear its own playback queue.

Connection restarts

Use restart events to track connection replacement and identify interrupted turns. With automatic restart enabled, the agent can replace its model connection on a schedule or after a timeout. It emits BidiConnectionRestartEvent before replacement and BidiConnectionStartEvent when the new connection is ready:

Scheduled restart. A warning estimates the time remaining in time_left_s; conversation events can occur before the restart. The restart event has reason: "scheduled" and timeout_error: None.
Timeout. No warning is required. The restart event has reason: "timeout", and timeout_error contains the model’s ConnectionTimeoutError.

When turn_interrupted is True, the restart cut off an active response or an unanswered turn. Replayed history supplies context but does not request an answer to that turn, so notify the user or send another prompt once the new connection is ready.

If your application tracks unfinished content streams, stop treating them as active when the new connection starts. You can keep partial content for display, but treat new streams separately. Background tools can continue across the restart.

Messages

BidiAgent builds conversation state in agent.messages as it processes streamed events. For each text, reasoning, or transcript stream, it groups events by content_id and assembles a separate message:

Start. The agent appends a placeholder message with an empty content list and a status of "pending".
Delta. It accumulates text in an internal buffer while the pending message stays empty.
Stop. It fills the placeholder with the accumulated content, marks it "complete", and emits the corresponding completed block event.

Reserving each message at stream start keeps history in that order, even when streams finish in a different order. A single response can contribute several messages.

For these streamed messages, message["metadata"]["custom"]["bidi"] records the content kind ("text", "reasoning", or "transcript") and completion status.

If a connection ends before a stream stops, the agent marks its message "incomplete". Text and reasoning retain their partial content; unfinished transcripts contain [Transcript unavailable.]. The agent does not emit completed blocks for unfinished streams.

The messages list stores assembled content alongside user input and tool exchanges:

Content	Representation in history
User input sent as text or images	A user message containing those blocks.
User or assistant transcript	A user or assistant message containing a `text` block.
Assistant text	An assistant message containing a `text` block.
Reasoning	An assistant message containing a `reasoningContent` block.
Tool activity	Assistant messages containing `toolUse` blocks, paired with user messages containing `toolResult` blocks.

Audio chunks are not stored in history. Speech appears as transcript text when the model provides it.

Tool requests add an exchange containing the calls and dispatch acknowledgements. After all calls in the group finish, the agent appends a second exchange with the same calls and their results, then emits ToolResultMessageEvent.