# Architecture Patterns

## Basic Module Model

```text
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？
- 如何评估一次运行是否成功？
- 如何防止回归？