AI Agent 工程进阶：从 Demo 到可靠系统

很多人第一次把 Agent 跑起来时，都会经历一个很有成就感的瞬间：

模型理解了任务
  -> 自己选择工具
  -> 修改了文件
  -> 测试通过
  -> 给出一份像样的结果

但当同一套流程开始处理更多真实任务，问题也会很快出现：

• 同一个输入运行三次，走了三条不同路径；
• 工具已经调用成功，任务却没有真正完成；
• 一次重试修好了问题，另一次重试制造了重复写入；
• 上下文越来越长，却仍然遗漏关键规则；
• 日志里只有最终回答，无法解释中间发生了什么；
• 换了模型、Prompt 或 Harness 后，没人能证明新版本更好；
• 多加几个 Agent 以后，成本和冲突先于质量一起上升。

到这一步，继续寻找“更强 Prompt”通常不够了。

真正需要补上的，是一套围绕 Agent 的工程方法：怎样定义任务，怎样建立基线，怎样设计运行时，怎样恢复失败，怎样观察行为，又怎样把生产问题变成下一轮可验证的改进。

这也是我准备继续写 AI Agent 工程进阶 系列的原因。

一分钟概览

如果只想先判断这个系列是否适合自己，可以记住七点：

1. 会调用工具 只能证明 Agent 能运行，不能证明它可靠。
2. 系列先写任务契约和 Eval，再写 Context、Harness 与复杂编排。
3. 每篇都围绕 GitHub 项目 ai-agent-learn 中的同一个 Agent Reliability Lab 演进，并对应一个可运行的代码检查点。
4. 单 Agent Loop 没有建立基线、停止条件和 Trace 前，不急着升级多 Agent。
5. Memory、Graph 和自动改进都属于条件性能力，不是成熟度勋章。
6. 每篇必须留下模板、Schema、脚本、策略或检查清单，而不只解释概念。
7. 最终目标不是“全自动”，而是让每次决定有合同、每次失败能还原、每次改进可测量、高风险动作可控制。

图 1：Agent 从一次可运行的 Demo 走向可依赖的工程系统

图 1：模型和工具只是可运行 Agent 的起点。任务契约、评测、状态、追踪、权限和发布反馈共同决定系统是否值得依赖。移动端可打开原始 SVG查看。

1. 为什么还要写一个进阶系列

前面的 Codex 系列 主要解决“怎样把工程 Agent 用进真实项目”：

• 入口怎么选；
• Prompt 和 AGENTS.md 怎么写；
• 权限、Git 与回滚怎么管理；
• Skills、MCP、GitHub 和发布流程怎么使用；
• 团队如何共享规则并划定工作边界。

这些内容解决的是工具实践。

而 Agent 工程进阶要继续追问：

当一个 Agent 已经可以工作时，怎样证明它工作得稳定？当它失败时，怎样知道是哪一层失败？当任务变长、工具增多、状态需要跨进程保存时，系统怎样继续保持可控？

两套内容的区别，可以简单概括为：

Codex 实用系列：把 Agent 用起来
Agent 工程进阶：把 Agent 系统做可靠

这不是换一套流行术语。

OpenAI 在 Harness Engineering 的实践里，强调仓库结构、机械约束、可观测性和持续维护；Anthropic 的 Context、Tool、Eval 与长任务 Harness 文章，也不断把问题从模型回答扩展到上下文选择、工具合同、结构化交接和独立评估。不同团队使用的产品和框架并不相同，但它们逐渐指向同一件事：

Agent 的能力来自模型，Agent 的可靠性来自模型之外那套可检查的系统。

2. 系列的主线不是框架，而是十二个工程对象

这个系列不会按 OpenAI Agents SDK、Claude Agent SDK、LangGraph 或其他框架分别写一遍。

框架会变化，接口也会变化。更值得长期保存的是十二个工程对象：

Contract
  -> Eval
  -> Context
  -> Harness
  -> Tool
  -> Durable Loop
  -> Trace
  -> Memory
  -> Graph
  -> Human Control
  -> Production Ops
  -> Improvement Loop

这十二个对象被分成四个阶段。

图 2：AI Agent 工程进阶十二篇路线图

图 2：路线先建立成功标准和评测方法，再增加运行时能力，最后进入生产治理与持续改进。复杂度升级必须有前置证据。

3. 第一阶段：先定义，再测量

第一阶段只有两篇，却是后面所有内容的地基。

第 1 篇：Agent 系统契约

这一篇解决：

“做一个能回答内部问题的 Agent”为什么不是一个可执行需求？

文章会把模糊目标拆成：

• 任务单元；
• 输入与输出合同；
• 完成条件；
• 允许和禁止的动作；
• 失败与人工接管条件；
• 非 Agent 基线。

读者最终会得到一份 Agent System Card，并建立第一版真实任务集。

这里特意加入“非 Agent 基线”，因为很多任务用脚本、检索加单次模型调用，或者一个固定工作流就能完成。只有先证明任务真的需要自主决策，才值得承担 Agent 带来的额外复杂度。

第 2 篇：Agent Evals

这一篇解决：

版本 B 看起来比版本 A 更聪明，怎样证明它真的更好？

评测不会只看最终文字，还会区分：

• 最终结果是否正确；
• 是否完成现实任务；
• 是否走了允许的行为路径；
• 工具调用是否正确；
• 步骤、耗时和成本是否可接受；
• 人工是否需要频繁接管。

文章会提供任务集、Grader、重复运行和失败样本台账。

把 Eval 放在第 2 篇，而不是系列末尾，是一个有意的顺序：

如果没有测量方法，后面对 Context、Harness、Tool 和 Graph 的所有优化都只能依靠感觉。

4. 第二阶段：构造可靠运行时

第二阶段开始进入 Agent 真正工作的地方。

第 3 篇：Context Architecture

Prompt 只是 Context 的一部分。

真正进入模型上下文的，还可能包括：

• 系统和项目规则；
• 工具定义；
• 当前任务文件；
• 检索结果与来源；
• 历史消息；
• 压缩摘要；
• 运行状态；
• 外部记忆。

这一篇会讨论选择、来源、新鲜度、压缩与预算，并回答“什么应该进入当前推理，什么只需要保存在可恢复的 Session 里”。

已经完成的《AGENTS.md 真的有用吗》会作为这篇之后的实验篇：用同一任务集比较无说明、自动生成说明和最小规则三种条件，而不是继续争论“上下文越多是否越好”。

第 4 篇：Harness Engineering

Harness 不是一个大 Prompt，也不是工具清单。

它是模型之外负责组织运行的系统，包括：

• 怎样组装 Context；
• 怎样分发工具调用；
• 怎样保存状态；
• 怎样限制权限；
• 怎样处理错误；
• 怎样停止、恢复和追踪；
• 怎样把结果交给验证器或人。

这一篇会建立模型、Harness、Session 与 Sandbox 的责任边界，并讨论一个容易被忽略的问题：

为旧模型补上的 Harness 机制，可能在模型升级后变成技术债。

因此 Harness 也必须版本化、评测和删减。

第 5 篇：Tool Engineering

传统 API 连接的是两个确定性系统，Agent 工具连接的是确定性程序与非确定性调用者。

工具设计除了参数正确，还要考虑：

• 名称和描述是否容易被模型区分；
• 输入 Schema 是否消除歧义；
• 返回结果是否高信号；
• 分页和截断是否保护上下文；
• 错误能否指导恢复；
• 写操作是否支持 dry-run 和幂等；
• 权限与副作用是否明确。

这一篇会让同一能力暴露成两种工具接口，再用 Tool Eval 比较选择正确率、参数错误率和上下文占用。

第 6 篇：Durable Loop

“调用工具，读取结果，再继续调用”只是循环，不一定是可靠循环。

可靠 Loop 还需要：

• 完成与停止条件；
• 重试、超时和 Token 预算；
• 检查点；
• 暂停、取消和恢复；
• 副作用幂等；
• 失败后的明确终态。

文章会在模型、工具和人工等待三个位置主动注入故障，验证系统能否从最近检查点恢复，而不是每次从头再来。

5. 第三阶段：解释行为，再扩大能力

只有先解释单 Agent 为什么成功或失败，扩大系统才有意义。

第 7 篇：Agent Tracing

普通日志经常只能告诉我们“发生了错误”，却不能回答：

• 当时模型看见了哪些上下文；
• 为什么选择这个工具；
• 参数从哪里来；
• 哪次重试改变了结果；
• 哪个版本的 Prompt、工具和策略参与了运行；
• 最终结果正确，但路径是否存在风险。

这一篇会设计一份框架中立的 Trace Schema，再映射到 OpenAI Agents SDK、OpenTelemetry、Phoenix 或 Langfuse 等实现。

Trace 也会讨论隐私边界。工具参数和结果可能包含密钥、个人信息或业务数据，“记录一切”不是可观测性的正确答案。

第 8 篇：Memory Engineering

Memory 不是把所有历史重新塞回 Context。

这一篇会分清：

• 当前推理需要的工作状态；
• 同一任务跨进程恢复所需的 Session；
• 可在未来任务复用的情节或语义记忆；
• 用户长期偏好；
• 不能持久化的敏感数据。

读者会得到一份 Memory Policy，明确何时写、何时读、怎样处理冲突、何时衰减和怎样删除。

第 9 篇：Graph Engineering

当一个任务包含真实依赖、并行工作、独立验证和人工闸门时，单 Loop 才可能需要升级成 Graph。

这一篇直接复用并纳入已经发布的《Graph Engineering：从单 Agent 循环到可验证的工作图》，继续讨论：

• Node、Edge 与 State；
• 真实依赖和假边；
• Diamond Pattern；
• 状态所有权；
• 并发隔离；
• 独立 Verifier；
• 预算和人工闸门。

它不会把“多开几个 Agent”包装成 Graph Engineering。

多 Agent 的改善可能只是来自更多计算、更多上下文或更多采样。如果没有等预算基线，就不能证明拓扑本身更优。

6. 第四阶段：进入生产与持续改进

最后三篇讨论的不是“能不能完成”，而是“能不能长期负责”。

第 10 篇：Human Control 与 Agent Security

不同动作应该进入不同控制路径：

只读查询        -> 自动执行并记录
可逆修改        -> 策略判断或批量审批
外部发送        -> 明确预览与人工批准
生产发布/付款   -> 强审批、身份校验与审计

文章会讨论最小权限、Sandbox、凭据代理、审批状态持久化、拒绝与超时恢复。

安全不会等到第 10 篇才第一次出现。Context、Tool、Trace 和 Memory 各篇都会包含自己的风险注记；第 10 篇负责把它们整理成一套完整策略。

第 11 篇：Agent Production Ops

一个 Agent 上线后，除了成功率，还要面对：

• 延迟；
• 单任务成本；
• 并发与队列；
• 外部工具限流；
• 模型或服务不可用；
• 人工接管率；
• 版本发布与回滚。

这一篇会建立 Agent SLO、单任务预算、降级矩阵和 Canary 发布清单。

当预算耗尽、工具变慢或失败率升高时，系统应该能够降级到只读、草稿或人工处理，而不是继续盲目重试。

第 12 篇：Agent 持续改进

最后一篇把前面的所有能力接成反馈闭环：

生产 Trace
  -> 识别失败
  -> 加入 Eval 任务
  -> 提出候选改动
  -> 与旧版本对照
  -> Canary
  -> 发布或回滚

图 3：Agent 持续改进闭环

图 3：生产失败不会直接触发自动修改。它先变成可重复的评测任务，候选改动通过对照与人工闸门后，才进入渐进发布。

AutoHarness、自优化 Agent 和自然语言 Harness 会作为前沿观察放在这里，但文章不会把它们写成无人监管的“自我进化”。

没有固定任务集、版本记录、人工闸门和回滚时，系统自动修改的只是自己，不一定是质量。

7. 贯穿项目：在真实 GitHub 工程上继续加固

很多教程每篇都会换一个最适合展示当前概念的 Demo。

这样容易写，也容易得到漂亮结果；问题是读者看不到一个系统从“能运行”进入“可负责”时真正增加了哪些代码、测试和约束。

这个系列不再虚构一个孤立示例，而是直接使用我的公开学习仓库 RalfNick/ai-agent-learn。

仓库的 Phase 6 已经有一个企业知识库 Agent：包含资料导入、检索、Agentic QA 工作图、证据检查、拒答、Web UI 和发布评测。它不是一张空白画布，正好可以用来回答更接近真实工程的问题：

• 原有 Trace 能否解释一次失败？
• 现有 Eval 是否覆盖结果、路径、成本和拒答？
• 进程中断后能否恢复，而不重复副作用？
• Context、工具、Memory 和 Graph 的状态分别归谁所有？
• 线上指标恶化后，能否降级、回滚并生成新的回归用例？

我在仓库的草稿分支中新增了 phase-7-agent-engineering/agent-reliability-lab。它不是重新实现 Phase 6，而是把既有 Agent 当成棕地项目，逐篇补齐可靠性能力。

图 4：GitHub 工程中的 Agent Reliability Lab

图 4：以知识库问题和受控资料为输入，输出必须同时包含答案、来源、状态与运行证据。文章、代码检查点与 Git tag 保持一一对应。

第一个检查点为什么没有模型

0.1.0 先只实现四样东西：

Agent System Card
  + 5 条可执行任务
  + 确定性非 Agent 基线
  + JSON / Markdown 报告

当前基线不需要 API Key，使用 Python 标准库完成段落检索，并故意保留能力上限。它的作用是提供控制组，而不是假装成 Agent。

本地验证结果是：

contract: valid
tasks: 5
passed: 5
task_pass_rate: 100%
correct_abstention_rate: 100%
unknown case: qa-005 -> abstained
unit tests: 4 passed

这个 100% 只描述当前 5 条小型基线任务，不能外推为系统已经可靠。随着第 1、2 篇补充真实任务和失败样本，数字大概率会下降，而这正是建立评测的意义。

读者可以从同一仓库开始：

git clone --branch agent-engineering-series https://github.com/RalfNick/ai-agent-learn.git
cd ai-agent-learn/phase-7-agent-engineering/agent-reliability-lab

python run_lab.py check-contract
python run_lab.py baseline
python -m unittest discover -s tests -v

基础实验遵循这些原则：

1. 使用 Python 3.10+ 和确定性控制组，不把 API Key 设为入门条件。
2. 需要真实模型时增加可选 Provider Adapter，任务合同不随 Provider 改写。
3. 每篇只增加一个主要变量，避免同时替换模型、Prompt、工具和流程。
4. 每次运行保留结构化输入、输出、版本、评分和必要 Trace。
5. 成功案例与失败案例同等重要。
6. 已发布文章对应不可变 Git tag；开发中的下一篇留在普通分支。
7. 早期检查点必须可以独立运行，不能只留下最终状态的截图。

8. 十二篇文章怎样对应代码

仅有“配套仓库”还不够。读者需要知道读完一篇后究竟应该查看哪个版本、修改什么、运行哪条命令。

下面是系列的代码合同。Tag 名目前是发布计划，只有文章与实验同时通过审稿后才会创建，避免把半成品伪装成稳定版本。

对读者来说，推荐的跟做方式不是不断复制新目录，而是观察相邻检查点的真实差异：

git checkout ae-05-tools
python run_lab.py tool-eval

git diff ae-05-tools..ae-06-loop
git checkout ae-06-loop
python run_lab.py fault-test

这样一篇文章至少要同时交付四份证据：

概念解释
  + Git diff
  + 可运行命令
  + 失败与评测报告

如果文章解释得很顺，但对应版本无法检出、实验无法复现或结果没有进入报告，就不算完成。

9. 四条最短阅读路线

十二篇并不要求所有人从头读到尾。

路线 A：个人开发者，让编码 Agent 更稳定

1 任务契约
  -> 2 Evals
  -> 3 Context
  -> 4 Harness
  -> 6 Durable Loop
  -> 7 Tracing

这条路线先解决“为什么有时好用、有时不好用”。

路线 B：Agent 应用或平台开发者

1 任务契约
  -> 2 Evals
  -> 4 Harness
  -> 5 Tool
  -> 6 Durable Loop
  -> 7 Tracing
  -> 10 Security
  -> 11 Production Ops

这条路线重点是运行时、接口与生产可靠性。

路线 C：准备做多 Agent 或复杂编排

1 任务契约
  -> 2 Evals
  -> 6 Durable Loop
  -> 7 Tracing
  -> 9 Graph
  -> 10 Security
  -> 11 Production Ops

这条路线故意把 Graph 放得很晚。

路线 D：团队负责人或 Agent 治理

1 任务契约
  -> 2 Evals
  -> 7 Tracing
  -> 10 Human Control
  -> 11 Production Ops
  -> 12 Continuous Improvement

这条路线关注责任、证据、发布和改进闭环。

10. 这个系列明确不做什么

为了让范围保持清楚，有些热门方向不会直接进入主线：

• 不做十二个 Agent 框架的功能横评；
• 不把 Swarm、无限并发或 Agent Society 当作默认终点；
• 不用一次成功的录屏证明长期可靠；
• 不只比较模型排行榜；
• 不把 LLM-as-a-Judge 当作唯一验收；
• 不把自动改 Prompt 或 Harness 称为自然发生的自我进化；
• 不为了追赶新术语，打乱 Contract、Eval、Trace 与 Ops 的依赖顺序。

社区讨论和 X 适合发现新问题，但中心结论会尽量回到官方资料、论文、源代码和本地实验。

11. 现在就能做的 20 分钟体检

在正式开始第 1 篇前，可以先选一个你已经在使用的 Agent 工作流，填写这张最小卡片：

# Agent System Card 0.1

## Job
- 它替谁完成什么具体任务？
- 为什么需要 Agent，而不是脚本或固定工作流？

## Input
- 最小输入是什么？
- 哪些来源可以信任？

## Done
- 什么现实结果代表完成？
- 哪个命令、数据或人工判断可以验证？

## Boundaries
- 允许读取、修改和调用什么？
- 哪些动作必须人工批准？

## Failure
- 超时、预算耗尽或工具失败后怎样结束？
- 什么情况必须交给人？

## Evidence
- 当前是否有任务集、Trace、评分和版本记录？
- 改动后怎样证明比旧版本更好？

如果其中一半问题现在答不出来，不代表 Agent 不能工作。

它只说明下一步最值得投入的，可能不是换模型或加一个 Agent，而是先补上可验证的任务定义。

收藏清单

开始这个系列前，可以先确认：

• 我已经运行过至少一个真实 Agent 工作流。
• 我能指出它完成的现实任务，而不只描述模型输出。
• 我保留了至少一个成功样本和一个失败样本。
• 我愿意先建立基线，再优化 Context 或 Harness。
• 我不会在单 Loop 尚不可解释时急着升级多 Agent。
• 我会把权限、隐私和人工接管放进每一层设计。
• 我接受“删除不再承重的机制”也是 Harness Engineering。

结语

Agent 工程很容易被写成一条不断增加复杂度的路线：

更长的 Prompt
  -> 更多工具
  -> 更长上下文
  -> 更多 Agent
  -> 更复杂的 Graph

但我更想沿着另一条路线来写这个系列：

先定义成功
  -> 再测量行为
  -> 只增加必要能力
  -> 让失败可以恢复
  -> 让过程可以解释
  -> 让改进可以回滚

进阶不是让 Agent 看起来更像一个自主组织。

进阶是让它在面对不确定性时，仍然像一个可以被理解、验证和负责的工程系统。

参考资料

官方资料

• OpenAI：Harness Engineering
• OpenAI Agents SDK
• OpenAI Agents SDK：Tracing
• OpenAI Agents SDK：Human-in-the-loop
• OpenAI：Separating signal from noise in coding evaluations
• OpenAI：Building self-improving tax agents with Codex
• Anthropic：Effective context engineering for AI agents
• Anthropic：Writing effective tools for AI agents
• Anthropic：Demystifying evals for AI agents
• Anthropic：Harness design for long-running application development
• Anthropic：Scaling Managed Agents
• LangGraph：Persistence
• LangGraph：Interrupts
• OpenTelemetry：GenAI Semantic Conventions

开源实现

• openai/openai-agents-python
• langchain-ai/langgraph
• langfuse/langfuse
• Arize-ai/phoenix
• lastmile-ai/mcp-agent
• aiming-lab/AutoHarness