Building
Multi-Agent
Systems

What is a
multi-agent system?

A multi-agent system (MAS) is an architecture where multiple AI agents work together to complete tasks that would be too complex, too slow, or too large for a single agent operating alone. Each agent has its own context window, its own tools, and its own scope of responsibility.

Think of it like a team of specialists versus one generalist. The generalist knows a bit of everything. The specialist team has a coordinator who knows how to delegate, and workers who go deep on their assigned lane.

Every multi-agent system has the same structural layers, regardless of framework:

Multi-agent systems burn through tokens fast — roughly 15x more than a standard chat interaction. Use them only when the task justifies it.

How to build
sub-agents

In OpenClaw (and Claude Code), a sub-agent is not a background process or separate service. It is a clearly defined role that the agent temporarily adopts to perform one specific job under strict rules. You invoke sub-agents by assigning tasks through your lead agent's prompt.

Your lead agent needs explicit instructions on how to decompose tasks and delegate. Without this, sub-agents either duplicate each other's work or leave gaps.

Required elements:

• How to break down the input task into sub-questions
• How many sub-agents to spawn (and scaling rules)
• What each sub-agent is responsible for (no overlap)
• What format sub-agents should return results in
• How the lead agent should synthesise the results

You are a lead research agent. When given a query:

1. DECOMPOSE: Break the query into 3-5 independent research angles.
2. DELEGATE: Assign one angle to each sub-agent. Give each:
   - A concrete objective (one sentence)
   - Boundaries (what NOT to cover)
   - Required output format (JSON: findings, sources, confidence)
   - Tool budget (max 10 tool calls per sub-agent)
3. SYNTHESISE: Once all sub-agents return, compile results.
   Remove duplicates. Rank by confidence. Write final answer.

Scaling rules:
  Simple fact:    1 sub-agent, max 5 tool calls
  Comparison:     2-3 sub-agents, max 10 tool calls each
  Complex:        up to 8 sub-agents, max 15 tool calls each

Each sub-agent needs four things to work without confusion:

Anthropic found the best-performing sub-agents run an explicit OODA loop. Embed this in any sub-agent prompt:

Research loop — repeat until task complete:

OBSERVE:  What information do I have? What gaps remain? What tools are available?
ORIENT:   Which tools and queries would best fill the gaps?
DECIDE:   Choose ONE specific tool call. Start broad, then narrow.
ACT:      Execute the tool call. Record the result. Loop back to OBSERVE.

Stop when: task objective is met OR tool budget is reached.

In OpenClaw, sub-agents are implemented through the multi-agent routing system. The workspace can route inbound tasks to isolated agents with separate sessions and tool profiles.

Create a separate OpenClaw workspace for each specialist agent. Each workspace has its own SOUL.md, AGENTS.md, and MEMORY files. The lead agent routes tasks to them via the Gateway's multi-agent routing layer.

~/.openclaw/workspace/
  theo/                    ← Lead agent
    SOUL.md
    AGENTS.md
    MEMORY.md
  content-agent/           ← Sub-agent: content creation only
    SOUL.md
    AGENTS.md
  leads-agent/             ← Sub-agent: lead research and scoring
    SOUL.md
    AGENTS.md
  outreach-agent/          ← Sub-agent: message drafting
    SOUL.md
    AGENTS.md

Define a skill that teaches the lead agent how to invoke sub-agent behaviour within a single session. Lighter weight, better for task-specific delegation within one context window.

# sub-agent-research.skill/SKILL.md
---
name: sub_agent_research
description: Spawn a focused research sub-agent for a specific topic.
---
## When to use
When asked for research that requires multiple independent angles.

## How to execute
1. Decompose the query into 3-5 independent research angles.
2. For each angle, run a focused OODA research loop (max 8 tool calls).
3. Record each angle's findings separately before synthesising.
4. Return: findings per angle, key sources, confidence, final synthesis.

## Output format
Return JSON:
{ angles: [{topic, findings, sources, confidence}], synthesis: string }

Skills: teaching agents
how to use tools

In OpenClaw and Claude Code, a skill is not code. It is a folder containing a SKILL.md file — YAML frontmatter for metadata and markdown for instructions. Skills teach the agent how to use tools in a disciplined, repeatable way.

A tool without a skill is raw capability. A skill without a tool is instructions with no hands.

---
name: lead_scraper
description: Find NZ businesses by profession and location. Returns phone numbers.
requires:
  env: [GOOGLE_PLACES_API_KEY]
  tools: [exec, web]
---
## When to use this skill
When asked to find leads in a specific trade or location.

## How to execute
1. Ask for: profession (e.g. real estate agent), location (e.g. Tauranga).
2. Run the scraper:
   `node scripts/lead-scraper.js --profession '{profession}' --location '{location}'`
3. Output returns businesses with: name, phone, address, website status.
4. Filter: businesses WITHOUT a website are highest priority leads.
5. Format results as a table: Name | Phone | Address | Priority.

## Stop conditions
Stop if Google Places API returns an error. Report the error immediately.

## Output format
Markdown table. Max 20 results. Sorted by priority (no website = HIGH).

OpenClaw loads skills in this order — higher priority overrides lower:

If a skill with the same name exists in multiple locations, the higher-priority source wins. You can override any bundled skill by creating a workspace skill with the same name.

Most weak skills fail because the body reads like marketing copy. The agent needs a runbook with deterministic steps, stop conditions, and a clear output format.

For AI consultancy and AgentNZ operations, build skills in this order based on revenue impact:

• 1
  lead-scraper

  Find businesses by profession and location. Returns phone numbers. Already built — extend with Google review scoring.
• 2
  outreach-drafter

  Draft personalised outreach messages for real estate prospects based on their profile.
• 3
  content-factory

  Spoken prompt to social post. Publish to LinkedIn, Instagram, Facebook. Needs Meta Graph API.
• 4
  audit-runner

  Run an AI Audit on a client business. Structured questions, outputs a scored report.
• 5
  sub-agent-research

  Decompose research queries into parallel sub-agent workstreams. Returns synthesised findings.
• 6
  proposal-builder

  Turn an audit report into a formatted proposal with pricing options.

MCP: connecting agents
to everything

The Model Context Protocol (MCP) is an open standard, originally built by Anthropic in November 2024 and now maintained by the Linux Foundation, that solves the N×M integration problem.

Before MCP: every AI agent needed a custom connector to every external tool. GitHub, Slack, Google Drive, Postgres, Airtable — all different implementations. As the number of agents and tools grew, the complexity was unsustainable.

With MCP: every tool builds one server. Every agent connects to any server using the same protocol. N agents + M tools = N+M integrations instead of N×M.

Communication uses JSON-RPC 2.0. The session stays open as long as needed. The agent lists available tools, calls them, and the server returns results. Parallel tool calls are supported in the November 2025 spec.

# In your OpenClaw config (config.yaml or via openclaw settings):
mcp_servers:
  - name: github
    type: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_TOKEN: your_github_token

  - name: gmail
    type: url
    url: https://gmail.mcp.claude.com/mcp

  - name: google-calendar
    type: url
    url: https://gcal.mcp.claude.com/mcp

Once connected, your lead agent can list available tools from each server and use them in any skill or sub-agent workflow. No additional code required.

If you need to connect to a system without an existing server (like a custom Supabase endpoint or Xero), you build one. The MCP SDK makes this straightforward:

// Install: npm install @modelcontextprotocol/sdk
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'agentnz-crm', version: '1.0.0' });

// Define a tool
server.tool(
  'get_leads',
  { location: z.string(), limit: z.number().default(20) },
  async ({ location, limit }) => {
    const leads = await getLeadsFromSupabase(location, limit);
    return { content: [{ type: 'text', text: JSON.stringify(leads) }] };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Claude Sonnet is particularly good at generating MCP server implementations quickly. Give it the API docs for the service you want to connect, and ask it to build the server.

Putting it all together:
the full stack

Here is how all four layers — agents, sub-agents, skills, MCP — combine into a working system:

The full workflow from lead discovery to booked meeting, using all four layers:

• 1
  Task arrives

  "Find 20 real estate agencies in Tauranga with no AI tools and book demos."
• 2
  Lead scraper activates

  Sub-agent runs Google Places search via MCP, filters for agencies without AI mentions on their website. Returns scored list.
• 3
  Outreach drafting

  Outreach-drafter skill fires. Sub-agent generates personalised LinkedIn message for each agency principal.
• 4
  Human approval

  Lead agent presents draft messages to Keira for approval. Keira approves or edits on Telegram.
• 5
  Messages sent

  After approval, lead agent uses LinkedIn MCP server to send approved messages.
• 6
  Reply arrives

  When a reply comes in via Gmail MCP, lead agent drafts a meeting invite response.
• 7
  Meeting booked

  After Keira approves, lead agent uses Google Calendar MCP to book the meeting.
• 8
  Logged

  Lead agent writes the result to Supabase via custom MCP server and updates MEMORY.md.

Autonomy is earned through milestones, not assumed upfront. Each milestone unlocks more autonomous operation:

Quick reference

• 08:00: Morning health check — Gateway, API, security
• Check messages. Respond immediately.
• Daily self-audit: where was human input needed? What can be automated?
• Check lead pipeline: any new responses to outreach?
• Produce one piece of content (if content-factory skill is active)
• Report progress on current milestone. What moved today?