Skip to content

About

A lightweight multi-agent orchestration framework built with LangGraph using a Supervisor pattern to coordinate specialized AI agents

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Multi-Agent Orchestrator

CI Coverage: 99% Python 3.11+ LangGraph License: MIT Streamlit Ruff

A lightweight multi-agent orchestration framework built with LangGraph that uses a Supervisor pattern to coordinate specialized AI agents for collaborative task solving.


Table of Contents


Architecture

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

How It Works

  1. User submits a task via Streamlit UI or API
  2. Supervisor agent analyzes the task and routes to the appropriate specialist
  3. Specialist agents execute their part and return results to shared state
  4. Supervisor evaluates progress and either routes to another agent or finalizes
  5. Final output is assembled and presented to the user

Agent Roles

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

Quick Start

Prerequisites

  • Python 3.11+
  • API keys: OpenAI or Anthropic + Tavily (for web search)

Installation

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

Run the Demo

# 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

docker compose up --build
# Open http://localhost:8501

Project Structure

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

Configuration

Environment Variables

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.

Customizing Agents

Each agent is a self-contained module. To add a new agent:

  1. Create src/agents/your_agent.py with an async node function
  2. Register it in src/orchestrator.py
  3. 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)]
    }

Testing

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"

Example Use Cases

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

Tech Stack

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

License

MIT License -- see LICENSE for details.


Related Projects

  • RAG Pipeline -- Retrieval-Augmented Generation with hybrid search

Built by Thiago Reiquileut · AI Engineer

About

A lightweight multi-agent orchestration framework built with LangGraph using a Supervisor pattern to coordinate specialized AI agents

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages