agent/docs/02-architecture-patterns.md

Architecture Patterns

Basic Module Model

User / Task
    |
    v
Controller / Policy
    |
    +--> Context Builder
    +--> Planner
    +--> Tool Router
    +--> Memory
    +--> Evaluator
    |
    v
Action / Response

Pattern 1: Single-loop Agent

一个模型在循环中完成理解、规划、调用工具、观察和回答。

适合：

• 任务边界清楚。
• 工具数量不多。
• 错误成本可控。

不适合：

• 长链路、多角色协作。
• 需要强审计或稳定流程。
• 工具调用风险很高。

Pattern 2: Planner-executor

Planner 负责拆解任务，Executor 负责执行具体步骤。

适合：

• 任务步骤较多。
• 需要保存和更新计划。
• 执行结果会影响后续步骤。

设计要点：

• 计划必须可修改。
• Executor 要返回结构化观察结果。
• Planner 需要知道停止条件。

Pattern 3: Workflow plus Agent Hybrid

固定流程负责主路径，Agent 处理开放问题、异常分支和自然语言交互。

适合：

• 企业业务系统。
• 有明确合规或审批流程。
• 希望稳定性优先于自主性。

设计要点：

• 确定性流程和模型决策分层。
• 关键动作走显式状态机。
• Agent 输出最好转成结构化意图。

Pattern 4: Retrieval-augmented Agent

Agent 在行动前检索知识库、文档、代码或历史记录。

适合：

• 知识密集型任务。
• 需要引用项目内部上下文。
• 有长期记忆需求。

设计要点：

• 检索结果要保留来源。
• 区分长期知识和当前任务状态。
• 防止旧知识覆盖新事实。

Pattern 5: Multi-agent Collaboration

多个 Agent 分担角色，例如研究、实现、评审、测试、协调。

适合：

• 大任务需要并行探索。
• 需要独立评审。
• 子任务边界清晰。

风险：

• 协调成本高。
• 上下文传递损耗。
• 多个 Agent 可能互相放大错误。

Pattern Selection

Need	Recommended Pattern
简单自动化	Single-loop agent
长任务、步骤多	Planner-executor
稳定业务流程	Workflow plus agent hybrid
大量内部知识	Retrieval-augmented agent
并行研究或独立评审	Multi-agent collaboration

Architecture Checklist

• 任务入口是什么？
• 成功标准是什么？
• Agent 能观察哪些状态？
• Agent 能执行哪些动作？
• 哪些动作需要确认？
• 状态存在哪里？
• 工具错误如何恢复？
• 如何记录 trace？
• 如何评估一次运行是否成功？
• 如何防止回归？