strands.interrupt

Human-in-the-loop interrupt system for agent workflows.

Interrupt

@dataclass
class Interrupt()

Defined in: src/strands/interrupt.py:17

Represents an interrupt that can pause agent execution for human-in-the-loop workflows.

Attributes:

• id - Unique identifier. Treat as opaque: pass it back to resume the agent, do not parse or construct it.
• name - User defined name.
• reason - User provided reason for raising the interrupt.
• response - Human response provided when resuming the agent after an interrupt.

to_dict

def to_dict() -> dict[str, Any]

Defined in: src/strands/interrupt.py:33

Serialize to dict for session management.

InterruptException

class InterruptException(Exception)

Defined in: src/strands/interrupt.py:38

Exception raised when human input is required.

__init__

def __init__(interrupt: Interrupt) -> None

Defined in: src/strands/interrupt.py:41

Set the interrupt.

PendingToolExecution

@dataclass
class PendingToolExecution()

Defined in: src/strands/interrupt.py:47

State required to resume tool execution without calling the model again.

Attributes:

• assistant_message - Assistant message containing the pending tool uses.
• completed_tool_results - Results completed or synthesized during the interrupted execution.

_InterruptState

@dataclass
class _InterruptState()

Defined in: src/strands/interrupt.py:60

Track the state of interrupt events raised by the user.

Note, unanswered interrupts are cleared after resuming; an answered invocation-scoped response is retained for the rest of its interrupt cycle.

Attributes:

• interrupts - Interrupts raised by the user. May be non-empty even when activated is False because retained responses persist until their cycle ends.
• context - Additional context associated with an interrupt event.
• activated - True if agent is in an interrupt state, False otherwise.
• pending_tool_execution - State required to resume an interrupted tool execution.

activate

def activate() -> None

Defined in: src/strands/interrupt.py:80

Activate the interrupt state.

deactivate

def deactivate() -> None

Defined in: src/strands/interrupt.py:85

Deactivate the interrupt state.

Interrupts, context, and pending tool execution are cleared.

end_tool_cycle

def end_tool_cycle() -> None

Defined in: src/strands/interrupt.py:96

Clear a completed tool cycle’s state, keeping answered invocation-scoped responses.

end_interrupt_cycle

def end_interrupt_cycle() -> None

Defined in: src/strands/interrupt.py:108

Release invocation-scoped interrupts once their interrupt cycle is over.

resume

def resume(prompt: "AgentInput") -> None

Defined in: src/strands/interrupt.py:121

Configure the interrupt state if resuming from an interrupt event.

Arguments:

• prompt - User responses if resuming from interrupt.

Raises:

• TypeError - If in interrupt state but user did not provide responses.

set_pending_tool_results

def set_pending_tool_results(
        completed_tool_results: list["ToolResult"]) -> None

Defined in: src/strands/interrupt.py:157

Update completed results for a pending tool execution.

to_dict

def to_dict() -> dict[str, Any]

Defined in: src/strands/interrupt.py:178

Serialize to dict for session management.

Exclude deactivated invocation-scoped responses — persisting them would give a restored agent a standing approval.

from_dict

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "_InterruptState"

Defined in: src/strands/interrupt.py:202

Initialize interrupt state from serialized interrupt state.

Interrupt state can be serialized with the to_dict method. Legacy tool execution context is migrated into the typed pending state.