README.md

metadata

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

Autonomous Multi-Agent Workflow System

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 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

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	14,400 req/day
SERPER_API_KEY	serper.dev	2,500 searches/month
GOOGLE_API_KEY	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:

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

No other code changes needed.

API

# 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