Subagents - Docs by LangChain

Architecture Overview

In the subagents architecture, a central main agent (often called a supervisor) coordinates subagents by calling them as tools. The main agent decides which subagent to invoke, what input to provide, and how to combine results. Subagents are stateless—they don’t remember past interactions, with all conversation memory maintained by the main agent. This provides context isolation: each subagent invocation works in a clean context window, preventing context bloat.

Key characteristics include centralized control (all routing passes through the main agent), no direct user interaction (subagents return results to the main agent), subagents invoked via tools, and parallel execution (the main agent can invoke multiple subagents in a single turn). Use this pattern when you have distinct domains (e.g., calendar, email, CRM) and want centralized workflow control.

Basic Implementation and Design Decisions

The core mechanism wraps a subagent as a tool that the main agent can call. For example, a `research` subagent is created and then decorated with `@tool('research', description='Research a topic...')`. The main agent is then created with that tool in its tool list. Several design decisions must be made: sync vs. async execution, tool patterns (tool per agent vs. single dispatch tool), subagent specs (system prompt enumeration, enum constraint, or tool-based discovery), subagent inputs (query only vs. full context), and subagent outputs (result only vs. full history).

Sync vs. async: Synchronous blocks the main agent until the subagent completes, best when the next step depends on the result. Asynchronous uses a three-tool pattern (start job, check status, get result) and allows the user to continue chatting while work happens in the background. For tool patterns, tool per agent provides fine-grained control, while single dispatch tool uses a convention-based approach with one parameterized tool that can invoke any registered subagent by name.

Context Engineering and Advanced Topics

Context engineering controls how context flows between the main agent and subagents. It covers subagent specs (names and descriptions that guide routing), subagent inputs (customizing the context the subagent receives, e.g., full message history or state keys), and subagent outputs (specifying what the subagent returns, either via prompting or formatted in code). These choices impact routing decisions, subagent performance, and main agent performance.

For subagent specs, system prompt enumeration is simple for small static lists; enum constraints add type safety; tool-based discovery supports large or dynamic registries via a `list_agents` tool. Subagent inputs can be enriched by pulling from agent state (e.g., `runtime.state['messages']`). Subagent outputs can be controlled by prompting the subagent or by formatting the response in code using a `Command` to pass back additional state. Checkpointing and state inspection: by default subagents start fresh each invocation; if persistence is needed, compile with `checkpointer=True`.