Agents

Define AI agents with specific roles and capabilities

Agents are the workers in your formation. Each has a role, system prompt, and set of tools. MUXI automatically routes requests to the right agent.

New to agents? Read Agent Concepts → first for an overview of how agents work in MUXI.

API Reference: GET /v1/agents | GET /v1/agents/{id}

Your First Agent

Create agents/assistant.afs:

schema: "1.0.0"
id: assistant
name: Assistant
description: Helpful assistant

system_message: You are a helpful assistant who answers questions clearly.

That's it. One agent, ready to chat.

Agent Configuration

Full Example

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

system_message: |
  You research topics thoroughly and provide accurate,
  well-sourced information. Always cite your sources.

knowledge:
  enabled: true
  sources:
    - path: knowledge/docs/
      description: Internal documentation

llm_models:
  - text: "openai/gpt-4o"
    settings:
      temperature: 0.7

Configuration Fields

Required Fields

Field Type Description
schema string Schema version ("1.0.0")
id string Unique identifier (used in routing)
description string What the agent does - used by Overlord for routing

Identity & Behavior

Field Type Default Description
name string - Human-readable display name
system_message string - System prompt defining behavior
role enum - Agent's role: specialist, generalist, coordinator, researcher, executor
a2a_enabled bool true Enable agent-to-agent communication
enable_direct_delegation bool true Allow direct task delegation to other agents
delegation_strategy enum automatic How delegation works: automatic, ask_user, never

Specialization (for better routing)

specialization:
  domain: "customer-support"      # Primary expertise area
  subdomain: "technical-support"  # Specific focus
  expertise_level: "expert"       # junior, intermediate, senior, expert
  keywords: ["help", "issue", "troubleshoot"]  # Routing keywords

System Behavior (advanced)

system_behavior:
  constraints:
    - "Only answer questions about weather"
    - "Do not provide medical advice"
  capabilities:
    - "Weather forecasting"
    - "Climate data analysis"
  interaction_style: "friendly"    # formal, casual, technical, friendly, professional
  response_length: "moderate"      # concise, moderate, detailed, comprehensive
  error_handling: "user-friendly"  # graceful, explicit, technical, user-friendly

LLM Overrides

llm:
  settings:
    temperature: 0.7
    max_tokens: 4096
    timeout_seconds: 60
    max_retries: 3
    fallback_model: "openai/gpt-4o-mini"
  models:
    - text: "openai/gpt-4o"
    - vision: "openai/gpt-4o"
    - embedding: "openai/text-embedding-3-small"

Memory Overrides

memory:
  buffer:
    size: 50              # Context window size
    multiplier: 2         # Buffer multiplier
    vector_search: true   # Enable vector search

Knowledge

knowledge:
  files: ["knowledge/faq.md"]
  directories: ["knowledge/docs/"]
  auto_update: true
  embedding_model: "openai/text-embedding-3-small"
  chunk_size: 1000
  chunk_overlap: 100

Agent-Specific MCP Servers

Reference formation-level MCP servers by ID, or define agent-private servers inline:

mcp_servers:
  - web-search              # Reference formation-level MCP by ID
  - id: private-tool        # Agent-private inline definition
    description: Private tool
    type: command
    command: npx
    args: ["-y", "@example/private-tool"]

Rate Limiting & Timeouts

rate_limiting:
  requests_per_minute: 60
  requests_per_hour: 1000
  requests_per_day: 10000
  burst_limit: 10

timeout:
  default: 300   # seconds
  max: 600       # seconds

Metadata

metadata:
  version: "1.0.0"
  author: "Your Team"
  tags: ["support", "customer-facing"]
  icon: "🤖"

Multi-Agent Formations

The real power comes from multiple specialized agents:

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Researcher
description: Gathers accurate information

system_message: |
  You are a research specialist.
  Your job is to gather accurate information...
# agents/writer.afs
schema: "1.0.0"
id: writer
name: Writer
description: Creates content

system_message: |
  You are a content writer.
  Your job is to create clear, engaging content...
# agents/reviewer.afs
schema: "1.0.0"
id: reviewer
name: Reviewer
description: Reviews content quality

system_message: |
  You are an editor.
  Your job is to review content for accuracy, and to...
graph LR
    U[User Request] --> O[Overlord]
    O --> R[Researcher]
    O --> W[Writer]
    O --> V[Reviewer]
    R --> |research| W
    W --> |draft| V

MUXI's Overlord automatically routes requests to the best agent based on the task. You can also specify agents explicitly.

Agent Routing

Automatic Routing

MUXI analyzes requests and picks the right agent:

User:  "Find information about AI trends"
→ Routes to: researcher (has web-search)

User:  "Write a blog post about our product"
→ Routes to: writer (writing role)

Explicit Routing

Override automatic routing when needed:

muxi chat --agent researcher "Find info about AI trends"
curl -X POST http://localhost:8001/v1/chat \
  -d '{"message": "...", "agent": "researcher"}'
response = formation.chat(
    "Find info about AI trends",
    agent="researcher"
)
const response = await formation.chat('Find info about AI trends', {
  agent: 'researcher'
});
response, _ := formation.ChatWithOptions("Find info about AI trends", muxi.ChatOptions{
    Agent: "researcher",
})

Agent-Specific Tools

MCP servers are defined in mcp/*.afs files and declared in the formation's mcp.servers list. All agents have access to formation-level MCP servers. Agents can also reference specific formation-level servers by ID, or define agent-private tools inline:

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Researcher
description: Research specialist

system_message: |
  You are a research specialist.
  Your job is to gather accurate information...

# Reference formation-level MCP by ID
mcp_servers:
  - web-search
# agents/developer.afs
schema: "1.0.0"
id: developer
name: Developer
description: Code assistant

system_message: |
  You are a software developer.
  Your job is to write, review, and debug code...

# Mix: reference by ID + agent-private inline definition
mcp_servers:
  - filesystem             # Formation-level MCP
  - database               # Formation-level MCP
  - id: dev-tools          # Agent-private inline definition
    description: Development utilities
    type: command
    command: npx
    args: ["-y", "@example/dev-tools"]
# agents/writer.afs
schema: "1.0.0"
id: writer
name: Writer
description: Content writer

system_message: |
  You are a content writer.
  Your job is to create compelling written content...
# No mcp_servers - focuses purely on writing

Agent-Specific Knowledge

Different agents can access different knowledge bases:

# agents/support.afs
schema: "1.0.0"
id: support
name: Support Agent
description: Customer support specialist

system_message: Customer support specialist with FAQ access.

knowledge:
  enabled: true
  sources:
    - path: knowledge/faq/
      description: Customer FAQs
    - path: knowledge/troubleshooting/
      description: Troubleshooting guides
# agents/sales.afs
schema: "1.0.0"
id: sales
name: Sales Agent
description: Sales advisor

system_message: |
  You are a sales advisor.
  Your job is to help customers find the right products...

knowledge:
  enabled: true
  sources:
    - path: knowledge/pricing/
      description: Pricing and plans
    - path: knowledge/features/
      description: Product features

Agent-Specific Skills

Agents can have private skills that only they see:

my-formation/
└── agents/
    └── analyst/
        ├── analyst.afs
        └── skills/
            └── forecasting/
                └── SKILL.md

Formation-level skills (in skills/) are visible to all agents. Agent-level skills are private.

# agents/analyst.afs
schema: "1.0.0"
id: analyst
name: Data Analyst
description: Analyzes data and produces reports

system_message: |
  You are a data analyst.
  Use your skills to analyze data and generate reports.

The agent automatically sees its private forecasting skill plus all formation-level skills in its catalog.

Skills give agents knowledge and procedures. Tools (MCP) give agents external service access. Use both together for capable agents.

See Skills Reference for full SKILL.md syntax.

Separate Agent Files

Agents are defined in agents/*.afs files and must be listed in the formation manifest:

muxi new agent researcher

Creates agents/researcher.afs and adds researcher to the agents: list in your formation.afs:

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Research Specialist
description: Expert at gathering information

system_message: |
  You are an expert researcher who:
  - Gathers accurate information from multiple sources
  - Cites all sources properly
  - Provides balanced, objective analysis
  - Admits uncertainty when appropriate

In your formation, list the agents you want loaded:

# formation.afs
agents:
  - researcher

Best Practices

Clear roles matter. Well-defined, non-overlapping roles lead to better routing and results.

  1. Be specific - "Customer support for Acme SaaS products" beats "helpful assistant"
  2. Match tools to roles - Researchers get search, developers get filesystem
  3. One specialty per agent - Let each agent focus on what they do best
  4. Use separate files - Keep complex agent definitions organized

Next Steps

Tools (MCP) - Give agents capabilities
Skills - Add specialized knowledge and scripts
Knowledge - Add domain expertise
Multi-Agent Guide - Build agent teams
Examples - Complete agent examples

Home Registry Documentation Star on GitHub
Get priority support