strands.types.events

Public stream event types.

The agent stream is a sequence of TypedEvent instances. The types in this module are public because middleware constructs or receives them: ModelStopReason is the result of a model call and ToolResultEvent is the result of a tool call. The other stream events are internal.

TypedEvent

class TypedEvent(dict)

Defined in: src/strands/types/events.py:19

Base class for every event in the agent stream.

An event is a dict whose items are its payload. Events that a middleware Wrap handler yields into the stream must be TypedEvent instances: the agent loop calls prepare() and reads is_callback_event on every event, so a plain dict fails.

__init__

def __init__(data: dict[str, Any] | None = None) -> None

Defined in: src/strands/types/events.py:27

Initialize the typed event with optional data.

Arguments:

• data - Optional dictionary of event data to initialize with

is_callback_event

@property
def is_callback_event() -> bool

Defined in: src/strands/types/events.py:36

True if this event should trigger the callback_handler to fire.

as_dict

def as_dict() -> dict

Defined in: src/strands/types/events.py:40

Convert this event to a raw dictionary for emitting purposes.

prepare

def prepare(invocation_state: dict) -> None

Defined in: src/strands/types/events.py:44

Prepare the event for emission by adding invocation state.

This allows a subset of events to merge with the invocation_state without needing to pass around the invocation_state throughout the system.

ModelStopReason

class ModelStopReason(TypedEvent)

Defined in: src/strands/types/events.py:53

Final event of a model call, carrying the aggregated response.

This is the result event of InvokeModelStage: the model stream ends with it, an Output handler receives it as InvokeModelResult.result, and a Wrap handler yields one to short-circuit the model call. Read it through stop_reason, message, usage and metrics. event["stop"] holds the same values as a (stop_reason, message, usage, metrics) tuple for model providers that unpack it from process_stream. It is not sent to callback handlers.

__init__

def __init__(stop_reason: StopReason, message: Message, usage: Usage,
             metrics: Metrics) -> None

Defined in: src/strands/types/events.py:64

Initialize with the final execution results.

Arguments:

• stop_reason - Why the model stopped generating
• message - Final message from the model
• usage - Usage information from the model
• metrics - Execution metrics and performance data

stop_reason

@property
def stop_reason() -> StopReason

Defined in: src/strands/types/events.py:86

Why the model stopped generating.

message

@property
def message() -> Message

Defined in: src/strands/types/events.py:91

Final message from the model.

usage

@property
def usage() -> Usage

Defined in: src/strands/types/events.py:96

Usage information from the model.

metrics

@property
def metrics() -> Metrics

Defined in: src/strands/types/events.py:101

Execution metrics and performance data.

ToolResultEvent

class ToolResultEvent(TypedEvent)

Defined in: src/strands/types/events.py:111

Final event of a tool call, carrying the tool result.

This is the result event of ExecuteToolStage: tool execution ends with it, an Output handler receives it as ExecuteToolResult.result, and a Wrap handler yields one to short-circuit or deny the tool call. When building a replacement for an existing result, pass its exception through so AfterToolCallEvent still receives it. It is not sent to callback handlers.

__init__

def __init__(tool_result: ToolResult,
             exception: Exception | None = None,
             *,
             backgrounded: bool = False) -> None

Defined in: src/strands/types/events.py:120

Initialize tool result event.

Arguments:

• tool_result - The tool result returned to the model.
• exception - The exception behind an error result, if any.
• backgrounded - Whether this result only acknowledges that the tool was dispatched to the background.

backgrounded

@property
def backgrounded() -> bool

Defined in: src/strands/types/events.py:136

Whether this result only acknowledges that the tool was dispatched to the background.

exception

@property
def exception() -> Exception | None

Defined in: src/strands/types/events.py:141

The original exception that occurred, if any.

Can be used for re-raising or type-based error handling.

tool_use_id

@property
def tool_use_id() -> str

Defined in: src/strands/types/events.py:149

The toolUseId associated with this result.

tool_result

@property
def tool_result() -> ToolResult

Defined in: src/strands/types/events.py:154

Final result from the completed tool execution.