Skip to content

README.md

Latest commit

 

History

History
225 lines (169 loc) · 8.87 KB

README.md

File metadata and controls

225 lines (169 loc) · 8.87 KB

Multi-Agent Task Solver (MATS)

A production-ready orchestration platform that enables specialized AI agents to collaborate through configurable workflows. The system delivers resilient execution with retries, per-agent timeouts, dependency-aware scheduling, and a pluggable tool ecosystem — all accessible through a FastAPI service and a command-line interface.

📌 Highlights

  • 47 automated tests covering agents, workflows, tools, execution engine, CLI, and API
  • Zero warnings — Pydantic v2 compliant (ConfigDict), clean lint status
  • Comprehensive documentation for developers and operators
  • Extensible architecture for adding new agents, tools, and workflow templates

🧱 Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│     Clients     │───▶│    FastAPI       │───▶│  Execution Engine │
└─────────────────┘    └──────────────────┘    └──────────────────┘
          │                        │                     │
          ▼                        ▼                     ▼
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│  Agent Registry │    │  Workflow  DAG   │    │   Tool Registry   │
└─────────────────┘    └──────────────────┘    └──────────────────┘
          │                        │                     │
          ▼                        ▼                     ▼
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ Built-in Agents │    │  Execution Tasks │    │  Built-in Tools  │
└─────────────────┘    └──────────────────┘    └──────────────────┘

Core modules:

Module Purpose
src/models/ Pydantic schemas for agents, workflows, and execution results
src/agents/ Base agent class, registry, and built-in agent implementations
src/core/ Workflow DAG builder and async execution engine
src/tools/ Tool interface, registry, and built-in tools
src/api/ FastAPI routes exposing workflow orchestration
src/main.py CLI entry point for running servers, workflows, and registry inspection

📂 Project Structure

src/
├── main.py                     # CLI entry point
├── agents/
│   ├── base_agent.py           # BaseAgent with retry & timeout
│   ├── builtin_agents.py       # Tool-backed agent implementations
│   └── registry.py             # AgentRegistry and global singleton
├── api/
│   └── routes.py               # FastAPI application factory & routes
├── core/
│   ├── workflow.py             # DAG construction & validation
│   └── execution_engine.py     # Layered async execution engine
├── models/
│   └── schemas.py              # Pydantic data models (ConfigDict based)
└── tools/
    ├── base_tool.py            # Tool abstraction
    ├── builtin_tools.py        # Fetcher, processor, calculator, chart tools
    └── registry.py             # ToolRegistry & global instance

tests/
├── test_agents.py              # Agent registry & retry logic
├── test_api.py                 # ASGI integration tests
├── test_builtin_agents.py      # Tool-backed agent behaviour
├── test_cli.py                 # CLI command coverage
├── test_execution_engine.py    # Execution engine workflows
├── test_models.py              # Schema validation & serialization
├── test_tools.py               # Tool registry & operations
└── test_workflow.py            # DAG validation and layering

🛠️ Installation & Setup

python -m venv .venv
.\.venv\Scripts\activate  # Windows

python -m pip install --upgrade pip
pip install -r requirements.txt
pip install pytest pytest-asyncio httpx  # optional dev deps

⚙️ Command-Line Interface

All runtime operations are available via the CLI:

# Launch the FastAPI server
python -m src.main runserver --host 0.0.0.0 --port 8000 [--reload]

# Inspect registered components
python -m src.main list-agents
python -m src.main list-tools

# Execute a workflow from a JSON definition
python -m src.main run-workflow --config path/to/workflow.json

The CLI bootstraps built-in tools and agents automatically before executing commands (other than runserver, which delegates to FastAPI initialization).

🌐 API Overview

create_app() builds a FastAPI application registered with all routes listed below.

Method Route Description
GET / Application metadata
GET /health Health check
GET /agents List registered agent types
GET /tools List registered tools
POST /workflows Execute a workflow (body: WorkflowRequest)
GET /workflows/{workflow_id} Retrieve workflow status
POST /workflows/{workflow_id}/cancel Cancel a running workflow
GET /workflows/templates/{template} Fetch built-in workflow templates

Sample WorkflowRequest

{
  "workflow_id": "example_pipeline",
  "initial_input": {"counter": 1},
  "agents": [
    {
      "agent_id": "step_a",
      "agent_type": "data_fetcher",
      "inputs": [],
      "config": {"source": "static"}
    },
    {
      "agent_id": "step_b",
      "agent_type": "data_processor",
      "inputs": ["step_a"],
      "config": {"operation": "sum"}
    }
  ]
}

🤖 Built-in Agents & Tools

Agent Type Backing Tool Purpose
data_fetcher data_fetcher Retrieves payloads from static/configured sources
data_processor data_processor Aggregates or transforms numeric lists
calculator calculator Performs arithmetic (add/subtract/multiply/divide)
chart_generator chart_generator Produces chart-ready series structures

Tool registry can be extended by registering new BaseTool implementations; agents can be added by subclassing ToolBackedAgent or BaseAgent directly.

🧮 Workflow Engine Features

  • Directed Acyclic Graph validation (cycles rejected)
  • Automatic calculation of execution layers for parallelism
  • Dependency checking (is_ready) before agent invocation
  • Async execution with configurable retries and exponential backoff
  • Per-agent timeouts enforced via asyncio.wait_for
  • Cancellation support for active workflows

✅ Testing

python -m pytest -v

Test suites: 47 total tests spanning agents, workflows, tools, API, CLI, and models. All tests pass with no warnings.

📦 Requirements

  • Python 3.8+
  • fastapi==0.104.1
  • uvicorn==0.24.0
  • pydantic==2.5.0
  • networkx==3.2.1
  • python-multipart==0.0.6

Dev/testing (optional): pytest, pytest-asyncio, httpx

🧭 Development Notes

  • All Pydantic models use ConfigDict, ensuring compatibility with Pydantic v2
  • .gitignore excludes bytecode caches, build artifacts, and virtual environments
  • CLI and API share the same execution engine and registries for consistency
  • Project status and verification details available in PROJECT_STATUS.md

📈 Roadmap Ideas

  • Pluggable authentication for the API
  • Persistent workflow history storage
  • Additional built-in tools (LLM integration, data exporters)
  • Front-end dashboard consuming the API

🛡️ License

Replace with your chosen license text.

Version: 1.0.0