How langchain-ai/open_deep_research works
Purpose and Entry Points
Open Deep Research is a configurable Python/LangGraph deep-research agent: it turns a user messages request into a sourced research report through iterative search and LLM reasoning. The production graph is exposed to LangGraph Server/Studio via langgraph.json; core implementation is in src/open_deep_research/deep_researcher.py. Local operation uses langgraph dev, while the same graph can deploy to LangGraph Platform or be configured through OAP.
Graph Orchestration
src/open_deep_research/deep_researcher.py defines the current agent workflow and its node/control transitions. It coordinates query generation, searching, research iteration, compression, and final writing rather than exposing a conventional HTTP application. The input/output and intermediate graph state are defined separately in src/open_deep_research/state.py, forming the key persistence/checkpoint boundary used by LangGraph.
Configuration and Model Routing
src/open_deep_research/configuration.py centralizes runtime-selectable behavior: distinct models for result summarization, research/tool use, compression, and final reporting; search API selection; and MCP configuration. It relies on LangChain’s provider-neutral chat-model initialization, so model providers are external runtime dependencies rather than hardwired integrations. Environment-backed credentials and defaults are represented by .env.example.
Research and Search Stage
The graph’s research agent uses a tool-calling/structured-output-capable LLM to formulate and refine searches, then invokes a configured search backend. Default search is Tavily; supported alternatives include native OpenAI/Anthropic web search and MCP-provided tools. Search result handling and common integration logic are concentrated in src/open_deep_research/utils.py; prompt contracts are in src/open_deep_research/prompts.py.
Evidence Synthesis and Report Generation
Retrieved evidence passes through a lower-cost summarization path, followed by research finding compression to control context size. The final report model consumes the accumulated/compressed findings and produces the user-facing report. This separates high-volume retrieval processing from the more expensive research and final-writing models, with state in src/open_deep_research/state.py carrying artifacts across stages.
External Services and Runtime Boundaries
Material integrations are LangGraph Server/Studio for graph execution and interactive configuration, LangChain model providers for LLM calls, Tavily or alternate web-search services, and MCP servers for externally supplied tools. LangSmith is used for public datasets, experiments, and evaluation result extraction. The project is Python-based, dependency-managed with pyproject.toml and uv.lock.
Evaluation and Historical Architectures
The benchmark pipeline runs Deep Research Bench workloads through LangSmith, evaluates reports with an external LLM-as-judge workflow, and exports submission JSONL. Its operational entry points are tests/run_evaluate.py and tests/extract_langsmith_data.py. Earlier, non-primary approaches remain isolated under src/legacy/graph.py (plan/execute with human approval) and src/legacy/multi_agent.py (parallel supervisor/researcher design); they should not be confused with the current graph.
Main entry points: deep_researcher.py Deep researcher graph · configuration.py Runtime configuration · langgraph.json LangGraph Server / Studio · run_evaluate.py Benchmark runner
Components 19
Runtime
- User messages
- LangGraph Server / Studio · Serves and configures the production graph.
langgraph.json - Runtime configuration · Selects models, search API, and MCP settings.
src/open_deep_research/configuration.py
Current research graph
- Deep researcher graph · Coordinates iterative research through final reporting.
src/open_deep_research/deep_researcher.py - Research state · Carries requests, evidence, and findings between graph stages.
src/open_deep_research/state.py - Query generation
src/open_deep_research/deep_researcher.py - Research iteration · Refines searches and directs tool use.
src/open_deep_research/deep_researcher.py - Evidence summarization · Processes high-volume retrieved results with a lower-cost model.
src/open_deep_research/deep_researcher.py - Finding compression · Reduces accumulated research context.
src/open_deep_research/deep_researcher.py - Final report writing · Produces the sourced user-facing report.
src/open_deep_research/deep_researcher.py - Prompt and integration contracts · Defines prompt contracts and common search-result handling.
src/open_deep_research/prompts.py
External services
- Configured web search · Uses Tavily by default, native provider search, or MCP tools.
- LangChain model providers · Provider-neutral chat-model initialization supplies role-specific models.
- MCP servers
Evaluation pipeline
- Benchmark runner · Runs Deep Research Bench workloads through LangSmith.
tests/run_evaluate.py - LangSmith · Hosts datasets, experiments, and evaluation results.
- Submission JSONL export · Extracts LangSmith results into submission data.
tests/extract_langsmith_data.py
Other components
- Legacy plan/execute graph · Non-primary workflow with human approval.
src/legacy/graph.py - Legacy multi-agent design · Non-primary parallel supervisor/researcher design.
src/legacy/multi_agent.py
Connections 19
- User messages → LangGraph Server / Studio: submits request
- LangGraph Server / Studio → Deep researcher graph: hosts
- Deep researcher graph → Query generation: starts
- Query generation → Research iteration: search queries
- Research iteration → Configured web search: invokes
- Configured web search → Evidence summarization: retrieved evidence
- Evidence summarization → Finding compression: summaries
- Finding compression → Final report writing: compressed findings
- Final report writing → User messages: returns report
- Deep researcher graph → Research state: reads and persists artifacts
- Runtime configuration → Deep researcher graph: configures
- Runtime configuration → LangChain model providers: selects models
- Runtime configuration → Configured web search: selects backend
- Runtime configuration → MCP servers: loads tool settings
- MCP servers → Configured web search: may provide tools
- Prompt and integration contracts → Deep researcher graph: supports stages
- Benchmark runner → LangGraph Server / Studio: runs graph workloads
- Benchmark runner → LangSmith: uses datasets and logs experiments
- LangSmith → Submission JSONL export: evaluation results