Subagents

Subagents allow deep agents to delegate tasks to specialized child agents. This provides context isolation and enables focused problem-solving for complex subtasks.

Learn more: For patterns and best practices, see the Subagents documentation.

Why Use Subagents?

• Context quarantine: Prevent the main agent's context from growing too large
• Specialization: Give subagents specific tools, models, and prompts optimized for their task
• Modularity: Build reusable subagent definitions for common tasks

Defining a SubAgent

import { createDeepAgent, SubAgent } from "deepagents";
import { TavilySearch } from "@langchain/tavily";
import { tool } from "langchain";
import { z } from "zod";

const internetSearch = tool(
  async ({ query, maxResults = 5 }) => {
    const tavilySearch = new TavilySearch({ maxResults });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string(),
      maxResults: z.number().optional().default(5),
    }),
  },
);

const researchSubagent: SubAgent = {
  name: "research-agent",
  description: "Used to research more in depth questions",
  systemPrompt: "You are a great researcher",
  tools: [internetSearch],
  model: new ChatOpenAI({ model: "gpt-4o" }), // Optional model override
};

const agent = createDeepAgent({
  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
  subagents: [researchSubagent],
});

Using CompiledSubAgent

For complex workflows, use a pre-compiled LangGraph graph as a subagent:

import { createAgent } from "langchain";
import { createDeepAgent, CompiledSubAgent } from "deepagents";

// Create a custom agent graph
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "You are a specialized agent for data analysis...",
});

// Wrap it as a compiled subagent
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "Specialized agent for complex data analysis tasks",
  runnable: customGraph,
};

const agent = createDeepAgent({
  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
  subagents: [customSubagent],
});

SubAgent Configuration

Field	Type	Description
name	string	Identifier the main agent uses to invoke this subagent
description	string	Description shown to the main agent (helps it decide when to use the subagent)
systemPrompt	string	System prompt for the subagent
tools	StructuredTool[]	Tools available to the subagent
model	BaseChatModel	Optional model override (inherits from parent if not set)
middleware	AgentMiddleware[]	Optional additional middleware
interruptOn	InterruptOnConfig	Optional human-in-the-loop configuration

API Reference