🔍 Deep Research

A multi-agent AI pipeline that takes a research query and returns a detailed, structured report — delivered both in the browser and to your inbox.

Built with the OpenAI Agents SDK and Gradio.

---

How It Works

The pipeline runs four specialized agents in sequence:

Query → Planner → Search (parallel) → Writer → Email

1. Planner Agent — Breaks down the query into 5 targeted web search terms, each with a reasoning justification.
2. Search Agent — Runs all 5 searches in parallel, summarizing each result into a concise 2–3 paragraph digest.
3. Writer Agent — Synthesizes all search summaries into a detailed 1000+ word markdown report, with a short summary and follow-up questions.
4. Email Agent — Converts the report into clean HTML and sends it via SendGrid.

---

Features

• 🔎 Parallel web search for speed
• 📝 Long-form, structured markdown reports
• 📧 Automatic email delivery via SendGrid
• 🖥️ Live streaming status updates in the Gradio UI
• 🔭 Full trace visibility via OpenAI tracing dashboard

---

Project Structure

├── app.py                  # Gradio UI and entry point
├── research_manager.py     # Orchestrates the full pipeline
├── planner_agent.py        # Generates structured search plans
├── search_agent.py         # Performs web searches and summarizes results
├── writer_agent.py         # Synthesizes findings into a report
├── email_agent.py          # Formats and sends the report via email
├── .env                    # API keys (not committed)
└── requirements.txt

---

Setup

1. Clone the repo

git clone https://github.com/aneedrameshan/deep-research.git
cd deep-research

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a .env file in the root directory:

OPENAI_API_KEY=your_openai_api_key
SENDGRID_API_KEY=your_sendgrid_api_key

4. Configure email addresses

In email_agent.py, update the sender and recipient:

from_email = Email("you@yourdomain.com")   # Must be a verified SendGrid sender
to_email = To("recipient@example.com")

5. Run the app

python app.py

The Gradio UI will open in your browser automatically.

---

Requirements

• Python 3.10+
• OpenAI API key (with Agents SDK access)
• SendGrid account with a verified sender email

Key dependencies

gradio
openai-agents
sendgrid
pydantic
python-dotenv

---

Example Output

Given a query like "What are the latest breakthroughs in quantum computing?", the pipeline will:

• Plan 5 targeted searches across subtopics (hardware, error correction, commercial players, etc.)
• Search and summarize each in parallel
• Write a detailed multi-section markdown report
• Email you the report as formatted HTML

---

Limitations & Potential Improvements

• The writer agent uses gpt-4o-mini — upgrading to gpt-4o produces noticeably better long-form synthesis
• Follow-up questions generated by the writer are not yet surfaced in the UI
• Failed searches are silently skipped — adding error logging would help with debugging

---

License

MIT