build-agent-system-zh-cn

name	build-agent-system-zh-cn
description	AI Agent 系统设计与构建指南。广泛触发：只要用户在进行任何 Agent 相关的开发工作——构建、调试、重构或讨论 Agent、Agentic 架构、工具调用模式、多 Agent 编排、Agent 工作流、自主流水线、LLM 驱动的自动化、编码 Agent 系统，均应激活。覆盖 Codex SDK、Claude Agent SDK 及通用 Agent 设计模式。即使用户未明确说'Agent'，也应从上下文推断并激活（如工具调用循环、规划/执行模式、自主任务分解）。

Build Agent System

本技能涵盖使用 Codex SDK 或 Claude Agent SDK 构建 Agent System 的完整方法论。

SDK 具体的 API 调用方式请查阅对应参考文档：

• Codex SDK（OpenAI）：阅读 references/codex-sdk.md
• Claude Agent SDK（Anthropic）：阅读 references/claude-agent-sdk.md

如需查阅 SDK 的最新官方文档，请使用 OpenAI Docs 或 Anthropic Docs 技能获取最新 API 参考。

---

核心概念

单个 Agent 可以抽象为：输入字符串 → 执行操作 + 修改数据 → 返回结构化输出。

复杂的 Agent System 由多个 Agent 编排而成，每个 Agent 承担不同职责。构建系统分两步：

1. 定义好每一个单独的 Agent
2. 将 Agent 编排为系统

---

How to Build a Single Agent

Agent 三要素

无论使用哪个 SDK，定义一个 Agent 都需要配置三样东西：

要素	说明	Codex SDK	Claude Agent SDK
System Instruction	定义角色、职责和任务 workflow 的提示词	developer_instructions（TS/Python）	systemPrompt（TS）/ system_prompt（Python）
Output Schema	结构化输出格式，SDK 层面保证解析成功	outputSchema (JSON Schema)	outputFormat (JSON Schema / Zod / Pydantic)
Profile / Config	模型、权限、沙箱等运行参数	~/.codex/config.toml profile + 代码配置	options 对象

Agent Class 设计原则

每个 Agent 封装为一个 class，提供两个核心方法：

• run：首次执行，创建新会话
• continue：基于同一会话继续对话（用于多轮交互、反馈修正）

关键设计要点：

• 会话 ID：跨调用恢复状态的基础，是多轮交互和 redo 流程的核心
• 工作目录：限定 Agent 的文件系统操作范围
• 结构化输出：通过 Schema 在 SDK 层面强制约束，而非依赖提示词约束（提示词约束不可靠）

具体的 class 模板和代码示例请查阅对应 SDK 的参考文档。

---

如何编写 System Prompt

System Prompt 决定了 Agent 的行为质量。

管理方式

使用 TypeScript 文件定义，而非直接用 .md 文件——避免额外 IO 开销，并让 prompt 与代码共存：

export const myAgentInstruction = `
# SYSTEM PROMPT for {Agent Name}
...
`.trim();

在专门目录中统一管理所有 prompt：

src/devInstructions/
├── analyzer.ts
├── executor.ts
├── reviewer.ts
└── index.ts        # 统一导出

Prompt 模板结构

# SYSTEM PROMPT for {Agent Name}

## ROLE DEFINITION
简要定义 Agent 的职责和任务边界。明确该 Agent "是什么"和"不是什么"。

## Task Background
提供整体任务背景：整个 Agent System 在解决什么问题？其他 Agent 各自负责什么？
帮助当前 Agent 理解自己在系统中的位置，做出更合理的判断。

## ABOUT THE TASK
具体描述该 Agent 需要完成的任务：
- 需要交付什么？
- 输出会如何被下游消费？
- 任务完成的判定标准是什么？

## INPUT
描述输入的格式和含义，帮助 Agent 正确理解收到的内容。

## CONSTRAINTS
注意事项、约束边界、业务场景下的特殊规则。

## SOP
该 Agent 收到任务后的标准执行流程，按步骤列出。

## Output Example
如果使用结构化输出，描述每个字段的含义并给出完整示例。

编写原则

• 解释 why，而非堆砌 MUST：LLM 理解了背后的原因，在边界情况下能做出远比僵硬规则更好的判断
• 提供上下文而非仅指令：告诉 Agent 它在系统中的位置，比命令"你必须做 X"更有效
• 用示例代替长篇描述：一个具体的输出示例，胜过三段文字说明
• 明确边界：在 ROLE DEFINITION 中说清楚"不负责什么"，防止 Agent 越界和多个 Agent 之间职责重叠

System Prompt 示例

以下是一个文档生成系统中 Writer Agent 的 prompt 示例，展示了各模块的填写方式：

export const writerInstruction = `
# SYSTEM PROMPT for Writer

## ROLE DEFINITION
你是 autoDoc 系统中的 Writer Agent，负责为叶子节点生成高质量的 Markdown 文档。
你是整个文档生成流水线的最后一环——你的输出就是最终用户在文档站中看到的内容。

## Task Background
autoDoc 是一个自动文档生成系统，整个系统由以下 Agent 协作完成：
- Scaffold：顶层拆解，生成根图
- Decomposer：递归展开子图，决定哪些节点终止为文档页
- Checker：校验 Decomposer 产物的质量
- Writer（你）：为叶子节点生成最终的 Markdown 文档

## ABOUT THE TASK
当 Decomposer 的产物通过 Checker 校验后，所有 child.type = "page" 的节点分配给你。
你需要深入阅读该节点 codeScope 范围内的代码，生成一份结构完整、内容翔实的 Markdown 文档。

## INPUT
- 模块名称（name）：当前叶子节点的名称
- 模块描述（description）：Decomposer 对该节点的职责描述
- 代码范围（codeScope）：需要阅读的文件/目录路径列表
- 祖先上下文（ancestor context）（可选）：从根图到当前节点的完整层级信息

## CONSTRAINTS
1. 面向新人：读者是第一次接触项目的开发者
2. 代码驱动：所有内容必须基于实际读取到的代码，不要编造
3. 引用关键代码片段时，标注文件路径和行号

## SOP
1. 阅读代码：逐一阅读 codeScope 中的所有文件
2. 梳理结构：识别核心组件
3. 追踪调用链：理解关键流程的数据流向
4. 组织文档：按照概述、关键流程、函数签名、类型定义等章节组织
5. 输出结果

## Output Example
{ "content": "# 模块名称\\n\\n## 概述与职责\\n\\n..." }
`.trim();

---

How to Build Agent System

定义好单个 Agent 后，需要将它们编排为系统。核心设计决策：

决策点	说明
任务分配	如何将总任务拆解并分配给各 Agent
Context 流转	Agent 之间如何传递信息（直接传输出 / 共享存储 / 消息队列）
完成判定	如何判断任务是否达标
Redo 机制	不达标时如何重试或回退

编排模式

1. 非 LLM 编排（推荐用于确定性流程）

用代码逻辑控制 Agent 的执行顺序和条件判断。适合流程明确、步骤固定的场景。

顺序流水线（Pipeline）

前一个 Agent 的输出作为后一个 Agent 的输入：

[Analyzer] → analysis → [Executor] → result → [Reviewer] → review

适用于线性处理流程。实现时依次调用各 Agent 的 run 方法，将上一个的 data 序列化后作为下一个的 prompt。

并行扇出 + 汇聚（Fan-out / Fan-in）

将独立子任务并行分配给多个 Agent，收集结果后汇总：

           ┌→ [Worker 1] → result 1 ─┐
[Task] ────┼→ [Worker 2] → result 2 ──┼→ [Aggregator] → summary
           └→ [Worker 3] → result 3 ─┘

使用 Promise.all（TS）或 asyncio.gather（Python）并行执行，然后由汇聚 Agent 整合结果。

循环校验（Loop with Checker）

执行后由 Checker Agent 校验，不通过则将反馈送回执行 Agent 重做。这是实现质量保证的核心模式：

[Executor] → result → [Checker] → passed? ─Yes→ done
                          │
                          No
                          │
                          └→ feedback → [Executor.continue] → result → [Checker] → ...

关键点：

• 重试时使用 continue 而非 run——Agent 保留了之前出错的上下文和 Checker 的反馈，修复更有针对性。
• 务必设置 maxRetries 防止无限循环，3 次重试是合理的默认值。

2. LLM 编排（适用于动态决策流程）

用一个 Orchestrator Agent 来决定调用哪个 Agent、传递什么参数。适合任务流程不确定、需要动态决策的场景。

Orchestrator 的结构化输出格式：

interface OrchestratorDecision {
  nextAgent: string;      // 下一个要调用的 agent
  prompt: string;         // 传给该 agent 的 prompt
  done: boolean;          // 是否完成整个任务
  finalResult?: string;   // done=true 时的最终结果
}

执行循环：Orchestrator 决策 → 执行选定的 Agent → 将结果反馈给 Orchestrator → 下一轮决策，直到 done=true。

注意：Claude Agent SDK 内置了 subagent 机制，可以直接通过 agents 配置定义子 Agent，由 Claude 自行决定何时调用。详见 references/claude-agent-sdk.md 的 Subagents 章节。

3. 后台子 Agent（Claude Agent SDK）

在 AgentDefinition 中设置 background: true，子 Agent 将与主 Agent 并发执行，完成后通过 TaskCompleted hook 通知：

[主 Agent] ──────────────────────────────→ 继续工作
      │
      └── 启动 ──→ [后台 Agent] ──→ TaskCompleted 通知

适用于：

• 主 Agent 工作时，后台 Agent 监控错误
• 并行收集研究信息
• 不阻塞主流程的长时间任务

4. Thread 分叉（Codex SDK）

thread_fork() 实现推测性执行——从同一状态尝试多种方案，选择最优结果：

[Thread A] ─── fork ──┬→ [Thread B: 方案 1] → result 1
                       └→ [Thread C: 方案 2] → result 2
                              ↓
                       [选择最优] → 最终结果

结合 Promise.all / asyncio.gather，可安全地并行探索而不污染原始 thread。

编排模式选择指南

场景	推荐模式	原因
流程固定，步骤明确	顺序流水线	简单可靠，易调试
大量同类子任务	并行扇出	充分利用并发，缩短总耗时
需要质量保证	循环校验	Checker 提供自动化反馈，减少人工介入
流程动态、需临场判断	LLM 编排	Orchestrator 可根据中间结果灵活调整策略
长任务 + 非阻塞辅助工作	后台子 Agent	主 Agent 继续工作，后台 Agent 处理次要任务
需探索多种方案	Thread 分叉	并行尝试不同方案，不污染基础状态
复杂系统	组合使用	例如 LLM 编排 + 局部循环校验 + 后台 Agent

---

项目结构建议

my-agent-system/
├── src/
│   ├── agents/                    # 每个 Agent 一个文件
│   │   ├── analyzer.ts
│   │   ├── executor.ts
│   │   ├── reviewer.ts
│   │   └── orchestrator.ts
│   ├── devInstructions/           # System Prompt 统一管理
│   │   ├── analyzer.ts
│   │   ├── executor.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── schemas/               # Output Schema 定义
│   │   │   ├── schemas.ts
│   │   │   └── parsers.ts
│   │   └── response.ts           # AgentStructuredResponse 类型
│   └── workflows/                 # 编排逻辑
│       ├── pipeline.ts
│       └── index.ts
├── package.json
└── tsconfig.json

实用建议

错误处理与重试

Agent 调用可能因速率限制、网络问题或输出格式错误而失败：

• 每次 Agent 调用都包在 try/catch 中。遇到瞬时错误（速率限制、超时），使用指数退避重试。
• 循环校验模式下通过 maxRetries 限制重试次数。Checker 连续拒绝 3 次后应升级处理，而非无限循环。
• 重试时使用 continue 而非 run——会话保留了失败的上下文，Agent 知道哪里出了问题。全新 run 会丢失这些历史。

费用与 Token 管理

多 Agent 系统会放大 API 费用，需要注意控制：

• 按 Agent 使用满足质量要求的最便宜模型。不是每个 Agent 都需要 opus——Checker 和简单分类器用 haiku 或 sonnet（Claude）或标准层级 gpt-5.5（OpenAI）即可。
• 设置 maxTurns 防止失控循环，大多数任务 10–30 次是合理的默认值。
• 使用 maxBudgetUsd（Claude Agent SDK）设置硬性费用上限——达到限制后 Agent 自动停止，而非无限烧预算。
• 通过 total_cost_usd（Claude Agent SDK）或 token 计数追踪累积费用。记录每个 Agent 的费用，找出最贵的环节。
• 扇出模式下，扩大规模前先估算总费用：单个 worker 费用 × worker 数量。
• Codex Python SDK 的 retry_on_overload() 自动处理速率限制和退避，无需自定义重试逻辑。

调试与可观测性

• 记录每次 Agent 调用的 prompt（截断）、session/thread ID、模型、耗时和费用。
• Agent 产出意外结果时，检查 transcript（完整消息流）而非靠猜。中间的工具调用和推理能揭示问题所在。
• 多 Agent 系统中，为每个 Agent 的日志添加名称前缀（如 [Analyzer]、[Checker]），方便追踪流程。
• 开发阶段使用 maxTurns: 1 或 permissionMode: "plan" 预览 Agent 行为，避免执行副作用。

---

SDK 选择指南

两个 SDK 都是功能完整的 Agent 开发平台，能力相当。选择取决于模型偏好和生态系统契合度。

维度	Codex SDK (OpenAI)	Claude Agent SDK (Anthropic)
语言支持	TypeScript + Python	TypeScript + Python
运行模型	Thread/Turn 模型	Session/Query 模型
配置方式	TOML profile + 代码配置 + 环境变量覆盖	代码内 options 对象 + .claude/ 配置文件
子 Agent	手动编排（完全可控）	内置 subagent 机制（Claude 自动调度）
工具系统	丰富的内置工具 + 沙箱 + 插件	丰富的内置工具 + MCP 协议 + 插件
权限控制	approval_policy + 沙箱模式	permissionMode + hooks + "auto" 分类器
结构化输出	outputSchema (JSON Schema)	outputFormat (JSON Schema / Zod / Pydantic)
执行中途控制	TurnHandle 支持 steer/interrupt/stream	Query 对象支持 interrupt/rewindFiles/setModel
后台 / 长任务	目标持久化（create/pause/resume/clear）	后台子 Agent，通过 background: true 启用
会话分支	thread_fork()	forkSession

模型选择指南

维度	Claude (Anthropic)	OpenAI
顶级模型	Opus 4.6 / 4.7	GPT-5.5 / GPT-5.4
文字与写作	Opus 4.6 自然流畅；Opus 4.7 AI 味明显偏重	GPT-5.5 SOTA——文风自然，写作质量优秀
前端开发	设计美感好，生成的 UI 代码质量高	强
数学与算法	强	GPT-5.5 SOTA——竞赛数学和算法题顶尖水平
代码	强	GPT-5.5 在各项代码 benchmark 中 SOTA
长时间 Agent 任务	后台 Agent、自动压缩、文件检查点	目标持久化、Turn 级别 steer/interrupt
费用层级	Opus（高端）/ Sonnet（均衡）/ Haiku（经济）	GPT-5.5（高端）/ fast tier / default tier

选择建议：

• GPT-5.5 是当前综合能力最强的前沿模型（写作、代码、数学）——追求极致能力时优先选择
• Claude Opus 4.6 文风独特自然、AI 感轻，适合对行文风格有要求的任务。Opus 4.7 能力更强但 AI 味偏重
• Opus 4.7 需要 Claude Agent SDK v0.2.111+
• 预算敏感的扇出场景，使用 Sonnet 4.6（Claude）或标准层级 GPT-5.5（OpenAI）
• 两个 SDK 都支持按 Agent 混用模型——关键思考环节用高端模型，简单任务用经济模型

根据项目需求选择 SDK 后，查阅对应的参考文档获取具体 API 用法。