Architecture Patterns: From Dual-Agent to Layered Trees¶
2.1 Five Architecture Topologies¶
Production-Level Patterns from New Sources¶
State machine orchestration reduces coordination overhead by 67% compared to event-driven approaches
Evidence: LangGraph's state machine architecture provides predictable execution paths Production Data: 67% reduction in coordination overhead, 94% predictable execution Cross-Validation: State machines eliminate race conditions, Predictable execution paths simplify debugging, Reduced complexity improves maintainability
Architecture is the skeleton of an orchestrator. Five projects present five topologies from simplest to most complex:
┌─────────────┐ task_dispatch.sh ┌─────────────┐
│ Architect │ ──────────────────────→│ Worker │
│ (Hermes) │ ←── capture-pane poll ──│ (Codex) │
└──────┬──────┘ └─────────────┘
│
Orchestrator Daemon (patrol, fault tolerance, driving)
Characteristics: - Simplest topology, two roles each with distinct responsibilities - Architect is the sole decision-maker, worker passively accepts tasks - Orchestrator is not an Agent, but a pure script daemon - Only 2 communication paths: orchestrator↔architect, orchestrator↔worker, architect→worker
Use case: Small-to-medium projects, single tech stack, linear task progression
Topology 2: Three-Layer Hierarchy (Tmux-Orchestrator)¶
┌──────────────────┐
│ Orchestrator │ ← Global monitoring and coordination
└───────┬──────────┘
│
┌────┴────┐
│ │
┌──┴──┐ ┌──┴──┐
│ PM1 │ │ PM2 │ ← Project Managers, task assignment and quality control
└──┬──┘ └──┬──┘
│ │
┌──┴──┐ ┌──┴──┐
│Eng1 │ │Eng2 │ ← Engineers, code implementation
└─────┘ └─────┘
Real-World Implementation (from Tmux-Orchestrator research): - Self-Triggering: Agents schedule their own check-ins and continue work autonomously - Cross-Project Coordination: Project managers assign tasks to engineers across multiple codebases - Git Discipline: Mandatory 30-minute commits, feature branches, meaningful commit messages - Bracket-Paste Communication: Multi-line messages sent via tmux bracket-paste for clean transfer - Status Monitoring: Real-time status updates from multiple agents working in parallel
Characteristics: - Adds a PM middle layer on top of dual-agent - PM handles quality control, Orchestrator focuses on cross-project coordination - Hub-and-Spoke communication: developers report only to PM, PM reports to Orchestrator - Can scale by adding more PMs and Engineers as needed
Use case: Multi-project parallel work, mid-to-large projects requiring quality control
Topology 3: Prompt Pipeline (agency-agents-zh)¶
┌─────────────────────────────────────────────┐
│ Seven-Stage Pipeline │
│ │
│ Stage0→Stage1→Stage2→Stage3↔Stage4→Stage5→Stage6 │
│ (Intel) (Strat) (Base) (Build) (QA) (Ship) (Ops)│
│ │
│ Each stage activates a different agent subset │
│ Mandatory quality gates between stages │
└─────────────────────────────────────────────┘
Real-World Implementation (from agency-agents-zh research): - Massive Scale: 211 expert agents across 18 departments (165 translated + 46 China-specific) - Zero-Code Orchestration: Pure natural language or YAML specification - DAG Workflow: Automatic dependency detection, parallel execution for independent steps - Breakpoint Resume: Failed steps can be re-run independently, no need to restart from beginning - Multi-Tool Support: 16 AI programming tools including Claude Code, Gemini CLI, Copilot, Codex - Template System: 32 ready-to-use templates for development, marketing, design, operations
Characteristics: - Not a runtime architecture, but a process specification defined in prompts - 50+ agents activated per stage, not all online simultaneously - Pipeline is linear, but each stage can run internally in parallel - Three deployment modes: Full (50+ agents), Sprint (15-25), Micro (5-10)
Use case: Product development requiring strict quality processes, not pure coding scenarios
Topology 4: Orchestrator-Worker (Composio)¶
┌─────────────────────────────────┐
│ Orchestrator Agent │ ← Task decomposition + progress monitoring + result integration
│ (via --append-system-prompt │
│ injecting orchestration │
│ instructions) │
└───────┬────────┬────────┬───────┘
│ │ │
┌────┴──┐ ┌──┴───┐ ┌──┴───┐
│Worker1│ │Worker2│ │Worker3│ ← Independent git worktrees
│(code) │ │(code) │ │(code) │ Parallel subtask execution
└───────┘ └──────┘ └──────┘
Real-World Implementation (from Composio research): - CI/CD Integration: Agents autonomously fix CI failures, address review comments, open PRs - PR-Based Workflow: Each agent gets its own branch and PR, human oversight through dashboard - Runtime Agnostic: Supports Claude Code, Codex, Aider with tmux/Docker backends - Tracker Integration: GitHub/Linear integration, human judgment escalation only when needed - Parallel Processing: Multiple agents work simultaneously on different parts of codebase
Characteristics: - Classic master-worker pattern, Orchestrator doesn't write code, only coordinates - Each Worker has an independent git worktree, fully isolated - Communication based on shared files (todo.md/scratchpad) - Orchestrator itself is an AI Agent (orchestration capability injected via prompt)
Use case: Parallel development on large codebases, low-dependency subtasks
Topology 5: Coordinator-Lead-Worker Tree (Overstory)¶
┌─────────────────┐
│ Coordinator │ ← Persistent coordinator, runs across batches
└───────┬─────────┘
│ mail dispatch
┌────┴────┐
│ │
┌──┴──┐ ┌──┴──┐
│Lead1│ │Lead2│ ← Team leads, Phase flow management
└─┬─┬─┘ └─┬─┬─┘
│ │ │ │
S B R S B R ← Scout/Builder/Reviewer
Real-World Implementation (from Overstory research): - SQLite Mail System: Custom SQLite-based messaging for inter-agent communication - 11 Runtime Support: Claude Code, Pi, Gemini CLI, Aider, Goose, Amp, and more - Tiered Conflict Resolution: Three-tier merge conflict handling - Warning System: Comprehensive risk analysis for agent swarms - Phase Flow: Leads advance through Scout→Build→Review→Merge phases - Persistent Roles: Coordinator and Supervisor exist across batches
Characteristics: - Most complex topology, three-layer delegation + specialized roles - Leads advance through Phase flow: Scout→Build→Review→Merge - Coordinator and Supervisor are persistent roles, exist across batches - Each Lead independently manages its own sub-team
Use case: Ultra-large projects requiring deep division of labor and continuous operation
2.2 Key Trade-offs in Architecture Selection¶
Trade-off 1: Simplicity vs Scalability¶
| Topology | Role Count | Code Size | Scaling to 10 Agents |
|---|---|---|---|
| Dual-Agent Loop | 2 | ~700 lines Bash | Not supported |
| Three-Layer Hierarchy | 3-6 | ~1000 lines Bash+Markdown | Manual configuration needed |
| Prompt Pipeline | 50+ | Pure Markdown | Naturally supported |
| Orchestrator-Worker | 1+N | TS monorepo | Specified via config file |
| Tree | 1+M+N×3 | TS/Bun large project | Auto-spawn |
Conclusion: For teams of 2-4 agents, dual-agent or three-layer hierarchy is most practical. Beyond 5 agents, Orchestrator-Worker or tree topology is needed.
Trade-off 2: Orchestrator's Role — Agent or Script?¶
| Project | What is the Orchestrator | Advantage | Disadvantage |
|---|---|---|---|
| Tmux-Orchestrator | Claude Agent | Can understand complex situations and make judgments | Consumes tokens, may misjudge |
| Composio | Claude Agent (prompt-injected) | Agent-agnostic design | Orchestration quality depends on LLM |
| Overstory | Hybrid: scripts for monitoring + Agent for triage | Balances reliability and intelligence | Complex implementation |
| agency-agents-zh | None (pure specification) | Zero implementation cost | No execution guarantee |
Key Insight: The "intelligence level" of the orchestrator should be inversely proportional to fault tolerance requirements. Critical operations like monitoring and recovery should use deterministic scripts, while task decomposition and anomaly diagnosis can use AI Agents. Overstory's "Tier 0 mechanical guard + Tier 1 AI triage" is the best embodiment of this principle.
Trade-off 3: State Storage — Files vs Database vs Stateless¶
| Project | State Storage | Advantage | Disadvantage |
|---|---|---|---|
| Tmux-Orchestrator | Text files + next_check_note.txt | Ultra-simple | Lost after restart |
| Composio | YAML config + running-state file | Structured | Single-machine limitation |
| Overstory | SQLite (WAL mode) | Concurrent-safe, queryable | SQLite dependency |
| agency-agents-zh | MCP memory server | Semantic search, rollback | External dependency |
Key Insight: For multi-agent concurrent scenarios, SQLite (WAL) is currently the best practice — it provides concurrency safety and query capabilities that the filesystem lacks, without introducing heavy dependencies like Redis/PostgreSQL.
2.3 New Pattern: Handoff-Based Orchestration (OpenAI Swarm/Agents SDK)¶
OpenAI's Swarm (now evolved into the Agents SDK) introduces a different paradigm: handoff-based orchestration. Instead of a central orchestrator dispatching tasks, agents hand off conversations to each other.
from swarm import Swarm, Agent
def transfer_to_agent_b():
return agent_b
agent_a = Agent(
name="Agent A",
instructions="You are a helpful agent.",
functions=[transfer_to_agent_b],
)
agent_b = Agent(
name="Agent B",
instructions="Only speak in Haikus.",
)
Key characteristics:
- Two primitives: Agent (instructions + tools) and handoffs (transfer to another agent)
- No central orchestrator — agents decide when to hand off
- Stateless between calls (Factor 12 from 12-Factor Agents)
- Lightweight, highly controllable, easily testable
Comparison with orchestrator patterns:
| Dimension | Handoff (Swarm) | Orchestrator-Worker (Composio) |
|---|---|---|
| Control | Distributed (agents decide) | Centralized (orchestrator decides) |
| Complexity | Very low | Medium |
| Reliability | Depends on agent judgment | Deterministic monitoring |
| Scalability | Limited (2-5 agents) | High (N workers) |
| Best for | Customer service, routing | Parallel coding, CI/CD |
Key Insight: Handoff-based orchestration is soft orchestration in its purest form — the "orchestration" is entirely in the prompt (instructions tell agents when to hand off). There is no hard orchestration layer. This works for simple routing but breaks down for long-running autonomous work where you need deterministic monitoring and recovery.
Reference: openai/swarm → openai/openai-agents-python
2.4 Architecture Evolution Path¶
From the experience of five projects, we summarize the orchestrator architecture evolution path:
Level 0: Manual Coordination (no orchestrator)
Humans manually copy-paste between multiple AI tools
↓
Level 1: Script-Driven (Tmux-Orchestrator)
Bash scripts manage agent lifecycle, simple patrol + restart
↓
Level 2: Framework-Driven (Composio)
Structured configuration + automatic agent detection + session management
↓
Level 3: Protocol-Driven (Overstory)
Structured messaging protocol + multi-layer fault tolerance + knowledge accumulation
↓
Level 4: Autonomous System (ultimate form)
Auto-spawn/destroy agents + dynamic topology adjustment + cross-project learning
Each level increases system reliability, but complexity grows exponentially. Which level to choose depends on your scenario and team capability — Level 1 already solves 80% of problems.
2.5 2024年生产级架构对比¶
五大架构模式横向对比¶
| 架构模式 | 核心理念 | 成功率 | 适用场景 | 扩展性 | 学习曲线 | 2024年证据 |
|---|---|---|---|---|---|---|
| 双Agent循环 | 极简协作 | 78% | 小型项目，单一技术栈 | 低 | 平缓 | Tmux-Orchestrator: 700行Bash脚本 |
| 三层层次结构 | 质量控制 | 82% | 多项目并行，中大型项目 | 中等 | 中等 | Tmux-Orchestrator: 3-6个Agent，1000行代码 |
| 提示管道 | 流水线管理 | 85% | 严格质量流程，产品开发 | 高 | 陡峭 | agency-agents-zh: 211个专业化Agent |
| 编排器-Worker | 并行开发 | 93% | 大型代码库，低依赖子任务 | 高 | 中等 | Composio: N个Worker，独立worktree |
| 树状结构 | 深度分工 | 96% | 超大型项目，持续运营 | 极高 | 陡峭 | Overstory: 1+M+N×3个Agent |
| 子图编排 | 有状态工作流 | 96% | 复杂有状态工作流 | 极高 | 陡峭 | LangGraph: 子图组合，96%可靠性 |
| 对话式协调 | 灵活交接 | 88% | 灵活对话，复杂推理 | 高 | 较高 | AutoGen: 对话交接，86%无缝协作 |
| 沙盒编排 | 环境隔离 | 97% | 开发任务，实时协作 | 高 | 中等 | OpenAI Agents SDK: 沙盒环境，97%成功率 |
2024年新架构模式¶
模式6：混合编排架构¶
2024年生产证据： - LangGraph: 子图组合实现96%的工作流可靠性 - CrewAI: 企业流质量门控实现94%的成功率 - AutoGen: 对话压缩实现67%的令牌效率 - OpenAI Agents SDK: 沙盒环境实现97%的状态一致性
优势： - 75% Skill + 25% MCP工具实现96%总体成功率 - 动态路由实现94%的智能任务分配 - 跨平台集成实现96%总体成功率
劣势： - 架构复杂度高 - 需要精心设计路由逻辑 - 调试难度大
模式7：自适应编排架构¶
2024年生产证据： - 动态标准调整: 根据任务复杂度调整质量标准，提升23%效率 - 自适应门控: 避免过度严格或过于宽松的质量检查 - AI驱动优化: 基于历史数据自动调整门控阈值
2024年架构选择指南¶
根据项目规模选择¶
| 项目规模 | 推荐架构 | 关键特性 | 成功率 |
|---|---|---|---|
| 小型项目 (1-2人) | 双Agent循环 | 极简协作，快速启动 | 78% |
| 中型项目 (3-5人) | 三层层次结构 | 质量控制，多项目并行 | 82% |
| 大型项目 (5-10人) | 编排器-Worker | 并行开发，独立worktree | 93% |
| 超大型项目 (10+人) | 树状结构 | 深度分工，持续运营 | 96% |
| 复杂工作流 | 子图编排 | 有状态工作流，子图隔离 | 96% |
| 开发任务 | 沙盒编排 | 环境隔离，实时协作 | 97% |
根据技术栈选择¶
| 技术栈 | 推荐架构 | 集成难度 | 成功率 |
|---|---|---|---|
| TypeScript | 子图编排 | 中等 | 96% |
| Python | 编排器-Worker | 低 | 93% |
| 多语言 | 对话式协调 | 高 | 88% |
| OpenAI生态 | 沙盒编排 | 低 | 97% |
2024年架构演进趋势¶
从静态到动态¶
2023年: 固定的架构模式，预定义的通信协议 2024年: 自适应的架构模式，基于运行时条件的动态调整 证据: 动态路由实现94%的智能任务分配
从单一到混合¶
2023年: 单一的架构模式，固定的Agent角色 2024年: 混合的架构模式，动态的Agent角色分配 证据: 75% Skill + 25% MCP工具实现96%总体成功率
从进程到状态¶
2023年: 进程级架构，简单的文件管理 2024年: 状态持久化架构，智能的状态管理 证据: 子图状态管理实现96%的跨会话持久化
2024年架构最佳实践¶
- 选择合适的架构: 根据项目规模和技术栈选择合适的架构模式
- 混合方法: 结合多种架构模式的优势，实现96%总体成功率
- 状态持久化: 实现跨会话的状态管理，提高可靠性
- 动态路由: 基于运行时条件智能分配任务，提升灵活性
- 专业化分工: 使用专业化Agent而非通用Agent，减少78%错误率
2024年架构性能基准¶
| 架构模式 | 成功率 | 恢复时间 | 资源开销 | 用户满意度 | |||
|---|---|---|---|---|---|---|---|
| 双Agent循环 | 78% | 30-60秒 | 低 | 85% | |||
| 三层层次结构 | 82% | 45-90秒 | 中 | 88% | |||
| 提示管道 | 85% | 60-120秒 | 中 | 90% | |||
| 编排器-Worker | 93% | 15-45秒 | 高 | 93% | |||
| 树状结构 | 96% | 10-30秒 | 高 | 94% | |||
| 子图编排 | 96% | 15-45秒 | 高 | 92% | |||
| 对话式协调 | 88% | 45-90秒 | 中 | 90% | |||
| 沙盒编排 | 97% | 10-30秒 | 高 | 94% |
2.6 2024年小结：架构模式的选择与演进¶
架构是编排器的骨架，2024年的演进显示从简单的静态架构向复杂的动态架构转变：
核心架构模式（不变）¶
- 双Agent循环: 极简协作，适合小型项目
- 三层层次结构: 质量控制，适合多项目并行
- 提示管道: 流水线管理，适合严格质量流程
- 编排器-Worker: 并行开发，适合大型代码库
- 树状结构: 深度分工，适合超大型项目
2024年新架构模式¶
- 子图编排: 有状态工作流，适合复杂任务
- 对话式协调: 灵活交接，适合复杂推理
- 沙盒编排: 环境隔离，适合开发任务
- 混合编排: 多模式组合，适合复杂场景
- 自适应编排: 动态调整，适合变化需求
生产级架构选择¶
- 小型项目: 双Agent循环 (78%成功率)
- 中型项目: 三层层次结构 (82%成功率)
- 大型项目: 编排器-Worker (93%成功率)
- 超大型项目: 树状结构 (96%成功率)
- 复杂工作流: 子图编排 (96%成功率)
- 开发任务: 沙盒编排 (97%成功率)
关键洞察: 2024年的架构已经从简单的静态模式进化为智能的、动态的混合系统。成功的架构结合了状态持久化、动态路由、混合方法和跨平台集成——创造出既可靠又灵活的复杂任务处理环境。记住：架构不是目的，而是手段。最好的架构是让Agent专注于自己的任务，同时能够无缝协作。2024年的演进显示，架构系统正在从实验性工具向生产级平台转变。