strands.experimental.hooks.events

Experimental hook events emitted as part of invoking Agents and BidiAgents.

This module defines the events that are emitted as Agents and BidiAgents run through the lifecycle of a request.

BidiHookEvent

@dataclass
class BidiHookEvent(BaseHookEvent)

Defined in: src/strands/experimental/hooks/events.py:44

Base class for BidiAgent hook events.

Attributes:

• agent - The BidiAgent instance that triggered this event.

BidiAgentInitializedEvent

@dataclass
class BidiAgentInitializedEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:55

Event triggered when a BidiAgent has finished initialization.

This event is fired after the BidiAgent has been fully constructed and all built-in components have been initialized. Hook providers can use this event to perform setup tasks that require a fully initialized agent.

BidiBeforeInvocationEvent

@dataclass
class BidiBeforeInvocationEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:67

Event triggered when BidiAgent starts a streaming session.

This event is fired before the BidiAgent begins a streaming session, before any model connection or audio processing occurs. Hook providers can use this event to perform session-level setup, logging, or validation.

This event is triggered at the beginning of agent.start().

BidiAfterInvocationEvent

@dataclass
class BidiAfterInvocationEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:81

Event triggered when BidiAgent ends a streaming session.

This event is fired after the BidiAgent has completed a streaming session, regardless of whether it completed successfully or encountered an error. Hook providers can use this event for cleanup, logging, or state persistence.

Note: This event uses reverse callback ordering, meaning callbacks registered later will be invoked first during cleanup.

This event is triggered at the end of agent.stop().

should_reverse_callbacks

@property
def should_reverse_callbacks() -> bool

Defined in: src/strands/experimental/hooks/events.py:95

True to invoke callbacks in reverse order.

BidiMessageAddedEvent

@dataclass
class BidiMessageAddedEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:101

Event triggered when BidiAgent adds a message to the conversation.

This event is fired whenever the BidiAgent adds a new message to its internal message history, including user messages (from transcripts), assistant responses, and tool results. Hook providers can use this event for logging, monitoring, or implementing custom message processing logic.

Note: This event is only triggered for messages added by the framework itself, not for messages manually added by tools or external code.

Attributes:

• message - The message that was added to the conversation history.

BidiBeforeToolCallEvent

@dataclass
class BidiBeforeToolCallEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:120

Event triggered before BidiAgent executes a tool.

This event is fired just before the BidiAgent executes a tool during a streaming session, allowing hook providers to inspect, modify, or replace the tool that will be executed. The selected_tool can be modified by hook callbacks to change which tool gets executed.

Attributes:

• selected_tool - The tool that will be invoked. Can be modified by hooks to change which tool gets executed. This may be None if tool lookup failed.
• tool_use - The tool parameters that will be passed to selected_tool.
• invocation_state - Keyword arguments that will be passed to the tool.
• cancel_tool - A user defined message that when set, will cancel the tool call. The message will be placed into a tool result with an error status. If set to True, Strands will cancel the tool call and use a default cancel message.

BidiAfterToolCallEvent

@dataclass
class BidiAfterToolCallEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:148

Event triggered after BidiAgent executes a tool.

This event is fired after the BidiAgent has finished executing a tool during a streaming session, regardless of whether the execution was successful or resulted in an error. Hook providers can use this event for cleanup, logging, or post-processing.

Note: This event uses reverse callback ordering, meaning callbacks registered later will be invoked first during cleanup.

Attributes:

• selected_tool - The tool that was invoked. It may be None if tool lookup failed.
• tool_use - The tool parameters that were passed to the tool invoked.
• invocation_state - Keyword arguments that were passed to the tool.
• result - The result of the tool invocation. Either a ToolResult on success or an Exception if the tool execution failed.
• exception - Exception if the tool execution failed, None if successful.
• cancel_message - The cancellation message if the user cancelled the tool call.
• duration - Elapsed time in seconds spent executing the tool. Starts after BeforeToolCallEvent returns and stops before AfterToolCallEvent is constructed. None when the tool call was cancelled by a BeforeToolCallEvent hook before execution.

should_reverse_callbacks

@property
def should_reverse_callbacks() -> bool

Defined in: src/strands/experimental/hooks/events.py:185

True to invoke callbacks in reverse order.

BidiInterruptionEvent

@dataclass
class BidiInterruptionEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:191

Event triggered when model generation is interrupted.

This event is fired when the user interrupts the assistant (e.g., by speaking during the assistant’s response) or when an error causes interruption. This is specific to bidirectional streaming and doesn’t exist in standard agents.

Hook providers can use this event to log interruptions, implement custom interruption handling, or trigger cleanup logic.

Attributes:

• reason - The reason for the interruption (“user_speech” or “error”).
• interrupted_response_id - Optional ID of the response that was interrupted.

BidiBeforeConnectionRestartEvent

@dataclass
class BidiBeforeConnectionRestartEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:211

Event emitted before the agent restarts the model connection.

A restart is triggered either reactively, after the model reports a timeout, or proactively, when the reconnect timer fires ahead of the provider’s limit.

Attributes:

• reason - What triggered the restart (“timeout” reactively, “scheduled” proactively).
• timeout_error - The model’s timeout error on the reactive path; None when scheduled.

BidiAfterConnectionRestartEvent

@dataclass
class BidiAfterConnectionRestartEvent(BidiHookEvent)

Defined in: src/strands/experimental/hooks/events.py:227

Event emitted after the agent attempts to restart the model connection.

Attributes:

• reason - What triggered the restart (“timeout” reactively, “scheduled” proactively).
• exception - Populated if an exception was raised during the restart. None means success.