A lightweight multi-agent orchestration framework built with LangGraph that uses a Supervisor pattern to coordinate specialized AI agents for collaborative task solving.
- Architecture
- Quick Start
- Project Structure
- Configuration
- Testing
- Example Use Cases
- Tech Stack
- License
graph LR
A[User Task] --> B[Planner]
B --> C[Supervisor]
C -->|route| D[Researcher]
C -->|route| E[Analyst]
C -->|route| F[Writer]
D -->|result| G[(Shared State)]
E -->|result| G
F -->|result| G
G -->|evaluate| C
C -->|finish| H[Assemble Output]
- User submits a task via Streamlit UI or API
- Supervisor agent analyzes the task and routes to the appropriate specialist
- Specialist agents execute their part and return results to shared state
- Supervisor evaluates progress and either routes to another agent or finalizes
- Final output is assembled and presented to the user
| Agent | Role | Tools |
|---|---|---|
| Supervisor | Task decomposition, routing, quality control | Routing logic |
| Researcher | Information gathering from web sources | Web Search (Tavily), URL scraping |
| Analyst | Data processing, extraction, structured analysis | Calculator, Text summarization, Key point extraction |
| Writer | Content synthesis, formatting, final output | Text generation |
- Python 3.11+
- API keys: OpenAI or Anthropic + Tavily (for web search)
git clone https://github.com/reiquileut/multi-agent-orchestrator.git
cd multi-agent-orchestrator
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys# Quick demo (no API keys needed — uses mock responses)
python demo.py
# Streamlit UI (requires API keys)
streamlit run app.py
# CLI (requires API keys)
python -m src.cli "Research the latest AI agent frameworks and write a comparison report"docker compose up --build
# Open http://localhost:8501multi-agent-orchestrator/
├── src/
│ ├── __init__.py
│ ├── config.py # Environment & LLM configuration
│ ├── state.py # Shared state definition (TypedDict)
│ ├── orchestrator.py # LangGraph graph builder & compiler
│ ├── cli.py # CLI entry point
│ ├── agents/
│ │ ├── __init__.py
│ │ ├── supervisor.py # Supervisor: task routing & evaluation
│ │ ├── researcher.py # Researcher: web search & info gathering
│ │ ├── analyst.py # Analyst: data processing & structuring
│ │ └── writer.py # Writer: content synthesis & formatting
│ └── tools/
│ ├── __init__.py
│ ├── search.py # Tavily web search wrapper
│ ├── calculator.py # Safe math evaluation
│ └── text_processing.py # Text utilities (summarize, extract, etc.)
├── tests/
│ ├── __init__.py
│ ├── test_orchestrator.py # Integration tests for the full graph
│ ├── test_agents.py # Unit tests for individual agents
│ ├── test_tools.py # Unit tests for tools
│ ├── test_cli.py # CLI entry point tests
│ └── test_config.py # Configuration & environment tests
├── .github/
│ ├── workflows/
│ │ └── ci.yml # GitHub Actions CI pipeline
│ ├── ISSUE_TEMPLATE/ # Bug report & feature request templates
│ └── pull_request_template.md
├── app.py # Streamlit demo application
├── demo.py # Quick demo with mock responses (no keys)
├── .env.example # Environment variables template
├── .pre-commit-config.yaml # Ruff + pre-commit hooks
├── .streamlit/
│ └── config.toml # Streamlit theming
├── requirements.txt
├── pyproject.toml # Project metadata & tool config
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── README.md
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
Yes* | OpenAI API key (default provider) |
ANTHROPIC_API_KEY |
Yes* | Anthropic API key (alternative provider) |
TAVILY_API_KEY |
Yes | Tavily API key for web search |
LLM_PROVIDER |
No | openai (default) or anthropic |
LLM_MODEL |
No | Model name (default: gpt-5.4-nano) |
LANGSMITH_API_KEY |
No | LangSmith tracing (recommended) |
*At least one LLM provider key is required.
Each agent is a self-contained module. To add a new agent:
- Create
src/agents/your_agent.pywith an async node function - Register it in
src/orchestrator.py - Update the Supervisor's routing logic
# src/agents/your_agent.py
from src.state import OrchestratorState
async def your_agent_node(state: OrchestratorState) -> dict:
"""Your custom agent logic."""
# Access shared state
task = state["task"]
# Do work...
result = "Your agent output"
return {
"agent_outputs": [{"agent": "your_agent", "output": result}],
"messages": state["messages"] + [AIMessage(content=result)]
}The test suite includes 30+ tests across 5 test modules with 99% code coverage.
# Run all tests
pytest tests/ -v
# Run with coverage report
pytest tests/ --cov=src --cov-report=html --cov-report=term-missing
# Run only unit tests (no API keys needed)
pytest tests/ -v -m "not integration"
# Run specific test
pytest tests/test_orchestrator.py -v -k "test_full_pipeline"Research & Report
Input: "Research the top 3 AI agent frameworks in 2025 and write a comparison"
Researcher gathers info → Analyst structures data → Writer produces report
Data Analysis
Input: "Analyze the key metrics from this quarterly report and summarize findings"
Researcher gathers context → Analyst extracts & structures metrics → Writer summarizes
Content Creation
Input: "Write a technical blog post about LangGraph multi-agent patterns"
Researcher gathers sources → Analyst organizes key points → Writer drafts content
| Technology | Purpose |
|---|---|
| LangGraph | Stateful agent orchestration with conditional routing |
| LangChain | LLM abstractions, tools, and prompt management |
| Anthropic Claude / OpenAI | LLM providers |
| Tavily | Web search API for the Researcher agent |
| Streamlit | Interactive demo interface |
| Pydantic | Structured tool schemas and validation |
MIT License -- see LICENSE for details.
- RAG Pipeline -- Retrieval-Augmented Generation with hybrid search
Built by Thiago Reiquileut · AI Engineer