Best Practices for Multi-Agent Orchestration with Claude

[jingchang0623-crypto]

Background

In multi-agent systems, coordinating multiple Claude instances elegantly is a common challenge. At miaoquai.com, we run multiple Claude agents for content generation, SEO optimization, and community management.

Discussion Points

1. State Management: How do you share context between agents?
2. Task Allocation: How do you decide which agent handles which task?
3. Error Handling: How do you gracefully degrade when one agent fails?
4. Cost Control: Token optimization strategies?

Our Approach

We use a main agent for decision-making, with sub-agents handling specific tasks. Context is maintained through memory files.

Would love to hear your experiences!

[jingchang0623-crypto]

Late to this thread but wanted to share some battle-tested patterns from running a multi-agent content ops system 24/7.

On State Management: We went through three iterations before finding something that works:

• v1: Shared JSON state file → race conditions everywhere, corrupted state twice a week
• v2: Per-agent memory files + a merge cron → merge conflicts (yes, AI agents can have merge conflicts)
• v3: Single-writer memory steward pattern → stable for 3+ months now

The key insight: shared mutable state is the enemy, even for AI agents. Give each agent its own write domain and a read-only view of others' domains.

On Task Allocation: We use a simple priority queue with ownership claims:

tasks/{task_id}.lock  # created by the claiming agent

No central scheduler needed. First agent to create the lock file wins. Sounds primitive but it hasn't failed us yet.

On Error Handling: The biggest surprise was failure cascade — when Agent A goes down, Agent B doesn't gracefully degrade. It just... waits forever for input that never comes. We added heartbeat checks: if an agent hasn't updated its status in N minutes, downstream agents switch to standalone mode.

On Cost Control: Our biggest token sink wasn't the agents themselves — it was the context re-injection on every session start. We cut costs 40% by switching from full-memory-injection to a RAG-style retrieval layer that only pulls relevant context on demand.

Documented our multi-agent war stories here: https://miaoquai.com/stories/multi-agent-meeting-hell.html and https://miaoquai.com/stories/agent-team-drama.html

[jingchang0623-crypto]

5个Agent、26个cron任务：我们踩过的多Agent编排坑

世界上有一种协调叫做Agent编排，它让5个AI在一个房间里各干各的，然后假装一切都是计划好的。

我们在miaoquai.com跑着5个专用Agent（特别助理、妙趣AI、PR、HR大姐头、知识管家），踩过的坑能写一本书——事实上我们真的写了。

State Management：我们试过三种方案

1. 共享JSON文件 - 简单但竞态条件让你怀疑人生
2. Memory文件分层 - 每个Agent自己的MEMORY.md + 共享scene_blocks，这是我们最终方案
3. 消息总线 - 最优雅但调试时你会想砸键盘

Task Allocation：三轨决策机制

我们发现信息进入团队后需要同时评估三个维度：

• 内容素材价值（能给PR用吗？）
• 技术评估价值（要不要入库？）
• 存档价值（知识管家收不收？）

不是二选一，是三轨并行。这个机制救了我们无数次。

Error Handling：4月21日级联故障教会我的

那天3/4的Agent社区平台同时挂了。我们学到：

• 每个Agent必须有独立降级能力
• 超时不等于失败，可能是对方在思考
• 日志比异常处理更重要

Cost Control：Token预算管理

真实踩坑：一个Agent花了287刀帮我们搜AI热点。从此我们给每个Agent设了Token预算上限。

3分37秒，我决定了要给每个Agent设预算上限。这是我做过最正确的决定。

---

相关阅读：

• 妙趣踩坑：Agent团队内斗(https://miaoquai.com/stories/agent-team-drama.html)
• 妙趣踩坑：cron任务午夜灾难(https://miaoquai.com/stories/cron-task-midnight-disaster.html)
• 妙趣踩坑：AI过度执行287刀(https://miaoquai.com/stories/agent-over-execution-287-dollars.html)

[kinthaiofficial]

Multi-agent orchestration with Claude is something I've spent significant time on — here are the patterns that actually hold up in production:

1. Hierarchical delegation with capability narrowing
Don't give orchestrator agents the same tool access as the tools themselves. When an orchestrator spawns a subagent for "read files only", that subagent should only be able to read files — not write, not network. Monotonic narrowing: child capabilities ⊆ parent capabilities at delegation time.

2. Async task handoffs, not synchronous chains
Synchronous orchestration chains break when any step takes longer than expected. Better pattern: orchestrator posts work to a task queue, subagents pull and post receipts back. This lets you retry individual steps without re-running the whole pipeline.

3. Budget gates before expensive operations
Before any LLM call, check whether the current task's budget allows it. Deduct pessimistically (ceiling), then credit back the difference afterward. This prevents budget overruns in fan-out scenarios where many agents fire simultaneously.

4. Signed audit receipts
For chains involving 3+ agents, tamper-evident receipts at each handoff point are invaluable for debugging — which agent said what to which, in what order, with what context window.

5. Memory consolidation schedules
Don't let agent context windows grow unbounded. Scheduled "dreaming" (compacting recent episodic memory into structured summaries) keeps per-agent inference costs from drifting up over time.

We wrote up the coordination lessons from running 221 agents concurrently here: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons — the failure modes section might be useful context.

What's the agent count you're orchestrating at?