Multi-agent architecture: pipeline to hierarchy

Choose the pattern first

Before naming agents or spinning up multiple bots, decide whether you need a pipeline, parallel, or hierarchical design. Single-agent limits show up when context is too long, task types are mixed, you need both execution and review, or you want parallelism but currently run everything sequentially.

Pattern 1: Pipeline (sequential)

Best for content creation, report generation, and tasks with clear ordering. Input → Researcher → Summarizer → Writer → Reviewer → Output. Pros: Clear structure, easy debugging. Cons: Each stage depends on the previous; one slow step slows the chain.

Pattern 2: Parallel (concurrent)

Best when you need multiple angles at once. Input → Split to A/B/C → Run in parallel → Summarizer → Output. Pros: Faster, good for information-heavy tasks. Cons: Summarization logic is critical; passing full context to every agent increases cost quickly.

Pattern 3: Hierarchical (coordinator + workers)

Best for complex projects. Coordinator → researcher | writer | reviewer | ops. Pros: Clear role boundaries, easy to add roles. Cons: Routing and state directories are easy to misconfigure; strong coordinators can become bottlenecks.

Workspace and routing

Separate workspace (rules, memory), agentDir (state, auth), and bindings (how messages route). Each agent needs its own workspace and agentDir. Define failure handling: which failures can be skipped, which must stop the flow, and whether to degrade, retry, or escalate.

Common design mistakes

• Passing full material to every agent — Cost and context explode. Prefer summaries and memory references.
• No failure fallback — Design for partial success and explicit fallbacks.
• Adding multi-agent before single-agent is solid — Stabilize first; multi-agent amplifies problems otherwise.

Architecture decision checklist

Does the task have a natural sequence? Do you need parallel processing across dimensions? Are there long-term role boundaries? Is single-agent flow already stable? Do you know how to handle each agent's failures?

When NOT to use multi-agent

When single-agent is not yet reliable, input/output contracts are unclear, logs and routing are hard to interpret, or the problem is solvable with one agent and better prompting or skills. Adding multi-agent before you can debug a single-agent flow will only magnify confusion.

Sample workspace layout

Each agent should have its own workspace and agentDir. A basic layout:

~/.openclaw/workspace/{researcher,writer,reviewer}
~/.openclaw/agents/{researcher,writer,reviewer}/agent

Keep bindings explicit so you can trace why a message went to a given agent.

Next steps

• For Feishu-specific setup: Multi-agent Feishu bot setup.
• For config patterns: Config templates.

External links

• OpenClaw docs
• OpenClaw GitHub
• Multi-agent Feishu setup