Multi-Agent Systems

Create teams of specialized agents

Ask ChatGPT Ask Claude.ai Open in Cursor

Build formations where multiple agents with different skills work together. A researcher gathers information, a writer creates content, a reviewer checks quality - MUXI orchestrates them automatically.

Overview

Multi-agent systems divide work among specialists:

         User Request
              ↓
      ┌───────────────┐
      │   Overlord    │  ← Coordinates
      └───────────────┘
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
Researcher  Writer   Reviewer

The Overlord routes requests automatically. SOP matches take priority, then explicit agent selection, then complexity-based routing.

Step 1: Define Agents

Create agent files in agents/ directory.

Be specific about roles and specialties. The Overlord uses description, role, and specialization fields to route requests to the right agent. Vague descriptions lead to poor routing.

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Research Specialist
description: Gathers accurate information from web searches and documents

role: researcher
specialization:
  domain: research
  keywords: [search, investigate, find, gather, sources]

system_message: |
  You research topics thoroughly.
  Gather accurate, well-sourced information.

# agents/writer.afs
schema: "1.0.0"
id: writer
name: Content Writer
description: Creates blog posts, articles, and marketing copy

role: executor
specialization:
  domain: content-writing
  keywords: [write, draft, compose, article, blog, copy]

system_message: |
  You write clear, engaging content.
  Follow style guidelines.

# agents/reviewer.afs
schema: "1.0.0"
id: reviewer
name: Content Reviewer
description: Reviews and edits content for accuracy, clarity, and tone

role: specialist
specialization:
  domain: editing
  keywords: [review, edit, proofread, check, quality]

system_message: |
  You review content for accuracy.
  Check clarity and tone.

Why this matters:

description - The Overlord reads this to understand what the agent does
role - Categorizes the agent (specialist, generalist, coordinator, researcher, executor)
specialization.keywords - Helps match user requests to the right agent

Step 2: Add Tools

Prefer per-agent tools over global tools. Define MCP servers in agent files (mcp_servers:) rather than formation-level (mcp/*.afs) for better routing accuracy.

Why: The Overlord uses tool capabilities to select the right agent. Per-agent tools mean:

Better agent routing (Overlord knows which agent has which tools)
Better tool selection (agents only see relevant tools)

When to use global tools: Only for tools that genuinely apply to ALL agents. For example, a web fetch tool useful for both a research agent AND a shopping agent.

Per-Agent Tools (Recommended)

Define tools directly in agent files:

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Research Specialist
description: Gathers accurate information from web searches

mcp_servers:
  - id: web-search
    description: Brave web search
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    auth:
      type: env
      BRAVE_API_KEY: "${{ secrets.BRAVE_API_KEY }}"

Global Tools (When Needed)

For tools used by ALL agents, create MCP files in mcp/ directory:

# mcp/web-fetch.afs - Useful for research, shopping, support agents
schema: "1.0.0"
id: web-fetch
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-fetch"]

Step 3: Configure Orchestration

# formation.afs
overlord:
  workflow:
    auto_decomposition: true
    complexity_threshold: 5.0

Step 4: Test

muxi dev

Complex request:

You: Research AI trends and write a blog post about them

MUXI:

Routes to researcher (gathers info)
Routes to writer (creates draft)
(Optionally) Routes to reviewer

Agent Specialization

By System Message

Each agent has a specialized system_message in agents/*.afs:

# agents/support.afs - Customer support focus
# agents/sales.afs - Sales advisor focus
# agents/technical.afs - Technical expert focus

By Tools

Give agents specific MCP servers via mcp_servers in agent files:

# agents/researcher.afs - Has web-search mcp_servers
# agents/data-analyst.afs - Has database mcp_servers
# agents/developer.afs - Has github, filesystem mcp_servers

By Knowledge

Configure knowledge sources per agent:

# agents/product-expert.afs
schema: "1.0.0"
id: product-expert
name: Product Expert
description: Product knowledge expert

system_message: |
  You are a product expert.
  Your job is to answer questions about our products...

knowledge:
  enabled: true
  sources:
    - path: knowledge/product/

Explicit Agent Selection

Override automatic routing:

# CLI
muxi chat --agent researcher "Find info on X"

# API
curl -d '{"message": "...", "agent": "researcher"}'

Best Practices

Clear roles - Non-overlapping responsibilities
Right tools - Match tools to agent purpose
Focused knowledge - Relevant sources per agent
Test routing - Verify correct agent selection

Learn More

Agents Reference - Configuration
Agents Concept - Architecture
Workflows Reference - Routing configuration
Deep Dive: Orchestration - How routing works
Write SOPs - Standard procedures
Example: Multi-Agent Team - Working example

We use cookies