feat: mark _AgentAsTool as private; take Agent instead of AgentBase in the constructor

Author: Owen Kaplan

src/strands/__init__.py

@@ -1,7 +1,7 @@
 """A framework for building, deploying, and managing AI agents."""
 
 from . import agent, models, telemetry, types
-from .agent._agent_as_tool import AgentAsTool
+from .agent._agent_as_tool import _AgentAsTool
 from .agent.agent import Agent
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
@@ -12,7 +12,7 @@
 
 __all__ = [
     "Agent",
-    "AgentAsTool",
+    "_AgentAsTool",
     "AgentBase",
     "AgentSkills",
     "agent",

src/strands/agent/__init__.py

@@ -10,7 +10,7 @@
 from typing import Any
 
 from ..event_loop._retry import ModelRetryStrategy
-from ._agent_as_tool import AgentAsTool
+from ._agent_as_tool import _AgentAsTool
 from .agent import Agent
 from .agent_result import AgentResult
 from .base import AgentBase
@@ -25,7 +25,7 @@
     "Agent",
     "AgentBase",
     "AgentResult",
-    "AgentAsTool",
+    "_AgentAsTool",
     "ConversationManager",
     "NullConversationManager",
     "SlidingWindowConversationManager",

src/strands/agent/_agent_as_tool.py

@@ -1,13 +1,15 @@
 """Agent-as-tool adapter.
 
-This module provides the AgentAsTool class that wraps an Agent (or any AgentBase) as a tool
+This module provides the _AgentAsTool class that wraps an Agent as a tool
 so it can be passed to another agent's tool list.
 """
 
+from __future__ import annotations
+
 import copy
 import logging
 import threading
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from typing_extensions import override
 
@@ -16,12 +18,14 @@
 from ..types.content import Messages
 from ..types.interrupt import InterruptResponseContent
 from ..types.tools import AgentTool, ToolGenerator, ToolSpec, ToolUse
-from .base import AgentBase
+
+if TYPE_CHECKING:
+    from .agent import Agent
 
 logger = logging.getLogger(__name__)
 
 
-class AgentAsTool(AgentTool):
+class _AgentAsTool(AgentTool):
     """Adapter that exposes an Agent as a tool for use by other agents.
 
     The tool accepts a single ``input`` string parameter, invokes the wrapped
@@ -30,18 +34,14 @@ class AgentAsTool(AgentTool):
     Example:
         ```python
         from strands import Agent
-        from strands.agent import AgentAsTool
 
         researcher = Agent(name="researcher", description="Finds information")
 
-        # Use directly
-        tool = AgentAsTool(researcher, name="researcher", description="Finds information")
-
-        # Or via convenience method
+        # Use via convenience method (default: fresh conversation each call)
         tool = researcher.as_tool()
 
-        # Start each invocation with a fresh conversation
-        tool = researcher.as_tool(preserve_context=False)
+        # Preserve context across invocations
+        tool = researcher.as_tool(preserve_context=True)
 
         writer = Agent(name="writer", tools=[tool])
         writer("Write about AI agents")
@@ -50,36 +50,35 @@ class AgentAsTool(AgentTool):
 
     def __init__(
         self,
-        agent: AgentBase,
+        agent: Agent,
         *,
         name: str,
-        description: str,
+        description: str | None = None,
         preserve_context: bool = False,
     ) -> None:
         r"""Initialize the agent-as-tool adapter.
 
         Args:
             agent: The agent to wrap as a tool.
             name: Tool name. Must match the pattern ``[a-zA-Z0-9_\\-]{1,64}``.
-            description: Tool description.
+            description: Tool description. Defaults to the agent's description, or a
+                generic description if the agent has no description set.
             preserve_context: Whether to preserve the agent's conversation history across
                 invocations. When False, the agent's messages and state are reset to the
                 values they had at construction time before each call, ensuring every
                 invocation starts from the same baseline regardless of any external
-                interactions with the agent. Defaults to False. Only effective when the
-                wrapped agent exposes a mutable ``messages`` list and/or an ``AgentState``
-                (e.g. ``strands.agent.Agent``).
+                interactions with the agent. Defaults to False.
         """
         super().__init__()
         self._agent = agent
         self._tool_name = name
-        self._description = description
+        self._description = (
+            description or agent.description or f"Use the {name} agent as a tool by providing a natural language input"
+        )
         self._preserve_context = preserve_context
 
         # When preserve_context=False, we snapshot the agent's initial state so we can
         # restore it before each invocation. This mirrors GraphNode.reset_executor_state().
-        # We require an Agent instance for this since AgentBase doesn't guarantee
-        # messages/state attributes.
         self._initial_messages: Messages = []
         self._initial_state: AgentState = AgentState()
         # Serialize access so _reset_agent_state + stream_async are atomic.
@@ -88,15 +87,17 @@ def __init__(
         self._lock = threading.Lock()
 
         if not preserve_context:
-            from .agent import Agent
-
-            if not isinstance(agent, Agent):
-                raise TypeError(f"preserve_context=False requires an Agent instance, got {type(agent).__name__}")
+            if getattr(agent, "_session_manager", None) is not None:
+                raise ValueError(
+                    "preserve_context=False cannot be used with an agent that has a session manager. "
+                    "The session manager persists conversation history externally, which conflicts with "
+                    "resetting the agent's state between invocations."
+                )
             self._initial_messages = copy.deepcopy(agent.messages)
             self._initial_state = AgentState(agent.state.get())
 
     @property
-    def agent(self) -> AgentBase:
+    def agent(self) -> Agent:
         """The wrapped agent instance."""
         return self._agent
 
@@ -259,12 +260,6 @@ def _reset_agent_state(self, tool_use_id: str) -> None:
         Args:
             tool_use_id: Tool use ID for logging context.
         """
-        from .agent import Agent
-
-        # isinstance narrows the type for mypy; __init__ guarantees this when preserve_context=False
-        if not isinstance(self._agent, Agent):
-            return
-
         logger.debug(
             "tool_name=<%s>, tool_use_id=<%s> | resetting agent to initial state",
             self._tool_name,
@@ -275,8 +270,7 @@ def _reset_agent_state(self, tool_use_id: str) -> None:
 
     def _is_sub_agent_interrupted(self) -> bool:
         """Check whether the wrapped agent is in an activated interrupt state."""
-        interrupt_state = getattr(self._agent, "_interrupt_state", None)
-        return interrupt_state is not None and interrupt_state.activated
+        return self._agent._interrupt_state.activated
 
     def _build_interrupt_responses(self) -> list[InterruptResponseContent]:
         """Build interrupt response payloads from the sub-agent's interrupt state.
@@ -288,13 +282,9 @@ def _build_interrupt_responses(self) -> list[InterruptResponseContent]:
         Returns:
             List of interrupt response content blocks for resuming the sub-agent.
         """
-        interrupt_state = getattr(self._agent, "_interrupt_state", None)
-        if interrupt_state is None:
-            return []
-
         return [
             {"interruptResponse": {"interruptId": interrupt.id, "response": interrupt.response}}
-            for interrupt in interrupt_state.interrupts.values()
+            for interrupt in self._agent._interrupt_state.interrupts.values()
             if interrupt.response is not None
         ]
 

src/strands/agent/agent.py

@@ -62,7 +62,7 @@
 from ..types.content import ContentBlock, Message, Messages, SystemContentBlock
 from ..types.exceptions import ConcurrencyException, ContextWindowOverflowException
 from ..types.traces import AttributeValue
-from ._agent_as_tool import AgentAsTool
+from ._agent_as_tool import _AgentAsTool
 from .agent_result import AgentResult
 from .base import AgentBase
 from .conversation_manager import (
@@ -618,21 +618,22 @@ def as_tool(
         name: str | None = None,
         description: str | None = None,
         preserve_context: bool = False,
-    ) -> AgentAsTool:
+    ) -> _AgentAsTool:
         r"""Convert this agent into a tool for use by another agent.
 
         Args:
             name: Tool name. Must match the pattern ``[a-zA-Z0-9_\\-]{1,64}``.
                 Defaults to the agent's name.
-            description: Tool description. Defaults to the agent's description.
+            description: Tool description. Defaults to the agent's description, or a
+                generic description if the agent has no description set.
             preserve_context: Whether to preserve the agent's conversation history across
                 invocations. When False, the agent's messages and state are reset to the
                 values they had at construction time before each call, ensuring every
                 invocation starts from the same baseline regardless of any external
                 interactions with the agent. Defaults to False.
 
         Returns:
-            An AgentAsTool wrapping this agent.
+            An _AgentAsTool wrapping this agent.
 
         Example:
             ```python
@@ -643,9 +644,7 @@ def as_tool(
         """
         if not name:
             name = self.name
-        if not description:
-            description = self.description or f"Use the {name} agent as a tool by providing a natural language input"
-        return AgentAsTool(self, name=name, description=description, preserve_context=preserve_context)
+        return _AgentAsTool(self, name=name, description=description, preserve_context=preserve_context)
 
     def cleanup(self) -> None:
         """Clean up resources used by the agent.

src/strands/tools/executors/_executor.py

@@ -228,7 +228,7 @@ async def _stream(
                     if isinstance(event, ToolInterruptEvent):
                         # Register any interrupts not already in the agent's state.
                         # For normal hooks this is a no-op (already registered by _Interruptible.interrupt()).
-                        # For sub-agent interrupts propagated via AgentAsTool, this is where they get
+                        # For sub-agent interrupts propagated via _AgentAsTool, this is where they get
                         # registered so that _interrupt_state.resume() can locate them by ID.
                         for interrupt in event.interrupts:
                             agent._interrupt_state.interrupts.setdefault(interrupt.id, interrupt)

src/strands/types/_events.py

@@ -21,7 +21,7 @@
 
 if TYPE_CHECKING:
     from ..agent import AgentResult
-    from ..agent._agent_as_tool import AgentAsTool
+    from ..agent._agent_as_tool import _AgentAsTool
     from ..multiagent.base import MultiAgentResult, NodeResult
 
 
@@ -327,25 +327,25 @@ def tool_use_id(self) -> str:
 class AgentAsToolStreamEvent(ToolStreamEvent):
     """Event emitted when an agent-as-tool yields intermediate events during execution.
 
-    Extends ToolStreamEvent with a reference to the originating AgentAsTool so callers
+    Extends ToolStreamEvent with a reference to the originating _AgentAsTool so callers
     can distinguish sub-agent stream events from regular tool stream events and access
     the wrapped agent, tool name, description, etc.
     """
 
-    def __init__(self, tool_use: ToolUse, tool_stream_data: Any, agent_as_tool: "AgentAsTool") -> None:
+    def __init__(self, tool_use: ToolUse, tool_stream_data: Any, agent_as_tool: "_AgentAsTool") -> None:
         """Initialize with tool streaming data and agent-tool reference.
 
         Args:
             tool_use: The tool invocation producing the stream.
             tool_stream_data: The yielded event from the sub-agent execution.
-            agent_as_tool: The AgentAsTool instance that produced this event.
+            agent_as_tool: The _AgentAsTool instance that produced this event.
         """
         super().__init__(tool_use, tool_stream_data)
         self._agent_as_tool = agent_as_tool
 
     @property
-    def agent_as_tool(self) -> "AgentAsTool":
-        """The AgentAsTool instance that produced this event."""
+    def agent_as_tool(self) -> "_AgentAsTool":
+        """The _AgentAsTool instance that produced this event."""
         return self._agent_as_tool
 
 

tests/strands/agent/test_agent.py

@@ -15,7 +15,7 @@
 
 import strands
 from strands import Agent, Plugin, ToolContext
-from strands.agent import AgentAsTool, AgentResult
+from strands.agent import AgentResult, _AgentAsTool
 from strands.agent.conversation_manager.null_conversation_manager import NullConversationManager
 from strands.agent.conversation_manager.sliding_window_conversation_manager import SlidingWindowConversationManager
 from strands.agent.state import AgentState
@@ -2702,11 +2702,11 @@ def hook_callback(event: BeforeModelCallEvent):
 
 
 def test_as_tool_returns_agent_tool():
-    """Test that as_tool returns an AgentAsTool wrapping the agent."""
+    """Test that as_tool returns an _AgentAsTool wrapping the agent."""
     agent = Agent(name="researcher", description="Finds information")
     tool = agent.as_tool()
 
-    assert isinstance(tool, AgentAsTool)
+    assert isinstance(tool, _AgentAsTool)
     assert tool.agent is agent