interrupts - decorated tools (strands-agents#1041)

Author: pgrayy

src/strands/hooks/events.py

@@ -10,7 +10,7 @@
 from typing_extensions import override
 
 from ..types.content import Message
-from ..types.interrupt import InterruptHookEvent
+from ..types.interrupt import _Interruptible
 from ..types.streaming import StopReason
 from ..types.tools import AgentTool, ToolResult, ToolUse
 from .registry import HookEvent
@@ -88,7 +88,7 @@ class MessageAddedEvent(HookEvent):
 
 
 @dataclass
-class BeforeToolCallEvent(HookEvent, InterruptHookEvent):
+class BeforeToolCallEvent(HookEvent, _Interruptible):
     """Event triggered before a tool is invoked.
 
     This event is fired just before the agent executes a tool, allowing hook
@@ -124,7 +124,7 @@ def _interrupt_id(self, name: str) -> str:
         Returns:
             Interrupt id.
         """
-        return f"v1:{self.tool_use['toolUseId']}:{uuid.uuid5(uuid.NAMESPACE_OID, name)}"
+        return f"v1:before_tool_call:{self.tool_use['toolUseId']}:{uuid.uuid5(uuid.NAMESPACE_OID, name)}"
 
 
 @dataclass

src/strands/tools/decorator.py

@@ -62,7 +62,8 @@ def my_tool(param1: str, param2: int = 42) -> dict:
 from pydantic import BaseModel, Field, create_model
 from typing_extensions import override
 
-from ..types._events import ToolResultEvent, ToolStreamEvent
+from ..interrupt import InterruptException
+from ..types._events import ToolInterruptEvent, ToolResultEvent, ToolStreamEvent
 from ..types.tools import AgentTool, JSONSchema, ToolContext, ToolGenerator, ToolResult, ToolSpec, ToolUse
 
 logger = logging.getLogger(__name__)
@@ -493,6 +494,10 @@ async def stream(self, tool_use: ToolUse, invocation_state: dict[str, Any], **kw
                 result = await asyncio.to_thread(self._tool_func, **validated_input)  # type: ignore
                 yield self._wrap_tool_result(tool_use_id, result)
 
+        except InterruptException as e:
+            yield ToolInterruptEvent(tool_use, [e.interrupt])
+            return
+
         except ValueError as e:
             # Special handling for validation errors
             error_msg = str(e)

src/strands/tools/executors/_executor.py

@@ -163,11 +163,16 @@ async def _stream(
                 # we yield it directly; all other cases (non-sdk AgentTools), we wrap events in
                 # ToolStreamEvent and the last event is just the result.
 
+                if isinstance(event, ToolInterruptEvent):
+                    yield event
+                    return
+
                 if isinstance(event, ToolResultEvent):
                     # below the last "event" must point to the tool_result
                     event = event.tool_result
                     break
-                elif isinstance(event, ToolStreamEvent):
+
+                if isinstance(event, ToolStreamEvent):
                     yield event
                 else:
                     yield ToolStreamEvent(tool_use, event)

src/strands/types/interrupt.py

@@ -118,8 +118,8 @@ def approve(self, event: BeforeToolCallEvent) -> None:
     from ..agent import Agent
 
 
-class InterruptHookEvent(Protocol):
-    """Interface that adds interrupt support to hook events."""
+class _Interruptible(Protocol):
+    """Interface that adds interrupt support to hook events and tools."""
 
     agent: "Agent"
 

src/strands/types/tools.py

@@ -5,12 +5,14 @@
 - Bedrock docs: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Types_Amazon_Bedrock_Runtime.html
 """
 
+import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Awaitable, Callable, Literal, Protocol, Union
 
 from typing_extensions import NotRequired, TypedDict
 
+from .interrupt import _Interruptible
 from .media import DocumentContent, ImageContent
 
 if TYPE_CHECKING:
@@ -126,7 +128,7 @@ class ToolChoiceTool(TypedDict):
 
 
 @dataclass
-class ToolContext:
+class ToolContext(_Interruptible):
     """Context object containing framework-provided data for decorated tools.
 
     This object provides access to framework-level information that may be useful
@@ -148,6 +150,17 @@ class ToolContext:
     agent: "Agent"
     invocation_state: dict[str, Any]
 
+    def _interrupt_id(self, name: str) -> str:
+        """Unique id for the interrupt.
+
+        Args:
+            name: User defined name for the interrupt.
+
+        Returns:
+            Interrupt id.
+        """
+        return f"v1:tool_call:{self.tool_use['toolUseId']}:{uuid.uuid5(uuid.NAMESPACE_OID, name)}"
+
 
 # Individual ToolChoice type aliases
 ToolChoiceAutoDict = dict[Literal["auto"], ToolChoiceAuto]

tests/strands/agent/test_agent.py

@@ -1957,7 +1957,7 @@ def test_agent__call__resume_interrupt(mock_model, tool_decorated, agenerator):
     )
 
     interrupt = Interrupt(
-        id="v1:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
+        id="v1:before_tool_call:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
         name="test_name",
         reason="test reason",
     )

tests/strands/event_loop/test_event_loop.py

@@ -884,7 +884,7 @@ def interrupt_callback(event):
     exp_stop_reason = "interrupt"
     exp_interrupts = [
         Interrupt(
-            id="v1:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
+            id="v1:before_tool_call:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
             name="test_name",
             reason="test reason",
         ),
@@ -911,8 +911,8 @@ def interrupt_callback(event):
             },
         },
         "interrupts": {
-            "v1:t1:78714d6c-613c-5cf4-bf25-7037569941f9": {
-                "id": "v1:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
+            "v1:before_tool_call:t1:78714d6c-613c-5cf4-bf25-7037569941f9": {
+                "id": "v1:before_tool_call:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
                 "name": "test_name",
                 "reason": "test reason",
                 "response": None,
@@ -925,7 +925,7 @@ def interrupt_callback(event):
 @pytest.mark.asyncio
 async def test_event_loop_cycle_interrupt_resume(agent, model, tool, tool_times_2, agenerator, alist):
     interrupt = Interrupt(
-        id="v1:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
+        id="v1:before_tool_call:t1:78714d6c-613c-5cf4-bf25-7037569941f9",
         name="test_name",
         reason="test reason",
         response="test response",

tests/strands/hooks/test_registry.py

@@ -38,12 +38,12 @@ def test_hook_registry_invoke_callbacks_interrupt(registry, agent):
     _, tru_interrupts = registry.invoke_callbacks(event)
     exp_interrupts = [
         Interrupt(
-            id="v1:test_tool_id:da3551f3-154b-5978-827e-50ac387877ee",
+            id="v1:before_tool_call:test_tool_id:da3551f3-154b-5978-827e-50ac387877ee",
             name="test_name_1",
             reason="test reason 1",
         ),
         Interrupt(
-            id="v1:test_tool_id:0f5a8068-d1ba-5a48-bf67-c9d33786d8d4",
+            id="v1:before_tool_call:test_tool_id:0f5a8068-d1ba-5a48-bf67-c9d33786d8d4",
             name="test_name_2",
             reason="test reason 2",
         ),

tests/strands/tools/executors/conftest.py

@@ -7,6 +7,7 @@
 from strands.agent.interrupt import InterruptState
 from strands.hooks import AfterToolCallEvent, BeforeToolCallEvent, HookRegistry
 from strands.tools.registry import ToolRegistry
+from strands.types.tools import ToolContext
 
 
 @pytest.fixture
@@ -79,12 +80,22 @@ def func():
 
 
 @pytest.fixture
-def tool_registry(weather_tool, temperature_tool, exception_tool, thread_tool):
+def interrupt_tool():
+    @strands.tool(name="interrupt_tool", context=True)
+    def func(tool_context: ToolContext) -> str:
+        return tool_context.interrupt("test_name", reason="test reason")
+
+    return func
+
+
+@pytest.fixture
+def tool_registry(weather_tool, temperature_tool, exception_tool, thread_tool, interrupt_tool):
     registry = ToolRegistry()
     registry.register_tool(weather_tool)
     registry.register_tool(temperature_tool)
     registry.register_tool(exception_tool)
     registry.register_tool(thread_tool)
+    registry.register_tool(interrupt_tool)
     return registry
 
 
@@ -113,5 +124,5 @@ def cycle_span():
 
 
 @pytest.fixture
-def invocation_state():
-    return {}
+def invocation_state(agent):
+    return {"agent": agent}

tests/strands/tools/executors/test_concurrent.py

@@ -38,7 +38,7 @@ async def test_concurrent_executor_interrupt(
     executor, agent, tool_results, cycle_trace, cycle_span, invocation_state, alist
 ):
     interrupt = Interrupt(
-        id="v1:test_tool_id_1:78714d6c-613c-5cf4-bf25-7037569941f9",
+        id="v1:before_tool_call:test_tool_id_1:78714d6c-613c-5cf4-bf25-7037569941f9",
         name="test_name",
         reason="test reason",
     )