# Deep Research Agents - AI-Powered Research System

A sophisticated AI-powered research system that uses **OpenAI Agents** and **tool-based architecture** to provide deep, interactive research capabilities with automated email delivery.
Developed with 💜 by Tiago Iesbick

## 🏗️ Architecture Overview

This system is built around **OpenAI Agents** with specialized tools, providing several key benefits:

### Why This Architecture Works

1. **Agent-Based Workflow**: Uses OpenAI's Agent framework for intelligent task orchestration
2. **Tool Specialization**: Each tool has a single, well-defined responsibility
3. **Automated Pipeline**: Complete research workflow from query to email delivery
4. **Interactive Q&A**: Refines research scope through intelligent questioning
5. **Web Search Integration**: Real web search capabilities with result summarization
6. **Email Delivery**: Automated report delivery via SendGrid
7. **Gradio Interface**: User-friendly web interface for interaction

## 🛠️ Available Tools

### Core Research Tools
- **`generate_question`**: Ask clarifying questions to refine research scope (up to 3 rounds)
- **`generate_search_terms`**: Generate exactly 3 optimized web search queries
- **`execute_search_plan`**: Execute web searches in parallel and summarize results
- **`report_writer`**: Synthesize search results into a structured research report
- **`email_writer`**: Convert report to HTML email and send via SendGrid

## 🔄 Research Workflow

The system follows a structured research workflow:

1. **Query Understanding**: Interactive questioning (up to 3 rounds) to clarify user needs
2. **Search Planning**: Generate exactly 3 optimized web search queries
3. **Search Execution**: Execute searches in parallel using OpenAI's WebSearchTool
4. **Result Synthesis**: Combine and analyze gathered information into structured report
5. **Email Delivery**: Convert report to HTML and send via SendGrid

## 🚀 Getting Started

### Prerequisites
- Python 3.13+
- OpenAI API key
- SendGrid API key (for email delivery)

### Installation
```bash
# Clone the repository
git clone <repository-url>
cd deep-research-agents

# Install dependencies using uv (recommended)
uv sync

# Or using pip
pip install -e .

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys:
# OPENAI_API_KEY=your_openai_key
# SENDGRID_API_KEY=your_sendgrid_key
```

### Usage

#### Web Interface (Recommended)
```bash
python main.py
```
This launches a Gradio web interface where you can interact with the research agent through a chat interface.

#### Programmatic Usage
```python
from ai_agents.manager_agent import ManagerAgent
from schema import ResearchContext

# Create a research manager
manager = ManagerAgent()

# Set up research context
manager.context = ResearchContext(
    initial_query="Your research question here",
    qa_history=[]
)

# Run research workflow
result = await manager.run()
```

### Configuration
- **Email Settings**: Update sender/recipient emails in `tools/send_email.py`
- **Search Limits**: Modify `HOW_MANY_QUESTIONS` and `HOW_MANY_SEARCHES` constants
- **Models**: Currently uses GPT-5 and GPT-5-mini (configurable in agent definitions)
- **UI Customization**: Modify loading animations in `utils/loading_message.py`
- **Session Management**: The system automatically resets after each research completion

## 🧩 Adding New Tools

To add a new tool to the system:

1. Create a new tool using the `tool_from_agent` helper:
```python
from tools.tool_wrapper import tool_from_agent
from schema import YourOutputType

# Define agent instructions
MY_TOOL_INSTRUCTIONS = """
Role: You are a specialized agent for [purpose]
Task: [specific task description]
...
"""

# Create the tool
my_new_tool = tool_from_agent(
    agent_name="MyNewAgent",
    agent_instructions=MY_TOOL_INSTRUCTIONS,
    output_type=YourOutputType,
    tool_name="my_new_tool",
    tool_description="Description of what this tool does"
)
```

2. Add it to the ManagerAgent's tools list:
```python
# In ai_agents/manager_agent.py
self.tools = [
    question_generator_tool,
    search_terms_generator_tool,
    execute_search_plan,
    report_writer_tool,
    email_writer_tool,
    my_new_tool  # Add your new tool here
]
```

3. Update the manager instructions to use the new tool in the workflow.

## 🔍 Tool Architecture

The system uses OpenAI's Agent framework with specialized tools:

- **Agent-Based Tools**: Each tool is an AI agent with specific instructions
- **Type Safety**: All tools use Pydantic models for input/output validation
- **Parallel Execution**: Search execution runs multiple queries simultaneously
- **Error Handling**: Built-in error handling and status reporting

## 📊 Example Usage

### Complete Research Session
```python
from ai_agents.manager_agent import ManagerAgent
from schema import ResearchContext

# Initialize the research manager
manager = ManagerAgent()

# Set up your research query
manager.context = ResearchContext(
    initial_query="What are the latest trends in AI code completion?",
    qa_history=[]
)

# The system will:
# 1. Ask up to 3 clarifying questions
# 2. Generate 3 optimized search queries
# 3. Execute searches in parallel
# 4. Create a structured report
# 5. Send the report via email

result = await manager.run()
```

### Web Interface Interaction
1. Run `python main.py`
2. Open the Gradio interface in your browser
3. Type your research question
4. Watch the loading animation while the agent processes your request
5. Answer clarifying questions as they appear (up to 3 rounds)
6. Receive confirmation when your research report is sent via email
7. The system automatically resets for your next research query

## 🎯 Benefits of This Architecture

- **Intelligent Orchestration**: OpenAI Agents manage the entire workflow automatically
- **Real Web Search**: Uses OpenAI's WebSearchTool for actual web research
- **Interactive Refinement**: Q&A process ensures accurate research scope
- **Automated Delivery**: Complete pipeline from query to email delivery
- **Type Safety**: Pydantic models ensure data integrity throughout the pipeline
- **Parallel Processing**: Multiple searches execute simultaneously for efficiency
- **User-Friendly Interface**: Gradio provides an intuitive chat interface with loading animations
- **Automatic Reset**: System resets after each research session for clean state management

## 🔮 Future Enhancements

- **Custom Search Sources**: Integration with academic databases, news APIs
- **Report Templates**: Multiple output formats (PDF, Word, etc.)
- **Advanced Analytics**: Research quality metrics and insights
- **Multi-language Support**: Research in different languages
- **Collaborative Features**: Team research sessions and sharing
- **API Endpoints**: REST API for programmatic access
- **Caching System**: Store and reuse research results

## 📁 Project Structure

```
deep-research-agents/
├── ai_agents/           # Core agent implementations
│   ├── manager_agent.py # Main orchestrator agent
│   └── search_agent.py  # Web search execution agent
├── tools/               # Specialized research tools
│   ├── email_writer.py  # Email report generation
│   ├── question_generator.py # Interactive Q&A
│   ├── report_writer.py # Research report synthesis
│   ├── search_executor.py # Parallel search execution
│   ├── search_terms_generator.py # Search query optimization
│   ├── send_email.py    # SendGrid email delivery
│   └── tool_wrapper.py  # Agent-to-tool conversion utility
├── main.py              # Gradio web interface
├── schema.py            # Pydantic data models
├── utils/               # Utility modules
    └── loading_message.py # Loading animation for UI
```
