feat: auto-wrap Agent instances passed in tools list (#1997)

Co-authored-by: agent-of-mkmeral <217235299+strands-agent@users.noreply.github.com>
Co-authored-by: agent-of-mkmeral <agent-of-mkmeral@users.noreply.github.com>

Author: agent-of-mkmeral

src/strands/agent/agent.py

@@ -153,7 +153,8 @@ def __init__(
                 - Imported Python modules (e.g., from strands_tools import current_time)
                 - Dictionaries with name/path keys (e.g., {"name": "tool_name", "path": "/path/to/tool.py"})
                 - ToolProvider instances for managed tool collections
-                - Functions decorated with `@strands.tool` decorator.
+                - Functions decorated with `@strands.tool` decorator
+                - Agent instances (auto-wrapped via `agent.as_tool()` with defaults)
 
                 If provided, only these tools will be available. If None, all tools will be available.
             system_prompt: System prompt to guide model behavior.

src/strands/tools/registry.py

@@ -19,6 +19,7 @@
 from typing_extensions import TypedDict
 
 from .._async import run_async
+from ..agent.base import AgentBase
 from ..tools.decorator import DecoratedFunctionTool
 from ..types.tools import AgentTool, ToolSpec
 from . import ToolProvider
@@ -62,6 +63,7 @@ def process_tools(self, tools: list[Any]) -> list[str]:
                 3. A module for a module based tool
                 4. Instances of AgentTool (@tool decorated functions)
                 5. Dictionaries with name/path keys (deprecated)
+                6. Agent instances with an ``as_tool()`` method (auto-wrapped)
 
 
         Returns:
@@ -140,6 +142,12 @@ async def get_tools() -> Sequence[AgentTool]:
                     for provider_tool in provider_tools:
                         self.register_tool(provider_tool)
                         tool_names.append(provider_tool.tool_name)
+                # Agent instances - auto-wrap with .as_tool() for convenience
+                elif isinstance(tool, AgentBase) and hasattr(tool, "as_tool") and callable(tool.as_tool):
+                    wrapped_tool = tool.as_tool()
+                    self.register_tool(wrapped_tool)
+                    tool_names.append(wrapped_tool.tool_name)
+
                 else:
                     logger.warning("tool=<%s> | unrecognized tool specification", tool)
 

tests/strands/agent/test_agent_as_tool.py

@@ -674,3 +674,49 @@ async def test_stream_releases_lock_after_error(tool, mock_agent, tool_use):
         pass
 
     assert not tool._lock.locked()
+
+
+# --- Agent-as-tool sugar (passing agents directly in tools list) ---
+
+
+def test_agent_passed_directly_in_tools_list():
+    """Test that an Agent can be passed directly in another Agent's tools list."""
+    from strands.agent.agent import Agent
+
+    sub_agent = Agent(name="research_agent", description="Does research", callback_handler=None)
+
+    # This should work without calling .as_tool() explicitly
+    parent_agent = Agent(name="orchestrator", tools=[sub_agent], callback_handler=None)
+
+    assert "research_agent" in parent_agent.tool_names
+
+
+def test_multiple_agents_passed_directly_in_tools_list():
+    """Test that multiple Agents can be passed directly in another Agent's tools list."""
+    from strands.agent.agent import Agent
+
+    agent_a = Agent(name="agent_a", callback_handler=None)
+    agent_b = Agent(name="agent_b", callback_handler=None)
+
+    parent = Agent(name="parent", tools=[agent_a, agent_b], callback_handler=None)
+
+    assert "agent_a" in parent.tool_names
+    assert "agent_b" in parent.tool_names
+
+
+def test_agent_mixed_with_regular_tools_in_tools_list():
+    """Test that Agents can be mixed with regular tools in the tools list."""
+    from strands import tool as tool_decorator
+    from strands.agent.agent import Agent
+
+    @tool_decorator
+    def my_tool(x: str) -> str:
+        """A regular tool."""
+        return x
+
+    sub_agent = Agent(name="helper_agent", callback_handler=None)
+
+    parent = Agent(name="parent", tools=[my_tool, sub_agent], callback_handler=None)
+
+    assert "my_tool" in parent.tool_names
+    assert "helper_agent" in parent.tool_names

tests/strands/tools/test_registry.py

@@ -603,3 +603,92 @@ def test_tool_registry_replace_non_dynamic_with_dynamic():
 
     assert registry.registry["my_tool"] == new_tool
     assert registry.dynamic_tools["my_tool"] == new_tool
+
+
+# --- Agent-as-tool sugar ---
+
+
+def test_process_tools_with_agent_instance():
+    """Test that passing an Agent instance in tools list auto-wraps it with as_tool()."""
+    from strands.agent.agent import Agent
+
+    sub_agent = Agent(name="research_agent", description="Finds information", callback_handler=None)
+
+    registry = ToolRegistry()
+    tool_names = registry.process_tools([sub_agent])
+
+    assert "research_agent" in tool_names
+    assert "research_agent" in registry.registry
+    assert registry.registry["research_agent"].tool_type == "agent"
+
+
+def test_process_tools_with_agent_instance_uses_agent_name():
+    """Test that the auto-wrapped tool uses the agent's name."""
+    from strands.agent.agent import Agent
+
+    sub_agent = Agent(name="my_custom_agent", callback_handler=None)
+
+    registry = ToolRegistry()
+    registry.process_tools([sub_agent])
+
+    assert "my_custom_agent" in registry.registry
+    spec = registry.registry["my_custom_agent"].tool_spec
+    assert spec["name"] == "my_custom_agent"
+
+
+def test_process_tools_with_agent_instance_uses_agent_description():
+    """Test that the auto-wrapped tool uses the agent's description."""
+    from strands.agent.agent import Agent
+
+    sub_agent = Agent(name="helper", description="A helpful assistant", callback_handler=None)
+
+    registry = ToolRegistry()
+    registry.process_tools([sub_agent])
+
+    spec = registry.registry["helper"].tool_spec
+    assert spec["description"] == "A helpful assistant"
+
+
+def test_process_tools_with_agent_in_nested_list():
+    """Test that Agent instances in nested iterables are auto-wrapped."""
+    from strands.agent.agent import Agent
+
+    agent_a = Agent(name="agent_a", callback_handler=None)
+    agent_b = Agent(name="agent_b", callback_handler=None)
+
+    registry = ToolRegistry()
+    tool_names = sorted(registry.process_tools([[agent_a, agent_b]]))
+
+    assert tool_names == ["agent_a", "agent_b"]
+
+
+def test_process_tools_with_mixed_agents_and_tools():
+    """Test that Agent instances can be mixed with regular tools."""
+    from strands.agent.agent import Agent
+
+    def function() -> str:
+        return "done"
+
+    regular_tool = tool(name="regular_tool")(function)
+    sub_agent = Agent(name="sub_agent", callback_handler=None)
+
+    registry = ToolRegistry()
+    tool_names = sorted(registry.process_tools([regular_tool, sub_agent]))
+
+    assert tool_names == ["regular_tool", "sub_agent"]
+    assert registry.registry["sub_agent"].tool_type == "agent"
+
+
+def test_process_tools_with_multiple_agents():
+    """Test that multiple Agent instances can be passed."""
+    from strands.agent.agent import Agent
+
+    agent_1 = Agent(name="researcher", description="Does research", callback_handler=None)
+    agent_2 = Agent(name="writer", description="Writes content", callback_handler=None)
+    agent_3 = Agent(name="reviewer", description="Reviews work", callback_handler=None)
+
+    registry = ToolRegistry()
+    tool_names = sorted(registry.process_tools([agent_1, agent_2, agent_3]))
+
+    assert tool_names == ["researcher", "reviewer", "writer"]
+    assert all(registry.registry[name].tool_type == "agent" for name in tool_names)