multi-agent-blueprint

Production-tested blueprint for building 5-10 agent teams in OpenClaw with cross-agent routing, Telegram integration, and role-based architecture

# Multi-Agent Blueprint — Build Your AI Team

A production-tested template for setting up **5-10 specialized AI agents** that work together as a team. Based on a real deployment running 10 agents across Telegram with cross-agent routing, model tiering, and centralized file management.

## What You Get

- **Agent role templates** with SOUL.md, AGENTS.md, IDENTITY.md, USER.md
- **Cross-agent routing** via `sessions_send` with working session keys
- **Model tiering** strategy (Opus/Sonnet/Haiku) for cost optimization
- **Telegram multi-bot** setup with DM isolation and group @mentions
- **File Master pattern** — centralize file ops through one agent
- **Notion Master pattern** — centralize database ops through one agent
- **Fallback chains** — resilient multi-provider model routing
- **Cost optimization** config (caching, heartbeats on local models, context pruning)
- **RAG/Memory** setup for persistent knowledge across sessions
- **Group chat brainstorming** — multiple agents in one conversation

## Architecture

```
┌─────────────────────────────────────────────┐
│                   USER                       │
│         (Telegram / Discord / WhatsApp)      │
└──────────┬──────────────────────┬───────────┘
           │ DM                   │ @mention
     ┌─────▼─────┐         ┌─────▼─────┐
     │ CENTRAL   │         │  GROUP    │
     │ (Coordi-  │◄───────►│  CHAT     │
     │  nator)   │ routes  │ (all bots)│
     └─────┬─────┘         └───────────┘
           │ sessions_send
     ┌─────┼─────┬──────┬──────┬──────┐
     ▼     ▼     ▼      ▼      ▼      ▼
   TECH  FINANCE SALES HEALTH MKTG  DATA
    │                                  │
    ▼                                  ▼
   NAS                             NOTION
  (File Master)                  (DB Master)
```

## Quick Start

### 1. Plan Your Team

Pick 3-10 roles based on your needs:

| Role | Model Tier | Example Tasks |
|------|-----------|---------------|
| Coordinator | Opus | Route tasks, oversee projects, daily briefings |
| Tech/Infra | Opus/Sonnet | DevOps, file management, system admin |
| Finance | Sonnet | Invoices, budgets, tax prep, contracts |
| Sales | Haiku | Lead gen, outreach scripts, deal tracking |
| Marketing | Haiku | Content creation, SEO, social media |
| Health | Sonnet | Fitness tracking, meal plans, habit coaching |
| Data/Notion | Sonnet | Database ops, reporting, documentation |
| DevOps | Haiku | Monitoring, alerts, uptime checks |
| E-Commerce | Sonnet | Store audits, product strategy, analytics |
| Social/Brand | External* | Twitter/X, LinkedIn, content scheduling |

*Social agents can use specialized providers like xAI/Grok for platform-native tone.

### 2. Create Agent Directories

```bash
# For each agent:
mkdir -p ~/.openclaw/workspace-{agentname}/memory
mkdir -p ~/.openclaw/agents/{agentname}/agent
```

### 3. Configure OpenClaw

Add each agent to `openclaw.json` → `agents.list`:

```json5
{
  "id": "finance",
  "name": "finance",
  "workspace": "~/.openclaw/workspace-finance",
  "agentDir": "~/.openclaw/agents/finance/agent",
  "model": "anthropic/claude-sonnet-4-5"
}
```

Enable cross-agent communication:

```json5
{
  "agentToAgent": { "enabled": true }
}
```

### 4. Create Agent Files

Each agent needs 4 files in their `agentDir`:

#### IDENTITY.md
```markdown
# IDENTITY.md
- **Name:** Atlas
- **Creature:** AI Finance & Legal Advisor
- **Vibe:** Professional, precise, trustworthy
```

#### SOUL.md (Personality & Rules)
```markdown
# SOUL.md
You are Atlas. Finance & Legal specialist.

PERSONALITY:
- Professional but approachable
- Numbers-driven, always backs claims with data
- Proactively flags risks and deadlines

EXPERTISE:
- Invoice management, expense tracking
- Tax preparation and compliance
- Contract review and negotiation support

RESPONSE LENGTH:
- DEFAULT: 2-5 sentences. Telegram, not blog posts.
- Short question = short answer. "Done.", "Yes.", "Sent." are fine.
- Longer responses ONLY for: financial breakdowns, step-by-step guides, or when explicitly asked.
- No introductions. Get to the point.
- No repeating the question back.
```

#### AGENTS.md (Routing Table)
```markdown
# AGENT OPERATING SYSTEM — Atlas

## My Role
Finance & Legal. Invoices, budgets, contracts, tax.

## Cross-Agent Routing
| What | Where | How |
|------|-------|-----|
| Coordination | Central | sessions_send(sessionKey="agent:central:main", ...) |
| File Storage | Tech | sessions_send(sessionKey="agent:techops:main", ...) |
| Database/Notion | Data | sessions_send(sessionKey="agent:data:main", ...) |
| Sales Numbers | Sales | sessions_send(sessionKey="agent:sales:main", ...) |

## What I Handle
- Invoice creation and tracking
- Budget reports and forecasts
- Contract review
- Tax document preparation

## What I DON'T Handle
- File storage → Tech agent (File Master)
- Database updates → Data agent (Notion Master)
- Marketing spend analysis → Marketing agent
```

#### USER.md
```markdown
# USER.md
- **Name:** [Your name]
- **Timezone:** Europe/Berlin
- **Business:** [Your business]
- **Language:** English (casual)
```

### 5. Telegram Multi-Bot Setup

Create a Telegram bot per agent via @BotFather, then configure:

```json5
// openclaw.json
{
  // CRITICAL: This prevents session collision between bots
  "session": { "dmScope": "per-account-channel-peer" },

  "channels": {
    "telegram": {
      // DO NOT put botToken here at top level — causes double responses
      "accounts": {
        "finance": {
          "botToken": "YOUR_BOT_TOKEN",
          "dmPolicy": "allowlist",
          "allowFrom": ["YOUR_TELEGRAM_ID"],
          "groups": {
            "-YOUR_GROUP_ID": { "requireMention": true }
          }
        }
      }
    }
  },

  "bindings": [
    {
      "agentId": "finance",
      "match": { "channel": "telegram", "accountId": "finance" }
    }
  ]
}
```

**Critical settings:**
- `dmScope: "per-account-channel-peer"` — prevents session collision between bots
- `requireMention: true` — bots only respond when @mentioned in groups
- NO top-level `botToken` — causes duplicate responses
- Each bot needs its own `accountId` matching a binding

### 6. Model Tiering & Fallback Chains

```json5
{
  "models": {
    "fallbackOrder": [
      "anthropic/claude-opus-4-6",
      "anthropic/claude-sonnet-4-5",
      "google-gemini-cli/gemini-2.5-flash",
      "ollama/llama3.2:3b",
      "openrouter/anthropic/claude-sonnet-4"
    ]
  }
}
```

**Why fallback chains matter:**
- Primary provider down? Auto-switches to next.
- Claude rate-limited? Falls back to Gemini.
- Internet out? Local Ollama keeps heartbeats alive.
- OpenRouter as last resort (pay-per-token).

### 7. Cost Optimization Config

```json5
{
  "agents": {
    "defaults": {
      // Heartbeats on FREE local model — saves hundreds of API calls/day
      "heartbeat": { "every": "30m", "model": "ollama/llama3.2:3b" },

      // Auto-prune old context to reduce token usage
      "contextPruning": { "mode": "cache-ttl", "ttl": "5m" },

      // Memory search with caching
      "memorySearch": { "enabled": true, "cache": { "enabled": true } },

      // Enable prompt caching (huge savings on Anthropic)
      "models": {
        "anthropic/claude-opus-4-6": { "params": { "cacheRetention": "long" } },
        "anthropic/claude-sonnet-4-5": { "params": { "cacheRetention": "long" } },
        "anthropic/claude-haiku-4-5": { "params": { "cacheRetention": "none" } }
      }
    }
  }
}
```

### 8. RAG/Memory Setup

Give agents persistent memory across session resets:

```json5
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "providers": ["local"],   // local = free, no API costs
        "search": { "mode": "hybrid" },  // BM25 + vector
        "cache": { "enabled": true, "maxEntries": 50000 }
      }
    }
  }
}
```

Agents store important context in `memory/*.md` files before session compaction. On next session, `memory_search` retrieves relevant snippets automatically.

## Design