# 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.py"
from __future__ import annotations

import asyncio
import json
import uuid
from typing import List, Literal, Optional

from crewai import LLM, Agent, Crew, Process, Task
from crewai.flow.flow import Flow, start
from litellm import acompletion
from pydantic import BaseModel, Field

from ag_ui_crewai import CopilotKitState, copilotkit_emit_state, copilotkit_stream


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


SubAgentName = Literal["research_agent", "writing_agent", "critique_agent"]


class Delegation(BaseModel):
    """Shape of one entry in the delegation log.

    Mirrors the LangGraph reference 1:1 so the frontend type can be
    shared verbatim across runtimes.
    """

    id: str
    sub_agent: SubAgentName
    task: str
    status: Literal["running", "completed", "failed"]
    result: str = ""


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

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


# ---------------------------------------------------------------------------
# Sub-agent crews (each is a real, single-agent CrewAI Crew)
# ---------------------------------------------------------------------------

_LLM = "gpt-6-luna"


# Each sub-agent is a real, single-agent CrewAI Crew with its own
# Agent role/goal/backstory and a single Task. They don't share
# memory or tools with the supervisor — the supervisor only sees
# the crew's final raw output (returned via `Crew.kickoff(...)`).
def _build_research_crew() -> Crew:
    researcher = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Researcher",
        goal="Produce a concise bulleted list of 3-5 key facts on the topic.",
        backstory=(
            "You are a research sub-agent. You gather and distil "
            "information into short, structured bullets. No preamble."
        ),
        verbose=False,
        allow_delegation=False,
    )
    research_task = Task(
        description=(
            "Topic: {task}\n\n"
            "Produce a concise bulleted list of 3-5 key facts about the "
            "topic. Each bullet ≤ 1 short sentence. No preamble or "
            "closing remarks."
        ),
        expected_output="3-5 short bullets, one per line, prefixed with '- '.",
        agent=researcher,
    )
    return Crew(
        agents=[researcher],
        tasks=[research_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )


def _build_writing_crew() -> Crew:
    writer = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Writer",
        goal="Turn a brief and any source facts into a polished single paragraph.",
        backstory=(
            "You are a writing sub-agent. You take a brief plus optional "
            "facts and produce one polished paragraph. Be clear and "
            "concrete. No preamble."
        ),
        verbose=False,
        allow_delegation=False,
    )
    writing_task = Task(
        description=(
            "Brief and source material:\n{task}\n\n"
            "Produce one polished paragraph (3-6 sentences). No "
            "headings, no bullet list, no preamble."
        ),
        expected_output="Exactly one polished paragraph.",
        agent=writer,
    )
    return Crew(
        agents=[writer],
        tasks=[writing_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )


def _build_critique_crew() -> Crew:
    critic = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Editorial Critic",
        goal="Give 2-3 crisp, actionable critiques of a draft.",
        backstory=(
            "You are a critique sub-agent. You read a draft and offer "
            "2-3 crisp, actionable improvements. No preamble, no rewrite."
        ),
        verbose=False,
        allow_delegation=False,
    )
    critique_task = Task(
        description=(
            "Draft to critique:\n{task}\n\n"
            "Provide 2-3 crisp, actionable critiques as short bullets "
            "(one critique per bullet). No preamble, no rewrite of the "
            "draft itself."
        ),
        expected_output="2-3 short bullet-point critiques.",
        agent=critic,
    )
    return Crew(
        agents=[critic],
        tasks=[critique_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )

```

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](/crewai-crews/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.py"
from __future__ import annotations

import asyncio
import json
import uuid
from typing import List, Literal, Optional

from crewai import LLM, Agent, Crew, Process, Task
from crewai.flow.flow import Flow, start
from litellm import acompletion
from pydantic import BaseModel, Field

from ag_ui_crewai import CopilotKitState, copilotkit_emit_state, copilotkit_stream


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


SubAgentName = Literal["research_agent", "writing_agent", "critique_agent"]


class Delegation(BaseModel):
    """Shape of one entry in the delegation log.

    Mirrors the LangGraph reference 1:1 so the frontend type can be
    shared verbatim across runtimes.
    """

    id: str
    sub_agent: SubAgentName
    task: str
    status: Literal["running", "completed", "failed"]
    result: str = ""


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

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


# ---------------------------------------------------------------------------
# Sub-agent crews (each is a real, single-agent CrewAI Crew)
# ---------------------------------------------------------------------------

_LLM = "gpt-6-luna"


# Each sub-agent is a real, single-agent CrewAI Crew with its own
# Agent role/goal/backstory and a single Task. They don't share
# memory or tools with the supervisor — the supervisor only sees
# the crew's final raw output (returned via `Crew.kickoff(...)`).
def _build_research_crew() -> Crew:
    researcher = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Researcher",
        goal="Produce a concise bulleted list of 3-5 key facts on the topic.",
        backstory=(
            "You are a research sub-agent. You gather and distil "
            "information into short, structured bullets. No preamble."
        ),
        verbose=False,
        allow_delegation=False,
    )
    research_task = Task(
        description=(
            "Topic: {task}\n\n"
            "Produce a concise bulleted list of 3-5 key facts about the "
            "topic. Each bullet ≤ 1 short sentence. No preamble or "
            "closing remarks."
        ),
        expected_output="3-5 short bullets, one per line, prefixed with '- '.",
        agent=researcher,
    )
    return Crew(
        agents=[researcher],
        tasks=[research_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )


def _build_writing_crew() -> Crew:
    writer = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Writer",
        goal="Turn a brief and any source facts into a polished single paragraph.",
        backstory=(
            "You are a writing sub-agent. You take a brief plus optional "
            "facts and produce one polished paragraph. Be clear and "
            "concrete. No preamble."
        ),
        verbose=False,
        allow_delegation=False,
    )
    writing_task = Task(
        description=(
            "Brief and source material:\n{task}\n\n"
            "Produce one polished paragraph (3-6 sentences). No "
            "headings, no bullet list, no preamble."
        ),
        expected_output="Exactly one polished paragraph.",
        agent=writer,
    )
    return Crew(
        agents=[writer],
        tasks=[writing_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )


def _build_critique_crew() -> Crew:
    critic = Agent(
        llm=LLM(
            model="openai/gpt-6-luna",
            is_litellm=True,
            additional_params={"extra_body": {"reasoning_effort": "none"}},
        ),
        role="Editorial Critic",
        goal="Give 2-3 crisp, actionable critiques of a draft.",
        backstory=(
            "You are a critique sub-agent. You read a draft and offer "
            "2-3 crisp, actionable improvements. No preamble, no rewrite."
        ),
        verbose=False,
        allow_delegation=False,
    )
    critique_task = Task(
        description=(
            "Draft to critique:\n{task}\n\n"
            "Provide 2-3 crisp, actionable critiques as short bullets "
            "(one critique per bullet). No preamble, no rewrite of the "
            "draft itself."
        ),
        expected_output="2-3 short bullet-point critiques.",
        agent=critic,
    )
    return Crew(
        agents=[critic],
        tasks=[critique_task],
        process=Process.sequential,
        verbose=False,
        chat_llm=_LLM,
    )




# Lazy singletons — each Crew is hot once built, so reuse across requests.
# Built lazily so import is cheap and aimock-mocked tests don't trigger
# any Crew machinery at module load.
_RESEARCH_CREW: Optional[Crew] = None
_WRITING_CREW: Optional[Crew] = None
_CRITIQUE_CREW: Optional[Crew] = None


def _get_research_crew() -> Crew:
    global _RESEARCH_CREW
    if _RESEARCH_CREW is None:
        _RESEARCH_CREW = _build_research_crew()
    return _RESEARCH_CREW


def _get_writing_crew() -> Crew:
    global _WRITING_CREW
    if _WRITING_CREW is None:
        _WRITING_CREW = _build_writing_crew()
    return _WRITING_CREW


def _get_critique_crew() -> Crew:
    global _CRITIQUE_CREW
    if _CRITIQUE_CREW is None:
        _CRITIQUE_CREW = _build_critique_crew()
    return _CRITIQUE_CREW


_CREW_FACTORIES = {
    "research_agent": _get_research_crew,
    "writing_agent": _get_writing_crew,
    "critique_agent": _get_critique_crew,
}


async def _kickoff_crew(crew: Crew, task: str) -> str:
    """Run a crew off the event loop and return its raw output."""
    # `Crew.kickoff` is synchronous and may issue blocking LLM calls; run
    # it in a worker thread so the supervisor flow keeps streaming.
    output = await asyncio.to_thread(crew.kickoff, inputs={"task": task})
    raw = getattr(output, "raw", None)
    if raw is None:
        raw = str(output)
    return str(raw)


# ---------------------------------------------------------------------------
# Supervisor tool schemas
# ---------------------------------------------------------------------------


# Each entry below is one "delegation tool" the supervisor LLM can call.
# CrewAI's hierarchical Process orchestrates sub-agents internally and
# only surfaces the final crew output to the AG-UI bridge, which would
# hide every intermediate delegation. Instead, we expose each sub-crew
# as a plain OpenAI-compatible tool schema and let the supervisor call
# them via litellm; the wrapper flow runs the matching crew on each call
# and records a Delegation entry into shared state.
def _delegation_tool(name: SubAgentName, description: str) -> dict:
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": {
                    "task": {
                        "type": "string",
                        "description": (
                            "The full task / brief to hand off to the "
                            "sub-agent. Include any facts or draft text "
                            "the sub-agent will need."
                        ),
                    }
                },
                "required": ["task"],
            },
        },
    }


RESEARCH_TOOL = _delegation_tool(
    "research_agent",
    (
        "Delegate a research task to the research sub-agent. Use for "
        "gathering facts, background, definitions, or statistics. "
        "Returns a bulleted list of key facts."
    ),
)
WRITING_TOOL = _delegation_tool(
    "writing_agent",
    (
        "Delegate a drafting task to the writing sub-agent. Use to "
        "produce a polished paragraph from a brief and optional facts. "
        "Pass relevant facts from prior research inside `task`."
    ),
)
CRITIQUE_TOOL = _delegation_tool(
    "critique_agent",
    (
        "Delegate a critique task to the critique sub-agent. Use to "
        "review a draft and surface 2-3 actionable improvements. Pass "
        "the draft inside `task`."
    ),
)

DELEGATION_TOOLS = [RESEARCH_TOOL, WRITING_TOOL, CRITIQUE_TOOL]
DELEGATION_TOOL_NAMES = {t["function"]["name"] for t in DELEGATION_TOOLS}
```

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.

Subscribe with `useAgent({ updates:
[UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged] })`,
read `agent.state.delegations`, and render one card per entry.

```typescript title="src/app/demos/subagents/delegation-log.tsx"
/**
 * Live delegation log — renders the `delegations` slot of agent state.
 *
 * Each entry corresponds to one invocation of a sub-agent. The list
 * grows in real time as the supervisor fans work out to its children.
 * The parent header shows how many sub-agents have been called and
 * whether the supervisor is still running.
 */
// Fixed list of the three sub-agent roles the supervisor can call.
// Rendered as always-visible indicator chips at the top of the log
// (regardless of whether the supervisor has delegated yet) so the user
// — and the e2e suite — can see at a glance which sub-agents exist and
// which are currently active.
const INDICATOR_ROLES: ReadonlyArray<{
  role: "researcher" | "writer" | "critic";
  subAgent: SubAgentName;
}> = [
  { role: "researcher", subAgent: "research_agent" },
  { role: "writer", subAgent: "writing_agent" },
  { role: "critic", subAgent: "critique_agent" },
];

export function DelegationLog({ delegations, isRunning }: DelegationLogProps) {
  const calledRoles = new Set<SubAgentName>(
    delegations.map((d) => d.sub_agent),
  );

  return (
    <div
      data-testid="delegation-log"
      className="w-full h-full flex flex-col bg-white rounded-2xl shadow-sm border border-[#DBDBE5] overflow-hidden dark:bg-card dark:border-border"
    >
      <div className="flex items-center justify-between px-6 py-3 border-b border-[#E9E9EF] bg-[#FAFAFC] dark:border-border dark:bg-muted">
        <div className="flex items-center gap-3">
          <span className="text-lg font-semibold text-[#010507] dark:text-foreground">
            Sub-agent delegations
          </span>
          {isRunning && (
            <span
              data-testid="supervisor-running"
              className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full border border-[#BEC2FF] bg-[#BEC2FF1A] text-[#010507] text-[10px] font-semibold uppercase tracking-[0.12em] dark:text-foreground"
            >
              <span className="w-1.5 h-1.5 rounded-full bg-[#010507] animate-pulse dark:bg-foreground" />
              Supervisor running
            </span>
          )}
        </div>
        <span
          data-testid="delegation-count"
          className="text-xs font-mono text-[#838389] dark:text-muted-foreground"
        >
          {delegations.length} calls
        </span>
      </div>

      <div
        data-testid="subagent-indicators"
        className="flex items-center gap-2 border-b border-[#E9E9EF] bg-white px-6 py-2 dark:border-border dark:bg-card"
      >
        {INDICATOR_ROLES.map(({ role, subAgent }) => {
          const style = SUB_AGENT_STYLE[subAgent];
          const fired = calledRoles.has(subAgent);
          return (
            <span
              key={role}
              data-testid={`subagent-indicator-${role}`}
              data-role={role}
              data-fired={fired ? "true" : "false"}
              className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-semibold uppercase tracking-[0.1em] border ${style.color} ${
                fired ? "" : "opacity-60"
              }`}
            >
              <span aria-hidden>{style.emoji}</span>
              <span>{style.label}</span>
            </span>
          );
        })}
      </div>

      <div className="flex-1 overflow-y-auto p-4 space-y-3">
        {delegations.length === 0 ? (
          <p className="text-[#838389] italic text-sm dark:text-muted-foreground">
            Ask the supervisor to complete a task. Every sub-agent it calls will
            appear here.
          </p>
        ) : (
          delegations.map((d, idx) => {
            const style = SUB_AGENT_STYLE[d.sub_agent];
            return (
              <div
                key={d.id}
                data-testid="delegation-entry"
                className="border border-[#E9E9EF] rounded-xl p-3 bg-[#FAFAFC] dark:border-border dark:bg-muted"
              >
                <div className="flex items-center justify-between mb-2">
                  <div className="flex items-center gap-2">
                    <span className="text-xs font-mono text-[#AFAFB7] dark:text-muted-foreground">
                      #{idx + 1}
                    </span>
                    <span
                      className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-semibold uppercase tracking-[0.1em] border ${style.color}`}
                    >
                      <span>{style.emoji}</span>
                      <span>{style.label}</span>
                    </span>
                  </div>
                  <span className="text-[10px] uppercase tracking-[0.12em] font-semibold text-[#189370] dark:text-[#85ECCE]">
                    {d.status}
                  </span>
                </div>
                <div className="text-xs text-[#57575B] mb-2 dark:text-muted-foreground">
                  <span className="font-semibold text-[#010507] dark:text-foreground">
                    Task:{" "}
                  </span>
                  {d.task}
                </div>
                <div className="text-sm text-[#010507] whitespace-pre-wrap bg-white rounded-lg p-2.5 border border-[#E9E9EF] dark:text-foreground dark:bg-card dark:border-border">
                  {d.result}
                </div>
              </div>
            );
          })
        )}
      </div>
    </div>
  );
}
```

To stream each sub-agent's output token by token inside its log entry, see
[State streaming](/crewai-crews/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.
