# ai-doneus/deep-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ai-doneus/deep-research-agent
- Repository: https://github.com/ai-doneus/deep-research-agent

## Overview

Deep-Research-Agent is a LangGraph research assistant: it accepts a query, scopes it into a brief, researches that brief with web tools, reduces findings, and writes a report. Context management (prompt caching, retrieval, offloading, reduction, and isolation) is a supporting layer. The graph, node, and helper connections shown are supported by the excerpts; some indexed modules, including model, configuration, isolation, and routing, were not excerpted, so their runtime wiring is not assumed.

Main entry points: [`src/agent/nodes/research.py`](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/research.py) (Research agent), [`src/main.py`](https://github.com/ai-doneus/deep-research-agent/blob/main/src/main.py) (CLI entry), [`src/agent/graph.py`](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/graph.py) (Workflow graph), [`src/agent/nodes/scope.py`](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/scope.py) (Scope brief)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_entry["CLI entry<br/>[main.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_scope["Scope brief<br/>[scope.py]"]
  node_research["Research agent<br/>[research.py]"]
  node_write["Report writer<br/>[write.py]"]
  node_router["Tool router<br/>[router.py]"]
end

subgraph group_context["Context engineering"]
  node_cache["Prompt caching<br/>[cache.py]"]
  node_retrieval["Tool retrieval<br/>[retrieve.py]"]
  node_offload["Note offload<br/>[offload.py]"]
  node_reduction["Note reduction<br/>[reduce.py]"]
  node_isolation["Context isolation<br/>[isolate.py]"]
end

subgraph group_integrations["Models and tools"]
  node_web["Web search tool<br/>[web_search.py]"]
  node_tavily["Tavily search"]
  node_model["Model wrapper<br/>[base_model.py]"]
  node_anthropic["Anthropic API"]
end

subgraph group_runtime["Runtime state"]
  node_state["Agent state<br/>[state.py]"]
  node_memory[("Research notes")]
  node_config["Configuration<br/>[configurations.py]"]
end

node_user(("Research user"))
node_report["Final report"]

node_user -->|"submits query"| node_entry
node_entry -->|"checks environment"| node_config
node_entry -->|"invokes graph"| node_graph
node_graph -->|"runs first"| node_scope
node_graph -->|"runs next"| node_research
node_graph -->|"runs last"| node_write
node_scope -->|"builds cached prompt"| node_cache
node_scope -->|"requests brief"| node_anthropic
node_research -->|"selects tools"| node_retrieval
node_research -->|"builds cached prompt"| node_cache
node_research -->|"invokes selected tool"| node_web
node_web -->|"searches web"| node_tavily
node_research -->|"saves tool results"| node_offload
node_offload -->|"writes notes"| node_memory
node_research -->|"summarizes notes"| node_reduction
node_research -->|"requests research"| node_anthropic
node_write -->|"builds cached prompt"| node_cache
node_write -->|"requests report"| node_anthropic
node_entry -->|"prints result"| node_report

click node_entry "https://github.com/ai-doneus/deep-research-agent/blob/main/src/main.py"
click node_graph "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/graph.py"
click node_scope "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/scope.py"
click node_research "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/research.py"
click node_write "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/write.py"
click node_router "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/router.py"
click node_state "https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/state.py"
click node_cache "https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/cache.py"
click node_retrieval "https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/retrieve.py"
click node_offload "https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/offload.py"
click node_memory "https://github.com/ai-doneus/deep-research-agent/tree/main/memory"
click node_reduction "https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/reduce.py"
click node_isolation "https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/isolate.py"
click node_web "https://github.com/ai-doneus/deep-research-agent/blob/main/src/tools/web_search.py"
click node_model "https://github.com/ai-doneus/deep-research-agent/blob/main/src/model/base_model.py"
click node_config "https://github.com/ai-doneus/deep-research-agent/blob/main/src/config/configurations.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_entry,node_graph,node_scope,node_research,node_write,node_router,node_user toneBlue
class node_cache,node_retrieval,node_offload,node_reduction,node_isolation toneAmber
class node_web,node_tavily,node_model,node_anthropic toneMint
class node_state,node_memory,node_config toneRose
class node_report toneIndigo
```

## Components

### Research workflow

- [CLI entry](https://github.com/ai-doneus/deep-research-agent/blob/main/src/main.py): `src/main.py`
- [Workflow graph](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Scope brief](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/scope.py): `src/agent/nodes/scope.py`
- [Research agent](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/research.py): `src/agent/nodes/research.py`
- [Report writer](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/nodes/write.py): `src/agent/nodes/write.py`
- [Tool router](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/router.py): `src/agent/router.py`

### Context engineering

- [Prompt caching](https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/cache.py): `src/ctx/cache.py`
- [Tool retrieval](https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/retrieve.py): `src/ctx/retrieve.py`
- [Note offload](https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/offload.py): `src/ctx/offload.py`
- [Note reduction](https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/reduce.py): `src/ctx/reduce.py`
- [Context isolation](https://github.com/ai-doneus/deep-research-agent/blob/main/src/ctx/isolate.py): `src/ctx/isolate.py`

### Models and tools

- [Web search tool](https://github.com/ai-doneus/deep-research-agent/blob/main/src/tools/web_search.py): `src/tools/web_search.py`
- **Tavily search**
- [Model wrapper](https://github.com/ai-doneus/deep-research-agent/blob/main/src/model/base_model.py): `src/model/base_model.py`
- **Anthropic API**

### Runtime state

- [Agent state](https://github.com/ai-doneus/deep-research-agent/blob/main/src/agent/state.py): `src/agent/state.py`
- [Research notes](https://github.com/ai-doneus/deep-research-agent/tree/main/memory): `memory`
- [Configuration](https://github.com/ai-doneus/deep-research-agent/blob/main/src/config/configurations.py): `src/config/configurations.py`

### Other components

- **Research user**
- **Final report**

## Connections

- Research user → CLI entry: submits query (evidence: `src/main.py`)
- CLI entry → Configuration: checks environment (evidence: `src/main.py`)
- CLI entry → Workflow graph: invokes graph (evidence: `src/main.py`)
- Workflow graph → Scope brief: runs first (evidence: `src/agent/graph.py`)
- Workflow graph → Research agent: runs next (evidence: `src/agent/graph.py`)
- Workflow graph → Report writer: runs last (evidence: `src/agent/graph.py`)
- Scope brief → Prompt caching: builds cached prompt (evidence: `src/agent/nodes/scope.py`)
- Scope brief → Anthropic API: requests brief (evidence: `src/agent/nodes/scope.py`)
- Research agent → Tool retrieval: selects tools (evidence: `src/agent/nodes/research.py`)
- Research agent → Prompt caching: builds cached prompt (evidence: `src/agent/nodes/research.py`)
- Research agent → Web search tool: invokes selected tool (evidence: `src/agent/nodes/research.py`)
- Web search tool → Tavily search: searches web (evidence: `src/tools/web_search.py`)
- Research agent → Note offload: saves tool results (evidence: `src/agent/nodes/research.py`)
- Note offload → Research notes: writes notes (evidence: `src/ctx/offload.py`)
- Research agent → Note reduction: summarizes notes (evidence: `src/agent/nodes/research.py`)
- Research agent → Anthropic API: requests research (evidence: `src/agent/nodes/research.py`)
- Report writer → Prompt caching: builds cached prompt (evidence: `src/agent/nodes/write.py`)
- Report writer → Anthropic API: requests report (evidence: `src/agent/nodes/write.py`)
- CLI entry → Final report: prints result (evidence: `src/main.py`)