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

Install the LangGraph Python SDK

uv add copilotkit

Wire CopilotKit middleware into your graph

Sub-agents are wired as tools on a supervisor create_agent call. The supervisor's middleware list includes CopilotKitMiddleware() so the delegation log slot streams back to the UI through shared state.

subagents.py
import operator
import uuid
from typing import Annotated, Literal, TypedDict

from langchain.agents import AgentState as BaseAgentState, create_agent
from langchain.tools import ToolRuntime, tool
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langchain_openai import ChatOpenAI
from langgraph.types import Command

from copilotkit import CopilotKitMiddleware

from src.agents._header_forwarding_middleware import HeaderForwardingMiddleware


# ---------------------------------------------------------------------------
# Shared state
# ---------------------------------------------------------------------------


class Delegation(TypedDict):
    id: str
    sub_agent: Literal["research_agent", "writing_agent", "critique_agent"]
    task: str
    status: Literal["completed"]
    result: str


# Cap the supervisor → critique sub-agent loop at a single iteration.
# Without this, the supervisor LLM occasionally re-calls `critique_agent`
# repeatedly on the same draft (visible as stacking 🧐 cards in the
# chat). The critic only adds value once per draft, so we hard-stop
# after `_MAX_CRITIQUE_ITERATIONS` invocations and return a no-op
# result.
_MAX_CRITIQUE_ITERATIONS = 1


class AgentState(BaseAgentState):
    """Shared state. `delegations` is rendered as a live log in the UI.

    `delegations` uses an `operator.add` reducer so that concurrent
    sub-agent emissions in the same supervisor step accumulate into a
    single list instead of conflicting (LangGraph would otherwise raise
    `INVALID_CONCURRENT_GRAPH_UPDATE` — "Can receive only one value per
    step. Use an Annotated key to handle multiple values.").
    """

    delegations: Annotated[list[Delegation], operator.add]


# ---------------------------------------------------------------------------
# Sub-agents (real LLM agents under the hood)
# ---------------------------------------------------------------------------

# Each sub-agent is a full-fledged `create_agent(...)` with its own
# system prompt. They don't share memory or tools with the supervisor —
# the supervisor only sees their return value.
_sub_model = ChatOpenAI(reasoning_effort="none", model="gpt-6-luna")

# Each sub-agent gets the minimal HeaderForwardingMiddleware so the
# inbound x-aimock-context (and other x-*) headers from the supervisor's
# inbound HTTP request propagate to the sub-agent's outbound LLM call.
# We intentionally do NOT attach the full CopilotKitMiddleware here —
# the supervisor handles App-Context / frontend-tool injection for the
# whole run, and adding it on sub-agents would double-inject prompt
# state. Header forwarding alone is enough to keep aimock matching.
_research_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are a research sub-agent. Given a topic, produce a concise "
        "bulleted list of 3-5 key facts. No preamble, no closing."
    ),
    middleware=[HeaderForwardingMiddleware()],
)

_writing_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "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."
    ),
    middleware=[HeaderForwardingMiddleware()],
)

_critique_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are an editorial critique sub-agent. Given a draft, give "
        "2-3 crisp, actionable critiques. No preamble."
    ),
    middleware=[HeaderForwardingMiddleware()],
)

See src/agents/subagents.py for the canonical supervisor + three sub-agents pattern with a live delegation log.

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

subagents.py
import uuid
from operator import add
from typing import Annotated, Literal, TypedDict

from langchain.agents import AgentState as BaseAgentState, create_agent
from langchain.tools import ToolRuntime, tool
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_openai import ChatOpenAI
from langgraph.types import Command

from copilotkit import CopilotKitMiddleware


# ---------------------------------------------------------------------------
# Shared state
# ---------------------------------------------------------------------------


class Delegation(TypedDict):
    id: str
    sub_agent: Literal["research_agent", "writing_agent", "critique_agent"]
    task: str
    status: Literal["running", "completed", "failed"]
    result: str


class AgentState(BaseAgentState):
    """Shared state. `delegations` is rendered as a live log in the UI.

    `delegations` uses `operator.add` as its channel reducer so concurrent
    tool calls within a single supervisor turn each contribute their own
    entry. Without a reducer, parallel `tool_calls` would each read the
    same snapshot and the channel would last-write-wins, silently dropping
    every delegation but one from the UI log.
    """

    delegations: Annotated[list[Delegation], add]


# ---------------------------------------------------------------------------
# Sub-agents (real LLM agents under the hood)
# ---------------------------------------------------------------------------

# Each sub-agent is a full-fledged `create_agent(...)` with its own
# system prompt. They don't share memory or tools with the supervisor —
# the supervisor only sees their return value.
_sub_model = ChatOpenAI(reasoning_effort="none", model="gpt-6-luna")

_research_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are a research sub-agent. Given a topic, produce a concise "
        "bulleted list of 3-5 key facts. No preamble, no closing."
    ),
)

_writing_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "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_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are an editorial critique sub-agent. Given a draft, give "
        "2-3 crisp, actionable critiques. No preamble."
    ),
)

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 uuid
from operator import add
from typing import Annotated, Literal, TypedDict

from langchain.agents import AgentState as BaseAgentState, create_agent
from langchain.tools import ToolRuntime, tool
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_openai import ChatOpenAI
from langgraph.types import Command

from copilotkit import CopilotKitMiddleware


# ---------------------------------------------------------------------------
# Shared state
# ---------------------------------------------------------------------------


class Delegation(TypedDict):
    id: str
    sub_agent: Literal["research_agent", "writing_agent", "critique_agent"]
    task: str
    status: Literal["running", "completed", "failed"]
    result: str


class AgentState(BaseAgentState):
    """Shared state. `delegations` is rendered as a live log in the UI.

    `delegations` uses `operator.add` as its channel reducer so concurrent
    tool calls within a single supervisor turn each contribute their own
    entry. Without a reducer, parallel `tool_calls` would each read the
    same snapshot and the channel would last-write-wins, silently dropping
    every delegation but one from the UI log.
    """

    delegations: Annotated[list[Delegation], add]


# ---------------------------------------------------------------------------
# Sub-agents (real LLM agents under the hood)
# ---------------------------------------------------------------------------

# Each sub-agent is a full-fledged `create_agent(...)` with its own
# system prompt. They don't share memory or tools with the supervisor —
# the supervisor only sees their return value.
_sub_model = ChatOpenAI(reasoning_effort="none", model="gpt-6-luna")

_research_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are a research sub-agent. Given a topic, produce a concise "
        "bulleted list of 3-5 key facts. No preamble, no closing."
    ),
)

_writing_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "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_agent = create_agent(
    model=_sub_model,
    tools=[],
    system_prompt=(
        "You are an editorial critique sub-agent. Given a draft, give "
        "2-3 crisp, actionable critiques. No preamble."
    ),
)


def _invoke_sub_agent(agent, task: str) -> str:
    """Run a sub-agent on `task` and return its final message content."""
    result = agent.invoke({"messages": [HumanMessage(content=task)]})
    messages = result.get("messages", [])
    if not messages:
        return ""
    return str(messages[-1].content)


def _delegation_command(
    sub_agent: str,
    task: str,
    status: Literal["completed", "failed"],
    result: str,
    tool_call_id: str,
) -> Command:
    """Build a Command that appends a single new delegation entry.

    Emits ONLY the new entry under `delegations`. The channel reducer
    (`operator.add` on `AgentState.delegations`) extends the existing
    list, so parallel tool calls within one supervisor turn each
    contribute their own entry instead of clobbering each other via a
    last-write-wins read-modify-write.
    """
    entry: Delegation = {
        "id": str(uuid.uuid4()),
        "sub_agent": sub_agent,  # type: ignore[typeddict-item]
        "task": task,
        "status": status,
        "result": result,
    }
    return Command(
        update={
            "delegations": [entry],
            "messages": [
                ToolMessage(
                    content=result,
                    tool_call_id=tool_call_id,
                )
            ],
        }
    )


def _delegate(
    sub_agent_name: str,
    agent,
    task: str,
    tool_call_id: str,
) -> Command:
    """Invoke a sub-agent and turn the outcome into a Command.

    Wrapped in try/except so that a sub-agent LLM failure (rate limit,
    transport error, missing API key, etc.) is recorded as a `failed`
    delegation entry and surfaced to the supervisor as a ToolMessage,
    instead of propagating and crashing the supervisor turn. The
    user-facing `result` is scrubbed to the exception class name only;
    full details are captured server-side via the standard logging path
    when the exception is re-raised at the caller's discretion (we do
    not re-raise here — recovery is the supervisor's job).
    """
    try:
        result = _invoke_sub_agent(agent, task)
        return _delegation_command(
            sub_agent_name, task, "completed", result, tool_call_id
        )
    except Exception as exc:  # noqa: BLE001 - intentional broad catch
        # Keep the message generic; class name only, no exception args
        # (which can contain prompts, keys, or other sensitive data).
        message = (
            f"sub-agent call failed: {exc.__class__.__name__} "
            f"(see server logs for details)"
        )
        return _delegation_command(
            sub_agent_name, task, "failed", message, tool_call_id
        )


# ---------------------------------------------------------------------------
# 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 synchronously runs the
# matching sub-agent, records the delegation into shared state, and
# returns the sub-agent's output as a ToolMessage the supervisor can
# read on its next step.
@tool
def research_agent(task: str, runtime: ToolRuntime) -> Command:
    """Delegate a research task to the research sub-agent.

    Use for: gathering facts, background, definitions, statistics.
    Returns a bulleted list of key facts.
    """
    return _delegate("research_agent", _research_agent, task, runtime.tool_call_id)


@tool
def writing_agent(task: str, runtime: ToolRuntime) -> Command:
    """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`.
    """
    return _delegate("writing_agent", _writing_agent, task, runtime.tool_call_id)


@tool
def critique_agent(task: str, runtime: ToolRuntime) -> Command:
    """Delegate a critique task to the critique sub-agent.

    Use for: reviewing a draft and suggesting concrete improvements.
    """
    return _delegate("critique_agent", _critique_agent, task, runtime.tool_call_id)

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?