Core Concepts

Overview

MARSYS is built on a layered architecture where each component has a specific responsibility. Understanding these core concepts will help you build sophisticated multi-agent systems effectively.

Architecture Overview

The MARSYS architecture consists of several interconnected layers:

• Orchestration Layer: Orchestra (High-level API), Topology Controller, Execution Coordinator
• Execution Layer: Branch Executor, Step Executor, Branch Spawner
• Validation & Routing: Validation Processor, Router, Rules Engine
• Agent Layer: Agent Registry, Agent Pools, Agents
• Infrastructure: Communication Manager, State Manager, Memory Manager

Concept Categories

Core Components

These are the fundamental building blocks of every MARSYS application:

Advanced Topics

Advanced concepts for building sophisticated systems:

Learning Path

For Beginners

1. Start with Agents to understand the basic building blocks
2. Learn about Memory and how agents retain information
3. Explore Tools to extend agent capabilities
4. Understand Communication patterns

For Intermediate Users

1. Master Topology for complex workflows
2. Implement Error Handling for production systems
3. Explore State Management for persistence
4. Learn Custom Agents development

For Advanced Users

1. Build Learning Agents with adaptation
2. Implement Browser Automation for web tasks
3. Design complex topologies with dynamic branching
4. Optimize performance with agent pools

Key Design Principles

1. Pure Agent Logic

Agents implement pure _run() methods without side effects:

async def _run(self, prompt, context, **kwargs):
    # Pure logic - no memory manipulation
    # No logging, no state changes
    # Just process and return
    messages = self._prepare_messages(prompt)
    response = await self.model.run(messages)
    return Message(role="assistant", content=response.content)

2. Centralized Validation

All response processing happens in one place:

# ValidationProcessor handles ALL parsing
- JSON responses
- Structured data
- Tool calls
- Agent invocations
- Error classification

3. Dynamic Branching

Branches created at runtime for parallel execution:

# Agents decide parallelism dynamically
{
    "next_action": "parallel_invoke",
    "agents": ["A", "B", "C"],  # Spawns 3 branches
    "agent_requests": {...}
}

4. Branch Isolation

Each branch maintains independent state:

• Separate memory contexts
• Individual execution traces
• Isolated metadata
• Independent status tracking

5. Topology-Driven Routing

All routing decisions based on topology:

topology = {
    "agents": ["A", "B", "C"],
    "flows": ["A -> B", "B -> C"],  # Defines allowed paths
    "rules": [...]  # Additional constraints
}

Core Execution Flow

Understanding the execution flow is crucial:

1. Task Submission

result = await Orchestra.run(task, topology)

2. Topology Analysis

• Identify entry points
• Detect convergence nodes
• Validate agent permissions
• Apply rules

3. Branch Creation

• Initial branches at entry points
• Dynamic spawning for parallel work
• Parent-child relationships

4. Step Execution

Validate → Route → Execute → Process → Continue

5. Convergence

• Wait for child branches
• Aggregate results
• Resume parent execution

6. Completion

• Extract final response
• Return OrchestraResult

Agent Communication Patterns

Sequential

A → B → C → Final

Parallel

┌→ B →┐
A →─┼→ C →┼→ E
    └→ D →┘

Conversation

A ⟷ B (multiple rounds)

Hierarchical

Manager
    /        \
  Lead1      Lead2
  /   \      /   \
W1    W2    W3    W4

Error Recovery Strategies

MARSYS provides multiple levels of error handling:

1. Step-Level Retry

Automatic retry with exponential backoff

2. Error Classification

Different strategies for different error types:

• Rate Limits: Wait and retry
• Invalid Input: Route to user
• API Errors: Fallback models
• Timeouts: Cancel and recover

3. User Recovery

Route errors to User node for manual intervention

4. Graceful Degradation

Continue with partial results when possible

Performance Considerations

Agent Pools

Use pools for true parallelism:

pool = AgentPool(agent_class=BrowserAgent, num_instances=3)

Memory Management

Choose appropriate retention:

• single_run: Stateless, minimal memory
• session: Balanced for most use cases
• persistent: Long-term learning

Timeout Configuration

Set appropriate timeouts:

• Step timeout: Individual operations
• Branch timeout: Complete workflows
• Convergence timeout: Parallel coordination

Status Verbosity

Adjust output for performance:

• QUIET: Production (minimal overhead)
• NORMAL: Development
• VERBOSE: Debugging

Next Steps

Ready to dive deeper into specific concepts?

• Learn About Agents - Start with the fundamental building blocks
• Explore Topologies - Design complex interaction patterns
• API Reference - Detailed class and method documentation
• See Examples - Learn from real-world implementations