README.md

---
title: Multi-Agent System
emoji: 🤖
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
app_port: 7860
---

# Autonomous Multi-Agent Workflow System

[![Python 3.11](https://img.shields.io/badge/python-3.11-blue)](https://www.python.org/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.2-green)](https://github.com/langchain-ai/langgraph)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688)](https://fastapi.tiangolo.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> A production-grade LangGraph multi-agent system — Planner, Executor, Critic, and Memory agents — that collaborate to decompose and execute complex tasks with state management, failure recovery, and persistent memory.

## Live Demo

Deployed on [Hugging Face Spaces](https://huggingface.co/spaces) via Docker.

## Architecture

```
User Task
    │
    ▼
┌─────────────────────────────────────────────────┐
│               LangGraph Workflow                │
│                                                 │
│  Memory Retrieve → Planner → Executor (loop)   │
│                        ↑         │              │
│                    replan     all done          │
│                        │         ▼              │
│                      Critic ← Executor          │
│                        │                        │
│                     approved                    │
│                        ▼                        │
│                  Memory Store → END             │
└─────────────────────────────────────────────────┘
```

| Agent | Role |
|---|---|
| **Memory Retrieve** | Pull relevant past context from SQLite |
| **Planner** | Decompose task into 2–4 ordered steps |
| **Executor** | Run each step using tools (web search, code, etc.) |
| **Critic** | Score output 0–100, trigger replan if score < 60 |
| **Memory Store** | Persist learnings for future tasks |

## Tools

| Tool | Description |
|---|---|
| `web_search` | Google via Serper API, fallback to DuckDuckGo |
| `fetch_url` | Scrape and clean URL content |
| `calculate` | Safe math expression evaluator |
| `run_python` | Sandboxed Python execution (pandas, numpy, matplotlib supported) |
| `write_file` / `read_file` | In-memory file store |
| `get_datetime` | Current UTC datetime |
| `synthesize` | Final answer generation |

## Stack

- **Orchestration**: LangGraph 0.2 (stateful graph with conditional routing)
- **LLM**: Groq (Llama 3.3 70B) — free tier, 14,400 req/day · also supports Gemini
- **Search**: Serper (Google Search API) with DuckDuckGo fallback
- **API**: FastAPI + Server-Sent Events for real-time streaming
- **Memory**: SQLite (long-term) + Redis optional (short-term cache)
- **Frontend**: Vanilla JS dashboard with live agent graph visualization

## Local Setup

```bash
git clone https://github.com/jatingyass/multi-agent-system
cd multi-agent-system

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

pip install -r requirements.txt

# Create .env with your API keys (see .env.example)
cp .env.example .env

python run.py
# Open http://localhost:8000
```

### Required API Keys

| Key | Where to get | Free tier |
|---|---|---|
| `GROQ_API_KEY` | [console.groq.com](https://console.groq.com) | 14,400 req/day |
| `SERPER_API_KEY` | [serper.dev](https://serper.dev) | 2,500 searches/month |
| `GOOGLE_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Optional (Gemini fallback) |

## Hugging Face Deployment

1. Create a new Space → **Docker** SDK
2. Add secrets in **Settings → Variables and secrets**:
   - `GROQ_API_KEY`
   - `SERPER_API_KEY`
   - `GOOGLE_API_KEY` (optional)
3. Push this repo — the `Dockerfile` handles the rest (port 7860, production mode)

> Redis is optional. The app runs fully without it (short-term memory disabled).

## Switching LLM Provider

Change `llm_provider` in `backend/core/config.py`:

```python
llm_provider: str = "groq"    # Llama 3.3 70B via Groq
llm_provider: str = "gemini"  # Gemini 2.5 Flash
```

No other code changes needed.

## API

```bash
# Submit a task (streaming)
curl -X POST http://localhost:8000/api/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{"task": "Research quantum computing breakthroughs in 2024"}'

# Submit a task (batch)
curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"task": "Calculate compound interest on $10,000 at 7% for 20 years"}'

# Health check
curl http://localhost:8000/api/health
```

Interactive docs: `http://localhost:8000/docs`

## Key Design Decisions

**Why LangGraph?** Explicit graph control — every routing decision is visible and testable, unlike chain-based frameworks.

**Why a separate Critic?** Self-evaluation is biased. A dedicated evaluator LLM catches significantly more errors and provides structured scoring.

**Why two-tier memory?** Redis for sub-millisecond working memory during task execution; SQLite for persistent episodic and semantic memory across sessions.

**Why Groq?** 14,400 free requests/day vs Gemini's 20/day on the free tier — orders of magnitude more headroom for development and demos.

**Failure recovery:** Critic-triggered replanning for low-quality outputs; hard iteration cap (3) prevents infinite loops; Serper → DuckDuckGo fallback ensures web search always has a path.

## License

MIT