Deep-Research-Agent

KO | EN

gitlite — search

#javascript #ai #go #android #deep-learning #macos #nodejs #java #awesome #cli #vue #awesome-list #security #mcp

Deep-Research-Agent

(★ 9)

Deep research Agent

Deep-Research-Agent Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Deep Research Platform 🔍⚡

[![Python Version](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![A2AS Certified](https://img.shields.io/badge/A2AS-Certified-brightgreen)](https://a2as.org/certified/agents/abdullahmalik17/deep-research-agent)
[![MCP Powered](https://img.shields.io/badge/MCP-Playwright%20Enabled-purple.svg)](https://modelcontextprotocol.io)

An enterprise-grade, multi-agent AI research infrastructure engineered to transform raw user queries into comprehensive, evidence-backed research reports. The platform features dynamic model routing, Playwright MCP browser research, automated citation verification, 3-tiered memory, and structured observability.

---

## 🌟 Architecture Overview

```
                         ┌──────────────────────┐
                         │      User Query      │
                         └──────────┬───────────┘
                                    ↓
                         ┌──────────────────────┐
                         │ Research Orchestrator│
                         └──────────┬───────────┘
                                    ↓
                     ┌──────────────────────────────┐
                     │ Query Understanding / Scope │
                     └──────────────┬───────────────┘
                                    ↓
                     ┌──────────────────────────────┐
                     │ Adaptive Research Planner    │
                     └──────────────┬───────────────┘
                                    ↓
              ┌─────────────────────┼─────────────────────┐
              ↓                     ↓                     ↓
       Web Search Agent      Browser Research Agent   API/Data Agent
              │                     │                     │
              │              Playwright MCP              │
              │                     │                     │
              └─────────────────────┼─────────────────────┘
                                    ↓
                         ┌──────────────────────┐
                         │ Evidence Collector  │
                         └──────────┬───────────┘
                                    ↓
                         ┌──────────────────────┐
                         │ Evidence Verifier   │
                         └──────────┬───────────┘
                                    ↓
                         ┌──────────────────────┐
                         │ Research Synthesizer │
                         └──────────┬───────────┘
                                    ↓
                   ┌────────────────────────────────┐
                   │ Citation + Fact Verification   │
                   └───────────────┬────────────────┘
                                   ↓
                         ┌──────────────────────┐
                         │ Reflection / Critic  │
                         └──────────┬───────────┘
                                    ↓
                         ┌──────────────────────┐
                         │ Final Report Builder │
                         └──────────┬───────────┘
                                    ↓
                             User / UI / CLI
```

---

## ✨ Feature Matrix

---

## 🛠️ Installation & Setup

### 1. Prerequisites
- Python 3.11+
- Node.js & `npx` (optional, for Playwright MCP server stdio mode)

### 2. Installation
```bash
# Clone repository
git clone https://github.com/AbdullahMalik17/Deep-Research-Agent.git
cd Deep-Research-Agent

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

### 3. Environment Configuration
Copy `.env.example` to `.env` and insert your credentials:
```bash
cp .env.example .env
```
Example `.env`:
```env
GEMINI_API_KEY="your_gemini_api_key"
TAVILY_API_KEY="your_tavily_api_key"
DEFAULT_MODEL="gemini-2.5-flash"
RESEARCH_MODEL="gemini-2.5-pro"
```

---

## 💻 Usage

### Command-Line Interface (CLI)
Execute deep research directly from your terminal:
```bash
deep-research "Analyze recent developments in AI Agent frameworks" --browser --export report.md
```
CLI Options:
- `--model`: Override target model (e.g., `gemini-2.5-pro`, `gpt-4o`)
- `--provider`: Override provider (`gemini`, `openai`, `anthropic`, `openrouter`)
- `--browser` / `--no-browser`: Enable or disable Playwright MCP browser research
- `--max-searches`: Set maximum web search budget (default: 20)
- `--max-runtime`: Set maximum execution time in seconds (default: 300)
- `--export`: Export report to `.md`, `.html`, `.json`, or `.pdf`
- `--verbose`: Enable detailed telemetry logging

### Web Interface (Chainlit)
Launch the interactive web UI:
```bash
chainlit run src/app.py
```

---

## 📊 Evaluation & Benchmark Results

The platform includes a built-in evaluation framework tested against multi-category research benchmarks:

```txt
Deep Research Agent Evaluation
───────────────────────────────

Citation Accuracy       94.2%
Factual Accuracy        92.7%
Source Quality          91.8%
Completeness            89.4%
Tool Success Rate       97.1%

Average Runtime         38.4 sec
Average Searches        7.2
Average Sources         18.6
```

Run benchmarks locally:
```bash
python -m src.evaluation.benchmark
```

---

## 🧪 Testing

Execute unit and integration tests:
```bash
pytest
```

Run linting checks:
```bash
ruff check .
ruff format --check .
```

---

## 📚 Documentation

Comprehensive architecture guides are available in `docs/`:
- [System Architecture](docs/architecture.md)
- [Agent System & Handoff Pipeline](docs/agent-system.md)
- [Model Routing Architecture](docs/model-routing.md)
- [Playwright MCP Integration](docs/playwright-mcp.md)
- [3-Tiered Memory Architecture](docs/memory.md)
- [Evaluation Framework](docs/evaluation.md)
- [Security Protections](docs/security.md)
- [Troubleshooting Guide](docs/troubleshooting.md)

---

## 📄 License

MIT License - feel free to use and modify for open-source or commercial applications.

Deep-Research-Agent

Deep-Research-Agent Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Deep-Research-Agent

Deep-Research-Agent Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README