Skip to content

deep-research.mdx

Latest commit

 

History

History
333 lines (252 loc) · 8.67 KB

deep-research.mdx

File metadata and controls

333 lines (252 loc) · 8.67 KB
Raw
title Build a deep research agent
sidebarTitle Deep Research
description Build a multi-step web research agent with subagent delegation

import DeepResearchToolsPy from '/snippets/code-samples/deep-research-tools-py.mdx'; import DeepResearchAgentClaudePy from '/snippets/code-samples/deep-research-agent-claude-py.mdx'; import DeepResearchRunSyncPy from '/snippets/code-samples/deep-research-run-sync-py.mdx'; import DeepResearchRunStreamPy from '/snippets/code-samples/deep-research-run-stream-py.mdx'; import DeepResearchToolsJs from '/snippets/code-samples/deep-research-tools-js.mdx'; import DeepResearchAgentClaudeJs from '/snippets/code-samples/deep-research-agent-claude-js.mdx'; import DeepResearchRunSyncJs from '/snippets/code-samples/deep-research-run-sync-js.mdx'; import DeepResearchRunStreamJs from '/snippets/code-samples/deep-research-run-stream-js.mdx'; import DeepResearchWorkflowInstructionsPy from '/snippets/code-samples/deep-research-workflow-instructions-py.mdx'; import DeepResearchWorkflowInstructionsJs from '/snippets/code-samples/deep-research-workflow-instructions-js.mdx'; import DeepResearchResearcherInstructionsPy from '/snippets/code-samples/deep-research-researcher-instructions-py.mdx'; import DeepResearchResearcherInstructionsJs from '/snippets/code-samples/deep-research-researcher-instructions-js.mdx'; import DeepResearchSubagentDelegationInstructionsPy from '/snippets/code-samples/deep-research-subagent-delegation-instructions-py.mdx'; import DeepResearchSubagentDelegationInstructionsJs from '/snippets/code-samples/deep-research-subagent-delegation-instructions-js.mdx'; import DeepResearchAgentGeminiPy from '/snippets/code-samples/deep-research-agent-gemini-py.mdx';

Overview

This guide demonstrates how to build a multi-step web research agent from scratch using Deep Agents. 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 the opt-in todo list middleware
  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:

Prerequisites

API keys for:

  • Anthropic (Claude) or Google (Gemini)
  • Tavily for web search (optional - free tier sufficient)
  • LangSmith for tracing (optional)

Setup

:::python 

mkdir deep-research-agent
cd deep-research-agent
```bash pip wrap pip install deepagents tavily-python httpx markdownify langchain-anthropic langchain-core ``` 
uv init
uv add deepagents tavily-python httpx markdownify langchain-anthropic langchain-core
uv sync
```bash pip wrap pip install deepagents tavily-python httpx markdownify langchain-google-genai langchain-core ``` 
uv init
uv add deepagents tavily-python httpx markdownify langchain-google-genai langchain-core
uv sync
```bash 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 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 ``` :::

:::js 

mkdir deep-research-agent
cd deep-research-agent
```bash npm wrap npm install deepagents @langchain/anthropic @langchain/core ``` ```bash npm wrap npm install deepagents @langchain/google-genai @langchain/core ``` ```bash 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 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

:::python Create agent.py in your project directory: :::

:::js 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.

:::python :::

:::js :::

:::python Add the orchestrator workflow and sub-agent prompt templates to agent.py: :::

:::js Add the orchestrator workflow and sub-agent prompt templates to agent.ts: :::

:::python

:::

:::js

:::

Task planning is opt-in. The research workflow uses write_todos to break questions into focused tasks, so pass @[TodoListMiddleware] when you create the agent.

:::python

from langchain.agents.middleware import TodoListMiddleware

:::

:::js

import { todoListMiddleware } from "langchain";

:::

You include this middleware in the next step when you create the agent.

:::python Add the model initialization and agent creation to agent.py. Choose your provider. Include @[TodoListMiddleware] so the planning tool is available:

:::

:::js Add the model initialization and agent creation to agent.ts. Include todoListMiddleware so the planning tool is available:

:::

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.

:::python Add the code from the respective tab at the bottom of agent.py: :::

:::js Add the code from the respective tab at the bottom of agent.ts: :::

:::python :::

:::js :::

:::python :::

:::js :::

Run the agent from the project root:

:::python

python agent.py

:::

:::js

npx tsx agent.ts

:::

If you set the LANGSMITH_API_KEY environment variable before running, you can view the agent's traces in LangSmith to debug and monitor multi-step behavior.

Full code

View the complete Deep Research example 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: