> ## Documentation Index > Fetch the complete documentation index at: https://docs.langchain.com/llms.txt > Use this file to discover all available pages before exploring further. # Build a deep research agent > Build a multi-step web research agent with subagent delegation ## Overview This guide demonstrates how to build a multi-step web research agent from scratch using [Deep Agents](/oss/javascript/deepagents). The agent decomposes research questions into focused tasks, delegates them to specialized sub-agents, and synthesizes findings into a comprehensive report. The agent you build will: 1. Plan research using a todo list 2. Delegate focused research tasks to sub-agents with isolated context 3. Assess search results and plan next steps as you gather information 4. Synthesize findings with proper citations into a final report The spawned sub-agents will conduct web searches with Tavily, fetching full webpage content for analysis. ### Key concepts This tutorial covers: * [Subagents](/oss/javascript/deepagents/subagents) for parallel, context-isolated research * Custom [tools](/oss/javascript/langchain/tools) for web search * Multi-step planning with the [built-in planning tool](/oss/javascript/deepagents/harness#planning-capabilities) ## Prerequisites API keys for: * Anthropic (Claude) or Google (Gemini) * [Tavily](https://www.tavily.com/) for web search (optional - free tier sufficient) * [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-deepagents-deep-research) for tracing (optional) ## Setup ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} mkdir deep-research-agent cd deep-research-agent ``` ```bash npm wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npm install deepagents @langchain/anthropic @langchain/core ``` ```bash npm wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npm install deepagents @langchain/google-genai @langchain/core ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export ANTHROPIC_API_KEY="your_anthropic_api_key" export TAVILY_API_KEY="your_tavily_api_key" export LANGSMITH_API_KEY="your_langsmith_api_key" # Optional ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export GOOGLE_API_KEY="your_google_api_key" export TAVILY_API_KEY="your_tavily_api_key" export LANGSMITH_API_KEY="your_langsmith_api_key" # Optional ``` ## Build the agent Create `agent.ts` in your project directory: Add the custom search tool. The `tavily_search` tool uses Tavily for URL discovery, then fetches full webpage content so the agent can analyze complete sources instead of summaries. ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { tool } from "langchain"; import { z } from "zod"; async function fetchWebpageContent( url: string, timeout = 10_000, ): Promise { try { const controller = new AbortController(); const id = setTimeout(() => controller.abort(), timeout); const response = await fetch(url, { headers: { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", }, signal: controller.signal, }); clearTimeout(id); if (!response.ok) { return `Error fetching ${url}: HTTP ${response.status}`; } return await response.text(); } catch (e) { return `Error fetching ${url}: ${e}`; } } const tavilySearch = tool( async ({ query, maxResults = 1, topic = "general", }: { query: string; maxResults?: number; topic?: "general" | "news" | "finance"; }) => { const response = await fetch("https://api.tavily.com/search", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.TAVILY_API_KEY}`, }, body: JSON.stringify({ query, max_results: maxResults, topic }), }); const data = (await response.json()) as { results: Array<{ url: string; title: string }>; }; const results = data.results ?? []; const resultTexts: string[] = []; for (const result of results) { const content = await fetchWebpageContent(result.url); resultTexts.push( `## ${result.title}\n**URL:** ${result.url}\n\n${content}\n---`, ); } return ( `Found ${resultTexts.length} result(s) for '${query}':\n\n` + resultTexts.join("\n") ); }, { name: "tavily_search", description: "Search the web for information on a given query. Uses Tavily to discover relevant URLs, then fetches and returns full webpage content.", schema: z.object({ query: z.string().describe("Search query to execute"), maxResults: z .number() .optional() .default(1) .describe("Maximum number of results to return (default: 1)"), topic: z .enum(["general", "news", "finance"]) .optional() .default("general") .describe( "Topic filter - 'general', 'news', or 'finance' (default: 'general')", ), }), }, ); ``` Add the orchestrator workflow and sub-agent prompt templates to `agent.ts`: ```ts expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const RESEARCH_WORKFLOW_INSTRUCTIONS = `# Research Workflow Follow this workflow for all research requests: 1. **Plan**: Create a todo list with write_todos to break down the research into focused tasks 2. **Save the request**: Use write_file() to save the user's research question to \`/research_request.md\` 3. **Research**: Delegate research tasks to sub-agents using the task() tool - ALWAYS use sub-agents for research, never conduct research yourself 4. **Synthesize**: Review all sub-agent findings and consolidate citations (each unique URL gets one number across all findings) 5. **Write Report**: Write a comprehensive final report to \`/final_report.md\` (see Report Writing Guidelines below) 6. **Verify**: Read \`/research_request.md\` and confirm you've addressed all aspects with proper citations and structure ## Research Planning Guidelines - Batch similar research tasks into a single TODO to minimize overhead - For simple fact-finding questions, use 1 sub-agent - For comparisons or multi-faceted topics, delegate to multiple parallel sub-agents - Each sub-agent should research one specific aspect and return findings ## Report Writing Guidelines When writing the final report to \`/final_report.md\`, follow these structure patterns: **For comparisons:** 1. Introduction 2. Overview of topic A 3. Overview of topic B 4. Detailed comparison 5. Conclusion **For lists/rankings:** Simply list items with details - no introduction needed: 1. Item 1 with explanation 2. Item 2 with explanation 3. Item 3 with explanation **For summaries/overviews:** 1. Overview of topic 2. Key concept 1 3. Key concept 2 4. Key concept 3 5. Conclusion **General guidelines:** - Use clear section headings (## for sections, ### for subsections) - Write in paragraph form by default - be text-heavy, not just bullet points - Do NOT use self-referential language ("I found...", "I researched...") - Write as a professional report without meta-commentary - Each section should be comprehensive and detailed - Use bullet points only when listing is more appropriate than prose **Citation format:** - Cite sources inline using [1], [2], [3] format - Assign each unique URL a single citation number across ALL sub-agent findings - End report with ### Sources section listing each numbered source - Number sources sequentially without gaps (1,2,3,4...) - Format: [1] Source Title: URL (each on separate line for proper list rendering) - Example: Some important finding [1]. Another key insight [2]. ### Sources [1] AI Research Paper: https://example.com/paper [2] Industry Analysis: https://example.com/analysis `; ``` ```ts expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const RESEARCHER_INSTRUCTIONS = `You are a research assistant conducting research on the user's input topic. For context, today's date is {date}. Your job is to use tools to gather information about the user's input topic. You can use the tavily_search tool to find resources that can help answer the research question. You can call it in series or in parallel, your research is conducted in a tool-calling loop. You have access to the tavily_search tool for conducting web searches. Think like a human researcher with limited time. Follow these steps: 1. **Read the question carefully** - What specific information does the user need? 2. **Start with broader searches** - Use broad, comprehensive queries first 3. **After each search, pause and assess** - Do I have enough to answer? What's still missing? 4. **Execute narrower searches as you gather information** - Fill in the gaps 5. **Stop when you can answer confidently** - Don't keep searching for perfection **Tool Call Budgets** (Prevent excessive searching): - **Simple queries**: Use 2-3 search tool calls maximum - **Complex queries**: Use up to 5 search tool calls maximum - **Always stop**: After 5 search tool calls if you cannot find the right sources **Stop Immediately When**: - You can answer the user's question comprehensively - You have 3+ relevant examples/sources for the question - Your last 2 searches returned similar information After each search, assess results before continuing: What key information did I find? What's missing? Do I have enough to answer? Should I search more or provide my answer? When providing your findings back to the orchestrator: 1. **Structure your response**: Organize findings with clear headings and detailed explanations 2. **Cite sources inline**: Use [1], [2], [3] format when referencing information from your searches 3. **Include Sources section**: End with ### Sources listing each numbered source with title and URL Example: ## Key Findings Context engineering is a critical technique for AI agents [1]. Studies show that proper context management can improve performance by 40% [2]. ### Sources [1] Context Engineering Guide: https://example.com/context-guide [2] AI Performance Study: https://example.com/study The orchestrator will consolidate citations from all sub-agents into the final report. `; ``` ```ts expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const SUBAGENT_DELEGATION_INSTRUCTIONS = `# Sub-Agent Research Coordination Your role is to coordinate research by delegating tasks from your TODO list to specialized research sub-agents. ## Delegation Strategy **DEFAULT: Start with 1 sub-agent** for most queries: - "What is quantum computing?" -> 1 sub-agent (general overview) - "List the top 10 coffee shops in San Francisco" -> 1 sub-agent - "Summarize the history of the internet" -> 1 sub-agent - "Research context engineering for AI agents" -> 1 sub-agent (covers all aspects) **ONLY parallelize when the query EXPLICITLY requires comparison or has clearly independent aspects:** **Explicit comparisons** -> 1 sub-agent per element: - "Compare OpenAI vs Anthropic vs DeepMind AI safety approaches" -> 3 parallel sub-agents - "Compare Python vs JavaScript for web development" -> 2 parallel sub-agents **Clearly separated aspects** -> 1 sub-agent per aspect (use sparingly): - "Research renewable energy adoption in Europe, Asia, and North America" -> 3 parallel sub-agents (geographic separation) - Only use this pattern when aspects cannot be covered efficiently by a single comprehensive search ## Key Principles - **Bias towards single sub-agent**: One comprehensive research task is more token-efficient than multiple narrow ones - **Avoid premature decomposition**: Don't break "research X" into "research X overview", "research X techniques", "research X applications" - just use 1 sub-agent for all of X - **Parallelize only for clear comparisons**: Use multiple sub-agents when comparing distinct entities or geographically separated data ## Parallel Execution Limits - Use at most {maxConcurrentResearchUnits} parallel sub-agents per iteration - Make multiple task() calls in a single response to enable parallel execution - Each sub-agent returns findings independently ## Research Limits - Stop after {maxResearcherIterations} delegation rounds if you haven't found adequate sources - Stop when you have sufficient information to answer comprehensively - Bias towards focused research over exhaustive exploration`; ``` Add the model initialization and agent creation to `agent.ts`: ```ts Google theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "google-genai:gemini-3.1-pro-preview", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "openai:gpt-5.4", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts Anthropic theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "anthropic:claude-sonnet-4-6", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts OpenRouter theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "openrouter:anthropic/claude-sonnet-4-6", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts Fireworks theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "fireworks:accounts/fireworks/models/qwen3p5-397b-a17b", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts Baseten theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "baseten:zai-org/GLM-5", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ```ts Ollama theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; import { ChatAnthropic } from "@langchain/anthropic"; const maxConcurrentResearchUnits = 3; const maxResearcherIterations = 3; const currentDate = new Date().toISOString().split("T")[0]; const INSTRUCTIONS = RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=".repeat(80) + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.replace( "{maxConcurrentResearchUnits}", String(maxConcurrentResearchUnits), ).replace("{maxResearcherIterations}", String(maxResearcherIterations)); const researchSubAgent = { name: "research-agent", description: "Delegate research to the sub-agent. Give one topic at a time.", systemPrompt: RESEARCHER_INSTRUCTIONS.replace("{date}", currentDate), tools: [tavilySearch], }; const model = new ChatAnthropic({ model: "ollama:devstral-2", temperature: 0, }); const agent = createDeepAgent({ model, tools: [tavilySearch], systemPrompt: INSTRUCTIONS, subagents: [researchSubAgent], }); ``` ## Run the agent You can run the agent synchronously, meaning it will wait for the full result and then print it, or you can stream updates as they come in. Add the code from the respective tab at the bottom of `agent.ts`: ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { async function main() { const result = await agent.invoke({ messages: [ { role: "user", content: "What are the main differences between RAG and fine-tuning for LLM applications?", }, ], }); for (const msg of result.messages ?? []) { if (msg.content) { console.log(msg.content); } } } main().catch((err) => { console.error(err); process.exitCode = 1; }); } ``` ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { async function main() { for await (const chunk of await agent.stream( { messages: [ { role: "user", content: "Compare Python vs JavaScript for web development", }, ], }, { streamMode: "updates" }, )) { for (const [, update] of Object.entries(chunk)) { const messages = (update as any)?.messages; if (!messages) continue; const msgList = Array.isArray(messages) ? messages : [messages]; for (const msg of msgList) { if (msg.content) { console.log(msg.content); } } } } } main().catch((err) => { console.error(err); process.exitCode = 1; }); } ``` Run the agent from the project root: ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npx tsx agent.ts ``` If you set the `LANGSMITH_API_KEY` environment variable before running, you can view the agent's traces in [LangSmith](/langsmith/home) to debug and monitor multi-step behavior. ## Full code View the complete [Deep Research example](https://github.com/langchain-ai/deepagents/tree/main/examples/deep_research) on GitHub. ## Next steps Now that you've built the agent, customize it by changing the prompt constants in your agent file to adjust the workflow, delegation strategy, or researcher behavior. You can also tune the delegation limits to allow for more parallel sub-agents or delegation rounds. For more information on the concepts in this tutorial, check out the following resources: * [Subagents](/oss/javascript/deepagents/subagents): Learn how to configure subagents with different tools and prompts * [Customization](/oss/javascript/deepagents/customization): Customize models, tools, system prompts, and planning behavior * [LangSmith](/langsmith/home): Trace research runs and debug multi-step behavior * [Deep Research Course](https://academy.langchain.com/courses/deep-research-with-langgraph): Full course on deep research with LangGraph ***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/deep-research.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).