Deep Research Agent (OpenAI Agents + Docker MCP)
This project is a multi-agent deep research system built on top of the OpenAI Agents SDK and Docker MCP Gateway.
It is designed as a professional-grade application that combines web research, long-form synthesis, and email delivery in a single workflow.
Key capabilities
- Multi-step query clarification and scope negotiation
- Search planning with structured Pydantic models
- Web search via Tavily MCP and browser automation via Playwright MCP
- Parallel search execution with streaming progress updates
- Long-form markdown report generation with follow-up questions
- Email delivery using SendGrid
- Chat-style Gradio UI that surfaces the agent's internal reasoning (planning, searches, writing, email)
Architecture
Main components in this folder:
deep_research.py– Gradio UI (chat interface) and app entrypointresearch_manager.py– Orchestrator that runs the full pipelineplanner_agent.py– PlansWebSearchItems using OpenAI Agents SDKsearch_agent.py– Uses MCP (Tavily + Playwright) for web searchwriter_agent.py– Turns search results into a long markdown reportemail_agent.py– Sends the report via SendGridclarifier_agent.py– Clarifies the user query and asks for confirmation
Control flow:
- User enters a topic in the chat UI
clarifier_agentanalyzes the request, proposes a scope, and asks for confirmation- On confirmation,
research_manager:
- Connects to Docker MCP Gateway (MCPServerStreamableHttp)
- Asksplanner_agentfor 5 search queries
- Runssearch_agentin parallel for each query (Tavily + Playwright MCP tools)
- Callswriter_agentto synthesize a detailed markdown report
- Callsemail_agentto send the report as HTML via SendGrid - Progress and thoughts are streamed back into the chat (planning, each search, report, email)
Requirements
This subproject is isolated from the rest of the repo and only needs:
See requirements.txt:```txt
openai-agents==0.0.15
openai==1.68.2
gradio==5.22.0
python-dotenv==1.1.1
pydantic==2.11.9
sendgrid==6.11.0
Install into a fresh virtualenv:```bash
pip install -r requirements.txt
Using uv (optional)
If you use uv, you can create the environment and run the app with:```bash
From this folder
Create a virtual environment managed by uv
uv venv .venv
Install dependencies from requirements.txt
uv pip install -r requirements.txt
Run the app
uv run python deep_research.py
> Note: The `agents` package at the repo root provides the custom Agent abstractions that this project imports.
---
## Environment Variables
Create a `.env` file in this folder with at least:```env
OPENAI_API_KEY=sk-...
SENDGRID_API_KEY=...
You may also want:```env
Optional: model overrides, etc.
DEEP_RESEARCH_MODEL=...
The app loads this file via `python-dotenv` in `deep_research.py`.
---
## Docker MCP Gateway Setup
This app expects a running **Docker MCP Gateway** exposing Tavily and Playwright MCP servers on `http://localhost:8081/mcp`.
### 1. Enable MCP Toolkit in Docker Desktop
1. Open Docker Desktop → Settings → Beta features
2. Enable **Docker MCP Toolkit**
### 2. Enable required MCP servers
In a terminal:```bash
docker mcp server enable tavily
docker mcp server enable playwright
Configure API keys (example for Tavily):```bash
docker mcp config write '
servers:
tavily:
env:
TAVILY_API_KEY: your_tavily_key_here
'
### 3. Run the gateway```bash
docker mcp gateway run --port 8081 --transport streaming
research_manager.py connects via:```python
MCP_GATEWAY_URL = "http://localhost:8081/mcp"
---
## Running the App
From this folder:```bash
python deep_research.py
Then open the printed local URL (usually http://127.0.0.1:7860).
Workflow in the UI:
- Enter a research question (e.g. "Latest developments in quantum computing")
- The assistant:
- Clarifies your request and proposes a research scope
- Asks you to confirm or refine - Reply with confirmation (e.g. "yes", "sure, go ahead", "yeah proceed") or refine the scope
- Once confirmed, you will see live updates:
- Connecting to MCP Gateway
- Planning searches
- Each web search as it completes
- Report drafting
- Email sending status - Final message contains the full markdown report + follow-up questions
Notes
- This project is intended as a reference implementation; you should review and adapt email recipients in
email_agent.py(and related security settings) before using it in production. - The MCP setup assumes Docker MCP Toolkit is installed and configured on your machine.
- Models used are
gpt-4o-minivia the OpenAI Agents SDK.