Fairy is a lightweight web agent that supports deep research capabilities, built with LangGraph.

• 🔬 Deep Research: Iterative web search with intelligent stopping criteria
• 🎯 Scope Definition: User clarification and research brief generation
• 🤖 Multi-Agent System: Supervisor + Research Agents for parallel task execution
• 📁 MCP Support: Local file system access via Model Context Protocol
• 🔗 LangGraph Studio: Visual debugging and monitoring
• 🌐 Web Demo: Full-featured Next.js + FastAPI application

User Query
     ↓
Scope Research (Clarification + Brief)
     ↓
Supervisor Agent (Task Analysis)
     ↓
  ┌────┴────┬────────┬────────┐
  ↓         ↓        ↓        ↓
Agent 1   Agent 2  Agent 3  Agent N
(Parallel Research)
  ↓         ↓        ↓        ↓
  └────┬────┴────────┴────────┘
       ↓
Aggregate Results
       ↓
   Final Report

# Install dependencies
uv sync

Copy the environment template:

cp env.template .env

Edit .env and add your API keys:

MODEL_BASE_URL=https://api.openai.com/v1
MODEL_API_KEY=your_api_key_here
TAVILY_API_KEY=your_tavily_key_here

langgraph dev

Open LangGraph Studio to visualize and debug the agents.

Backend Setup:

cd apps/backend
cp env.template .env
# Edit .env with your API keys
uv sync
uv run uvicorn app.main:app --reload --port 8000

Frontend Setup:

cd apps/frontend
cp env.template .env.local
npm install
npm run dev

Open http://localhost:3000 to see the demo.

• scope_research: User clarification and research brief generation
• research_agent: Single agent with web search
• research_agent_mcp: Agent with local file system access
• research_agent_supervisor: Multi-agent coordinator
• research_agent_full: Complete workflow with all features

# Run tests
uv run pytest

# Format code
uv run black .
uv run ruff check .

# Type check
uv run mypy src/

• LangGraph Tutorial: Learn LangGraph concepts
• Deep Research Blog: Building multi-agent research systems

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.

• LangChain for the excellent framework
• LangGraph for the agent orchestration
• Tavily for the search API