# langchain-ai/open_deep_research architecture

> Architecture diagram of the GitHub repository langchain-ai/open_deep_research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/open_deep_research
- Repository: https://github.com/langchain-ai/open_deep_research

## Overview

#### 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: [`src/open_deep_research/deep_researcher.py`](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py) (Deep researcher graph), [`src/open_deep_research/configuration.py`](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/configuration.py) (Runtime configuration), [`langgraph.json`](https://github.com/langchain-ai/open_deep_research/blob/main/langgraph.json) (LangGraph Server / Studio), [`tests/run_evaluate.py`](https://github.com/langchain-ai/open_deep_research/blob/main/tests/run_evaluate.py) (Benchmark runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_user_request["User messages<br/>agent input"]
  node_langgraph_server{{"LangGraph Server / Studio<br/>graph host<br/>[langgraph.json]"}}
  node_configuration["Runtime configuration<br/>configuration layer<br/>[configuration.py]"]
end

subgraph group_workflow["Current research graph"]
  node_research_graph{{"Deep researcher graph<br/>LangGraph workflow<br/>[deep_researcher.py]"}}
  node_research_state[("Research state<br/>checkpointed state<br/>[state.py]")]
  node_query_generation["Query generation<br/>graph stage<br/>[deep_researcher.py]"]
  node_research_iteration["Research iteration<br/>graph stage<br/>[deep_researcher.py]"]
  node_evidence_summarization["Evidence summarization<br/>graph stage<br/>[deep_researcher.py]"]
  node_finding_compression["Finding compression<br/>graph stage<br/>[deep_researcher.py]"]
  node_final_report["Final report writing<br/>graph stage<br/>[deep_researcher.py]"]
  node_prompts_utils["Prompt and integration contracts<br/>shared workflow support<br/>[prompts.py]"]
end

subgraph group_integrations["External services"]
  node_search_backend{{"Configured web search<br/>tool integration"}}
  node_model_providers{{"LangChain model providers<br/>LLM runtime dependency"}}
  node_mcp_servers{{"MCP servers<br/>external tool source"}}
end

subgraph group_evaluation["Evaluation pipeline"]
  node_evaluation_runner["Benchmark runner<br/>evaluation entry point<br/>[run_evaluate.py]"]
  node_langsmith{{"LangSmith<br/>datasets and experiment service"}}
  node_result_export["Submission JSONL export<br/>evaluation entry point"]
end

node_legacy_graph["Legacy plan/execute graph<br/>historical architecture<br/>[graph.py]"]
node_legacy_multi_agent["Legacy multi-agent design<br/>historical architecture<br/>[multi_agent.py]"]

node_user_request -->|"submits request"| node_langgraph_server
node_langgraph_server -->|"hosts"| node_research_graph
node_research_graph -->|"starts"| node_query_generation
node_query_generation -->|"search queries"| node_research_iteration
node_research_iteration -->|"invokes"| node_search_backend
node_search_backend -->|"retrieved evidence"| node_evidence_summarization
node_evidence_summarization -->|"summaries"| node_finding_compression
node_finding_compression -->|"compressed findings"| node_final_report
node_final_report -->|"returns report"| node_user_request
node_research_graph -->|"reads and persists artifacts"| node_research_state
node_configuration -.->|"configures"| node_research_graph
node_configuration -.->|"selects models"| node_model_providers
node_configuration -.->|"selects backend"| node_search_backend
node_configuration -.->|"loads tool settings"| node_mcp_servers
node_mcp_servers -.->|"may provide tools"| node_search_backend
node_prompts_utils -.->|"supports stages"| node_research_graph
node_evaluation_runner -->|"runs graph workloads"| node_langgraph_server
node_evaluation_runner -->|"uses datasets and logs experiments"| node_langsmith
node_langsmith -->|"evaluation results"| node_result_export

click node_langgraph_server "https://github.com/langchain-ai/open_deep_research/blob/main/langgraph.json"
click node_research_graph "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_research_state "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/state.py"
click node_query_generation "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_research_iteration "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_evidence_summarization "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_finding_compression "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_final_report "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py"
click node_configuration "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/configuration.py"
click node_prompts_utils "https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/prompts.py"
click node_evaluation_runner "https://github.com/langchain-ai/open_deep_research/blob/main/tests/run_evaluate.py"
click node_result_export "https://github.com/langchain-ai/open_deep_research/blob/main/tests/extract_langsmith_data.py"
click node_legacy_graph "https://github.com/langchain-ai/open_deep_research/blob/main/src/legacy/graph.py"
click node_legacy_multi_agent "https://github.com/langchain-ai/open_deep_research/blob/main/src/legacy/multi_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user_request,node_langgraph_server,node_configuration toneBlue
class node_research_graph,node_research_state,node_query_generation,node_research_iteration,node_evidence_summarization,node_finding_compression,node_final_report,node_prompts_utils toneAmber
class node_search_backend,node_model_providers,node_mcp_servers toneMint
class node_evaluation_runner,node_langsmith,node_result_export toneRose
class node_legacy_graph,node_legacy_multi_agent toneNeutral
```

## Components

### Runtime

- **User messages**: agent input
- [LangGraph Server / Studio](https://github.com/langchain-ai/open_deep_research/blob/main/langgraph.json): graph host · Serves and configures the production graph. · `langgraph.json`
- [Runtime configuration](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/configuration.py): configuration layer · Selects models, search API, and MCP settings. · `src/open_deep_research/configuration.py`

### Current research graph

- [Deep researcher graph](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): LangGraph workflow · Coordinates iterative research through final reporting. · `src/open_deep_research/deep_researcher.py`
- [Research state](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/state.py): checkpointed state · Carries requests, evidence, and findings between graph stages. · `src/open_deep_research/state.py`
- [Query generation](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): graph stage · `src/open_deep_research/deep_researcher.py`
- [Research iteration](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): graph stage · Refines searches and directs tool use. · `src/open_deep_research/deep_researcher.py`
- [Evidence summarization](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): graph stage · Processes high-volume retrieved results with a lower-cost model. · `src/open_deep_research/deep_researcher.py`
- [Finding compression](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): graph stage · Reduces accumulated research context. · `src/open_deep_research/deep_researcher.py`
- [Final report writing](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py): graph stage · Produces the sourced user-facing report. · `src/open_deep_research/deep_researcher.py`
- [Prompt and integration contracts](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/prompts.py): shared workflow support · Defines prompt contracts and common search-result handling. · `src/open_deep_research/prompts.py`

### External services

- **Configured web search**: tool integration · Uses Tavily by default, native provider search, or MCP tools.
- **LangChain model providers**: LLM runtime dependency · Provider-neutral chat-model initialization supplies role-specific models.
- **MCP servers**: external tool source

### Evaluation pipeline

- [Benchmark runner](https://github.com/langchain-ai/open_deep_research/blob/main/tests/run_evaluate.py): evaluation entry point · Runs Deep Research Bench workloads through LangSmith. · `tests/run_evaluate.py`
- **LangSmith**: datasets and experiment service · Hosts datasets, experiments, and evaluation results.
- [Submission JSONL export](https://github.com/langchain-ai/open_deep_research/blob/main/tests/extract_langsmith_data.py): evaluation entry point · Extracts LangSmith results into submission data. · `tests/extract_langsmith_data.py`

### Other components

- [Legacy plan/execute graph](https://github.com/langchain-ai/open_deep_research/blob/main/src/legacy/graph.py): historical architecture · Non-primary workflow with human approval. · `src/legacy/graph.py`
- [Legacy multi-agent design](https://github.com/langchain-ai/open_deep_research/blob/main/src/legacy/multi_agent.py): historical architecture · Non-primary parallel supervisor/researcher design. · `src/legacy/multi_agent.py`

## Connections

- 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
