Interrupts - Proposal to improve the user experience on Agent-as-tool / sub-agents

[thiagopo]

Hi everyone!

I would like to propose an improvement to interrupt handling mechanism that enables Agent-as-tool to properly support interrupts raised inside sub-agent hooks.

Problem statement

Currently, when using a sub-agent as a tool (Agent-as-tool pattern), interrupts raised inside hooks (e.g., BeforeToolCallEvent) are not naturally propagated through the execution chain.

A few days ago, I tried to use interrupts inside a hook triggered by a tool that belongs to a sub-agent. This sub-agent itself was registered as a tool in an orchestrator agent.

Although I managed to make it work, the solution required manually storing additional state, which makes the implementation more complex and less intuitive.

I reproduced this workaround here: https://github.com/thiagopo/strands-agents-interrupt-on-agent-as-tool

Proposed Improvement

I believe the framework could provide native support for cascaded interrupts, allowing interrupts raised at sub-agent levels (e.g., inside sub-agent hooks) to propagate correctly to upper levels (e.g., orchestrator).

Desired Flow

The ideal behavior would look like this:

1. Orchestrator → calls sub-agent (as a tool)
2. Sub-agent → calls another tool
3. A hook (BeforeToolCall) raises an Interrupt → sub-agent receives it (Interrupt ID: #1)
4. Sub-agent raises a new Interrupt to the orchestrator (via tool_context) → (Interrupt ID: #2)
5. Orchestrator receives the interrupt and prompts the user
6. User provides input
7. Main routine resumes execution using InterruptResponse (ID: #2)
8. Orchestrator resumes and calls the sub-agent again
9. Sub-agent retrieves cascaded interrupt context and resumes Interrupt #1
10. The tool execution continues normally

Key Objectives

• Backward compatibility: The solution must not impact existing interrupt flows (e.g., Swarm, Graph, and current resume behavior)
• Reuse existing mechanisms: Avoid introducing parallel interrupt systems
• Developer experience: The solution should be simple and intuitive to use from the user perspective

Proposed API Extensions

Below is an example of how this could be exposed for developers:

class ApprovalHook(HookProvider):

    def register_hooks(self, registry, **kwargs):
        registry.add_callback(BeforeToolCallEvent, self.my_hook)
		
	def my_hook(self, event: BeforeToolCallEvent):
		
		approval = event.interrupt("name_of_my_interrupt", reason="some details...." )
        if approval.lower() not in ["approved", "yes", "ok"]:
            event.cancel_tool = "User canceled the tool execution"


@tool(context=True)
def run_sub_agent(query: str, tool_context: ToolContext) -> str:
    
	sub_agent = agent(...)  # hooks=[ApprovalHook()]

    # Check if resuming from a cascaded interrupt
    responses = tool_context.get_cascaded_interrupt_responses()   <<<<< my proposition
    if responses:
        result = sub_agent(responses)
    else:
        result = sub_agent(query)

    if result.stop_reason == "interrupt":
        # Cascade sub-agent interrupts to orchestrator
        tool_context.cascade_interrupts(result.interrupts)        <<<<<< my proposition (rise a new exception type: CascadedInterruptException)

    return str(result)

Proposed Additions (resume)

• tool_context.cascade_interrupts(...): agent._interrupt_state.context will be used to store information about cascaded interrupts
• tool_context.get_cascaded_interrupt_responses(): will read from agent._interrupt_state.context and return a list of InterruptResponseContent
• A new internal exception type, e.g. CascadedInterruptException

Current Status

I have implemented a working prototype of this approach in a fork of sdk-python, using the Teacher Assistant example as a baseline to test.

The results so far are promising and demonstrate that this approach can work without breaking existing behavior.

I’m preparing to open a PR with the implementation and would really appreciate feedback on this design before moving forward.

[zastrowm]

@notowen333 this seems directly related to #1932; and something we should consider as part of the agent as tool feature

[thiagopo]

PR opened: #1965