Quick Start

Build your first multi-agent system in just 10 minutes! This guide will get you up and running with MARSYS quickly.

What We'll Build

In this quickstart, you'll create:

A simple single agent
A multi-agent research team
A system with parallel execution
An interactive system with user input

Prerequisites

Before starting, complete these setup steps:

1. Set Up Virtual Environment

Recommended: Use uv for faster installation

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh  # Unix/macOS
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate  # Windows

Alternative: Use standard Python venv

python -m venv .venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate  # Windows

2. Install MARSYS

# With uv (recommended)
uv pip install marsys

# Or with pip
pip install marsys

3. Configure API Keys (Required for API Models)

This is required if you are using API models to run the agents!

Create a .env file in your project directory:

# .env
OPENAI_API_KEY="your-key-here"
ANTHROPIC_API_KEY="your-key-here"
GOOGLE_API_KEY="your-key-here"

Or set environment variables:

# Unix/macOS/Linux
export OPENAI_API_KEY="your-key-here"

# Windows (PowerShell)
$env:OPENAI_API_KEY="your-key-here"

4. Install Playwright Browsers (Optional)

Only needed if using BrowserAgent examples

After installing MARSYS, run:

playwright install chromium

Skip this if you're not using BrowserAgent - all other features work without it.

Ready!

You now have Python 3.12+, MARSYS installed, and API keys configured.

Example 1: Your First Agent

Let's start with the simplest possible example:

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

async def main():
    # Create the agent first
    poet = Agent(
        model_config=ModelConfig(
            type="api",
            name="anthropic/claude-opus-4.6",
            provider="openrouter"
        ),
        name="Poet",
        goal="Creative poet",
        instruction="You are a talented poet who writes beautiful, evocative poetry."
    )

    # One-line execution
    result = await Orchestra.run(
        task="Write a haiku about artificial intelligence",
        topology={"agents": ["Poet"], "flows": []}
    )

    print(result.final_response)

asyncio.run(main())

Output:

Silicon mind thinks,
Algorithms dance in code,
Future awakening.

Example 2: Two-Agent Collaboration

Now let's have two agents work together using the simplest approach - allowed_peers:

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

async def main():
    # Create a single model configuration
    model_config = ModelConfig(
        type="api",
        name="anthropic/claude-opus-4.6",
        provider="openrouter"
    )

    # Create specialized agents with allowed_peers
    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"]  # Can invoke 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=[]  # Cannot invoke other agents
    )

    # Run with automatic topology creation from allowed_peers
    result = await researcher.auto_run(
        task="Research the latest AI breakthroughs and write a summary",
        max_steps=20,
        verbosity=1  # Show progress
    )

    print(result)

asyncio.run(main())

Four Ways to Define Multi-Agent Systems

This example uses the simplest approach (Way 1: allowed_peers + auto_run). MARSYS offers four different ways to define agent interactions, from simple peer-based to sophisticated pattern configurations.

Example 3: Simple Three-Agent Workflow

Let's create a workflow with three agents working in sequence:

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

async def main():
    # Use a single model configuration
    model_config = ModelConfig(
        type="api",
        name="anthropic/claude-opus-4.6",
        provider="openrouter"
    )

    # Create three specialized agents
    data_collector = Agent(
        model_config=model_config,
        name="DataCollector",
        goal="Collects and gathers relevant data",
        instruction="You are a data collection specialist. Gather relevant information systematically."
    )

    analyzer = Agent(
        model_config=model_config,
        name="Analyzer",
        goal="Analyzes collected data and finds patterns",
        instruction="You are a data analyst. Analyze data thoroughly and identify key patterns."
    )

    reporter = Agent(
        model_config=model_config,
        name="Reporter",
        goal="Creates comprehensive reports from analysis",
        instruction="You are a report writer. Create clear, comprehensive reports from analysis results."
    )

    # Define sequential workflow
    topology = {
        "agents": ["DataCollector", "Analyzer", "Reporter"],
        "flows": [
            "DataCollector -> Analyzer",
            "Analyzer -> Reporter"
        ]
    }

    # Run the workflow
    result = await Orchestra.run(
        task="Analyze market trends in the technology sector",
        topology=topology
    )

    print(result.final_response)

asyncio.run(main())

Congratulations!

You've completed the Quick Start and learned the core MARSYS patterns:

Single agent execution
Multi-agent collaboration
Sequential workflows

What's Next?

Ready to build more advanced systems? Explore these topics:

Agent Tools

Give agents superpowers with custom tools

User Interaction

Build human-in-the-loop workflows

Browser Automation

Automate web tasks with BrowserAgent

Advanced Patterns

Pipeline, mesh, and hierarchical topologies

Key Concepts to Remember

1. Everything is Async

All MARSYS operations are asynchronous. Always use async/await:

async def main():
    result = await Orchestra.run(...)

asyncio.run(main())

2. Topology Defines Flow

The topology determines how agents communicate:

topology = {
    "agents": ["A", "B", "C"],
    "flows": ["A -> B", "B -> C"]  # A calls B, B calls C
}

3. Agents Auto-Register

Creating an agent automatically registers it:

agent = Agent(name="MyAgent", ...)  # Auto-registered

4. Patterns Simplify Complex Workflows

Use pre-defined patterns instead of manual topology:

topology = PatternConfig.hub_and_spoke(...)  # Easier than manual

5. Configuration Controls Behavior

Fine-tune execution with configs:

config = ExecutionConfig(
    convergence_timeout=300,  # Max wait for parallel branches
    status=StatusConfig.from_verbosity(2)  # Detailed output
)

Performance Tips

Use Parallel Execution: Set parallel_spokes=True for independent tasks
Configure Timeouts: Prevent hanging with appropriate timeouts
Use Agent Pools: For true parallelism with stateful agents
Cache Results: Agents remember conversations within a session
Minimize Steps: Set reasonable max_steps to avoid unnecessary iterations

Next Steps

Now that you've built your first multi-agent systems:

Create Custom Agents

Learn to build specialized agents with custom logic

Master Configuration

Fine-tune timeouts, retries, and execution behavior

Understand Topologies

Design complex agent interaction patterns

Explore Examples

See real-world implementations

Troubleshooting

Why is my agent not responding?

Check that:

The agent name in topology matches the created agent
API keys are correctly configured
The model name is valid for your provider

How do I debug agent interactions?

Use verbose output:

config = ExecutionConfig(
    status=StatusConfig.from_verbosity(2)
)

Can agents work in parallel?

Yes! Use parallel_spokes=True in hub-and-spoke pattern or create parallel branches in your topology.

Ready for More?

You've mastered the basics! Now explore Your First Agent to create custom agents with specialized capabilities.

Navigation