Deep Research Agent

A Python research agent that decomposes questions, searches the web, fetches pages, and synthesizes cited markdown reports—with a React UI for interactive use.

Product spec: docs/PRD.md — kept in sync with the codebase; update it whenever behavior or architecture changes.

Architecture

research_agent/     Python agent (CLI + FastAPI)
frontend/           React + Vite UI

• Gemini (gemini-2.5-flash) drives decomposition, tool use, and synthesis
• DuckDuckGo for search, requests + BeautifulSoup for page content
• Tool-use loop: search_web → fetch_page → final markdown report

Setup

1. Python backend

cd research_agent
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt

Create research_agent/.env:

GEMINI_API_KEY=your_key_here

2. React frontend

cd frontend
npm install

Run

CLI only

cd research_agent
python main.py "What are the latest breakthroughs in fusion energy?"

Progress (searches/fetches) prints to stderr; the markdown report prints to stdout.

Full stack (UI)

Terminal 1 — API:

cd research_agent
uvicorn server:app --reload --host 127.0.0.1 --port 8000

Terminal 2 — UI:

cd frontend
npm run dev

Open http://localhost:5173

Example CLI output

============================================================

## Executive Summary

Fusion energy research in 2024–2025 has seen notable advances in magnet technology,
laser-driven ignition, and private-sector reactor timelines. National labs report improved
plasma confinement while startups push toward demonstration plants before 2035…

## Key Findings

### Magnetic confinement
…

### Inertial confinement
…

## Sources

1. [ITER Official Updates](https://…)
2. [DOE Fusion News](https://…)
…

Project layout

File	Role
main.py	CLI entry point
agent.py	Anthropic tool-use loop
tools.py	search_web, fetch_page
prompts.py	System prompt + tool schemas
utils.py	Text cleaning, truncation
server.py	FastAPI for the React UI

Notes

• Fetched pages are capped at 3000 characters
• Max 10 agent loop iterations
• .env is gitignored; use .env.example as a template