web-research

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:

1. Planning Tool - Strategic task decomposition
2. Sub-Agents - Specialized agents for subtasks
3. File System Access - Persistent state and memory
4. Detailed Prompts - Context-rich instructions

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.

• 🎯 Task Planning & Decomposition - Break complex tasks into manageable steps
• 🤖 Sub-Agent Architecture - Delegate specialized work to focused agents
• 💾 File System Integration - Persistent memory and state management
• 🌊 Streaming Support - Real-time updates, token streaming, and progress tracking
• 🔄 LangGraph Powered - Built on the robust LangGraph framework
• 📝 TypeScript First - Full type safety and IntelliSense support
• 🔌 Extensible - Easy to customize and extend for your use case

```bash

# 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](https://www.tavily.com/).

```typescript

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.

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](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.

`model`

By default, deepagents uses "claude-sonnet-4-5-20250929". You can customize this by passing any [LangChain model object](https://js.langchain.com/docs/integrations/chat/).

```typescript

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,

}),

});

```

`systemPrompt`

Deep Agents come with a built-in system prompt. This is relatively detailed prompt that is heavily based on and inspired by [attempts](https://github.com/kn1026/cc/blob/main/claudecode.md) to [replicate](https://github.com/asgeirtj/system_prompts_leaks/blob/main/Anthropic/claude-code.md)

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.

```typescript

import { createDeepAgent } from "deepagents";

const researchInstructions = `You are an expert researcher. Your job is to conduct thorough rese