MARSYS - Multi-Agent Reasoning Systems

---

What is MARSYS?

MARSYS (Multi-Agent Reasoning Systems) is a Python framework for building and coordinating multi-agent AI systems. It provides flexible topology definitions, parallel execution with agent pools, state persistence, and human-in-the-loop support.

Core Features

• Multi-Agent Orchestration: Coordinate workflows with multiple specialized agents
• Flexible Topologies: Define agent relationships using strings, objects, or pre-defined patterns
• Parallel Execution: True concurrency with AgentPool and dynamic branch spawning
• State Persistence: Pause/resume with checkpointing for long-running tasks
• Human-in-the-Loop: Built-in user interaction for approval workflows and error recovery
• Multi-Model Support: OpenAI, Anthropic, Google, OpenRouter, xAI, and local models

---

Quick Start

Installation

Create and activate a virtual environment with uv:

uv venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate   # Windows

Install MARSYS:

pip install marsys

With optional dependencies:

pip install marsys[local-models]  # Local model support (PyTorch, Transformers)
pip install marsys[production]    # Production inference (vLLM, Flash Attention)
pip install marsys[dev]           # Everything (local-models + production + testing + docs)

Install from source (for development):

git clone https://github.com/rezaho/MARSYS.git
cd MARSYS
pip install -e ".[dev]"

API Key Configuration

Configure your API keys via environment variables or a .env file:

# Environment variables
export OPENROUTER_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"

Or create a .env file in your project root:

OPENROUTER_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here

OAuth alternative (no API keys):

• OpenAI ChatGPT subscription: codex login → credentials in ~/.codex/auth.json
• Anthropic Claude Max subscription: claude login → credentials in ~/.claude/.credentials.json
• Google Antigravity gateway: marsys oauth add <profile> --provider google-oauth → credentials in ~/.marsys/oauth/<profile>/credentials.json

Use provider="openai-oauth", provider="anthropic-oauth", or provider="google-oauth" in ModelConfig.

Note:

• anthropic-oauth and google-oauth rely on non-official integration paths and may violate provider Terms of Service. Use at your own risk.

Playwright Setup (BrowserAgent only)

Only required if you plan to use BrowserAgent for web automation:

playwright install chromium --with-deps

Basic Usage

A simple two-agent collaboration using allowed_peers:

from marsys.agents import Agent
from marsys.models import ModelConfig

model_config = ModelConfig(
    type="api",
    name="anthropic/claude-opus-4.6",
    provider="openrouter"
)

researcher = Agent(
    model_config=model_config,
    name="Researcher",
    goal="Expert at finding and analyzing information",
    instruction="You are a research specialist. Find and analyze information thoroughly.",
    allowed_peers=["Writer"]
)

writer = Agent(
    model_config=model_config,
    name="Writer",
    goal="Skilled at creating clear, engaging content",
    instruction="You are a skilled writer. Create clear, engaging content based on research.",
    allowed_peers=[]
)

result = await researcher.auto_run(
    task="Research the latest AI breakthroughs and write a summary",
    max_steps=20,
    verbosity=1
)

print(result)

Using Orchestra with Topology

For more control, define the topology explicitly using Orchestra.run():

from marsys.coordination import Orchestra
from marsys.agents import Agent
from marsys.models import ModelConfig

model_config = ModelConfig(
    type="api",
    name="anthropic/claude-opus-4.6",
    provider="openrouter"
)

researcher = Agent(
    model_config=model_config,
    name="Researcher",
    goal="Expert at finding and analyzing information",
    instruction="You are a research specialist. Find and analyze information thoroughly."
)

writer = Agent(
    model_config=model_config,
    name="Writer",
    goal="Skilled at creating clear, engaging content",
    instruction="You are a skilled writer. Create clear, engaging content based on research."
)

topology = {
    "agents": ["Researcher", "Writer"],
    "flows": ["Researcher -> Writer"]
}

result = await Orchestra.run(
    task="Research the latest AI breakthroughs and write a summary",
    topology=topology
)

print(result.final_response)

More examples

---

Contributing

We welcome contributions from the community. MARSYS is an open-source project that thrives on collaboration.

Contributor License Agreement (CLA)

Before your first contribution can be merged, you must sign our CLA. This is a one-time, automated process:

1. Open a pull request
2. CLA Assistant bot will comment with a link
3. Click the link and sign
4. Your PR will be automatically unblocked

The CLA ensures legal clarity and protects both contributors and the project. You retain ownership of your code and can use it elsewhere. See docs/CLA.md for full details.

How to Contribute

1. Fork the repository and create your branch from main
2. Make your changes and ensure tests pass
3. Write/update tests for your changes
4. Submit a pull request with a clear description

Development Setup

git clone https://github.com/rezaho/MARSYS.git
cd MARSYS
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
flake8 src/
black src/ --check

Contributing guide

---

Citation

If you use MARSYS in your research or projects, please cite:

@software{marsys2025,
  author = {Hosseini, Reza},
  title = {MARSYS: Multi-Agent Reasoning Systems Framework},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/rezaho/MARSYS}
}

---

License

MARSYS is released under the Apache License 2.0. See LICENSE for full terms.

Copyright 2025 Marsys Project. Original Author: rezaho

---