Skill: neal-collab/multi-agent-blueprint (version 2.0.0)

--- 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 ```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", [REDACTED_SECRET] ] } } ``` **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 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`: ```javascript // 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: ```json5 { "session": { "maxIdleMinutes": 45, "dailyResetUtc": "04:00" } } ``` ### Memory Persistence Agents should save important context before reset: ```markdown <!-- 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


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: suspicious | SkillSpector: clean (LOW)