Formations

Define complete AI systems in YAML

A formation is everything your AI needs: agents, tools, memory, knowledge, and workflows - all in one portable package.

What's in a Formation?

my-formation/
├── formation.afs      # Main configuration
├── agents/            # Agent definitions (auto-discovered)
├── mcp/               # Tool configurations (auto-discovered)
├── sops/              # Standard procedures (auto-discovered)
├── triggers/          # Webhook templates (auto-discovered)
├── knowledge/         # RAG sources
├── secrets.enc        # Encrypted credentials
└── secrets.example    # Template for required secrets

Basic Formation

The simplest formation that works:

# formation.afs
schema: "1.0.0"
id: my-assistant
name: My Assistant

llm:
  models:
    - text: "openai/gpt-4o"
  api_keys:
    openai: "${{ secrets.OPENAI_API_KEY }}"

agents: []  # Auto-discovered from agents/ directory

File extension .afs stands for Agent Formation Schema. You can also use .afs or .yml.

Formation Components

Agents

AI agents with roles and capabilities. Define specialists like researchers, writers, or support staff.

Tools (MCP)

Give agents superpowers - web search, file access, databases, and any MCP server.

Memory

Three-tier memory system: buffer, vector search, and persistent storage.

Knowledge

RAG from your documents - PDFs, markdown, and more.

Triggers

Webhooks that invoke your agents from external systems.

SOPs

Standard operating procedures for consistent workflows.

Create Your First Formation

  1. Generate the structure

    muxi new formation my-assistant
cd my-assistant

  2. Configure your secrets

    muxi secrets setup

    Enter API keys when prompted.

  3. Run locally

    muxi dev

  4. Deploy to server

    muxi deploy

Quick Reference

Section Purpose Required
schema Schema version Yes
id Unique identifier Yes
llm Language model config Yes
agents Agent definitions Yes (at least one)
memory Memory configuration No
mcps MCP tool integrations No
triggers Webhook triggers No
knowledge RAG sources No

Minimal Example

The simplest multi-agent formation:

# formation.afs
schema: "1.0.0"
id: research-assistant
description: AI research and writing team

llm:
  models:
    - text: "openai/gpt-4o"
  api_keys:
    openai: "${{ secrets.OPENAI_API_KEY }}"

agents: []  # Auto-discovered from agents/ directory
# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Researcher
description: Research topics with web search

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

This minimal example works! MUXI provides sensible defaults for memory, workflows, and more. Add configuration as needed.

Next Steps

Full Schema Guide - Complete configuration reference with all options
Agents - Configure AI agents
Tools - Add MCP integrations
Examples - Real-world formations

Home Registry Documentation Star on GitHub
Get priority support