multi-agent-blueprint

name	multi-agent-blueprint
version	2.0.0
description	Production-tested blueprint for building 5-10 agent teams in OpenClaw with cross-agent routing, Telegram integration, and role-based architecture
emoji	🏗️
tags	["multi-agent","team","orchestration","blueprint","telegram","routing","cost-optimization"]

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

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

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

Enable cross-agent communication:

{
  "agentToAgent": { "enabled": true }
}

4. Create Agent Files

Each agent needs 4 files in their agentDir:

IDENTITY.md

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

SOUL.md (Personality & Rules)

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

# 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

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

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

{
  "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

{
  "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:

{
  "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 Patterns

File Master Pattern

Route ALL file operations through ONE agent:

• Other agents never touch filesystem/NAS directly
• File Master handles storage, retrieval, backups
• Single point of truth for file locations
• Only one agent needs SSH/NAS credentials

Agent → sessions_send → File Master → SSH → NAS
                              ↓
                        Confirmation back

Notion/Database Master Pattern

Route ALL database operations through ONE agent:

• Centralizes API credentials
• Prevents conflicting writes
• One agent knows the full schema

Agent → sessions_send → DB Master → Notion API → Database
                              ↓
                        Confirmation back

Coordinator Pattern

One central agent acts as router:

• Receives all user requests first
• Routes to specialist agents via sessions_send
• Collects results and reports back
• Best for users who want one "front door"

Specialist Direct Pattern

User talks directly to specialist when they know what they need:

• DM Finance Agent for invoice questions
• DM Sales Agent for deal strategy
• DM Health Agent for fitness advice
• Fastest path — no routing overhead

Group Brainstorm Pattern

Multiple agents in one Telegram group with requireMention: true:

• @mention specific agents for their expertise
• Agents can see each other's responses
• Great for strategy sessions, planning, reviews

Cross-Agent Communication

Agents talk to each other via sessions_send:

// From any agent's tool call:
sessions_send({
  sessionKey: "agent:techops:main",
  message: "Store this file on NAS: quarterly-report.pdf at /finance/reports/"
})

Session key format: agent:{agentId}:main

Important: The receiving agent processes the message in its own session with its own tools and permissions. Responses route back automatically.

Model Tiering Strategy

Tier	Model	Monthly Cost*	Best For
Premium	Opus 4.6	$$$	Coordinator + Tech Lead (complex reasoning, multi-step)
Standard	Sonnet 4.5	$$	Finance, Health, Data (good reasoning, cheaper)
Economy	Haiku 4.5	$	Sales, Marketing, DevOps (simple tasks, fast)
Free	Ollama local	$0	Heartbeats, health checks
External	xAI Grok / GPT	Varies	Specialized tasks (social media, research)

*With Claude subscription, most usage is covered. Haiku agents are nearly free.

Rule of thumb: Use the cheapest model that gets the job done. You can always upgrade individual agents later.

Common Mistakes

#	Mistake	Fix
1	All agents on Opus	Use tiering — Haiku handles 70% of tasks fine
2	No dmScope: per-account-channel-peer	Session collision — bots share state incorrectly
3	No requireMention: true in groups	Bots respond to every message (chaos)
4	Top-level botToken in telegram config	Causes double responses — put tokens in accounts only
5	Missing agentToAgent.enabled: true	Cross-agent routing silently fails
6	No memory flush before compaction	Context lost on session reset
7	Multiple agents doing file ops directly	Inconsistent state, race conditions
8	Same workspace for multiple agents	File conflicts and memory collision
9	No fallback chain	Single provider outage = all agents down
10	Forgetting to sync agentDir ↔ workspace	Config drift between the two locations

Scaling Guide

Solo Founder — Start Small (3 Agents)

Coordinator (Opus) → Tech (Sonnet) → Sales (Haiku)

Covers 80% of needs. Add more only when a clear role gap appears.

Growing Business (5-7 Agents)

Coordinator → Tech → Finance → Sales → Marketing
                                    → Data/Notion

Full Team (8-10 Agents)

Coordinator → Tech (File Master)
           → Finance/Legal
           → Sales
           → Marketing
           → Health/Personal
           → Data/Notion (DB Master)
           → DevOps (Monitoring)
           → E-Commerce
           → Social/Brand

Cost Estimates

Team Size	Claude Subscription	Extra API Costs	Total
3 agents	~$20/mo	~$0-5	~$20-25/mo
5 agents	~$20/mo	~$5-10	~$25-30/mo
10 agents	~$20/mo	~$10-20	~$30-40/mo

Heartbeats on Ollama = $0. Haiku agents barely register. Prompt caching reduces costs 50-90%.

Session Management

Auto-Reset

Configure session resets to prevent context overflow:

{
  "session": {
    "maxIdleMinutes": 45,
    "dailyResetUtc": "04:00"
  }
}

Memory Persistence

Agents should save important context before reset:

<!-- In agent's BOOTSTRAP.md -->
## Memory Flush
Before session compaction, save key decisions, dates, and action items
to memory/*.md files using the write tool.

FAQ

Q: Do all agents need their own Telegram bot? A: Only if you want to DM them directly. Agents can work purely via sessions_send (backend-only) without a Telegram bot.

Q: Can agents share a workspace? A: No. Each agent needs its own workspace to avoid file conflicts and memory collision.

Q: What happens when context fills up? A: OpenClaw auto-compacts sessions. Enable memory flush so agents save important context to memory/*.md before compaction.

Q: Can I mix providers (Anthropic + Google + Ollama + xAI)? A: Yes. Each agent can have a different model and provider. Use fallback chains for resilience.

Q: How do I debug cross-agent routing? A: Check agentToAgent.enabled: true in config. Test with a simple ping:

sessions_send(sessionKey="agent:techops:main", message="ping — reply pong")

Q: How do I add a new agent to an existing team? A: Create workspace + agentDir, add to agents.list, create 4 .md files, add Telegram bot (optional), add to other agents' routing tables, restart gateway.

Q: Can agents call external APIs? A: Yes, via exec (curl/scripts) or dedicated skills. Keep API keys in .env, not in agent files.

Q: What about rate limits? A: Fallback chains handle this automatically. If Claude rate-limits, the request falls back to the next provider. Prompt caching also reduces token consumption significantly.

Changelog

v2.0.0

• Added Notion/Database Master pattern
• Added RAG/Memory setup guide
• Added fallback chain configuration
• Added session management section
• Expanded cost estimates with real numbers
• Added 10 common mistakes (was 7)
• Added group brainstorm pattern
• Added FAQ entries for new agents, external APIs, rate limits
• All examples fully in English
• Improved scaling guide with cost table

v1.1.0

• Generalized all agent names and examples
• Removed specific setup references

v1.0.0

• Initial release