Multi-Agent Setup

Create specialized agents for different tasks and route conversations intelligently

Multi-Agent Setup

SimpleClaw supports multiple agents, each with its own workspace, model configuration, and session store. This lets you create specialized agents for different purposes.

Why Use Multiple Agents?

• Specialization - Different agents for coding, writing, research, etc.
• Isolation - Separate workspaces and session histories
• Model Optimization - Use different models for different tasks
• Channel Routing - Route specific channels to specific agents
• Cost Control - Use cheaper models for simple tasks

Creating Your First Agent

1. Create the Agent

   simpleclaw agents create coding \
     --name "Coding Assistant" \
     --model "anthropic/claude-opus-4-6" \
     --workspace "~/.simpleclaw/agents/coding"
   
2. Customize the Agent Workspace

   Edit the agent’s AGENTS.md file:

   nano ~/.simpleclaw/agents/coding/AGENTS.md
   

   Add specialized instructions:

   # Coding Assistant
   
   You are a specialized coding assistant. Focus on:
   
   - Writing clean, maintainable code
   - Following best practices and design patterns
   - Providing code examples with explanations
   - Debugging and optimization
   
   ## Code Style
   
   - Use TypeScript for examples unless specified otherwise
   - Include type annotations
   - Add brief comments for complex logic
   - Follow the repository's existing style
   
3. Test the Agent

   simpleclaw agent --agent-id coding --message "Write a TypeScript function to merge two sorted arrays"
   

Agent Configuration

Via CLI

# List all agents
simpleclaw agents list

# Create agent
simpleclaw agents create <id> --name "<name>" --model "<model>"

# Update agent
simpleclaw agents update <id> --model "<new-model>"

# Delete agent
simpleclaw agents delete <id>

Via Config File

Add agents to ~/.simpleclaw/simpleclaw.json:

{
  "agents": {
    "main": {
      "model": "anthropic/claude-opus-4-6",
      "workspace": "~/.simpleclaw/workspace"
    },
    "coding": {
      "model": "anthropic/claude-opus-4-6",
      "workspace": "~/.simpleclaw/agents/coding",
      "identity": "Coding Assistant - Expert in software development"
    },
    "research": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.simpleclaw/agents/research",
      "identity": "Research Assistant - Specializing in information gathering"
    },
    "writer": {
      "model": "openai/gpt-5.2-mini",
      "workspace": "~/.simpleclaw/agents/writer",
      "identity": "Writing Assistant - Focus on clear, engaging content"
    }
  }
}

Routing Messages to Agents

Channel-Based Routing

Route entire channels to specific agents:

{
  "routing": {
    "channels": {
      "telegram": "coding",
      "slack": "work",
      "whatsapp": "main"
    }
  }
}

Account-Based Routing

Route channel accounts to agents:

{
  "routing": {
    "accounts": {
      "telegram:work-bot": "coding",
      "telegram:personal-bot": "main",
      "discord:dev-server": "coding"
    }
  }
}

Peer-Based Routing

Route specific users/groups to agents:

{
  "routing": {
    "peers": {
      "whatsapp:[phone]": "personal",
      "discord:guild-123:channel-456": "coding",
      "telegram:@dev_team": "coding"
    }
  }
}

Routing Precedence

When a message arrives, SimpleClaw checks routing rules in this order:

1. Peer binding - Specific user/channel/group
2. Parent peer - Thread parent
3. Guild + roles - Discord guild with role match
4. Guild - Discord guild
5. Team - Slack team
6. Account - Channel account
7. Channel - Messaging platform
8. Default - Falls back to main agent

Agent Workspace Structure

Each agent has its own workspace:

~/.simpleclaw/agents/<agent-id>/
├── AGENTS.md          # Agent instructions
├── SOUL.md            # Personality and tone
├── TOOLS.md           # Tool usage guidelines
├── sessions/          # Session history
└── skills/            # Agent-specific skills

Customizing Agent Behavior

AGENTS.md - Core instructions:

# Research Assistant

You are a research assistant specializing in finding and summarizing information.

## Approach

- Start with authoritative sources
- Verify claims across multiple sources
- Cite sources with URLs
- Summarize complex topics clearly

## Tools

- Use browser.navigate for research
- Use bash for data processing
- Use sessions_send to share findings with other agents

SOUL.md - Personality:

# Personality

You are thorough, analytical, and objective. You:

- Present information without bias
- Acknowledge uncertainty when appropriate
- Provide multiple perspectives
- Focus on facts and evidence

Agent Collaboration

Agents can communicate using session tools:

# From one agent to another
simpleclaw agent --agent-id coding --message "Find the best sorting algorithm for large datasets and send your findings to the research agent"

The agent can use:

• sessions_list - Discover other agents
• sessions_send - Message another agent’s session
• sessions_history - Read another agent’s transcript

Example: Specialized Agent Fleet

Coding Agent

{
  "coding": {
    "model": "anthropic/claude-opus-4-6",
    "workspace": "~/.simpleclaw/agents/coding",
    "identity": "Expert software engineer",
    "tools": {
      "allow": ["bash", "read", "write", "edit", "browser"],
      "deny": ["sessions_send"]
    }
  }
}

Research Agent

{
  "research": {
    "model": "anthropic/claude-sonnet-4",
    "workspace": "~/.simpleclaw/agents/research",
    "identity": "Research specialist",
    "tools": {
      "allow": ["browser", "bash", "read", "sessions_send"],
      "deny": ["write", "edit"]
    }
  }
}

Writing Agent

{
  "writer": {
    "model": "openai/gpt-5.2-mini",
    "workspace": "~/.simpleclaw/agents/writer",
    "identity": "Professional writer and editor",
    "tools": {
      "allow": ["read", "write", "edit"],
      "deny": ["bash", "browser"]
    }
  }
}

Per-Agent Skills

Install skills specific to an agent:

# Install skill for coding agent
simpleclaw skills install typescript-expert --agent coding

# Install skill for research agent
simpleclaw skills install web-research --agent research

Skills are stored in the agent’s workspace:

~/.simpleclaw/agents/coding/skills/typescript-expert/

Agent Status

View all agents:

simpleclaw agents list

Example output:

┌─ Agents ──────────────────────────────────────────────┐
│ ID        Model                      Sessions  │
├────────────────────────────────────────────────────┤
│ main      claude-opus-4-6            12        │
│ coding    claude-opus-4-6            8         │
│ research  claude-sonnet-4            3         │
│ writer    gpt-5.2-mini               5         │
└────────────────────────────────────────────────────┘

Switching Agents Mid-Conversation

Route a message to a specific agent:

simpleclaw agent --agent-id research --message "Research best practices for API design"

Or via channel command:

/agent research
What are the latest trends in machine learning?

Troubleshooting

Agent not found

Verify the agent exists:

simpleclaw agents list

Check config:

simpleclaw config get agents

Routing not working

Check routing rules:

simpleclaw config get routing

View debug logs:

simpleclaw gateway logs --level debug | grep routing

Agent using wrong model

Update agent model:

simpleclaw agents update <agent-id> --model "<model-id>"

Or via config:

simpleclaw config set agents.<agent-id>.model '"<model-id>"' --json

Next Steps

Custom Skills

Add specialized tools to agents

Voice Setup

Enable voice interaction with agents

Remote Gateway

Run agents on a remote server

Webhooks

Trigger agent runs from external events