evalstate
diff --git a/‎README.md‎
Lines changed: 55 additions & 0 deletions b/‎README.md‎
Lines changed: 55 additions & 0 deletions
diff --git a/‎examples/workflows/agents_as_tools_extended.py‎
Lines changed: 73 additions & 0 deletions b/‎examples/workflows/agents_as_tools_extended.py‎
Lines changed: 73 additions & 0 deletions
diff --git a/‎examples/workflows/agents_as_tools_simple.py‎
Lines changed: 50 additions & 0 deletions b/‎examples/workflows/agents_as_tools_simple.py‎
Lines changed: 50 additions & 0 deletions
diff --git a/‎examples/workflows/fastagent.config.yaml‎
Lines changed: 3 additions & 0 deletions b/‎examples/workflows/fastagent.config.yaml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎src/fast_agent/agents/llm_decorator.py‎
Lines changed: 84 additions & 0 deletions b/‎src/fast_agent/agents/llm_decorator.py‎
Lines changed: 84 additions & 0 deletions
@@ -162,6 +162,61 @@ uv run workflow/chaining.py --agent post_writer --message "<url>"
 
 Add the `--quiet` switch to disable progress and message display and return only the final response - useful for simple automations.
 
+### Agents-as-Tools (child agents as tools)
+
+Sometimes one agent needs to call other agents as tools. `fast-agent` supports
+this via a hybrid *Agents-as-Tools* agent:
+
+- You declare a BASIC agent with `agents=[...]`.
+- At runtime it is instantiated as an internal `AgentsAsToolsAgent`, which:
+  - Inherits from `McpAgent` (keeps its own MCP servers/tools).
+  - Exposes each child agent as a tool (`agent__ChildName`).
+  - Merges MCP tools and agent-tools in a single `list_tools()` surface.
+  - Supports history/parallel controls:
+    - `history_mode` (default `fork`; `fork_and_merge` to merge clone history back)
+    - `max_parallel` (default unlimited), `child_timeout_sec` (default none)
+    - `max_display_instances` (default 20; collapse progress after top-N)
+
+Minimal example:
+
+```python
+@fast.agent(
+    name="NY-Project-Manager",
+    instruction="Return current time and project status.",
+    servers=["time"],  # MCP server 'time' configured in fastagent.config.yaml
+)
+@fast.agent(
+    name="London-Project-Manager",
+    instruction="Return current time and news.",
+    servers=["time"],
+)
+@fast.agent(
+    name="PMO-orchestrator",
+    instruction="Get reports. Separate call per topic. NY: {OpenAI, Fast-Agent, Anthropic}, London: Economics",
+    default=True,
+    agents=[
+        "NY-Project-Manager",
+        "London-Project-Manager",
+    ],  # children are exposed as tools: agent__NY-Project-Manager, agent__London-Project-Manager
+    # optional knobs:
+    #   history_mode=HistoryMode.FORK_AND_MERGE to merge clone history back
+    #   max_parallel=8 to cap parallel agent-tools
+    #   child_timeout_sec=600 to bound each child call
+    #   max_display_instances=10 to collapse progress UI after top-N
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        result = await agent("Get PMO report")
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Extended example is available in the repository as
+`examples/workflows/agents_as_tools_extended.py`.
+
 ## MCP OAuth (v2.1)
 
 For SSE and HTTP MCP servers, OAuth is enabled by default with minimal configuration. A local callback server is used to capture the authorization code, with a paste-URL fallback if the port is unavailable.
 
@@ -0,0 +1,73 @@
+"""Agents-as-Tools example: project managers for NY and London.
+
+Parent agent ("PMO-orchestrator") calls two child agents
+("NY-Project-Manager" and "London-Project-Manager") as tools. Each child uses
+the ``time`` MCP server for local time and the ``fetch`` MCP server for a short
+news-based update on the given topics.
+
+Defaults: clones fork parent history (no merge-back), no timeout, no parallel cap,
+and collapses progress display after the first 20 instances.
+To change behavior, pass decorator args such as
+`history_mode=HistoryMode.FORK_AND_MERGE`, `child_timeout_sec=600`,
+`max_parallel=8`, `max_display_instances=10`
+(HistoryMode import: fast_agent.agents.workflow.agents_as_tools_agent).
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Agents-as-Tools demo")
+
+
+@fast.agent(
+    name="NY-Project-Manager",
+    instruction=(
+        "You are a New York project manager. For each given topic, get the "
+        "current local time in New York and a brief, project-relevant news "
+        "summary using the 'time' and 'fetch' MCP servers. If a source returns "
+        "HTTP 403 or is blocked by robots.txt, try up to five alternative "
+        "public sources before giving up and clearly state any remaining "
+        "access limits. Hint: Fast-Agent site: https://fast-agent.ai"
+    ),
+    servers=[
+        "time",
+        "fetch",
+    ],  # MCP servers 'time' and 'fetch' configured in fastagent.config.yaml
+)
+@fast.agent(
+    name="London-Project-Manager",
+    instruction=(
+        "You are a London project manager. For each given topic, get the "
+        "current local time in London and a brief, project-relevant news "
+        "summary using the 'time' and 'fetch' MCP servers. If a source returns "
+        "HTTP 403 or is blocked by robots.txt, try up to five alternative "
+        "public sources before giving up and clearly state any remaining "
+        "access limits. Hint: BBC: https://www.bbc.com/ and FT: https://www.ft.com/"
+    ),
+    servers=["time", "fetch"],
+)
+@fast.agent(
+    name="PMO-orchestrator",
+    instruction=(
+        "Get project updates from the New York and London project managers. "
+        "Ask NY-Project-Manager three times about different projects: Anthropic, "
+        "evalstate/fast-agent, and OpenAI, and London-Project-Manager for economics review. "
+        "Return a brief, concise combined summary with clear city/time/topic labels."
+    ),
+    default=True,
+    agents=[
+        "NY-Project-Manager",
+        "London-Project-Manager",
+    ],  # children are exposed as tools: agent__NY-Project-Manager, agent__London-Project-Manager
+    # optional: history_mode="fork_and_merge", child_timeout_sec=600, max_parallel=8, max_display_instances=10
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        result = await agent("pls send me daily review.")
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,50 @@
+"""Simple Agents-as-Tools PMO example.
+
+Parent agent ("PMO-orchestrator") calls two child agents ("NY-Project-Manager"
+and "London-Project-Manager") as tools. Each child uses the ``time`` MCP
+server to include local time in a brief report.
+
+Defaults: clones fork parent history (no merge-back), no timeout, no parallel cap,
+and collapses progress display after the first 20 instances.
+If you want merge-back or other limits, pass decorator args:
+`history_mode=HistoryMode.FORK_AND_MERGE`, `child_timeout_sec=600`,
+`max_parallel=8`, `max_display_instances=10`
+(HistoryMode import: fast_agent.agents.workflow.agents_as_tools_agent).
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+fast = FastAgent("Agents-as-Tools simple demo")
+
+
+@fast.agent(
+    name="NY-Project-Manager",
+    instruction="Return current time and project status.",
+    servers=["time"],  # MCP server 'time' configured in fastagent.config.yaml
+)
+@fast.agent(
+    name="London-Project-Manager",
+    instruction="Return current time and news.",
+    servers=["time"],
+)
+@fast.agent(
+    name="PMO-orchestrator",
+    instruction="Get reports. Separate call per topic. NY: {OpenAI, Fast-Agent, Anthropic}, London: Economics",
+    default=True,
+    agents=[
+        "NY-Project-Manager",
+        "London-Project-Manager",
+    ],  # children are exposed as tools: agent__NY-Project-Manager, agent__London-Project-Manager
+    # optional: history_mode="fork_and_merge", child_timeout_sec=600, max_parallel=8, max_display_instances=10
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        result = await agent("Get PMO report")
+        await agent.interactive()
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -21,3 +21,6 @@ mcp:
     fetch:
       command: "uvx"
       args: ["mcp-server-fetch"]
+    time:
+      command: "uvx"
+      args: ["mcp-server-time"]
@@ -4,6 +4,7 @@
 
 import json
 from collections import Counter, defaultdict
+from copy import deepcopy
 from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
@@ -19,6 +20,8 @@
 if TYPE_CHECKING:
     from rich.text import Text
 
+    from fast_agent.agents.llm_agent import LlmAgent
+
 from a2a.types import AgentCard
 from mcp import ListToolsResult, Tool
 from mcp.types import (
@@ -187,6 +190,8 @@ def __init__(
         # Initialize the LLM to None (will be set by attach_llm)
         self._llm: FastAgentLLMProtocol | None = None
         self._initialized = False
+        self._llm_factory_ref: LLMFactoryProtocol | None = None
+        self._llm_attach_kwargs: dict[str, Any] | None = None
 
     @property
     def context(self) -> Context | None:
@@ -257,8 +262,71 @@ async def attach_llm(
             agent=self, request_params=effective_params, context=self._context, **additional_kwargs
         )
 
+        # Store attachment details for future cloning
+        self._llm_factory_ref = llm_factory
+        attach_kwargs: dict[str, Any] = dict(additional_kwargs)
+        attach_kwargs["request_params"] = deepcopy(effective_params)
+        self._llm_attach_kwargs = attach_kwargs
+
         return self._llm
 
+    def _clone_constructor_kwargs(self) -> dict[str, Any]:
+        """Hook for subclasses/mixins to supply constructor kwargs when cloning."""
+        return {}
+
+    async def spawn_detached_instance(self, *, name: str | None = None) -> "LlmAgent":
+        """Create a fresh agent instance with its own MCP/LLM stack."""
+
+        new_config = deepcopy(self.config)
+        if name:
+            new_config.name = name
+
+        constructor_kwargs = self._clone_constructor_kwargs()
+        clone = type(self)(config=new_config, context=self.context, **constructor_kwargs)
+        await clone.initialize()
+
+        if self._llm_factory_ref is not None:
+            if self._llm_attach_kwargs is None:
+                raise RuntimeError(
+                    "LLM attachment parameters missing despite factory being available"
+                )
+
+            attach_kwargs = dict(self._llm_attach_kwargs)
+            request_params = attach_kwargs.pop("request_params", None)
+            if request_params is not None:
+                request_params = deepcopy(request_params)
+
+            await clone.attach_llm(
+                self._llm_factory_ref,
+                request_params=request_params,
+                **attach_kwargs,
+            )
+
+        return clone
+
+    def merge_usage_from(self, other: "LlmAgent") -> None:
+        """Merge LLM usage metrics from another agent instance into this one."""
+
+        if not hasattr(self, "_llm") or not hasattr(other, "_llm"):
+            return
+
+        source_llm = getattr(other, "_llm", None)
+        target_llm = getattr(self, "_llm", None)
+        if not source_llm or not target_llm:
+            return
+
+        source_usage = getattr(source_llm, "usage_accumulator", None)
+        target_usage = getattr(target_llm, "usage_accumulator", None)
+        if not source_usage or not target_usage:
+            return
+
+        for turn in source_usage.turns:
+            try:
+                target_usage.add_turn(turn.model_copy(deep=True))
+            except AttributeError:
+                # Fallback if turn doesn't provide model_copy
+                target_usage.add_turn(turn)
+
     async def __call__(
         self,
         message: Union[
@@ -915,6 +983,22 @@ def _template_prefix_messages(self) -> list[PromptMessageExtended]:
                 break
         return prefix
 
+    def load_message_history(self, messages: list[PromptMessageExtended] | None) -> None:
+        """Replace message history with a deep copy of supplied messages (or empty list)."""
+        msgs = messages or []
+        self._message_history = [
+            msg.model_copy(deep=True) if hasattr(msg, "model_copy") else msg for msg in msgs
+        ]
+
+    def append_history(self, messages: list[PromptMessageExtended] | None) -> None:
+        """Append messages to history as deep copies."""
+        if not messages:
+            return
+        for msg in messages:
+            self._message_history.append(
+                msg.model_copy(deep=True) if hasattr(msg, "model_copy") else msg
+            )
+
     def pop_last_message(self) -> PromptMessageExtended | None:
         """Remove and return the most recent message from the conversation history."""
         if self.llm: