Deep Research Agent

A multi-loop deep research agent built with LangGraph + Google Gemini 2.5 Flash + Tavily Search. The agent iteratively searches the web, reflects on knowledge gaps, and produces a structured markdown report.

Architecture

START → generate_queries → web_search → reflect → [conditional edge]
                                                       ├── write_report  (sufficient OR loops >= 3)
                                                       └── generate_queries  (loop back with gap queries)
write_report → END

Components

Component	Description
agent/state.py	ResearchState TypedDict — shared state across all nodes
agent/nodes.py	Four node functions + ReflectionOutput Pydantic schema
agent/graph.py	LangGraph StateGraph with conditional routing
main.py	CLI entry point with streaming output and report saving

Node Descriptions

• generate_queries — Prompts Gemini to produce 3–5 targeted search queries. On subsequent loops, uses prior reflection gaps to focus queries.
• web_search — Calls Tavily Search for each query, accumulates results tagged with their source query.
• reflect — Uses llm.with_structured_output(ReflectionOutput) to evaluate research coverage. Returns is_sufficient, knowledge_gaps, follow_up_queries, and a summary.
• write_report — Prompts Gemini with all accumulated sources and reflections to produce a 5-section markdown report.

Setup

Requirements

• Python 3.11+
• A Google AI Studio API key (Gemini 2.0 Flash)
• A Tavily API key

Installation

# 1. Clone / navigate to the project directory
cd deep-agentsr

# 2. (Optional) Create a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\activate           # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure API keys
copy .env.example .env           # Windows
cp .env.example .env             # Linux/macOS
# Edit .env and fill in your GOOGLE_API_KEY and TAVILY_API_KEY

.env Configuration

GOOGLE_API_KEY=your_google_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

Usage

Interactive Mode (prompts for topic)

python main.py

You will see:

Deep Research Agent — Powered by Google Gemini + Tavily
============================================================
Default topic: Recent breakthroughs in quantum computing error correction and fault tolerance

Enter research topic (or press Enter for default):

Press Enter to use the default topic, or type your own.

CLI Argument Mode

python main.py --topic "IBM quantum error correction 2025"

python main.py --topic "Topological qubits and Microsoft quantum roadmap"

Example Execution Flow

Researching: Recent breakthroughs in quantum computing error correction and fault tolerance
============================================================

[Generating search queries] 5 queries generated
  [generate_queries] Generated 5 queries for loop 1

[Searching the web] 25 total results accumulated
  [web_search] Searching: quantum error correction breakthroughs 2024...
  ...

[Reflecting on research coverage] Loop 1 complete — sufficient: False
  [reflect] Gaps: 3 identified

[Generating search queries] 4 queries generated (gap-focused)

[Searching the web] 45 total results accumulated

[Reflecting on research coverage] Loop 2 complete — sufficient: True

[Writing final report] Report complete (4821 chars)

============================================================
RESEARCH COMPLETE
============================================================

Report saved to: C:\project2\deep-agentsr\reports\20260221_143022_recent_breakthroughs_in_quantum.md

Output Structure

Reports are saved to the reports/ directory with timestamped filenames:

reports/
└── 20260221_143022_recent_breakthroughs_in_quantum.md

Each report contains 5 sections:

1. Executive Summary — High-level overview of key findings
2. Key Findings — Bulleted list of breakthroughs with source citations
3. Technical Details — In-depth technical explanation of mechanisms
4. Future Outlook — Implications, future research directions, applications
5. Sources — Numbered list of all cited URLs

Configuration

Parameter	Default	Description
Max loops	3	Maximum research iterations before writing report
Recursion limit	25	LangGraph safety ceiling
Results per query	5	Tavily results per search query
LLM temperature	0.3	Gemini generation temperature

Project Structure

deep-agentsr/
├── agent/
│   ├── __init__.py      # Re-exports research_graph and ResearchState
│   ├── state.py         # ResearchState TypedDict definition
│   ├── nodes.py         # Node functions and ReflectionOutput schema
│   └── graph.py         # LangGraph StateGraph definition
├── reports/             # Auto-created; generated reports saved here
├── main.py              # CLI entry point
├── requirements.txt     # Python dependencies
├── .env.example         # Environment variable template
└── README.md