subagents

119 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

Generate and filter pattern

In the generate and filter pattern, multiple subagents generate independent solutions to the same problem. The agent compares, scores, and filters the results in code, keeping only the best. Use cases include architecture proposals, refactoring strategies, content variations, and any task where exploring multiple options before committing produces a better outcome.

Tournament pattern

In the tournament pattern, variations are compared head-to-head by a judge subagent, with winners advancing through elimination rounds. Use cases include optimization under subjective criteria, style selection, and choosing between competing implementations.

Loop until done pattern

In the loop until done pattern, the agent runs a discovery loop, deduplicating against what it has already found, until no new results appear. This is useful when the scope of the work is not known upfront. Use cases include exhaustive search, dead code detection, dependency audits, and any sweep where completeness is desired rather than a fixed number of results.

Dynamic subagents beta status and requirements

Dynamic subagents use the interpreter runtime, which is in beta. APIs and lifecycle behavior may change between releases. In Python, interpreters require langchain-quickjs>=0.2.0 and Python >=3.11. In JavaScript, interpreters require @langchain/quickjs.

dcode integration with dynamic subagents

dcode (the LangChain terminal coding agent) ships with the code interpreter enabled, so dynamic subagents work out of the box. See the dcode subagents page for setup and usage details.

Subagent streaming overview

When a coordinator agent spawns specialist subagents, render the orchestrator's messages separately from each subagent's streaming output. The v1 SDK keeps coordinator messages on the root stream and exposes subagents as discovery snapshots. Subagents are first-class stream entities with their own status, messages, tool-call metadata, and results. The UI can show delegation, progress, errors, and final synthesis without interleaving tokens from every worker.

Selector-based subagent streams architecture

The root stream stays focused on the coordinator conversation. stream.messages contains only the coordinator's messages, stream.subagents contains discovery snapshots with identity, namespace, and status. Each subagent's messages, tool calls, and values are read with selector helpers. This separation lets you render the orchestrator's messages in one place and mount subagent cards only when needed, keeping the UI clean and scalable.

useStream setup for deep agents

No extra stream options are required to use useStream with deep agents. Point the stream at your deep agent, render coordinator messages from stream.messages, and use stream.subagents to mount cards for active specialists. In chat layouts, index subagents by the tool-call ID that spawned them so each card appears under the coordinator turn that delegated the work.

Submitting messages to deep agents with recursion limit

Submit messages through the root stream using stream.submit({ messages: [{ type: "human", content: text }] }, { config: { recursion_limit: 100 } }). Deep Agents sets a default recursion limit of 10,000, which is sufficient for most multi-expert setups. You can override this via config.recursion_limit if needed for unusually deep custom workflows.

SubagentDiscoverySnapshot definition and use

Each SubagentDiscoverySnapshot is a lightweight discovery record for a subagent running inside the thread. It tells the UI that a subagent exists, where it sits in the subagent tree, and what lifecycle state it is in. The snapshot does not include the subagent's streamed messages or tool calls. Instead, pass the snapshot to selector hooks such as useMessages(stream, subagent) or useToolCalls(stream, subagent). These hooks use the snapshot namespace to subscribe to the subagent's stream primitives only when the corresponding card or panel is mounted.

SubagentCard component structure

A subagent card displays the specialist's name, status, streaming content, and tool calls. Use selector hooks useMessages(stream, subagent) and useToolCalls(stream, subagent) to subscribe to the subagent namespace. The card shows a collapsible interface with a status icon, the subagent name capitalized, tool call count, and a status badge. When expanded and displayContent is present, show the last AI message text or subagent.output with animated pulse indicator if status is "running".

Progress tracking for multiple subagents

Show a progress bar and counter so users know how many subagents have finished. Calculate completed count by filtering subagents with status === "complete". Display as "Subagent progress: X/total complete" with a percentage-based progress bar (Math.round((completed / total) * 100)).

Rendering coordinator messages with subagent cards layout

The key layout pattern is to render coordinator messages from the root stream and attach subagent cards to the AI message whose tool call spawned them. Map through stream.messages, filter subagents by matching message.tool_calls IDs against subagentsByCallId map, and render SubagentCard components under each coordinator turn. Indent subagent cards with left border styling to show nesting relationship.

Subagent card best practices

Mount selectors only where needed—scoped messages and tool calls stream when a card calls useMessages(stream, subagent) or useToolCalls(stream, subagent). Show specialist names using subagent.name to tell users which worker is active. Use collapsible cards; in workflows with 5+ subagents, auto-collapse completed cards so users can focus on active work. Override recursion only when needed—Deep Agents sets a high default recursion limit. Handle errors per subagent; one subagent failing shouldn't crash the entire UI. Show the error in that subagent's card while others continue running.

Combining inline cards with global subagent view

You can combine inline subagent cards with a global subagent view. Index subagents by the coordinator tool call that spawned them for transcript cards, and use stream.subagents for a persistent sidebar that summarizes all active workers. This gives users both local context and a bird's-eye view of the whole run.

React useStream example for subagent cards

import { useStream } from "@langchain/react"; import { AIMessage, HumanMessage } from "langchain"; const AGENT_URL = "http://localhost:2024"; export function DeepAgentChat() { const stream = useStream<typeof myAgent>({ apiUrl: AGENT_URL, assistantId: "deep_agent_subagent_cards", }); const subagents = [...stream.subagents.values()]; const subagentsByCallId = new Map(subagents.map((s) => [s.id, s])); return ( <div> {stream.messages.map((msg) => { const turnSubagents = AIMessage.isInstance(msg) ? (msg.tool_calls ?? []) .map((tc) => subagentsByCallId.get(tc.id ?? "")) .filter((s): s is NonNullable<typeof s> => !!s) : []; return ( <div key={msg.id}> {HumanMessage.isInstance(msg) && <HumanBubble>{msg.text}</HumanBubble>} {AIMessage.isInstance(msg) && msg.text.trim() && ( <AIBubble>{msg.text}</AIBubble> )} {turnSubagents.map((subagent) => ( <SubagentCard key={subagent.id} stream={stream} subagent={subagent} /> ))} </div> ); })} </div> ); } This shows how to set up useStream for a deep agent, extract subagents from the stream, map subagents to their spawning tool calls, and render subagent cards for each coordinator turn.

Vue useStream example for subagent cards

import { computed } from "vue"; import { useStream } from "@langchain/vue"; import { AIMessage, HumanMessage } from "langchain"; const AGENT_URL = "http://localhost:2024"; const stream = useStream<typeof myAgent>({ apiUrl: AGENT_URL, assistantId: "deep_agent_subagent_cards", }); const subagentsByCallId = computed( () => new Map([...stream.subagents.value.values()].map((s) => [s.id, s])) ); function subagentsForMessage(msg: unknown) { if (!AIMessage.isInstance(msg)) return []; return (msg.tool_calls ?? []) .map((tc) => subagentsByCallId.value.get(tc.id ?? "")) .filter(Boolean); } This shows Vue implementation of subagent discovery and filtering by tool call ID.

SubagentCard component implementation

import { useState } from "react"; import { AIMessage } from "langchain"; import { useMessages, useToolCalls, type AnyStream, type SubagentDiscoverySnapshot, } from "@langchain/react"; function SubagentCard({ stream, subagent, }: { stream: AnyStream; subagent: SubagentDiscoverySnapshot; }) { const [expanded, setExpanded] = useState(true); const messages = useMessages(stream, subagent); const toolCalls = useToolCalls(stream, subagent); const lastAIMessage = messages .filter(AIMessage.isInstance) .at(-1); const displayContent = lastAIMessage?.text ?? subagent.output ?? ""; return ( <div className="rounded-lg border bg-white shadow-sm"> <button onClick={() => setExpanded(!expanded)} className="flex w-full items-center justify-between p-4" > <div className="flex items-center gap-3"> <StatusIcon status={subagent.status} /> <div> <h4 className="font-semibold capitalize">{subagent.name}</h4> <p className="text-xs text-gray-500"> {toolCalls.length} tool call{toolCalls.length === 1 ? "" : "s"} </p> </div> </div> <div className="flex items-center gap-2"> <StatusBadge status={subagent.status} /> </div> </button> {expanded && displayContent && ( <div className="border-t px-4 py-3"> <div className="prose prose-sm max-w-none line-clamp-6"> {displayContent} {subagent.status === "running" && ( <span className="inline-block h-4 w-1 animate-pulse bg-blue-500" /> )} </div> </div> )} </div> ); } This shows a complete SubagentCard component with collapsible state, message display, tool call count, and animated pulse indicator.

SubagentProgress component implementation

DeepAgentLayout component implementation

recursionLimit for long-running subagent workflows

For deep agent workflows that spawn many subagents, set a high `recursionLimit` when submitting to avoid cutting off long-running executions. Example: `stream.submit({ messages: [{ type: "human", content: text }] }, { streamSubgraphs: true, config: { recursionLimit: 10000 } })`.

Dynamic subagents with task() global

Dynamic subagents let the interpreter dispatch configured subagents from code using the built-in task() global. A task that spans many independent units, such as reviewing every file in a directory or triaging a batch of tickets, becomes a loop that fans out work and synthesizes the results.

Use cases for dynamic subagents

Use dynamic subagents for fan-out and synthesize (run the same kind of work across many items in parallel, then combine results), verification (send findings to independent verifier subagents and keep only confirmed results), and recursive workflows (keep a working set in interpreter variables, select slices, call subagents, and refine the result).

Subagent permissions inheritance

Subagents inherit the parent agent's permissions by default. To give a subagent different permissions, set the permissions field in its spec. This replaces the parent's rules entirely. To explicitly grant a subagent unrestricted access, set permissions: []. An empty array overrides the parent rules with no restrictions. Omitting permissions inherits from the parent.

Subagent capabilities in Deep Agents

The harness includes a built-in task tool that lets the main agent create ephemeral subagents for isolated, long-running, multi-step, or parallel tasks. Subagent execution provides: fresh context (each invocation creates a new agent instance with its own context), autonomous execution (subagent runs independently until completion), single handoff (returns one final report to main agent), configurable strategy (default general-purpose subagent enabled by default, or define custom subagents), stateless messaging (subagents are stateless and cannot send multiple messages back), and context and token efficiency (heavy subtask work stays isolated and compressed into compact result).

Disable subagents and task tool

To run an agent without the task tool, disable the auto-added subagent via the harness profile and pass no synchronous subagents via subagents=. Do not try removing SubAgentMiddleware via excluded_middleware—that is intentionally rejected. Async subagents are unaffected by this configuration.

Subagent delegation in Deep Agents

Deep Agents can spawn and delegate to subagents as needed to handle complex subtasks with specialized subagents.

Running without task tool requires disabling general-purpose subagent

To run an agent without the task tool, set general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False) and pass no synchronous subagents via subagents=. SubAgentMiddleware (and the task tool) is only attached when at least one synchronous subagent exists, so this configuration leaves it out cleanly. Async subagents are unaffected.

Subagent delegation for chunk analysis

In the retrieve, offload, and delegate pattern, after search_documentation returns file paths, the orchestrator delegates one chunk-analyst task per file path. Up to multiple task() calls can be launched in parallel. Each task includes the user's question and the exact file path. Subagents use read_file to read the assigned chunk from /retrieved/ directory, extract facts that help answer the question, and return a concise summary (under 300 words) with key API names, steps, or configuration details, and the source URL from the chunk header.

Troubleshoot: Subagent cannot access a skill

If custom subagent does not see skills that the main agent uses: Custom subagents do not inherit the main agent's skills. Add a `skills` parameter to each subagent definition with that subagent's skill source paths. The general-purpose subagent inherits skills from create_deep_agent automatically.

Subagents purpose and context quarantine

Subagents allow a deep agent to delegate work to specialized agents. They solve the context bloat problem by isolating detailed work—the main agent receives only the final result, not the dozens of tool calls that produced it. This approach is called context quarantine.

When to use subagents

Use subagents for: multi-step tasks that would clutter the main agent's context, specialized domains that need custom instructions or tools, tasks requiring different model capabilities, and when you want to keep the main agent focused on high-level coordination. Do NOT use subagents for simple single-step tasks, when you need to maintain intermediate context, or when the overhead outweighs benefits.

Default general-purpose subagent

Deep Agents automatically adds a synchronous general-purpose subagent unless you already provide a synchronous subagent with that name. The general-purpose subagent has filesystem tools by default and can be customized with additional tools/middleware. To replace it, pass your own subagent named 'general-purpose'. To disable it, set general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False) on the active harness profile and pass no synchronous subagents via subagents= on create_deep_agent.

SubAgent dictionary specification - Python

SubAgent dictionaries accept these fields: | Field | Type | Description | |-------|------|-------------| | name | str | Required. Unique identifier for the subagent. Used by main agent when calling task() tool. Becomes metadata for AIMessages and streaming. | | description | str | Required. Description of what this subagent does. Be specific and action-oriented. Main agent uses this to decide when to delegate. | | system_prompt | str | Required. Instructions for the subagent. Custom subagents must define their own. Include tool usage guidance and output format requirements. Does not inherit from main agent. | | tools | list[Callable] | Optional. Tools the subagent can use. Keep minimal. Inherits from main agent by default. When specified, overrides inherited tools entirely. | | model | str or BaseChatModel | Optional. Overrides main agent's model. Use format 'provider:model' like 'openai:gpt-5.5' or pass LangChain chat model object. Inherits from main agent by default. | | middleware | list[Middleware] | Optional. Additional middleware for custom behavior, logging, rate limiting. Does not inherit from main agent. Merged into synchronous subagent stack. | | interrupt_on | dict[str, bool or InterruptOnConfig] | Optional. Configure human-in-the-loop for specific tools. Options: True, False, or InterruptOnConfig with allowed_decisions. Requires checkpointer. Inherits from main agent by default; subagent value overrides. | | skills | list[str] | Optional. Skills source paths as list of directories. Does not inherit from main agent. Only general-purpose subagent inherits main agent's skills. When specified, subagent runs independent SkillsMiddleware instance. Skill state fully isolated. | | response_format | ResponseFormat | Optional. Structured output schema for subagent. When set, parent receives subagent result as JSON instead of free-form text. Accepts Pydantic models, ToolStrategy(), ProviderStrategy(), or raw schema type. | | permissions | list[FilesystemPermission] | Optional. Filesystem permission rules for subagent. When set, replaces parent agent's permissions entirely. Inherits from main agent by default. |

SubAgent dictionary specification - JavaScript

SubAgent dictionaries accept these fields: | Field | Type | Description | |-------|------|-------------| | name | string | Required. Unique identifier for the subagent. Used by main agent when calling task() tool. Becomes metadata for AIMessages and streaming. | | description | string | Required. Description of what this subagent does. Be specific and action-oriented. Main agent uses this to decide when to delegate. | | systemPrompt | string | Required. Instructions for the subagent. Custom subagents must define their own. Include tool usage guidance and output format requirements. Does not inherit from main agent. | | tools | StructuredTool[] | Optional. Tools the subagent can use. Keep minimal. Inherits from main agent by default. When specified, overrides inherited tools entirely. | | model | LanguageModelLike or string | Optional. Overrides main agent's model. Use format 'provider:model' like 'openai:gpt-5.5' or pass LangChain chat model object. Inherits from main agent by default. | | middleware | AgentMiddleware[] | Optional. Additional middleware for custom behavior, logging, rate limiting. Does not inherit from main agent. Appended to synchronous subagent stack. | | interruptOn | Record<string, boolean or InterruptOnConfig> | Optional. Configure human-in-the-loop for specific tools. Options: True, False, or InterruptOnConfig with allowed_decisions. Requires checkpointer. Inherits from main agent by default; subagent value overrides. | | skills | string[] | Optional. Skills source paths as array of directories. Does not inherit from main agent. Only general-purpose subagent inherits main agent's skills. When specified, subagent runs independent SkillsMiddleware instance. Skill state fully isolated. | | responseFormat | ResponseFormat | Optional. Structured output schema for subagent. When set, parent receives subagent result as JSON instead of free-form text. Accepts Zod schemas, JSON schema objects, toolStrategy(), or providerStrategy(). | | permissions | FilesystemPermission[] | Optional. Filesystem permission rules for subagent. When set, replaces parent agent's permissions entirely. Inherits from main agent by default. |

CompiledSubAgent specification

For complex workflows, use a prebuilt LangGraph graph as a CompiledSubAgent with these fields: | Field | Type | Description | |-------|------|-------------| | name | str | Required. Unique identifier for the subagent. Becomes metadata for AIMessages and streaming. | | description | str | Required. What this subagent does. | | runnable | Runnable | Required. A compiled LangGraph graph (must call .compile() first). | When creating a custom LangGraph graph for CompiledSubAgent, ensure the graph has a state key called "messages".

Dynamic subagents overview

Dynamic subagents allow the main agent to dispatch subagents from code using loops, branches, and parallel batches instead of through task tool calls. They become available when the agent has both subagents and the interpreter middleware. Dynamic subagent dispatch is on by default whenever the agent has subagents and the interpreter middleware. Pass CodeInterpreterMiddleware(subagents=False) in Python or createCodeInterpreterMiddleware({ subagents: false }) in JavaScript to require dispatch through the normal task tool path only.

Dynamic subagents installation

To enable dynamic subagents in Python, install the QuickJS interpreter package with: pip install -U "deepagents[quickjs]" or uv add "deepagents[quickjs]". Interpreters require langchain-quickjs>=0.2.0 and Python >=3.11. In JavaScript, install with: npm install deepagents @langchain/quickjs (or pnpm/yarn equivalents).

Dynamic subagents workflow trigger

The word 'workflow' is a useful trigger for dynamic orchestration. The built-in interpreter system prompt treats a 'workflow' as a signal to organize work through the interpreter—dispatching subagents with task() from code. Phrasing a request as a 'workflow' opts into dynamic orchestration and fan-out from code. For a single, direct delegation, phrase the request plainly instead.

Subagent streaming with stream_events

Deep Agents support streaming updates from both the coordinator and every delegated subagent using stream_events (Python) or streamEvents (JavaScript). This provides typed projections—separate iterators for subagents, messages, tool calls, and values—allowing you to consume each independently. The simplest pattern is to iterate stream.subagents to track each delegated task as it starts, runs, and completes. Each subagent handle exposes .name, .messages, .tool_calls, and .output.

Subagent metadata in LangSmith tracing

All runs executed by a subagent or the coordinator will have the agent name in their metadata under the lc_agent_name key, for example {'lc_agent_name': 'research-agent'}. This lets you identify and filter runs by subagent in LangSmith. You can filter by metadata in the LangSmith UI by clicking Add filter, selecting Metadata, setting Key to lc_agent_name and Value to the subagent name.

Structured output for subagents

Subagents support structured output so the parent agent receives predictable, parseable JSON instead of free-form text. Pass response_format (Python) or responseFormat (JavaScript) on the subagent config. When the subagent finishes, its structured response is JSON-serialized and returned as the ToolMessage content to the parent agent. The schema accepts Pydantic models, ToolStrategy(), ProviderStrategy() (Python) or Zod schemas, JSON schema objects, toolStrategy(), providerStrategy() (JavaScript), or raw schema types. Structured output for subagents requires deepagents>=0.5.3 (Python) or deepagents>=1.8.4 (JavaScript).

General-purpose subagent default behavior

Every deep agent has access to a general-purpose subagent at all times. This subagent uses its own default system prompt with profile overlays applied, has access to all the same tools, uses the same model unless overridden, and inherits skills from the main agent when skills are configured. It is ideal for context isolation without specialized behavior.

Skills inheritance in subagents

When configuring skills with create_deep_agent: the general-purpose subagent automatically inherits skills from the main agent. Custom subagents do NOT inherit skills by default—use the skills parameter to give them their own skills. Only subagents configured with skills get a SkillsMiddleware instance. When present, skill state is fully isolated in both directions: the parent's skills are not visible to the child, and the child's skills are not propagated back to the parent.

Subagent context propagation

When you invoke a parent agent with runtime context, that context automatically propagates to all subagents. Each subagent run receives the same runtime context you passed on the parent invoke/ainvoke call. This means tools running inside any subagent can access the same context values you provided to the parent.

Per-subagent context configuration

All subagents receive the same parent context. To pass configuration specific to a particular subagent, use namespaced keys (prefix keys with the subagent name, for example 'researcher:max_depth') in a flat context mapping, or model those settings as separate fields on your context type.

Identifying which subagent called a tool

When the same tool is shared between the parent and multiple subagents, you can use the lc_agent_name metadata (the same value used in streaming) to determine which agent initiated the call. This is accessed from runtime.config metadata when branching tool behavior.

Subagent best practice: clear descriptions

The main agent uses subagent descriptions to decide which subagent to call. Be specific and action-oriented. Good example: 'Analyzes financial data and generates investment insights with confidence scores'. Bad example: 'Does finance stuff'.

Subagent best practice: detailed system prompts

Include specific guidance on how to use tools and format outputs in subagent system prompts. Provide clear instructions for the subagent's behavior and expectations.

Subagent best practice: minimize tool sets

Only give subagents the tools they need. This improves focus and security. When specifying tools on a subagent, override the inherited tools entirely to keep the tool set minimal and focused.

Subagent best practice: choose models by task

Different models excel at different tasks. Use the model parameter on subagent config to override the main agent's model for subagents that require different capabilities.

Subagent best practice: return concise results

Instruct subagents in their system_prompt to return summaries and concise results, not raw data. This keeps the main agent's context clean and prevents bloat.

Multiple specialized subagents pattern

Create specialized subagents for different domains. The typical workflow is: main agent creates high-level plan, delegates data collection to a data-collector subagent, passes results to data-analyzer subagent, sends insights to report-writer subagent, and compiles final output. Each subagent works with clean context focused only on its task.

Troubleshooting: subagent not being called

If the main agent tries to do work itself instead of delegating to a subagent: 1) Make descriptions more specific and action-oriented, 2) Instruct the main agent in its system prompt to delegate when appropriate. For example, include guidance like 'Delegate to the research subagent when researching topics' in the main agent's system prompt.

Troubleshooting: context bloat despite subagents

If context fills up despite using subagents: 1) Instruct subagent in its system_prompt to return only concise summaries, not raw tool outputs; 2) Use the filesystem (with filesystem tools) for large data instead of keeping it in context—instruct the subagent to write large results to files and reference them instead of including raw data in responses.

Troubleshooting: wrong subagent being selected

If the main agent calls an inappropriate subagent for the task, differentiate subagents clearly in their descriptions. Make each description specific to what that subagent uniquely does, avoiding overlap or ambiguity between subagent purposes.

Synchronous vs async subagents

This page covers synchronous subagents, where the supervisor blocks until the subagent finishes. For long-running tasks, parallel workstreams, or cases where you need mid-flight steering and cancellation, see the Async subagents documentation.

dcode tool with dynamic subagents

dcode is the LangChain terminal coding agent built on a Deep Agent with the code interpreter enabled, so dynamic subagents work out of the box with nothing to wire up. Install with: curl -LsSf https://langch.in/dcode | bash. Run with: dcode. To trigger dynamic subagents, ask for a 'workflow'. For example: 'Run a workflow to review every file in src/ for SQL injection.' As subagents spawn, dcode shows them live in the dynamic subagents panel, grouped into phases by dispatch.

Subagents parameter usage

Pass subagent definitions in `subagents` when the agent should delegate specialized or context-heavy work. Each subagent can have its own prompt, model, and tools.

Give your agent this brain