Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.
Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things: a planning tool, sub agents, access to a file system, and a detailed prompt.
deepagents is a TypeScript package that implements these in a general purpose way so that you can easily create a Deep Agent for your application.
💡 Tip: Looking for the Python version of this package? See langchain-ai/deepagents
Using an LLM to call tools in a loop is the simplest form of an agent. However, this architecture can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.
Applications like Deep Research, Manus, and Claude Code have overcome this limitation by implementing a combination of four key components:
Deep Agents is a TypeScript package that implements these patterns in a general-purpose way, enabling you to easily create sophisticated agents for your applications.
# npm
npm install deepagents
# yarn
yarn add deepagents
# pnpm
pnpm add deepagents(To run the example below, you will need to npm install @langchain/tavily).
Make sure to set TAVILY_API_KEY in your environment. You can generate one here.
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent } from "deepagents";
import { z } from "zod";
// Web search tool
const internetSearch = tool(
async ({
query,
maxResults = 5,
topic = "general",
includeRawContent = false,
}: {
query: string;
maxResults?: number;
topic?: "general" | "news" | "finance";
includeRawContent?: boolean;
}) => {
const tavilySearch = new TavilySearch({
maxResults,
tavilyApiKey: process.env.TAVILY_API_KEY,
includeRawContent,
topic,
});
return await tavilySearch._call({ query });
},
{
name: "internet_search",
description: "Run a web search",
schema: z.object({
query: z.string().describe("The search query"),
maxResults: z
.number()
.optional()
.default(5)
.describe("Maximum number of results to return"),
topic: z
.enum(["general", "news", "finance"])
.optional()
.default("general")
.describe("Search topic category"),
includeRawContent: z
.boolean()
.optional()
.default(false)
.describe("Whether to include raw content"),
}),
},
);
// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research, and then write a polished report.
You have access to an internet search tool as your primary means of gathering information.
> [!TIP]
> For developing, debugging, and deploying AI agents and LLM applications, see [LangSmith](https://docs.langchain.com/langsmith/home).
## \`internet_search\`
Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;
// Create the deep agent
const agent = createDeepAgent({
tools: [internetSearch],
systemPrompt: researchInstructions,
});
// Invoke the agent
const result = await agent.invoke({
messages: [{ role: "user", content: "What is langgraph?" }],
});See examples/research/research-agent.ts for a more complex example.
The agent created with createDeepAgent is just a LangGraph graph - so you can interact with it (streaming, human-in-the-loop, memory, studio)
in the same way you would any LangGraph agent.
Planning & Task Decomposition
Deep Agents include a built-in write_todos tool that enables agents to break down complex tasks into discrete steps, track progress, and adapt plans as new information emerges.
Context Management
File system tools (ls, read_file, write_file, edit_file, glob, grep) allow agents to offload large context to memory, preventing context window overflow and enabling work with variable-length tool results.
Subagent Spawning
A built-in task tool enables agents to spawn specialized subagents for context isolation. This keeps the main agent's context clean while still going deep on specific subtasks.
Long-term Memory
Extend agents with persistent memory across threads using LangGraph's Store. Agents can save and retrieve information from previous conversations.
There are several parameters you can pass to createDeepAgent to create your own custom deep agent.
modelBy default, deepagents uses "claude-sonnet-4-5-20250929". You can customize this by passing any LangChain model object.
import { ChatAnthropic } from "@langchain/anthropic";
import { ChatOpenAI } from "@langchain/openai";
import { createDeepAgent } from "deepagents";
// Using Anthropic
const agent = createDeepAgent({
model: new ChatAnthropic({
model: "claude-sonnet-4-20250514",
temperature: 0,
}),
});
// Using OpenAI
const agent2 = createDeepAgent({
model: new ChatOpenAI({
model: "gpt-5",
temperature: 0,
}),
});systemPromptDeep Agents come with a built-in system prompt. This is relatively detailed prompt that is heavily based on and inspired by attempts to replicate Claude Code's system prompt. It was made more general purpose than Claude Code's system prompt. The default prompt contains detailed instructions for how to use the built-in planning tool, file system tools, and sub agents.
Each deep agent tailored to a use case should include a custom system prompt specific to that use case as well. The importance of prompting for creating a successful deep agent cannot be overstated.
import { createDeepAgent } from "deepagents";
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research, and then write a polished report.`;
const agent = createDeepAgent({
systemPrompt: researchInstructions,
});toolsJust like with tool-calling agents, you can provide a deep agent with a set of tools that it has access to.
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent } from "deepagents";
import { z } from "zod";
const internetSearch = tool(
async ({
query,
maxResults = 5,
topic = "general",
includeRawContent = false,
}: {
query: string;
maxResults?: number;
topic?: "general" | "news" | "finance";
includeRawContent?: boolean;
}) => {
const tavilySearch = new TavilySearch({
maxResults,
tavilyApiKey: process.env.TAVILY_API_KEY,
includeRawContent,
topic,
});
return await tavilySearch._call({ query });
},
{
name: "internet_search",
description: "Run a web search",
schema: z.object({
query: z.string().describe("The search query"),
maxResults: z.number().optional().default(5),
topic: z
.enum(["general", "news", "finance"])
.optional()
.default("general"),
includeRawContent: z.boolean().optional().default(false),
}),
},
);
const agent = createDeepAgent({
tools: [internetSearch],
});middlewarecreateDeepAgent is implemented with middleware that can be customized. You can provide additional middleware to extend functionality, add tools, or implement custom hooks.
import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import type { AgentMiddleware } from "langchain";
import { z } from "zod";
const getWeather = tool(
async ({ city }: { city: string }) => {
return `The weather in ${city} is sunny.`;
},
{
name: "get_weather",
description: "Get the weather in a city.",
schema: z.object({
city: z.string().describe("The city to get weather for"),
}),
},
);
const getTemperature = tool(
async ({ city }: { city: string }) => {
return `The temperature in ${city} is 70 degrees Fahrenheit.`;
},
{
name: "get_temperature",
description: "Get the temperature in a city.",
schema: z.object({
city: z.string().describe("The city to get temperature for"),
}),
},
);
class WeatherMiddleware implements AgentMiddleware {
tools = [getWeather, getTemperature];
}
const agent = createDeepAgent({
model: "claude-sonnet-4-20250514",
middleware: [new WeatherMiddleware()],
});subagentsA main feature of Deep Agents is their ability to spawn subagents. You can specify custom subagents that your agent can hand off work to in the subagents parameter. Sub agents are useful for context quarantine (to help not pollute the overall context of the main agent) as well as custom instructions.
subagents should be a list of objects that follow the SubAgent interface:
interface SubAgent {
name: string;
description: string;
systemPrompt: string;
tools?: StructuredTool[];
model?: LanguageModelLike | string;
middleware?: AgentMiddleware[];
interruptOn?: Record<string, boolean | InterruptOnConfig>;
skills?: string[];
}SubAgent fields:
["/skills/research/"]). See skills inheritance below.When you configure skills on the main agent via createDeepAgent, the behavior differs between subagent types:
skills property on that subagent.const agent = createDeepAgent({
model: "claude-sonnet-4-20250514",
skills: ["/skills/"], // Main agent and general-purpose subagent get these skills
subagents: [
{
name: "researcher",
description: "Research assistant",
systemPrompt: "You are a researcher.",
// This subagent will NOT have access to /skills/ from the main agent
},
{
name: "coder",
description: "Coding assistant",
systemPrompt: "You are a coder.",
skills: ["/skills/coding/"], // This subagent has its own skills
},
],
});This design ensures context isolation - custom subagents only have access to the skills they explicitly need, preventing unintended skill leakage between specialized agents.
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent, type SubAgent } from "deepagents";
import { z } from "zod";
const internetSearch = tool(
async ({
query,
maxResults = 5,
topic = "general",
includeRawContent = false,
}: {
query: string;
maxResults?: number;
topic?: "general" | "news" | "finance";
includeRawContent?: boolean;
}) => {
const tavilySearch = new TavilySearch({
maxResults,
tavilyApiKey: process.env.TAVILY_API_KEY,
includeRawContent,
topic,
});
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),
topic: z
.enum(["general", "news", "finance"])
.optional()
.default("general"),
includeRawContent: z.boolean().optional().default(false),
}),
},
);
const researchSubagent: SubAgent = {
name: "research-agent",
description: "Used to research more in depth questions",
systemPrompt: "You are a great researcher",
tools: [internetSearch],
model: "gpt-4o", // Optional override, defaults to main agent model
};
const subagents = [researchSubagent];
const agent = createDeepAgent({
model: "claude-sonnet-4-20250514",
subagents: subagents,
});interruptOnA common reality for agents is that some tool operations may be sensitive and require human approval before execution. Deep Agents supports human-in-the-loop workflows through LangGraph's interrupt capabilities. You can configure which tools require approval using a checkpointer.
These tool configs are passed to our prebuilt HITL middleware so that the agent pauses execution and waits for feedback from the user before executing configured tools.
import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import { z } from "zod";
const getWeather = tool(
async ({ city }: { city: string }) => {
return `The weather in ${city} is sunny.`;
},
{
name: "get_weather",
description: "Get the weather in a city.",
schema: z.object({
city: z.string(),
}),
},
);
const agent = createDeepAgent({
model: "claude-sonnet-4-20250514",
tools: [getWeather],
interruptOn: {
get_weather: {
allowedDecisions: ["approve", "edit", "reject"],
},
},
});backendDeep Agents use backends to manage file system operations and memory storage. You can configure different backends depending on your needs:
import {
createDeepAgent,
StateBackend,
StoreBackend,
FilesystemBackend,
LocalShellBackend,
CompositeBackend,
} from "deepagents";
import { MemorySaver } from "@langchain/langgraph";
import { InMemoryStore } from "@langchain/langgraph-checkpoint";
// Default: StateBackend (in-memory, ephemeral)
const agent1 = createDeepAgent({
// No backend specified - uses StateBackend by default
});
// StoreBackend: Persistent storage using LangGraph Store
const agent2 = createDeepAgent({
backend: (config) => new StoreBackend(config),
store: new InMemoryStore(), // Provide a store
checkpointer: new MemorySaver(), // Optional: for conversation persistence
});
// FilesystemBackend: Store files on actual filesystem
const agent3 = createDeepAgent({
backend: (config) => new FilesystemBackend({ rootDir: "./agent-workspace" }),
});
// LocalShellBackend: Filesystem access + local shell command execution
const agent4 = createDeepAgent({
backend: new LocalShellBackend({
rootDir: "./agent-workspace",
inheritEnv: true,
}),
});
// CompositeBackend: Combine multiple backends
const agent5 = createDeepAgent({
backend: (config) =>
new CompositeBackend({
state: new StateBackend(config),
store: config.store ? new StoreBackend(config) : undefined,
}),
store: new InMemoryStore(),
checkpointer: new MemorySaver(),
});See examples/backends/ for detailed examples of each backend type.
For agents that need to run shell commands, you can create a sandbox backend by extending BaseSandbox. This enables the execute tool which allows agents to run arbitrary shell commands in an isolated environment.
import {
createDeepAgent,
BaseSandbox,
type ExecuteResponse,
type FileUploadResponse,
type FileDownloadResponse,
} from "deepagents";
import { spawn } from "child_process";
// Create a concrete sandbox by extending BaseSandbox
class LocalShellSandbox extends BaseSandbox {
readonly id = "local-shell";
private readonly workingDirectory: string;
constructor(workingDirectory: string) {
super();
this.workingDirectory = workingDirectory;
}
// Only execute() is required - BaseSandbox implements all file operations
async execute(command: string): Promise<ExecuteResponse> {
return new Promise((resolve) => {
const child = spawn("/bin/bash", ["-c", command], {
cwd: this.workingDirectory,
});
const chunks: string[] = [];
child.stdout.on("data", (data) => chunks.push(data.toString()));
child.stderr.on("data", (data) => chunks.push(data.toString()));
child.on("close", (exitCode) => {
resolve({
output: chunks.join(""),
exitCode,
truncated: false,
});
});
});
}
async uploadFiles(
files: Array<[string, Uint8Array]>,
): Promise<FileUploadResponse[]> {
// Implement file upload logic
return files.map(([path]) => ({ path, error: null }));
}
async downloadFiles(paths: string[]): Promise<FileDownloadResponse[]> {
// Implement file download logic
return paths.map((path) => ({
path,
content: null,
error: "file_not_found",
}));
}
}
// Use the sandbox with your agent
const sandbox = new LocalShellSandbox("./workspace");
const agent = createDeepAgent({
backend: sandbox,
systemPrompt: "You can run shell commands using the execute tool.",
});When using a sandbox backend, the agent gains access to an execute tool that can run shell commands. The tool automatically returns the command output, exit code, and whether the output was truncated.
See examples/sandbox/local-sandbox.ts for a complete implementation.
Deep Agents are built with a modular middleware architecture. As a reminder, Deep Agents have access to:
Each of these features is implemented as separate middleware. When you create a deep agent with createDeepAgent, we automatically attach todoListMiddleware, FilesystemMiddleware and SubAgentMiddleware to your agent.
Middleware is a composable concept, and you can choose to add as many or as few middleware to an agent depending on your use case. That means that you can also use any of the aforementioned middleware independently!
Planning is integral to solving complex problems. If you've used claude code recently, you'll notice how it writes out a To-Do list before tackling complex, multi-part tasks. You'll also notice how it can adapt and update this To-Do list on the fly as more information comes in.
todoListMiddleware provides your agent with a tool specifically for updating this To-Do list. Before, and while it executes a multi-part task, the agent is prompted to use the write_todos tool to keep track of what its doing, and what still needs to be done.
import { createAgent, todoListMiddleware } from "langchain";
// todoListMiddleware is included by default in createDeepAgent
// You can customize it if building a custom agent
const agent = createAgent({
model: "claude-sonnet-4-20250514",
middleware: [
todoListMiddleware({
// Optional: Custom addition to the system prompt
systemPrompt: "Use the write_todos tool to...",
}),
],
});Context engineering is one of the main challenges in building effective agents. This can be particularly hard when using tools that can return variable length results (ex. web_search, rag), as long ToolResults can quickly fill up your context window.
FilesystemMiddleware provides tools to your agent to interact with both short-term and long-term memory:
SandboxBackendProtocol)import { createAgent } from "langchain";
import { createFilesystemMiddleware } from "deepagents";
// FilesystemMiddleware is included by default in createDeepAgent
// You can customize it if building a custom agent
const agent = createAgent({
model: "claude-sonnet-4-20250514",
middleware: [
createFilesystemMiddleware({
backend: ..., // Optional: customize storage backend
systemPrompt: "Write to the filesystem when...", // Optional custom system prompt override
customToolDescriptions: {
ls: "Use the ls tool when...",
read_file: "Use the read_file tool to...",
}, // Optional: Custom descriptions for filesystem tools
}),
],
});Handing off tasks to subagents is a great way to isolate context, keeping the context window of the main (supervisor) agent clean while still going deep on a task. The subagents middleware allows you supply subagents through a task tool.
A subagent is defined with a name, description, system prompt, and tools. You can also provide a subagent with a custom model, or with additional middleware. This can be particularly useful when you want to give the subagent an additional state key to share with the main agent.
import { tool } from "langchain";
import { createAgent } from "langchain";
import { createSubAgentMiddleware, type SubAgent } from "deepagents";
import { z } from "zod";
const getWeather = tool(
async ({ city }: { city: string }) => {
return `The weather in ${city} is sunny.`;
},
{
name: "get_weather",
description: "Get the weather in a city.",
schema: z.object({
city: z.string(),
}),
},
);
const weatherSubagent: SubAgent = {
name: "weather",
description: "This subagent can get weather in cities.",
systemPrompt: "Use the get_weather tool to get the weather in a city.",
tools: [getWeather],
model: "gpt-4o",
middleware: [],
};
const agent = createAgent({
model: "claude-sonnet-4-20250514",
middleware: [
createSubAgentMiddleware({
defaultModel: "claude-sonnet-4-20250514",
defaultTools: [],
subagents: [weatherSubagent],
}),
],
});Deep Agents can be exposed as an Agent Client Protocol server, enabling integration with IDEs like Zed, JetBrains, and other ACP-compatible clients through a standardized JSON-RPC 2.0 protocol over stdio.
The deepagents-acp package wraps your Deep Agent with ACP support:
npm install deepagents-acpThe quickest way to get started is via the CLI:
npx deepagents-acp --name my-agent --workspace /path/to/projectOr programmatically:
import { startServer } from "deepagents-acp";
await startServer({
agents: {
name: "coding-assistant",
description: "AI coding assistant with filesystem access",
skills: ["./skills/"],
},
workspaceRoot: process.cwd(),
});To use with Zed, add the following to your Zed settings:
{
"agent": {
"profiles": {
"deepagents": {
"name": "DeepAgents",
"command": "npx",
"args": ["deepagents-acp"]
}
}
}
}See the deepagents-acp README and the ACP server example for full documentation and advanced configuration.
Base sandbox implementation with execute() as the only abstract method.
Backend that routes file operations to different backends based on path prefix.
Backend that reads and writes files directly from the filesystem.
Filesystem backend with unrestricted local shell command execution.
Custom error class for sandbox operations.
Backend that stores files in agent state (ephemeral).
Backend that stores files in LangGraph's BaseStore (persistent).
Base sandbox implementation with execute() as the only abstract method.
Backend that routes file operations to different backends based on path prefix.
Backend that reads and writes files directly from the filesystem.
Filesystem backend with unrestricted local shell command execution.
Custom error class for sandbox operations.
Backend that stores files in agent state (ephemeral).
Backend that stores files in LangGraph's BaseStore (persistent).
Create a Deep Agent with middleware-based architecture.
Group structured matches into the legacy dict form used by formatters.
Check if content is empty and return warning message.
Create a FileData object with timestamps.
Convert FileData to plain string content.
Format file content with line numbers (cat -n style).
Format structured grep matches using existing formatting logic.
Format grep search results based on output mode.
Format file data for read response with line numbers.
Search files dict for paths matching glob pattern.
Return structured grep matches from an in-memory files mapping.
Search file contents for literal text pattern.
Perform string replacement with occurrence validation.
Sanitize tool_call_id to prevent path traversal and separator issues.
Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).
Update FileData with new content, preserving creation timestamp.
Validate and normalize a file path for security.
Validate and normalize a directory path.
Type guard to check if a backend supports execution.
Create a Settings instance with detected environment.
Find the project root by looking for .git directory.
Extract the text content of the last step in a trajectory.
Invoke a deepagent with a user query and optional pre-seeded files,
Create a Deep Agent with middleware-based architecture.
Compute summarization defaults based on model profile.
Create filesystem middleware with all tools and features.
Create middleware for loading agent memory from AGENTS.md files.
Create middleware that patches dangling tool calls in the messages history.
Create backend-agnostic middleware for loading and exposing agent skills.
Create subagent middleware with task tool
Create summarization middleware with backend support for conversation history offloading.
Type guard to check if a backend supports execution.
List skills from user and/or project directories.
Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
Create a Deep Agent with middleware-based architecture.
Create a Settings instance with detected environment.
Find the project root by looking for .git directory.
Append text to a system message.
Create a preview of content showing head and tail with truncation marker.
Patch dangling tool calls in a messages array.
Prepend text to a system message.
Compute summarization defaults based on model profile.
Create filesystem middleware with all tools and features.
Create middleware for loading agent memory from AGENTS.md files.
Create middleware that patches dangling tool calls in the messages history.
Create backend-agnostic middleware for loading and exposing agent skills.
Create subagent middleware with task tool
Create summarization middleware with backend support for conversation history offloading.
List skills from user and/or project directories.
Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
Create middleware for loading agent-specific long-term memory.