agentmesh-orchestrator

AgentMesh

A production-grade multi-agent orchestration platform built on Microsoft AutoGen, enabling sophisticated agent collaboration through mesh networking with CLI and REST API interfaces.

Features

🤖 Multi-Agent Orchestration

• Sequential: Linear workflows where agents build on each other's work
• Round-Robin: Collaborative discussions with turn-based participation
• Graph-Based: Complex workflows with conditional branching and parallel execution
• Swarm Coordination: Autonomous agent collaboration with self-organizing behavior

🔧 Flexible Communication

• Message passing with context preservation
• Agent handoff mechanisms with specialization routing
• Real-time monitoring and analytics
• Parameter tuning during execution

💻 Dual Interface

• CLI Tool: Complete command-line interface for workflow management
• REST API: Full-featured API with OpenAPI documentation
• Configuration: YAML-based workflow definitions with validation

🚀 Production Ready

• Real-time monitoring and metrics
• Performance optimization and caching
• Comprehensive logging and debugging
• Scalable architecture with AutoGen native integration

📊 Advanced Features

• Graph visualization (ASCII, Mermaid, JSON)
• Swarm analytics and handoff pattern analysis
• Runtime parameter tuning
• Quality gates and conditional routing
• Parallel execution and synchronization

Quick Start

Installation

# Install with Poetry (recommended)
poetry install

# Or with pip
pip install -e .

Basic Usage

CLI Interface

# Create agents
agentmesh agent create --name "architect" --type "assistant" --model "gpt-4o"
agentmesh agent create --name "developer" --type "assistant" --model "gpt-4o"

# List agents
agentmesh agent list

# Create and run a workflow
agentmesh workflow create --config examples/code-review-workflow.yaml
agentmesh workflow run --id workflow-123 --task "Build a REST API for user management"

API Interface

# Start the API server
agentmesh server start --port 8000

# Create agent via API
curl -X POST "http://localhost:8000/api/v1/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "architect",
    "type": "assistant",
    "model": "gpt-4o",
    "system_message": "You are a software architect"
  }'

Orchestration Patterns & Examples

AutoGen A2A supports four distinct orchestration patterns, each optimized for different collaboration scenarios:

1. Sequential Orchestration

Use Case: Linear workflows where each agent builds on the previous agent's work.

# examples/workflows/sequential-code-review.yaml
name: "Code Review Pipeline"
pattern: "sequential"

agents:
  - name: "developer"
    type: "assistant"
    system_message: "You write clean, well-documented code"
  - name: "reviewer"
    type: "assistant"
    system_message: "You review code for best practices and bugs"
  - name: "architect"
    type: "assistant"
    system_message: "You ensure architectural compliance"

execution:
  max_rounds: 3
  timeout: 1800

# Run sequential workflow
agentmesh workflow create --config sequential-code-review.yaml
agentmesh workflow execute workflow-123 --task "Implement user authentication API"

2. Round-Robin Orchestration

Use Case: Collaborative discussions where agents take turns contributing ideas.

# examples/workflows/round-robin-brainstorm.yaml
name: "Product Brainstorming Session"
pattern: "round_robin"

agents:
  - name: "product_manager"
    type: "assistant"
    system_message: "You focus on user needs and business value"
  - name: "designer"
    type: "assistant"
    system_message: "You consider user experience and interface design"
  - name: "engineer"
    type: "assistant"
    system_message: "You evaluate technical feasibility"

termination:
  type: "max_messages"
  value: 12

execution:
  max_rounds: 4
  timeout: 2400

# Run round-robin workflow
agentmesh workflow create --config round-robin-brainstorm.yaml
agentmesh workflow execute workflow-123 --task "Design a mobile app for food delivery"

3. Graph-Based Orchestration

Use Case: Complex workflows with conditional branching, parallel execution, and quality gates.

# examples/workflows/graph-product-development.yaml
name: "Product Development Pipeline"
pattern: "graph"

agents:
  - name: "product_manager"
    type: "assistant"
  - name: "designer"
    type: "assistant"
  - name: "frontend_dev"
    type: "assistant"
  - name: "backend_dev"
    type: "assistant"
  - name: "qa_engineer"
    type: "assistant"

graph:
  nodes:
    - id: "requirements"
      agent: "product_manager"
      description: "Define product requirements"
    - id: "design"
      agent: "designer"
      description: "Create UI/UX designs"
    - id: "frontend"
      agent: "frontend_dev"
      description: "Implement frontend"
    - id: "backend"
      agent: "backend_dev"
      description: "Implement backend"
    - id: "testing"
      agent: "qa_engineer"
      description: "Test and validate"
  
  edges:
    - id: "req_to_design"
      source: "requirements"
      target: "design"
      type: "sequential"
    - id: "design_to_frontend"
      source: "design"
      target: "frontend"
      type: "parallel"
    - id: "design_to_backend"
      source: "design"
      target: "backend"
      type: "parallel"
    - id: "frontend_to_testing"
      source: "frontend"
      target: "testing"
      type: "synchronize"
    - id: "backend_to_testing"
      source: "backend"
      target: "testing"
      type: "synchronize"
  
  conditions:
    quality_gate:
      type: "evaluation"
      criteria: ["code_quality", "test_coverage"]

# Run graph workflow with visualization
agentmesh workflow create --config graph-product-development.yaml
agentmesh workflow visualize workflow-123 --format mermaid
agentmesh workflow execute workflow-123 --task "Build an e-commerce checkout system"

4. Swarm Coordination

Use Case: Autonomous agent collaboration with self-organizing behavior and dynamic handoffs.

# examples/workflows/swarm-research-analysis.yaml
name: "Research Analysis Swarm"
pattern: "swarm"

agents:
  - name: "data_collector"
    type: "assistant"
    system_message: "You excel at gathering research data from multiple sources"
  - name: "analyst"
    type: "assistant"
    system_message: "You analyze data and identify patterns and insights"
  - name: "statistician"
    type: "assistant"
    system_message: "You perform statistical analysis and validation"
  - name: "report_generator"
    type: "assistant"
    system_message: "You create comprehensive research reports"

swarm:
  participants:
    - agent_id: "data_collector"
      specializations: ["data_collection", "web_scraping", "research"]
      handoff_targets: ["analyst", "statistician"]
      participation_weight: 1.2
      max_consecutive_turns: 3
    
    - agent_id: "analyst"
      specializations: ["data_analysis", "pattern_recognition", "insights"]
      handoff_targets: ["statistician", "report_generator"]
      participation_weight: 1.0
      max_consecutive_turns: 4
    
    - agent_id: "statistician"
      specializations: ["statistics", "validation", "hypothesis_testing"]
      handoff_targets: ["analyst", "report_generator"]
      participation_weight: 0.8
      max_consecutive_turns: 2
    
    - agent_id: "report_generator"
      specializations: ["writing", "reporting", "documentation"]
      handoff_targets: ["analyst"]
      participation_weight: 1.0
      max_consecutive_turns: 3

  termination:
    max_messages: 25
    timeout_seconds: 1800

  handoff_config:
    autonomous_threshold: 0.7
    broadcast_threshold: 0.3
    load_balancing: true

# Run swarm workflow with monitoring
agentmesh swarm create --config swarm-research-analysis.yaml
agentmesh swarm monitor --id swarm-123 --metrics all --refresh 5
agentmesh swarm tune --id swarm-123 --parameter participation_balance --value 0.8
agentmesh swarm analytics --id swarm-123 --output json

Pattern Comparison

Advanced Examples

For complete examples with full configurations, see the examples/workflows/ directory:

• Sequential: sequential-document-processing.yaml, sequential-data-pipeline.yaml
• Round-Robin: round-robin-creative-writing.yaml, round-robin-problem-solving.yaml
• Graph: graph-code-review.yaml, graph-content-creation-pipeline.yaml, graph-advanced-product-development.yaml
• Swarm: swarm-product-development.yaml, swarm-content-creation.yaml, swarm-financial-analysis.yaml

Documentation

• Getting Started Guide
• API Reference
• CLI Reference
• Orchestration Patterns
• Graph Workflows
• Swarm Coordination
• Examples

Pattern-Specific Guides

• Sequential & Round-Robin: Built-in patterns for linear and collaborative workflows
• Graph Workflows: Complex workflows with conditional branching, parallel execution, and quality gates
• Swarm Coordination: Autonomous agent collaboration with self-organizing behavior

CLI Quick Reference

# Workflow Management
agentmesh workflow create --config config.yaml
agentmesh workflow list --status running
agentmesh workflow execute workflow-123 --task "Your task here"
agentmesh workflow get workflow-123 --format json

# Graph Workflows
agentmesh workflow visualize workflow-123 --format mermaid
agentmesh workflow pause workflow-123
agentmesh workflow resume workflow-123

# Swarm Coordination
agentmesh swarm create --config swarm-config.yaml
agentmesh swarm monitor --id swarm-123 --metrics all
agentmesh swarm tune --id swarm-123 --parameter participation_balance --value 0.8
agentmesh swarm analytics --id swarm-123 --output json

# Agent Management
agentmesh agent create --name "agent" --type "assistant" --model "gpt-4o"
agentmesh agent list --format table

Development

Prerequisites

• Python 3.11+
• Poetry
• Redis (for message queuing)
• PostgreSQL (for persistence)

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd autogen-agent

# Install dependencies
poetry install

# Setup pre-commit hooks
poetry run pre-commit install

# Start development services
docker-compose up -d redis postgres

# Run tests
poetry run pytest

# Start development server
poetry run agentmesh server start --reload

Project Structure

agentmesh/
├── src/
│   └── agentmesh/
│       ├── api/           # FastAPI application
│       ├── cli/           # CLI commands
│       ├── core/          # Core agent logic
│       ├── models/        # Data models
│       ├── services/      # Business logic
│       └── utils/         # Utilities
├── tests/                 # Test suite
├── docs/                  # Documentation
├── examples/              # Example workflows
└── deployment/            # Deployment configs

Implementation Status

This project is currently under active development following the Sprint Planning Document.

✅ Completed Sprints

• Sprint 1: Core Foundation & CLI Bootstrap
• Sprint 2: REST API Foundation & Agent Registry
• Sprint 3: Message Infrastructure & Communication
• Sprint 4: Security, Monitoring & Handoff Management
• Sprint 5: Sequential & Round-Robin Orchestration
• Sprint 6: Graph-based Workflows
• Sprint 7: Swarm Coordination

🔄 Current Focus: Sprint 8 - Performance Optimization & Caching

System Status: Production-ready for orchestration patterns, monitoring, and CLI/API interfaces.

Key Features Available:

• ✅ Multi-Agent Orchestration: All four patterns (Sequential, Round-Robin, Graph, Swarm)
• ✅ CLI Interface: Complete command-line tool with workflow management
• ✅ REST API: Full API with OpenAPI documentation
• ✅ Monitoring: Real-time metrics, analytics, and visualization
• ✅ Configuration: YAML-based workflow definitions with validation
• ✅ Examples: Comprehensive examples for all orchestration patterns

See the full implementation roadmap for detailed progress tracking.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• Microsoft AutoGen
• AutoGen Studio
• AutoGen Core