Sub-Agents

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

Sub-Agents

Waking up the demo

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?

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

Choose how the supervisor delegates

The demo below wraps each sub-agent in a delegation tool that you write, which also records the delegation log in shared state. AG2 1.0 and later also has a built-in shortcut: Agent.as_tool() turns a specialist into a tool that the coordinator calls. The tool runs the specialist on its own isolated stream with its own history, so the coordinator's context stays small.

pip install "ag2[ag-ui,openai]>=1.1.2"

Build each specialist as a plain Agent and hand it to the coordinator as a tool. Only the coordinator is wrapped in AGUIStream:

agent.py
from typing import Annotated

from fastapi import FastAPI, Header
from fastapi.responses import StreamingResponse
from pydantic import Field

from ag2 import Agent, tool
from ag2.ag_ui import AGUIStream, RunAgentInput
from ag2.config import OpenAIResponsesConfig

@tool
def search_docs(
    query: Annotated[str, Field(description="What to look up")],
) -> str:
    """Look a topic up in the product documentation."""
    return f"Docs say: {query} is supported since v1.0."

researcher = Agent(
    name="researcher",
    prompt="You research topics using the documentation tool and report findings plainly.",
    config=OpenAIResponsesConfig(model="gpt-6-luna"),
    tools=[search_docs],
)

writer = Agent(
    name="writer",
    prompt="You turn research notes into a single tight paragraph.",
    config=OpenAIResponsesConfig(model="gpt-6-luna"),
)

coordinator = Agent(
    name="coordinator",
    prompt=(
        "You coordinate specialists. Delegate research to `task_researcher`, "
        "then hand the findings to `task_writer`. Do not answer from memory."
    ),
    config=OpenAIResponsesConfig(model="gpt-6-luna"),
    tools=[
        researcher.as_tool(description="Research a topic in the product docs."),
        writer.as_tool(description="Turn research notes into one paragraph."),
    ],
)

stream = AGUIStream(coordinator)
app = FastAPI()

@app.post("/chat")
async def run_agent(
    message: RunAgentInput,
    accept: str | None = Header(None),
) -> StreamingResponse:
    return StreamingResponse(
        stream.dispatch(message, accept=accept),
        media_type=accept or "text/event-stream",
    )

as_tool() names the tool task_<agent name> by default (task_researcher and task_writer above). Pass name= to override it. description= is required: it is the only thing the coordinator's model reads when it decides whether to delegate.

Know what reaches the frontend

Each as_tool() delegation produces one tool call and one AG-UI 1.0 subagent invocation with its own subagentRunId, so two parallel delegations to the same agent can be told apart:

RUN_STARTED
TOOL_CALL_START      toolCallName: "task_researcher"
TOOL_CALL_ARGS
SUBAGENT_STARTED     subagentRunId: "4f1c…", name: "researcher", description: "<the objective>"
SUBAGENT_FINISHED    subagentRunId: "4f1c…", result: "<what it returned>"
TOOL_CALL_RESULT
TOOL_CALL_END
…
TEXT_MESSAGE_CHUNK
RUN_FINISHED
  • A failed delegation ends with SUBAGENT_ERROR carrying the message, and the run carries on: the coordinator's model is told the delegation failed and may recover. A cancelled or timed-out one also ends with SUBAGENT_ERROR (cancelled or expired).
  • The events carry no usage. The run's own usage already includes what the delegation spent.
  • If a specialist asks the human a question, it reaches the client like any other interrupt, tagged with the invocation's subagentRunId.

Three things to know before you build UI on top of it:

  • Delegations are ordinary tool calls. Render one with useRenderTool, or let the default tool renderer show it. A named useRenderTool registration needs a parameters schema. Every as_tool() delegation takes the same two arguments, objective and an optional context.
  • The specialist's own tool calls stay inside its stream. search_docs above runs in the researcher's isolated stream, so it does not appear as a separate TOOL_CALL_* pair in the coordinator's AG-UI output. If you need that visibility, give the specialist its own endpoint instead of delegating to it.
  • Shared state does not flow back out of a specialist. A delegation gets a copy of the coordinator's conversation variables, and writes that the specialist makes to context.variables are not merged back. A specialist that writes state changes nothing the UI sees, and nothing fails. Return the value from the delegation and have the coordinator write it instead. Dependencies are copied in the same way, so Inject(...) keeps working inside a specialist.

Track delegations with agent.subscribe

For a side panel or a progress list, subscribe to the invocation events on the agent from useAgent. A run is still running until a finished or error event with its subagentRunId arrives:

components/agent-panel.tsx
import type {
  SubagentErrorEvent,
  SubagentFinishedEvent,
  SubagentStartedEvent,
} from "@ag-ui/client";
import { useAgent } from "@copilotkit/react-core/v2";
import { useEffect, useState } from "react";

export function SubagentPanel() {
  const { agent } = useAgent({ agentId: "my_agent" });
  const [started, setStarted] = useState<SubagentStartedEvent[]>([]);
  const [finished, setFinished] = useState<Record<string, SubagentFinishedEvent>>({});
  const [failed, setFailed] = useState<Record<string, SubagentErrorEvent>>({});

  useEffect(() => {
    const subscription = agent.subscribe({
      onRunStartedEvent: () => {
        setStarted([]);
        setFinished({});
        setFailed({});
      },
      onSubagentStartedEvent: ({ event }) => setStarted((all) => [...all, event]),
      onSubagentFinishedEvent: ({ event }) =>
        setFinished((all) => ({ ...all, [event.subagentRunId]: event })),
      onSubagentErrorEvent: ({ event }) =>
        setFailed((all) => ({ ...all, [event.subagentRunId]: event })),
    });
    return () => subscription.unsubscribe();
  }, [agent]);

  return (
    <ul>
      {started.map((run) => (
        <li key={run.subagentRunId}>
          {run.name}:{" "}
          {failed[run.subagentRunId] ? "failed" : finished[run.subagentRunId] ? "done" : "running…"}
        </li>
      ))}
    </ul>
  );
}

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

subagents.py
import logging
import uuid
from textwrap import dedent
from typing import List, Literal

from ag2 import Agent, Context, tool
from ag2.ag_ui import AGUIStream
from ag2.config.openai import OpenAIResponsesConfig
from fastapi import FastAPI
from pydantic import BaseModel, Field

from ._loop_cap import loop_cap
from ._state import publish_state

logger = logging.getLogger(__name__)


SubAgentName = Literal["research_agent", "writing_agent", "critique_agent"]
DelegationStatus = Literal["running", "completed", "failed"]


class Delegation(BaseModel):
    """One entry in the delegation log shown by the UI."""

    id: str
    sub_agent: SubAgentName
    task: str
    status: DelegationStatus = "completed"
    result: str = ""


class SubagentsSnapshot(BaseModel):
    """Shape of the shared `delegations` state slot rendered by the UI."""

    delegations: List[Delegation] = Field(default_factory=list)


# ---------------------------------------------------------------------------
# Sub-agents (real AG2 Agents under the hood)
# ---------------------------------------------------------------------------
#
# Each sub-agent is its own LLM Agent with a focused system
# prompt. They don't share memory or tools with the supervisor — the
# supervisor only sees what each sub-agent's final reply produces.

_SUB_LLM_CONFIG = OpenAIResponsesConfig(model="gpt-6-luna", streaming=False)

_research_agent = Agent(
    "research_sub_agent",
    prompt=dedent(
        """
        You are a research sub-agent. Given a topic, produce a concise
        bulleted list of 3-5 key facts. No preamble, no closing.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)

_writing_agent = Agent(
    "writing_sub_agent",
    prompt=dedent(
        """
        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.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)

_critique_agent = Agent(
    "critique_sub_agent",
    prompt=dedent(
        """
        You are an editorial critique sub-agent. Given a draft, produce
        2-3 crisp, actionable critiques. No preamble.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)

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

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 (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.
subagents.py
import logging
import uuid
from textwrap import dedent
from typing import List, Literal

from ag2 import Agent, Context, tool
from ag2.ag_ui import AGUIStream
from ag2.config.openai import OpenAIResponsesConfig
from fastapi import FastAPI
from pydantic import BaseModel, Field

from ._loop_cap import loop_cap
from ._state import publish_state

logger = logging.getLogger(__name__)


SubAgentName = Literal["research_agent", "writing_agent", "critique_agent"]
DelegationStatus = Literal["running", "completed", "failed"]


class Delegation(BaseModel):
    """One entry in the delegation log shown by the UI."""

    id: str
    sub_agent: SubAgentName
    task: str
    status: DelegationStatus = "completed"
    result: str = ""


class SubagentsSnapshot(BaseModel):
    """Shape of the shared `delegations` state slot rendered by the UI."""

    delegations: List[Delegation] = Field(default_factory=list)


# ---------------------------------------------------------------------------
# Sub-agents (real AG2 Agents under the hood)
# ---------------------------------------------------------------------------
#
# Each sub-agent is its own LLM Agent with a focused system
# prompt. They don't share memory or tools with the supervisor — the
# supervisor only sees what each sub-agent's final reply produces.

_SUB_LLM_CONFIG = OpenAIResponsesConfig(model="gpt-6-luna", streaming=False)

_research_agent = Agent(
    "research_sub_agent",
    prompt=dedent(
        """
        You are a research sub-agent. Given a topic, produce a concise
        bulleted list of 3-5 key facts. No preamble, no closing.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)

_writing_agent = Agent(
    "writing_sub_agent",
    prompt=dedent(
        """
        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.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)

_critique_agent = Agent(
    "critique_sub_agent",
    prompt=dedent(
        """
        You are an editorial critique sub-agent. Given a draft, produce
        2-3 crisp, actionable critiques. No preamble.
        """
    ).strip(),
    config=_SUB_LLM_CONFIG,
    middleware=[loop_cap(1)],
)


async def _invoke_sub_agent(sub_agent: Agent, task: str) -> str:
    """Run a sub-agent on `task` and return its final reply text.

    `ask` runs one turn against a one-shot user message on the sub-agent's
    own stream, so none of its events leak into the supervisor's AG-UI run.
    """
    reply = await sub_agent.ask(task)
    return reply.body or ""


def _load_snapshot(ctx: Context) -> SubagentsSnapshot:
    """Best-effort load of the SubagentsSnapshot from the run's variables.

    Logs at WARNING when state fails validation so silent corruption is
    visible in server logs instead of degrading to an empty snapshot
    without a trace.
    """
    data = dict(ctx.variables)
    try:
        return SubagentsSnapshot.model_validate(data)
    except Exception as exc:
        logger.warning(
            "subagents: failed to validate SubagentsSnapshot from run "
            "variables (%s: %s); falling back to empty snapshot",
            exc.__class__.__name__,
            exc,
        )
        return SubagentsSnapshot()


async def _record_delegation(
    ctx: Context,
    sub_agent: SubAgentName,
    task: str,
    result: str,
    status: DelegationStatus = "completed",
) -> str:
    """Append a delegation entry to shared state, publish it, return the result."""
    snapshot = _load_snapshot(ctx)
    snapshot.delegations.append(
        Delegation(
            id=str(uuid.uuid4()),
            sub_agent=sub_agent,
            task=task,
            status=status,
            result=result,
        )
    )
    ctx.variables.update(snapshot.model_dump())
    await publish_state(ctx)
    return result


async def _run_delegation(
    ctx: Context,
    sub_agent_name: SubAgentName,
    sub_agent: Agent,
    task: str,
) -> str:
    """Invoke a sub-agent and record the outcome (completed or failed).

    If the underlying ``ask`` raises (transport error, quota,
    SDK bug, ...), we record the delegation with ``status='failed'`` and
    return a sane result string so the supervisor can recover instead of
    crashing the turn. The full traceback is logged server-side; the
    user-facing ``result`` text only mentions the exception class to
    avoid leaking internals.
    """
    try:
        result = await _invoke_sub_agent(sub_agent, task)
    except Exception as exc:
        logger.exception(
            "subagents: sub-agent %s failed while handling task", sub_agent_name
        )
        failure_message = (
            f"sub-agent call failed: {exc.__class__.__name__} (see server logs)"
        )
        return await _record_delegation(
            ctx,
            sub_agent_name,
            task,
            failure_message,
            status="failed",
        )

    return await _record_delegation(
        ctx,
        sub_agent_name,
        task,
        result,
        status="completed",
    )


# ---------------------------------------------------------------------------
# Supervisor tools (each tool delegates to one sub-agent)
# ---------------------------------------------------------------------------


# Each @tool wraps a sub-agent invocation. The supervisor LLM "calls"
# these tools to delegate work; each call asynchronously runs the
# matching sub-agent, records the delegation into shared state via the
# run's variables, and returns the sub-agent's text the supervisor reads
# as its tool output on the next step.
@tool
async def research_agent(
    ctx: Context,
    task: str,
) -> str:
    """Delegate a research task to the research sub-agent.

    Use for: gathering facts, background, definitions, statistics. Returns
    a bulleted list of key facts.

    Args:
        task: The specific research question or topic to investigate.
    """
    return await _run_delegation(ctx, "research_agent", _research_agent, task)


@tool
async def writing_agent(
    ctx: Context,
    task: str,
) -> str:
    """Delegate a drafting task to the writing sub-agent.

    Use for: producing a polished paragraph, draft, or summary. Pass
    relevant facts from prior research inside ``task``.

    Args:
        task: The brief plus any relevant facts the writer should use.
    """
    return await _run_delegation(ctx, "writing_agent", _writing_agent, task)


@tool
async def critique_agent(
    ctx: Context,
    task: str,
) -> str:
    """Delegate a critique task to the critique sub-agent.

    Use for: reviewing a draft and suggesting concrete improvements.

    Args:
        task: The draft to critique (paste it directly into ``task``).
    """
    return await _run_delegation(ctx, "critique_agent", _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.

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.

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.

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

How is this guide?