Parallel Research Agent Team

A multi-agent research system built on LangGraph. Given a research question, a team of Researcher agents investigates independent subtopics in parallel, then a Critic and Synthesizer merge the findings into one coherent, cited Markdown report.

Architecture

                    Orchestrator
               (splits into subtopics)
                        |
    ┌───────────────────┼───────────────────┐
    ▼                   ▼                   ▼
Researcher 1       Researcher 2       Researcher N     ← run in parallel
    └───────────────────┼───────────────────┘
                        ▼
                Shared State (LangGraph)
                        ▼
                      Critic
            (checks contradictions, gaps)
                        ▼
                   Synthesizer
             (produces final report)

Prerequisites

• Python 3.11+
• uv — fast Python package & environment manager (recommended over pip)
• An API key for your chosen provider (Gemini or Groq recommended)
• A Tavily API key for web search — get one free

Install uv (once)

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or with pipx / Homebrew if you prefer: pipx install uv / brew install uv.

Quick Start

1. Clone the repo

git clone https://github.com/LuniaKunal/Multi-Agent.git
cd Multi-Agent

2. Create a virtual environment with uv

uv venv

This creates .venv/ in the project root. Activate it:

Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

Windows (Command Prompt):

.venv\Scripts\activate.bat

macOS / Linux:

source .venv/bin/activate

You should see (.venv) at the start of your shell prompt when the environment is active.

To leave the virtual environment later:

deactivate

Optional: You can skip activation and use uv run … instead (see Run).

3. Install dependencies

uv pip install -r requirements.txt

uv pip is a drop-in replacement for pip — much faster, still uses requirements.txt.

4. Configure environment variables

# macOS / Linux
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Open .env and fill in your keys. Choose one of the model backends:

Option A — Gemini / Google (default, strong quality)

Get a key at Google AI Studio.

MODEL_PROVIDER=gemini
GOOGLE_API_KEY=your-google-api-key
# GEMINI_MODEL=gemini-2.0-flash          # Researchers / Orchestrator / Critic
# GEMINI_MODEL_STRONG=gemini-2.5-pro     # Synthesizer
TAVILY_API_KEY=tvly-...

Option B — Groq (very fast, OpenAI-compatible open models)

Get a key at Groq Console.

MODEL_PROVIDER=groq
GROQ_API_KEY=gsk_...
# GROQ_MODEL=llama-3.1-8b-instant            # fast default
# GROQ_MODEL_STRONG=llama-3.3-70b-versatile  # Synthesizer
TAVILY_API_KEY=tvly-...

Option C — Anthropic

MODEL_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
TAVILY_API_KEY=tvly-...

Option D — Ollama (fully local, no API key needed)

First, install Ollama and pull a model:

ollama pull llama3.1:8b            # fast, good for Researchers
ollama pull llama3.1:70b           # optional: stronger model for Synthesizer

Then set in .env:

MODEL_PROVIDER=ollama
OLLAMA_MODEL=llama3.1:8b
OLLAMA_MODEL_STRONG=llama3.1:70b   # leave unset to use the same model for all nodes
# OLLAMA_BASE_URL=http://localhost:11434   # default; change only if needed
TAVILY_API_KEY=tvly-...

Tip: Models that support tool-calling will use Tavily interactively. Others get search results injected into the prompt automatically — no code change needed.

5. Run

With the venv activated:

python main.py "What are the main challenges of deploying LLMs in production?"

Or without activating (uv finds .venv automatically):

uv run python main.py "What are the main challenges of deploying LLMs in production?"

Save the report to a file:

uv run python main.py "Your question" --output report.md

Print per-step state alongside agent output:

uv run python main.py "Your question" --steps

Project Structure

Multi-Agent/
├── main.py                         # CLI entry point
├── Prompts                         # All agent system prompts
├── requirements.txt
├── .env.example                    # Copy to .env and fill in keys
├── .venv/                          # Local virtual env (created by you; gitignored)
│
├── src/research_agent/
│   ├── state.py                    # LangGraph ResearchState schema
│   ├── llm.py                      # Gemini / Groq / Anthropic / Ollama factory
│   ├── tools.py                    # Tavily web search + skill loader
│   ├── prompts.py                  # Re-exports from Prompts file
│   ├── graph.py                    # LangGraph StateGraph wiring
│   └── nodes/
│       ├── orchestrator.py         # Decomposes question → subtopics
│       ├── researcher.py           # Parallel subtopic investigator
│       ├── critic.py               # Flags contradictions & gaps
│       └── synthesizer.py          # Writes the final report
│
├── skills/
│   └── web_research/SKILL.md       # Research playbook for web-based subtopics
│
└── tests/
    └── test_state.py               # Unit tests (run without API keys)

Running Tests

uv pip install pytest
uv run pytest tests/ -v

Tests run offline — no API keys required.

Adding a New Skill

Create skills/<skill-name>/SKILL.md with YAML frontmatter and a research playbook:

---
name: academic_research
description: >
  Use for subtopics requiring peer-reviewed literature...
---
# Academic Research Skill
...

The Researcher nodes automatically discover and apply matching skills based on subtopic title. See skills/web_research/SKILL.md for a complete example and Readme.md (this file was originally the Skills README) for the full pattern.

Environment Variable Reference

Variable	Default	Description
MODEL_PROVIDER	gemini	gemini, groq, anthropic, or ollama
GOOGLE_API_KEY	—	Required when provider is gemini
GEMINI_MODEL	gemini-3.6-flash	Default Gemini model
GEMINI_MODEL_STRONG	gemini-3.6-flash	Synthesizer Gemini model
GROQ_API_KEY	—	Required when provider is groq
GROQ_MODEL	llama-3.1-8b-instant	Default Groq model
GROQ_MODEL_STRONG	llama-3.3-70b-versatile	Synthesizer Groq model
ANTHROPIC_API_KEY	—	Required when provider is anthropic
ANTHROPIC_MODEL	claude-3-5-haiku-20241022	Default Anthropic model
ANTHROPIC_MODEL_STRONG	claude-3-5-sonnet-20241022	Synthesizer Anthropic model
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	llama3.1:8b	Default local model
OLLAMA_MODEL_STRONG	same as OLLAMA_MODEL	Stronger model for Synthesizer
TAVILY_API_KEY	—	Web search API key (required for real research)