strands.event_loop.event_loop

This module implements the central event loop.

The event loop allows agents to:

1. Process conversation messages
2. Execute tools based on model requests
3. Handle errors and recovery strategies
4. Manage recursive execution cycles

MAX_DELAY

4 minutes

event_loop_cycle

async def event_loop_cycle(
    agent: "Agent",
    invocation_state: dict[str, Any],
    structured_output_context: StructuredOutputContext | None = None
) -> AsyncGenerator[TypedEvent, None]

Defined in: src/strands/event_loop/event_loop.py:78

Execute a single cycle of the event loop.

This core function processes a single conversation turn, handling model inference, tool execution, and error recovery. It manages the entire lifecycle of a conversation turn, including:

1. Initializing cycle state and metrics
2. Checking execution limits
3. Processing messages with the model
4. Handling tool execution requests
5. Managing recursive calls for multi-turn tool interactions
6. Collecting and reporting metrics
7. Error handling and recovery

Arguments:

• agent - The agent for which the cycle is being executed.

• invocation_state - Additional arguments including:

  • request_state: State maintained across cycles
  • event_loop_cycle_id: Unique ID for this cycle
  • event_loop_cycle_span: Current tracing Span for this cycle

• structured_output_context - Optional context for structured output management.

Yields:

Model and tool stream events. The last event is a tuple containing:

• StopReason: Reason the model stopped generating (e.g., “tool_use”)
• Message: The generated message from the model
• EventLoopMetrics: Updated metrics for the event loop
• Any: Updated request state

Raises:

• EventLoopException - If an error occurs during execution
• ContextWindowOverflowException - If the input is too large for the model

recurse_event_loop

async def recurse_event_loop(
    agent: "Agent",
    invocation_state: dict[str, Any],
    structured_output_context: StructuredOutputContext | None = None
) -> AsyncGenerator[TypedEvent, None]

Defined in: src/strands/event_loop/event_loop.py:236

Make a recursive call to event_loop_cycle with the current state.

This function is used when the event loop needs to continue processing after tool execution.

Arguments:

• agent - Agent for which the recursive call is being made.
• invocation_state - Arguments to pass through event_loop_cycle
• structured_output_context - Optional context for structured output management.

Yields:

Results from event_loop_cycle where the last result contains:

• StopReason: Reason the model stopped generating
• Message: The generated message from the model
• EventLoopMetrics: Updated metrics for the event loop
• Any: Updated request state