5.2b Agent 设计模式

来源：Anthropic《Building Effective Agents》、Lilian Weng《LLM Powered Autonomous Agents》

📝 课程笔记

本课核心知识点整理：

学完你能做什么

选择合适的 Agent 架构

实现五种 Workflow 模式

设计复杂的多 Agent 协作系统

避免常见的设计陷阱

核心原则

Anthropic 在与数十个团队合作构建 Agent 后总结出三条核心原则：

1. 保持简单

"最成功的实现使用简单、可组合的模式，而非复杂框架。"

实践：

能用单个 Agent 解决的，不要用多个

能用固定流程的，不要用动态决策

能用 prompt 解决的，不要加工具

2. 透明度优先

"显式展示 Agent 的规划步骤。"

实践：

Agent 的思考过程应该可见

每个步骤都有明确的输入输出

用户能理解 Agent 在做什么

3. 精心设计工具接口（ACI）

"像设计人机界面（HCI）一样投入精力设计 Agent-计算机界面（ACI）。"

实践：

工具描述要像给初级开发者写的优秀 docstring

包含使用示例和边界情况

避免需要精确计数或复杂转义的格式

Workflow vs Agent：如何选择

类型	特点	适用场景	OpenCode 实现
Workflow	预定义代码路径，步骤固定	任务可预测、结构清晰	Skill、Command
Agent	LLM 动态决策，自主探索	开放性问题、无法预测步骤	Agent + Task tool

选择流程图

任务来了
    ↓
步骤是否固定？
    ├─ 是 → 用 Workflow（Skill/Command）
    └─ 否 → 需要多少自主性？
              ├─ 低 → 受限 Agent（steps + 权限控制）
              └─ 高 → 完全自主 Agent

五种 Workflow 模式

模式 1：Prompt Chaining（提示链）

原理：将任务分解为顺序执行的步骤，每一步的输出是下一步的输入。

适用场景：

任务可以清晰分解为固定子任务

需要用延迟换取准确性

示例：翻译 + 润色 + 格式化

模式 2：Routing（路由）

原理：根据输入特征，将任务导向不同的专门处理流程。

适用场景：

不同类别需要不同处理方式

分类可以准确完成

示例：代码问题分类器

配合 Task 权限控制：

{
  "agent": {
    "router": {
      "description": "代码问题分类路由器",
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "bug-fixer": "allow",
          "performance-optimizer": "allow",
          "security-auditor": "allow",
          "refactor-expert": "allow"
        }
      }
    }
  }
}

模式 3：Parallelization（并行化）

原理：多个任务同时执行，最后汇总结果。

两种变体：

Sectioning（分片）：独立子任务并行

Voting（投票）：同一任务多视角验证

适用场景：

子任务相互独立

需要多视角提高准确性

时间敏感，需要加速

示例：代码质量并行检查

模式 4：Orchestrator-Workers（编排-工人）

原理：中央 LLM（编排器）动态分析任务，将其分解并分配给专门的 Worker Agent。

适用场景：

无法预测需要哪些子任务

任务复杂度不确定

需要灵活应对

示例：项目分析编排器

模式 5：Evaluator-Optimizer（评估-优化）

原理：一个 Agent 生成内容，另一个 Agent 评估，循环直到满足标准。

适用场景：

有明确的评估标准

迭代改进有价值

类似人类的"写作-修改"过程

示例：代码优化循环

Agent 三大组件设计

根据 Lilian Weng 的研究，一个完整的 Agent 系统包含三大组件：

1. Planning（规划）

任务分解技术：

技术	说明	适用场景
Chain of Thought	"一步步思考"	通用推理
Tree of Thoughts	探索多个推理路径	复杂决策
ReAct	思考-行动-观察循环	需要与环境交互

在 Agent prompt 中应用：

2. Memory（记忆）

类型	对应	特点
短期记忆	上下文窗口	有限，约几万 token
长期记忆	外部向量库	无限，需要检索

OpenCode 中的实现：

短期：会话上下文

长期：MCP 集成向量数据库

3. Tool Use（工具使用）

工具设计原则：

描述清晰：像给初级开发者的 docstring

输入简单：避免复杂的格式要求

输出可解析：结构化，便于后续处理

错误友好：清晰的错误信息

实战案例 1：多语言文档生成系统

动手提醒

本案例中的 @doc-parser、@translator-zh 等都是示例名称，OpenCode 没有内置这些 Agent。你需要按照 5.2a Agent 快速入门学到的方法自己创建它们。

好消息是：案例 1 中的 Agent 比较简单，description 字段本身就是一个够用的 prompt，配合低 temperature 就能工作。不需要额外写 .md 文件。

需求：自动将 API 文档翻译成多语言版本。

系统设计

用户输入 API 文档
       ↓
   @doc-parser（解析文档结构）
       ↓
   @translator-zh（翻译成中文）
   @translator-ja（翻译成日文）  ← 并行
   @translator-ko（翻译成韩文）
       ↓
   @doc-formatter（格式化输出）
       ↓
   多语言文档

配置文件

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "doc-generator": {
      "description": "多语言文档生成编排器",
      "mode": "primary",
      "prompt": "{file:./prompts/doc-generator.md}",
      "permission": {
        "task": {
          "*": "deny",
          "doc-parser": "allow",
          "translator-*": "allow",
          "doc-formatter": "allow"
        }
      }
    },
    "doc-parser": {
      "description": "解析 API 文档结构，提取可翻译内容",
      "mode": "subagent",
      "temperature": 0.1
    },
    "translator-zh": {
      "description": "英译中专家，保持技术术语准确",
      "mode": "subagent",
      "temperature": 0.3
    },
    "translator-ja": {
      "description": "英译日专家",
      "mode": "subagent",
      "temperature": 0.3
    },
    "translator-ko": {
      "description": "英译韩专家",
      "mode": "subagent",
      "temperature": 0.3
    },
    "doc-formatter": {
      "description": "文档格式化，确保多语言版本格式一致",
      "mode": "subagent",
      "temperature": 0.1
    }
  }
}

编排器 Prompt

实战案例 2：代码审计流水线

动手提醒

本案例中的 @security-auditor、@test-auditor 等都是示例名称，OpenCode 没有内置这些 Agent。你需要按照 5.2a Agent 快速入门学到的方法自己创建它们。

和案例 1 不同，审计类的 Agent 需要专业的 prompt 才能给出有价值的分析结果。下面会给出完整的创建示例。

需求：对 PR 进行全方位代码审计。

系统设计

采用 Parallelization + Orchestrator-Workers 混合模式。

PR 代码变更
       ↓
   @audit-coordinator（协调器）
       ↓
   ┌──────────────────────────────────┐
   │  并行执行（Sectioning）          │
   │  @security-auditor              │
   │  @performance-auditor           │
   │  @quality-auditor               │
   │  @test-auditor                  │
   └──────────────────────────────────┘
       ↓
   汇总所有发现
       ↓
   @report-generator（生成报告）
       ↓
   审计报告

配置文件

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "audit-coordinator": {
      "description": "代码审计协调器，编排多维度审计",
      "mode": "subagent",
      "model": "anthropic/claude-opus-4-5-thinking",
      "prompt": "{file:./prompts/audit-coordinator.md}",
      "steps": 50
    },
    "security-auditor": {
      "description": "安全漏洞审计：注入、认证、数据泄露",
      "mode": "subagent",
      "temperature": 0.1,
      "prompt": "{file:./prompts/security-auditor.md}",
      "permission": {
        "edit": "deny"
      }
    },
    "performance-auditor": {
      "description": "性能审计：复杂度、内存、并发",
      "mode": "subagent",
      "temperature": 0.1,
      "permission": {
        "edit": "deny"
      }
    },
    "quality-auditor": {
      "description": "代码质量审计：可读性、SOLID、重复代码",
      "mode": "subagent",
      "temperature": 0.2,
      "permission": {
        "edit": "deny"
      }
    },
    "test-auditor": {
      "description": "测试审计：覆盖率、边界情况、Mock 质量",
      "mode": "subagent",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "npm test*": "allow",
          "npm run test*": "allow"
        }
      }
    },
    "report-generator": {
      "description": "生成结构化审计报告",
      "mode": "subagent",
      "temperature": 0.2
    }
  }
}

协调器 Prompt

创建专家 Agent

上面的配置文件定义了 Agent 的参数和权限，但 performance-auditor、quality-auditor、test-auditor、report-generator 这四个没有引用外部 prompt 文件，它们会使用模型的默认提示词。对审计任务来说这不太够，你需要为每个专家创建 .md 文件。

文件结构

.opencode/
├── agent/
│   └── security-auditor.md    ← 也可以放这里
└── prompts/
    ├── audit-coordinator.md   ← 协调器（上面已有）
    ├── security-auditor.md    ← 安全审计专家
    ├── performance-auditor.md ← 性能审计专家
    ├── quality-auditor.md     ← 质量审计专家
    ├── test-auditor.md        ← 测试审计专家
    └── report-generator.md    ← 报告生成器

完整示例：security-auditor.md

创建文件 .opencode/agent/security-auditor.md：

精简示例：其余专家 Agent

其余三个专家 Agent 结构类似，只需要替换审计范围。创建文件后，记得在 opencode.json 的配置中加上 "prompt": "{file:./prompts/xxx.md}"。

点击查看 performance-auditor.md 模板

点击查看 quality-auditor.md 模板

点击查看 test-auditor.md 模板

提示：上面这些 prompt 是起点，不是终点。根据你的项目特点（语言、框架、业务），调整审计范围才能获得最好的效果。

设计检查清单

在设计 Agent 前，问自己：

简单性：能用更简单的方案吗？

模式选择：选对 Workflow 模式了吗？

工具描述：描述清晰、易于理解吗？

评估标准：如何判断 Agent 完成了任务？

失败处理：出错时如何恢复？

权限控制：是否限制了不必要的权限？

资源限制：设置了 steps 限制吗？

常见设计陷阱

陷阱	表现	解决
过度设计	用多 Agent 解决简单问题	先用单 Agent 尝试
模糊描述	description 太泛导致错误调用	具体说明适用场景
无限循环	Agent 互相调用不停止	设置 steps 限制
权限过松	subagent 可以做任何事	明确 task/edit/bash 权限
缺乏透明	不知道 Agent 在做什么	要求输出中间步骤

本课小结

你学会了：

三条核心原则：简单、透明、精心设计 ACI

五种 Workflow 模式：提示链、路由、并行化、编排-工人、评估-优化

Agent 三大组件：规划、记忆、工具使用

两个实战案例：多语言文档系统、代码审计流水线

设计检查清单：避免常见陷阱

延伸阅读

Anthropic: Building Effective Agents（2024.12）

Lilian Weng: LLM Powered Autonomous Agents（2023.06）

OpenAI: Agents Overview

下一课预告

设计好 Agent 后，如何精确控制它能做什么、不能做什么？下一课深入权限系统。

下一课：5.2c Agent 权限与安全

📝 课程笔记#

学完你能做什么#

核心原则#

1. 保持简单#

2. 透明度优先#

3. 精心设计工具接口（ACI）#

Workflow vs Agent：如何选择#

选择流程图#

五种 Workflow 模式#

模式 1：Prompt Chaining（提示链）#

模式 2：Routing（路由）#

模式 3：Parallelization（并行化）#

模式 4：Orchestrator-Workers（编排-工人）#

模式 5：Evaluator-Optimizer（评估-优化）#

Agent 三大组件设计#

1. Planning（规划）#

2. Memory（记忆）#

3. Tool Use（工具使用）#

实战案例 1：多语言文档生成系统#

系统设计#

配置文件#

编排器 Prompt#

实战案例 2：代码审计流水线#

系统设计#

配置文件#

协调器 Prompt#

创建专家 Agent#

文件结构#

完整示例：security-auditor.md#

精简示例：其余专家 Agent#

设计检查清单#

常见设计陷阱#

本课小结#

延伸阅读#

下一课预告#

📝 课程笔记

学完你能做什么

核心原则

1. 保持简单

2. 透明度优先

3. 精心设计工具接口（ACI）

Workflow vs Agent：如何选择

选择流程图

五种 Workflow 模式

模式 1：Prompt Chaining（提示链）

模式 2：Routing（路由）

模式 3：Parallelization（并行化）

模式 4：Orchestrator-Workers（编排-工人）

模式 5：Evaluator-Optimizer（评估-优化）

Agent 三大组件设计

1. Planning（规划）

2. Memory（记忆）

3. Tool Use（工具使用）

实战案例 1：多语言文档生成系统

系统设计

配置文件

编排器 Prompt

实战案例 2：代码审计流水线

系统设计

配置文件

协调器 Prompt

创建专家 Agent

文件结构

完整示例：security-auditor.md

精简示例：其余专家 Agent

设计检查清单

常见设计陷阱

本课小结

延伸阅读

下一课预告