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

mcp_servers:
  - id: web-search
    description: Web search
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-brave-search"]

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. All agents in a formation have access to formation-level MCP servers. For agent-specific tools, define them in the agent file:

# 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...

# Agent-specific MCP server
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 }}"
# 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...

mcp_servers:
  - id: filesystem
    description: File access
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
  - id: database
    description: PostgreSQL access
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    auth:
      type: env
      DATABASE_URL: "${{ secrets.DATABASE_URL }}"
# 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

Separate Agent Files

Agents are auto-discovered from agents/*.afs files:

muxi new agent researcher

Creates agents/researcher.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, just leave agents empty - they're auto-discovered:

# formation.afs
agents: []  # Auto-discovered from agents/ directory

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
Knowledge - Add domain expertise
Multi-Agent Guide - Build agent teams
Examples - Complete agent examples

Home Registry Documentation Star on GitHub
Get priority support