Merge branch 'main' of https://github.com/strands-agents/sdk-python into tool-validation

Author: pgrayy

.github/workflows/test-lint.yml

@@ -66,6 +66,11 @@ jobs:
         id: tests
         run: hatch test tests --cover
         continue-on-error: false
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
   lint:
     name: Lint
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -36,6 +36,18 @@ Before starting work on any issue:
 3. Wait for maintainer confirmation before beginning significant work
 
 
+## Development Tenets
+Our team follows these core principles when designing and implementing features. These tenets help us make consistent decisions, resolve trade-offs, and maintain the quality and coherence of the SDK. When contributing, please consider how your changes align with these principles:
+
+1. **Simple at any scale:** We believe that simple things should be simple. The same clean abstractions that power a weekend prototype should scale effortlessly to production workloads. We reject the notion that enterprise-grade means enterprise-complicated - Strands remains approachable whether it's your first agent or your millionth.
+2. **Extensible by design:** We allow for as much configuration as possible, from hooks to model providers, session managers, tools, etc. We meet customers where they are with flexible extension points that are simple to integrate with.
+3. **Composability:** Primitives are building blocks with each other. Each feature of Strands is developed with all other features in mind, they are consistent and complement one another.
+4. **The obvious path is the happy path:** Through intuitive naming, helpful error messages, and thoughtful API design, we guide developers toward correct patterns and away from common pitfalls.
+5. **We are accessible to humans and agents:** Strands is designed for both humans and AI to understand equally well. We don’t take shortcuts on curated DX for humans and we go the extra mile to make sure coding assistants can help you use those interfaces the right way.
+6. **Embrace common standards:** We respect what came before, and do not want to reinvent something that is already widely adopted or done better.
+
+When proposing solutions or reviewing code, we reference these principles to guide our decisions. If two approaches seem equally valid, we choose the one that best aligns with our tenets.
+
 ## Development Environment
 
 This project uses [hatchling](https://hatch.pypa.io/latest/build/#hatchling) as the build backend and [hatch](https://hatch.pypa.io/latest/) for development workflow management.

README.md

@@ -143,7 +143,9 @@ agent("Tell me about Agentic AI")
 
 # Google Gemini
 gemini_model = GeminiModel(
-  api_key="your_gemini_api_key",
+  client_args={
+    "api_key": "your_gemini_api_key",
+  },
   model_id="gemini-2.5-flash",
   params={"temperature": 0.7}
 )

src/strands/_exception_notes.py

@@ -0,0 +1,21 @@
+"""Exception note utilities for Python 3.10+ compatibility."""
+
+# add_note was added in 3.11 - we hoist to a constant to facilitate testing
+supports_add_note = hasattr(Exception, "add_note")
+
+
+def add_exception_note(exception: Exception, note: str) -> None:
+    """Add a note to an exception, compatible with Python 3.10+.
+
+    Uses add_note() if it's available (Python 3.11+) or modifies the exception message if it is not.
+    """
+    if supports_add_note:
+        # we ignore the mypy error because the version-check for add_note is extracted into a constant up above and
+        # mypy doesn't detect that
+        exception.add_note(note)  # type: ignore
+    else:
+        # For Python 3.10, append note to the exception message
+        if hasattr(exception, "args") and exception.args:
+            exception.args = (f"{exception.args[0]}\n{note}",) + exception.args[1:]
+        else:
+            exception.args = (note,)

src/strands/agent/agent.py

@@ -13,6 +13,7 @@
 import json
 import logging
 import random
+import warnings
 from concurrent.futures import ThreadPoolExecutor
 from typing import (
     Any,
@@ -54,13 +55,15 @@
 from ..types.agent import AgentInput
 from ..types.content import ContentBlock, Message, Messages
 from ..types.exceptions import ContextWindowOverflowException
+from ..types.interrupt import InterruptResponseContent
 from ..types.tools import ToolResult, ToolUse
 from ..types.traces import AttributeValue
 from .agent_result import AgentResult
 from .conversation_manager import (
     ConversationManager,
     SlidingWindowConversationManager,
 )
+from .interrupt import InterruptState
 from .state import AgentState
 
 logger = logging.getLogger(__name__)
@@ -142,6 +145,9 @@ def caller(
                 Raises:
                     AttributeError: If the tool doesn't exist.
                 """
+                if self._agent._interrupt_state.activated:
+                    raise RuntimeError("cannot directly call tool during interrupt")
+
                 normalized_name = self._find_normalized_tool_name(name)
 
                 # Create unique tool ID and set up the tool request
@@ -337,6 +343,8 @@ def __init__(
 
         self.hooks = HookRegistry()
 
+        self._interrupt_state = InterruptState()
+
         # Initialize session management functionality
         self._session_manager = session_manager
         if self._session_manager:
@@ -374,7 +382,9 @@ def tool_names(self) -> list[str]:
         all_tools = self.tool_registry.get_all_tools_config()
         return list(all_tools.keys())
 
-    def __call__(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
+    def __call__(
+        self, prompt: AgentInput = None, *, invocation_state: dict[str, Any] | None = None, **kwargs: Any
+    ) -> AgentResult:
         """Process a natural language prompt through the agent's event loop.
 
         This method implements the conversational interface with multiple input patterns:
@@ -389,7 +399,8 @@ def __call__(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
                 - list[ContentBlock]: Multi-modal content blocks
                 - list[Message]: Complete messages with roles
                 - None: Use existing conversation history
-            **kwargs: Additional parameters to pass through the event loop.
+            invocation_state: Additional parameters to pass through the event loop.
+            **kwargs: Additional parameters to pass through the event loop.[Deprecating]
 
         Returns:
             Result object containing:
@@ -401,13 +412,15 @@ def __call__(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
         """
 
         def execute() -> AgentResult:
-            return asyncio.run(self.invoke_async(prompt, **kwargs))
+            return asyncio.run(self.invoke_async(prompt, invocation_state=invocation_state, **kwargs))
 
         with ThreadPoolExecutor() as executor:
             future = executor.submit(execute)
             return future.result()
 
-    async def invoke_async(self, prompt: AgentInput = None, **kwargs: Any) -> AgentResult:
+    async def invoke_async(
+        self, prompt: AgentInput = None, *, invocation_state: dict[str, Any] | None = None, **kwargs: Any
+    ) -> AgentResult:
         """Process a natural language prompt through the agent's event loop.
 
         This method implements the conversational interface with multiple input patterns:
@@ -422,7 +435,8 @@ async def invoke_async(self, prompt: AgentInput = None, **kwargs: Any) -> AgentR
                 - list[ContentBlock]: Multi-modal content blocks
                 - list[Message]: Complete messages with roles
                 - None: Use existing conversation history
-            **kwargs: Additional parameters to pass through the event loop.
+            invocation_state: Additional parameters to pass through the event loop.
+            **kwargs: Additional parameters to pass through the event loop.[Deprecating]
 
         Returns:
             Result: object containing:
@@ -432,7 +446,7 @@ async def invoke_async(self, prompt: AgentInput = None, **kwargs: Any) -> AgentR
                 - metrics: Performance metrics from the event loop
                 - state: The final state of the event loop
         """
-        events = self.stream_async(prompt, **kwargs)
+        events = self.stream_async(prompt, invocation_state=invocation_state, **kwargs)
         async for event in events:
             _ = event
 
@@ -484,6 +498,9 @@ async def structured_output_async(self, output_model: Type[T], prompt: AgentInpu
         Raises:
             ValueError: If no conversation history or prompt is provided.
         """
+        if self._interrupt_state.activated:
+            raise RuntimeError("cannot call structured output during interrupt")
+
         self.hooks.invoke_callbacks(BeforeInvocationEvent(agent=self))
         with self.tracer.tracer.start_as_current_span(
             "execute_structured_output", kind=trace_api.SpanKind.CLIENT
@@ -528,9 +545,7 @@ async def structured_output_async(self, output_model: Type[T], prompt: AgentInpu
                 self.hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
 
     async def stream_async(
-        self,
-        prompt: AgentInput = None,
-        **kwargs: Any,
+        self, prompt: AgentInput = None, *, invocation_state: dict[str, Any] | None = None, **kwargs: Any
     ) -> AsyncIterator[Any]:
         """Process a natural language prompt and yield events as an async iterator.
 
@@ -546,7 +561,8 @@ async def stream_async(
                 - list[ContentBlock]: Multi-modal content blocks
                 - list[Message]: Complete messages with roles
                 - None: Use existing conversation history
-            **kwargs: Additional parameters to pass to the event loop.
+            invocation_state: Additional parameters to pass through the event loop.
+            **kwargs: Additional parameters to pass to the event loop.[Deprecating]
 
         Yields:
             An async iterator that yields events. Each event is a dictionary containing
@@ -567,7 +583,21 @@ async def stream_async(
                     yield event["data"]
             ```
         """
-        callback_handler = kwargs.get("callback_handler", self.callback_handler)
+        self._resume_interrupt(prompt)
+
+        merged_state = {}
+        if kwargs:
+            warnings.warn("`**kwargs` parameter is deprecating, use `invocation_state` instead.", stacklevel=2)
+            merged_state.update(kwargs)
+            if invocation_state is not None:
+                merged_state["invocation_state"] = invocation_state
+        else:
+            if invocation_state is not None:
+                merged_state = invocation_state
+
+        callback_handler = self.callback_handler
+        if kwargs:
+            callback_handler = kwargs.get("callback_handler", self.callback_handler)
 
         # Process input and get message to add (if any)
         messages = self._convert_prompt_to_messages(prompt)
@@ -576,10 +606,10 @@ async def stream_async(
 
         with trace_api.use_span(self.trace_span):
             try:
-                events = self._run_loop(messages, invocation_state=kwargs)
+                events = self._run_loop(messages, invocation_state=merged_state)
 
                 async for event in events:
-                    event.prepare(invocation_state=kwargs)
+                    event.prepare(invocation_state=merged_state)
 
                     if event.is_callback_event:
                         as_dict = event.as_dict()
@@ -596,6 +626,38 @@ async def stream_async(
                 self._end_agent_trace_span(error=e)
                 raise
 
+    def _resume_interrupt(self, prompt: AgentInput) -> None:
+        """Configure the interrupt state if resuming from an interrupt event.
+
+        Args:
+            prompt: User responses if resuming from interrupt.
+
+        Raises:
+            TypeError: If in interrupt state but user did not provide responses.
+        """
+        if not self._interrupt_state.activated:
+            return
+
+        if not isinstance(prompt, list):
+            raise TypeError(f"prompt_type={type(prompt)} | must resume from interrupt with list of interruptResponse's")
+
+        invalid_types = [
+            content_type for content in prompt for content_type in content if content_type != "interruptResponse"
+        ]
+        if invalid_types:
+            raise TypeError(
+                f"content_types=<{invalid_types}> | must resume from interrupt with list of interruptResponse's"
+            )
+
+        for content in cast(list[InterruptResponseContent], prompt):
+            interrupt_id = content["interruptResponse"]["interruptId"]
+            interrupt_response = content["interruptResponse"]["response"]
+
+            if interrupt_id not in self._interrupt_state.interrupts:
+                raise KeyError(f"interrupt_id=<{interrupt_id}> | no interrupt found")
+
+            self._interrupt_state.interrupts[interrupt_id].response = interrupt_response
+
     async def _run_loop(self, messages: Messages, invocation_state: dict[str, Any]) -> AsyncGenerator[TypedEvent, None]:
         """Execute the agent's event loop with the given message and parameters.
 
@@ -671,6 +733,9 @@ async def _execute_event_loop_cycle(self, invocation_state: dict[str, Any]) -> A
                 yield event
 
     def _convert_prompt_to_messages(self, prompt: AgentInput) -> Messages:
+        if self._interrupt_state.activated:
+            return []
+
         messages: Messages | None = None
         if prompt is not None:
             if isinstance(prompt, str):

src/strands/agent/agent_result.py

@@ -4,8 +4,9 @@
 """
 
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Sequence
 
+from ..interrupt import Interrupt
 from ..telemetry.metrics import EventLoopMetrics
 from ..types.content import Message
 from ..types.streaming import StopReason
@@ -20,12 +21,14 @@ class AgentResult:
         message: The last message generated by the agent.
         metrics: Performance metrics collected during processing.
         state: Additional state information from the event loop.
+        interrupts: List of interrupts if raised by user.
     """
 
     stop_reason: StopReason
     message: Message
     metrics: EventLoopMetrics
     state: Any
+    interrupts: Sequence[Interrupt] | None = None
 
     def __str__(self) -> str:
         """Get the agent's last message as a string.

src/strands/agent/conversation_manager/summarizing_conversation_manager.py

@@ -5,6 +5,8 @@
 
 from typing_extensions import override
 
+from ...tools import tool
+from ...tools.registry import ToolRegistry
 from ...types.content import Message
 from ...types.exceptions import ContextWindowOverflowException
 from .conversation_manager import ConversationManager
@@ -23,6 +25,10 @@
 - You MUST create a structured and concise summary in bullet-point format.
 - You MUST NOT respond conversationally.
 - You MUST NOT address the user directly.
+- You MUST NOT comment on tool availability.
+
+Assumptions:
+- You MUST NOT assume tool executions failed unless otherwise stated.
 
 Task:
 Your task is to create a structured summary document:
@@ -182,9 +188,10 @@ def _generate_summary(self, messages: List[Message], agent: "Agent") -> Message:
         # Choose which agent to use for summarization
         summarization_agent = self.summarization_agent if self.summarization_agent is not None else agent
 
-        # Save original system prompt and messages to restore later
+        # Save original system prompt, messages, and tool registry to restore later
         original_system_prompt = summarization_agent.system_prompt
         original_messages = summarization_agent.messages.copy()
+        original_tool_registry = summarization_agent.tool_registry
 
         try:
             # Only override system prompt if no agent was provided during initialization
@@ -197,6 +204,13 @@ def _generate_summary(self, messages: List[Message], agent: "Agent") -> Message:
                 )
                 # Temporarily set the system prompt for summarization
                 summarization_agent.system_prompt = system_prompt
+
+            # Add no-op tool if agent has no tools to satisfy tool spec requirement
+            if not summarization_agent.tool_names:
+                tool_registry = ToolRegistry()
+                tool_registry.register_tool(self._noop_tool)
+                summarization_agent.tool_registry = tool_registry
+
             summarization_agent.messages = messages
 
             # Use the agent to generate summary with rich content (can use tools if needed)
@@ -207,6 +221,7 @@ def _generate_summary(self, messages: List[Message], agent: "Agent") -> Message:
             # Restore original agent state
             summarization_agent.system_prompt = original_system_prompt
             summarization_agent.messages = original_messages
+            summarization_agent.tool_registry = original_tool_registry
 
     def _adjust_split_point_for_tool_pairs(self, messages: List[Message], split_point: int) -> int:
         """Adjust the split point to avoid breaking ToolUse/ToolResult pairs.
@@ -249,3 +264,13 @@ def _adjust_split_point_for_tool_pairs(self, messages: List[Message], split_poin
             raise ContextWindowOverflowException("Unable to trim conversation context!")
 
         return split_point
+
+    @tool(name="noop", description="MUST NOT call or summarize")
+    def _noop_tool(self) -> None:
+        """No-op tool to satisfy tool spec requirement when tool messages are present.
+
+        Some model provides (e.g., Bedrock) will return an error response if tool uses and tool results are present in
+        messages without any tool specs configured. Consequently, if the summarization agent has no registered tools,
+        summarization will fail. As a workaround, we register the no-op tool.
+        """
+        pass