Sub-Agents as Primitives

One-Line Summary: A sub-agent is a full agent — its own context window, system prompt, scoped tool registry, and termination condition — that the main agent can spawn for a specific task; sub-agents differ from "role prompts" precisely because of that isolation, and treating them as the same is a common source of multi-agent bugs.

Prerequisites: What is an AI harness, agent loop, role-based specialization

What Is a Sub-Agent?

When the main agent needs to do something that benefits from isolation — a focused review, a research detour, a long subtask whose context would pollute the main conversation — it spawns a sub-agent. The sub-agent gets its own system prompt, its own tool list (often a subset of the parent's), its own context window, and its own termination criteria. It runs to completion and returns a final result; the main agent reads the result and continues.

Crucially, a sub-agent is not a role prompt. The naive "you are now a code reviewer" instruction inside a single context shares everything: history, tools, attention. A sub-agent has none of that. It cannot see the main conversation unless explicitly given context; it cannot use tools it was not granted; its trajectory does not contaminate the main agent's reasoning.

How They Work

In Claude Code, a sub-agent is a markdown file in .claude/agents/<name>.md with frontmatter declaring tools, model, and description, plus a system prompt as the body. The main agent invokes one via the Task tool (Task(description="review this PR", subagent_type="code-reviewer")). The harness:

Spawns a fresh agent loop with the sub-agent's system prompt and tool list.
Passes only the description and any explicitly attached context.
Runs the loop until termination.
Returns the sub-agent's final message to the parent.

In ruflo, sub-agents are first-class swarm members. In LangGraph, sub-agents are typically expressed as nested graphs. AutoGen models them as conversational peers under a GroupChatManager.

Why It Matters

Three reasons sub-agents are the load-bearing multi-agent primitive:

Context hygiene. A sub-agent's intermediate work doesn't compete with the parent's working memory. This is especially valuable for long subtasks (research, multi-file refactors) that would otherwise consume the parent's context.
Permission scoping. A sub-agent can be given exactly the tools it needs and no more — the linchpin of safe delegation. The main agent might have Bash, Edit, and Write; a sub-agent dispatched to summarize a doc has only Read.
Specialization that survives context pressure. A "you are now a security reviewer" prompt mid-conversation works for one turn. A dedicated security-reviewer sub-agent works as long as the harness exists.

Key Technical Details

Spawning is expensive: Each sub-agent invocation is a fresh model context — full system prompt, full tool descriptions. Token costs add up. Use sub-agents when the isolation is worth the overhead.
Sub-agents can be parallel: Spawning multiple in one turn is a basic pattern for fan-out work (review three files in parallel).
Termination is the sub-agent's responsibility: The harness usually provides defaults (max tokens, max steps), but a well-designed sub-agent has an explicit "I am done" criterion baked into its system prompt.
Communication is bounded: Sub-agents return one final message. Streaming intermediate results is possible but uncommon — most patterns aggregate at the end.
Sub-agents can themselves spawn sub-agents: Useful for hierarchical decomposition; expensive if uncontrolled.
Tool inheritance is opt-in, not default: Ruflo defaults to inheriting; Claude Code defaults to a curated list. Pick a default that matches your trust model.

How Harnesses & Frameworks Implement This

Harness / Framework	Sub-agent primitive	Definition format
Claude Code	Native — `Task` tool	Markdown in `.claude/agents/`
Claude Agent SDK	`agent.spawn(...)`	Programmatic
ruflo	First-class swarm members	Plugin / config
LangGraph	Nested `StateGraph`	Code
AutoGen	`ConversableAgent` peers under `GroupChatManager`	Code
CrewAI	`Agent` instances within a `Crew`	Code
OpenAI Agents SDK	`Agent` with `handoffs`	Code
Codex CLI	✗	N/A
Cursor	✗	N/A

Connections to Other Concepts

agent-definitions-and-personas.md — How sub-agents are described and reused.
permission-and-tool-scoping-primitives.md — Why scoping is critical.
topology-as-design-decision.md — How sub-agents compose into topologies.
supervisor-pattern-deep-dive.md — The most common sub-agent topology.
../../ai-agent-concepts/05-multi-agent-systems/agent-delegation.md — Foundational coverage.