🤖 AI Research Agent

An autonomous research agent that plans questions, searches for answers, analyzes findings, and synthesizes a full markdown report — with live progress streaming to the UI.

Built to run locally for free using Groq's OpenAI-compatible API.

Features

• 🧠 4-phase agentic workflow: Planning → Searching → Analyzing → Synthesizing
• 📡 Real-time streaming via Server-Sent Events (SSE)
• 🎯 Three depth modes: Quick (3 questions), Standard (5), Deep (8)
• 💬 Chat with the generated report for follow-ups
• 📥 One-click Markdown export
• 🔌 Provider-agnostic: works with Groq, OpenRouter, Cerebras, or OpenAI

Tech Stack

Backend

• Python 3.11 + FastAPI
• OpenAI Python SDK (used with Groq base_url)
• Uvicorn with reload
• python-dotenv

Frontend

• React 18
• Custom CSS (no UI framework)
• Native EventSource for SSE

AI Models (default)

• Fast tasks: llama-3.1-8b-instant (Groq)
• Report synthesis: llama-3.3-70b-versatile (Groq)

Architecture

[React UI]
     |
     | POST /research/stream
     ↓
[FastAPI + ResearchAgent]
     |
     | chat.completions.create
     ↓
[Groq API]
     |
     | JSON responses
     ↓
[FastAPI]
     |
     | SSE stream
     ↓
[React UI] ← live updates

Quick Start

1. Prerequisites

• Python 3.9+
• Node.js 18+
• Free Groq API key from https://console.groq.com

2. Backend setup

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

pip install -r requirements.txt

Create .env:

GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxx

Start server:

uvicorn main:app --reload --port 8000

3. Frontend setup

cd frontend
npm install
npm start

Open http://localhost:3000

Configuration

Environment Variables

Create backend/.env:

# Choose ONE provider

# Groq (recommended, free)
GROQ_API_KEY=gsk_...

# Optional: OpenAI (requires paid credits)
# OPENAI_API_KEY=sk-proj-...

# Optional: OpenRouter
# OPENROUTER_API_KEY=sk-or-...

Switching providers

Edit backend/agent.py:

# Groq
self.client = AsyncOpenAI(
    api_key=os.getenv("GROQ_API_KEY"),
    base_url="https://api.groq.com/openai/v1"
)

# OpenRouter
# base_url="https://openrouter.ai/api/v1"

# OpenAI
# base_url="https://api.openai.com/v1"

Also change model names at top of agent.py:

MODEL_FAST = "llama-3.1-8b-instant"
MODEL_SMART = "llama-3.3-70b-versatile"

API Endpoints

POST /research/stream

Starts a research job. Streams events.

Request

{
  "topic": "quantum computing in drug discovery",
  "depth": "standard",
  "focus_areas": ["pharma", "2024 breakthroughs"]
}

Response (SSE)

data: {"phase":"planning","status":"active","progress":5}
data: {"phase":"searching","status":"found","progress":35}
...

POST /chat

Ask follow-up questions.

Request

{
  "message": "Summarize the key risks",
  "session_id": "abc123",
  "report_context": "...full markdown..."
}

GET /health

Returns {"status":"healthy"}

How It Works

1. Planning: Generates 3-8 specific research questions using MODEL_FAST
2. Searching: Answers each question independently (parallelizable)
3. Analyzing: Finds patterns, contradictions, and gaps across answers
4. Synthesizing: Builds final report with MODEL_SMART using structured prompt

Depth controls token budget:

• quick: 800 tokens
• standard: 1500 tokens
• deep: 2500 tokens

Project Structure

ai-research-agent/
├── backend/
│ ├── main.py # FastAPI app, SSE endpoint
│ ├── agent.py # ResearchAgent class, 4-phase logic
│ ├── requirements.txt # fastapi, openai, python-dotenv, uvicorn
│ └──.env # your keys (gitignored)
└── frontend/
    ├── src/
    │ ├── components/
    │ │ └── ResearchAgent.js
    │ ├── App.js
    │ └── styles.css
    ├── public/
    └── package.json

Troubleshooting

401 Incorrect API key

• Check .env is in backend/ folder, not project root
• Ensure load_dotenv() runs before importing agent
• Key must start with gsk_ for Groq

429 insufficient_quota

• You are still using OpenAI. Switch to Groq in agent.py
• Or add $5 credit at platform.openai.com

Model not found

• Groq does not have gpt-4o-mini. Use llama-3.1-8b-instant
• Check available models at console.groq.com/docs/models

Stream stops early

• Look at terminal for Python traceback
• Add try/except around client.chat.completions.create to surface errors as SSE events

Requirements

backend/requirements.txt:

fastapi==0.110.0
uvicorn[standard]==0.27.0
openai>=1.30.0
python-dotenv==1.0.1
httpx==0.26.0

License

MIT — free for personal and commercial use.

Roadmap

• Add source citations with real web search
• Save research history to SQLite
• Add provider fallback (Groq → Cerebras → OpenRouter)
• Docker compose for one-command start