# Sub-Agents

> Decompose work across multiple specialized agents with a visible delegation log.

<!-- interactive demo: subagents -->

## What is this? [#what-is-this]

Sub-agents are the canonical multi-agent pattern: a top-level
**supervisor** LLM orchestrates one or more specialized **sub-agents**
by exposing each of them as a tool. The supervisor decides what to
delegate, the sub-agents do their narrow job, and their results flow
back up to the supervisor's next step.

This is fundamentally the same shape as tool-calling, but each "tool"
is itself a full-blown agent with its own system prompt and (often) its
own tools, memory, and model.

## When should I use this? [#when-should-i-use-this]

Reach for sub-agents when a task has distinct specialized sub-tasks
that each benefit from their own focus:

- **Research → Write → Critique** pipelines, where each stage needs a
  different system prompt and temperature.
- **Router + specialists**, where one agent classifies the request and
  dispatches to the right expert.
- **Divide-and-conquer**, for any problem that fits cleanly into parallel
  or sequential sub-problems.

The example below uses the Research → Write → Critique shape as the
canonical example.

## Setting up sub-agents [#setting-up-sub-agents]

Define one agent per role, each with its own system prompt:

```python title="src/agents/subagents_agent.py"
from __future__ import annotations

import asyncio
import contextvars
import json
import logging
import threading
import uuid
from collections.abc import AsyncGenerator, Awaitable, Callable
from textwrap import dedent
from typing import Annotated, Any

from ag_ui.core import BaseEvent
from agent_framework import (
    Agent,
    AgentContext,
    BaseChatClient,
    Content,
    agent_middleware,
    tool,
)
from agent_framework_ag_ui import AgentFrameworkAgent, state_update
from pydantic import Field

logger = logging.getLogger(__name__)


# ---------------------------------------------------------------------------
# State schema — `delegations` is rendered as a live log in the UI.
# ---------------------------------------------------------------------------

STATE_SCHEMA: dict[str, object] = {
    "delegations": {
        "type": "array",
        "description": (
            "Append-only log of supervisor -> sub-agent delegations. "
            "Each entry is a Delegation = "
            "{id, sub_agent, task, status, result}."
        ),
        "items": {
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "sub_agent": {"type": "string"},
                "task": {"type": "string"},
                "status": {"type": "string"},
                "result": {"type": "string"},
            },
        },
    }
}


# ---------------------------------------------------------------------------
# Per-request current_state bridge
#
# Tools cannot directly receive `current_state` from the AG-UI runtime,
# but `agent_middleware` runs once per agent invocation with full
# session context. We snapshot the latest `delegations` list into a
# ContextVar before `call_next()`, so each delegation tool (running in
# the same task / contextvar scope) can read it back, append, and
# return the FULL list via `state_update`.
# ---------------------------------------------------------------------------

_current_delegations: contextvars.ContextVar[list[dict[str, Any]]] = (
    contextvars.ContextVar("ms_subagents_current_delegations", default=[])
)


def _extract_delegations(raw: Any) -> list[dict[str, Any]]:
    """Pull a clean delegations list out of session metadata.

    `session.metadata["current_state"]` is JSON-serialized by the
    AG-UI runtime (see `_build_safe_metadata`) so we tolerate either
    a plain dict or its string form.
    """
    payload: Any = raw
    if isinstance(payload, str):
        try:
            payload = json.loads(payload)
        except json.JSONDecodeError:
            logger.warning(
                "subagents: current_state was not valid JSON; "
                "starting from empty delegations list"
            )
            return []
    if not isinstance(payload, dict):
        return []
    delegations = payload.get("delegations")
    if not isinstance(delegations, list):
        return []
    return [dict(d) for d in delegations if isinstance(d, dict)]


@agent_middleware
async def capture_current_state(
    context: AgentContext, call_next: Callable[[], Awaitable[None]]
) -> None:
    """Snapshot `delegations` from session metadata into a ContextVar."""
    snapshot: list[dict[str, Any]] = []
    session = context.session
    metadata = getattr(session, "metadata", None) if session else None
    if isinstance(metadata, dict):
        snapshot = _extract_delegations(metadata.get("current_state"))
    token = _current_delegations.set(snapshot)
    try:
        await call_next()
    finally:
        _current_delegations.reset(token)


# ---------------------------------------------------------------------------
# Sub-agent factory
#
# Each sub-agent is a full `Agent(...)` with its own system prompt.
# They share the chat client with the supervisor but otherwise have no
# shared memory or tools — the supervisor only sees their final text.
# ---------------------------------------------------------------------------


# Each sub-agent is a full-fledged `Agent(...)` with its own system
# prompt. They don't share memory or tools with the supervisor — the
# supervisor only sees their return value (final text content).
_RESEARCH_INSTRUCTIONS = (
    "You are a research sub-agent. Given a topic, produce a concise "
    "bulleted list of 3-5 key facts. No preamble, no closing."
)
_WRITING_INSTRUCTIONS = (
    "You are a writing sub-agent. Given a brief and optional source "
    "facts, produce a polished 1-paragraph draft. Be clear and "
    "concrete. No preamble."
)
_CRITIQUE_INSTRUCTIONS = (
    "You are an editorial critique sub-agent. Given a draft, give "
    "2-3 crisp, actionable critiques. No preamble."
)


def _make_sub_agent(chat_client: BaseChatClient, name: str, instructions: str) -> Agent:
    return Agent(
        client=chat_client,
        name=name,
        instructions=instructions,
        tools=[],
    )

```

Each sub-agent is an isolated agent call with its own model, system
prompt, and optional tools. They don't share memory or tools with the
supervisor; the supervisor only ever sees what the sub-agent returns.

Keep sub-agent system prompts narrow and focused. The point of this pattern
is that each one does one thing well. If a sub-agent needs to know
the whole user context to do its job, that's a signal the boundary is
wrong.

## Exposing sub-agents as tools [#exposing-sub-agents-as-tools]

The supervisor delegates by calling tools. Each delegation tool is a thin
wrapper around a specialized agent call that:

1. Runs the sub-agent on the supplied `task` string.
2. Records the delegation into a `delegations` slot in [shared agent
   state](/react-native/ms-agent-python/shared-state) (so the UI can render a live log). In the Built-in Agent
   example, the tool code below does not write this entry. The agent
   loop writes it: after each delegation tool result, the loop emits a
   `STATE_DELTA` event that sets `/delegations`.
3. Returns the sub-agent's final message as the tool result, which the
   supervisor sees on its next turn.

```python title="src/agents/subagents_agent.py"
from __future__ import annotations

import asyncio
import contextvars
import json
import logging
import threading
import uuid
from collections.abc import AsyncGenerator, Awaitable, Callable
from textwrap import dedent
from typing import Annotated, Any

from ag_ui.core import BaseEvent
from agent_framework import (
    Agent,
    AgentContext,
    BaseChatClient,
    Content,
    agent_middleware,
    tool,
)
from agent_framework_ag_ui import AgentFrameworkAgent, state_update
from pydantic import Field

logger = logging.getLogger(__name__)


# ---------------------------------------------------------------------------
# State schema — `delegations` is rendered as a live log in the UI.
# ---------------------------------------------------------------------------

STATE_SCHEMA: dict[str, object] = {
    "delegations": {
        "type": "array",
        "description": (
            "Append-only log of supervisor -> sub-agent delegations. "
            "Each entry is a Delegation = "
            "{id, sub_agent, task, status, result}."
        ),
        "items": {
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "sub_agent": {"type": "string"},
                "task": {"type": "string"},
                "status": {"type": "string"},
                "result": {"type": "string"},
            },
        },
    }
}


# ---------------------------------------------------------------------------
# Per-request current_state bridge
#
# Tools cannot directly receive `current_state` from the AG-UI runtime,
# but `agent_middleware` runs once per agent invocation with full
# session context. We snapshot the latest `delegations` list into a
# ContextVar before `call_next()`, so each delegation tool (running in
# the same task / contextvar scope) can read it back, append, and
# return the FULL list via `state_update`.
# ---------------------------------------------------------------------------

_current_delegations: contextvars.ContextVar[list[dict[str, Any]]] = (
    contextvars.ContextVar("ms_subagents_current_delegations", default=[])
)


def _extract_delegations(raw: Any) -> list[dict[str, Any]]:
    """Pull a clean delegations list out of session metadata.

    `session.metadata["current_state"]` is JSON-serialized by the
    AG-UI runtime (see `_build_safe_metadata`) so we tolerate either
    a plain dict or its string form.
    """
    payload: Any = raw
    if isinstance(payload, str):
        try:
            payload = json.loads(payload)
        except json.JSONDecodeError:
            logger.warning(
                "subagents: current_state was not valid JSON; "
                "starting from empty delegations list"
            )
            return []
    if not isinstance(payload, dict):
        return []
    delegations = payload.get("delegations")
    if not isinstance(delegations, list):
        return []
    return [dict(d) for d in delegations if isinstance(d, dict)]


@agent_middleware
async def capture_current_state(
    context: AgentContext, call_next: Callable[[], Awaitable[None]]
) -> None:
    """Snapshot `delegations` from session metadata into a ContextVar."""
    snapshot: list[dict[str, Any]] = []
    session = context.session
    metadata = getattr(session, "metadata", None) if session else None
    if isinstance(metadata, dict):
        snapshot = _extract_delegations(metadata.get("current_state"))
    token = _current_delegations.set(snapshot)
    try:
        await call_next()
    finally:
        _current_delegations.reset(token)


# ---------------------------------------------------------------------------
# Sub-agent factory
#
# Each sub-agent is a full `Agent(...)` with its own system prompt.
# They share the chat client with the supervisor but otherwise have no
# shared memory or tools — the supervisor only sees their final text.
# ---------------------------------------------------------------------------


# Each sub-agent is a full-fledged `Agent(...)` with its own system
# prompt. They don't share memory or tools with the supervisor — the
# supervisor only sees their return value (final text content).
_RESEARCH_INSTRUCTIONS = (
    "You are a research sub-agent. Given a topic, produce a concise "
    "bulleted list of 3-5 key facts. No preamble, no closing."
)
_WRITING_INSTRUCTIONS = (
    "You are a writing sub-agent. Given a brief and optional source "
    "facts, produce a polished 1-paragraph draft. Be clear and "
    "concrete. No preamble."
)
_CRITIQUE_INSTRUCTIONS = (
    "You are an editorial critique sub-agent. Given a draft, give "
    "2-3 crisp, actionable critiques. No preamble."
)


def _make_sub_agent(chat_client: BaseChatClient, name: str, instructions: str) -> Agent:
    return Agent(
        client=chat_client,
        name=name,
        instructions=instructions,
        tools=[],
    )




# Module-level holder so the delegation tools can reach the
# pre-built sub-agents without rebuilding them on every tool call.
# Populated lazily by `create_subagents_agent(...)`.
_SUB_AGENTS: dict[str, Agent] = {}


async def _invoke_sub_agent_async(sub_agent_name: str, task: str) -> str:
    """Run a sub-agent on `task` and return its final text content."""
    agent = _SUB_AGENTS.get(sub_agent_name)
    if agent is None:
        raise RuntimeError(
            f"sub-agent '{sub_agent_name}' is not registered; call "
            "create_subagents_agent(...) first"
        )
    response = await agent.run(task)
    text = (getattr(response, "text", "") or "").strip()
    if text:
        return text
    # Fall back to scanning messages — `Agent.run` always returns
    # an `AgentRunResponse`, but `.text` may be empty if the chat
    # client only emitted reasoning content or tool calls.
    messages = getattr(response, "messages", None) or []
    for message in reversed(messages):
        for content in getattr(message, "contents", None) or []:
            content_text = getattr(content, "text", None)
            if content_text:
                fallback = str(content_text).strip()
                if fallback:
                    return fallback
    raise RuntimeError(f"sub-agent '{sub_agent_name}' returned no text content")


def _invoke_sub_agent(sub_agent_name: str, task: str) -> str:
    """Sync bridge: drive the async invocation from inside a tool callback.

    `@tool` reflects on the underlying callable's signature, so the
    tool entry points are sync. The supervisor's chat client typically
    runs inside an existing event loop (FastAPI request handler), so
    `asyncio.run` would refuse — fall through to a worker thread that
    spins up its own loop.
    """
    try:
        return asyncio.run(_invoke_sub_agent_async(sub_agent_name, task))
    except RuntimeError as exc:
        if "asyncio.run() cannot be called" not in str(exc):
            raise

    container: dict[str, Any] = {}

    def _runner() -> None:
        try:
            container["result"] = asyncio.run(
                _invoke_sub_agent_async(sub_agent_name, task)
            )
        except Exception as inner:  # pragma: no cover -- defensive
            container["error"] = inner

    worker = threading.Thread(target=_runner, daemon=True)
    worker.start()
    worker.join()

    if "error" in container:
        raise container["error"]
    return str(container["result"])


def _delegate(sub_agent_name: str, task: str) -> Content:
    """Common delegation flow: invoke sub-agent, append entry, push state."""
    delegations = list(_current_delegations.get())
    entry_id = str(uuid.uuid4())
    try:
        result_text = _invoke_sub_agent(sub_agent_name, task)
    except Exception as exc:
        logger.exception("subagents: %s delegation failed", sub_agent_name)
        delegations.append(
            {
                "id": entry_id,
                "sub_agent": sub_agent_name,
                "task": task,
                "status": "failed",
                # Surface only the exception class — sub-agent error
                # messages can leak chat client URLs / quota details
                # in deployed environments.
                "result": (f"sub-agent error: {exc.__class__.__name__}"),
            }
        )
        # Mirror the contextvar so a follow-up sub-agent call within the
        # same supervisor turn sees this entry.
        _current_delegations.set(delegations)
        return state_update(
            text=(f"{sub_agent_name} failed; surfaced in delegation log."),
            state={"delegations": delegations},
        )

    delegations.append(
        {
            "id": entry_id,
            "sub_agent": sub_agent_name,
            "task": task,
            "status": "completed",
            "result": result_text,
        }
    )
    _current_delegations.set(delegations)
    return state_update(
        text=result_text,
        state={"delegations": delegations},
    )


# ---------------------------------------------------------------------------
# Supervisor delegation tools — each one wraps a sub-agent invocation.
# ---------------------------------------------------------------------------


# Each @tool wraps a sub-agent invocation. The supervisor LLM "calls"
# these tools to delegate work; each call synchronously runs the
# matching sub-agent (via `_delegate`), appends the entry to the
# `delegations` shared-state slot, and returns a `state_update(...)` so
# the AG-UI emitter pushes a deterministic StateSnapshotEvent — both
# surfacing the result to the supervisor and refreshing the live
# delegation log in the UI.
@tool(
    name="research_agent",
    description=(
        "Delegate a research task to the research sub-agent. Use for "
        "gathering facts, background, definitions, statistics. Returns "
        "a bulleted list of key facts."
    ),
)
def research_agent(
    task: Annotated[
        str,
        Field(description="The research question or topic to investigate."),
    ],
) -> Content:
    """Delegate a research task to the research sub-agent."""
    return _delegate("research_agent", task)


@tool(
    name="writing_agent",
    description=(
        "Delegate a drafting task to the writing sub-agent. Use for "
        "producing a polished paragraph, draft, or summary. Pass any "
        "relevant facts from prior research inside `task`."
    ),
)
def writing_agent(
    task: Annotated[
        str,
        Field(
            description=(
                "The drafting brief, including any relevant source "
                "facts the writer should weave in."
            )
        ),
    ],
) -> Content:
    """Delegate a drafting task to the writing sub-agent."""
    return _delegate("writing_agent", task)


@tool(
    name="critique_agent",
    description=(
        "Delegate a critique task to the critique sub-agent. Use for "
        "reviewing a draft and suggesting concrete improvements."
    ),
)
def critique_agent(
    task: Annotated[
        str,
        Field(
            description=(
                "The draft text to critique. Provide the full text -- "
                "the critique sub-agent has no other context."
            )
        ),
    ],
) -> Content:
    """Delegate a critique task to the critique sub-agent."""
    return _delegate("critique_agent", task)

```

If the excerpt uses a header-forwarding helper, such as `forwardingFetch` or `HeaderForwardingMiddleware`, leave it out of your app. The showcase uses it only to send request headers to its test server.

This is where CopilotKit's shared-state channel earns its keep: the
supervisor's tool calls mutate `delegations` as they happen, and the
frontend renders every new entry live.

<Callout type="warn">
  Give every delegation a stable `id` and merge new entries by that `id`. The
  client sends its copy of shared state back as run input on every run. A slot
  that appends everything it receives, such as a LangGraph
  `Annotated[list, operator.add]` reducer, adds those entries again. Then the
  log doubles when a thread continues. The LangGraph excerpt above uses
  `operator.add`, so in your app, write a reducer that merges by `id`.
</Callout>

## Rendering a live delegation log [#rendering-a-live-delegation-log]

On the frontend, the delegation log is a reactive render of the
`delegations` slot.

To stream each sub-agent's output token by token inside its log entry, see
[State streaming](/react-native/ms-agent-python/shared-state/streaming).

The log grows in real time as the supervisor delegates. The user sees each
step while it happens, not a long spinner.
