AI Agent 运行时必须"看得见"，可观测性要内置而非外挂

首先，明确术语

在深入主题之前，先介绍三个读者必须掌握的关键术语：

Observability（可观测性）：通过系统外部输出的信号来理解其内部状态的能力

Sprint Contract（冲刺契约）：编码前达成的简短协议，明确工作范围、验收标准和排除事项

Evaluator Rubric（评估量表）：将"好不好"从主观感觉转化为可量化证据的评分表

打个比方：observability 就是 agent 系统的"监控摄像头"，没有摄像头，出了问题你只能瞎猜是什么时候坏的。

问题：agent 运行了 20 分钟，却答不出"发生了什么"

你让 agent 开发一个功能，它跑了 20 分钟，改了一堆文件，然后说"完成了，但有两个测试挂了"。你问为什么，它说"不确定，可能是 timing 问题"。你问它改了哪些关键路径，它说"让我看看代码……"

这不是 agent 能力的问题，而是 harness 缺乏 observability。当 agent 在无法看到真实运行时状态的情况下工作，它的每一个决策都是在猜。

没有 observability 的真实代价（四个方面）

1. 无法区分"正确"与"看起来正确"

函数在 code review 中看起来正确，语法没问题，逻辑也合理，但运行时边界条件在特定输入下给出错误结果。

code review 展示的是"写了什么"，runtime tracing 展示的是"实际跑的是什么"，两者你都需要。

2. 评估沦为"玄学"

没有评分标准和验收条件，评估者（人或 agent）只能依赖主观假设。同一份输出，不同评估者给分可能天差地别，质量变成了不可复现的东西 [1]。

3. 重试沦为"随机猜测"

当 agent 不知道自己为什么会失败，重试方向就是随机的。它可能往错误方向猛攻，改了不相关的代码，忽略了真正的根因——每一次随机重试都在燃烧 token 和时间。

4. 交接悬崖

当任务卡住被交接给下一个 session，没有 observability 意味着新 session 必须从零诊断系统状态。Anthropic 观察到，这种冗余诊断占用了整个 session 30-50% 的时间 [1]。

真实案例：dark mode 耗时 3 倍

Harness 使用"planner-generator-evaluator"工作流执行"为应用添加 dark mode"任务：

无 observability：planner 写出模糊的描述，generator 按模糊的描述执行，但结果不符合模糊的预期，evaluator 按自己模糊的标准 reject，只说"感觉不对"，说不出哪里不对，generator 拿着模糊的 reject 理由随机重试，循环 3-4 轮 45 分钟，得到一个勉强能用的结果。

有完整 observability：planner 写出 sprint contract，明确要修改的组件、每个组件的验收标准，以及排除项（例如不处理 print styles）。generator 按 contract 执行，runtime observability 记录每个组件的样式加载情况，evaluator 逐维度评分并附上具体证据："button 对比度不足（WCAG AA 要求 4.5:1，实测 2.1:1）"。一轮 15 分钟得到高质量结果。

差 3 倍，唯一的变量就是 observability。

Observability 有两层（两者缺一不可）

根据 Charity Majors 的《Observability Engineering》框架 [2]：

Runtime Observability，"系统做了什么"

系统级信号：logs、traces、process events、health checks，回答"系统做了什么"。

Process Observability，"为什么接受这个变更"

可见 harness 的决策 artifact：plans、scoring rubrics、acceptance criteria，回答"为什么这个变更应该被接受"。

为什么 agent 自己做不到（光靠 print log 不够）

你可能觉得"让 agent 自己 print log 不就行了"，但问题在于：

Agent 不知道自己不知道什么，它不会记录自己没意识到需要记录的那些信号。

Log 格式不一致，不同 session 用不同格式，无法系统性分析。

Process observability 靠 logging 解决不了，sprint contract 和 rubric 是结构化 artifact，需要 harness 提供支持。

如何构建 observability（四种方法）

1. 将 runtime signal 收入 harness（不依赖 agent 自己 print）

• 应用生命周期：startup、ready、running、shutdown
• 功能路径执行：关键路径的 entry、checkpoint、exit
• 数据流：组件间数据如何流动
• 资源利用：异常资源使用（内存持续增长）
• 错误：完整 context，不只是 error message

2. 使用 Sprint Contract

generator 和 evaluator 开始工作前先达成契约：

# Sprint Contract: Dark Mode Support

## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests

## Verification Standards
- Visual regression tests pass for each component
- Main flow end-to-end tests pass
- No flash of unstyled content (FOUC)

## Exclusions
- Not handling print styles
- Not handling third-party component dark mode

3. 使用 Evaluator Rubric

将"好不好"转化为可衡量分数：

4. 使用 OpenTelemetry 作为标准

为每个 harness session 创建 trace，每个 task 创建 span，每个验证步骤创建 sub-span，observability 数据可以立即接入标准 toolchain（Jaeger、Zipkin）[3]。

真实数据：Anthropic 的三 Agent 架构

2026 年 3 月，Anthropic 用三个职责分离的 agent 执行了"构建基于浏览器的 DAW"任务：

每个 agent 在 observability 中都有明确角色 [1]：Planner 将需求扩展为 spec，Generator 按 sprint contract 逐个功能实现，Evaluator 使用 Playwright MCP 像真实用户一样点击测试，从四个维度评分（product depth、functionality、visual design、code quality）并配有硬性阈值。

第一轮 QA 反馈示例："这是一个漂亮且 AI 集成良好的应用，但多个核心 DAW 功能只是 presentation 层面：clips 无法拖拽、没有 instrument UI panel、没有 visual effects editor"——这不是 edge case，而是让 DAW 可用的关键交互。

我认为这是 harness engineering 的命脉：看不见就修不了，修不了就只能猜，猜就会坏。

因为数据很清楚：没有 observability → 无法区分正确与看起来正确 → 评估沦为玄学 → 重试变成随机猜测 → 30-50% 的 session 时间被冗余诊断消耗。

如果你只能做两件事：把 runtime signal 收入 harness + 使用 sprint contract，你的 agent 就会从"看不见"的工作模式切换到"有证据"的工作模式。

现在你的 agent 多频繁以"看不见"的方式工作？你在 harness 中有 observability（trace、log、health check）了吗？可以在评论区分享。

[1] Anthropic. "Harness design for long-running application development". 2026. https://www.anthropic.com/engineering/harness-design-long-running-apps

[2] Majors et al. "Observability Engineering". 2022. https://www.honeycomb.io/blog/observability-engineering-book

[3] Learn Harness Engineering, Lecture 11. 2026. https://github.com/walkinglabs/learn-harness-engineering

本文分析素材来自 Anthropic、Honeycomb 和 walkinglabs/learn-harness-engineering，数据截至 2026 年 8 月 23 日。Nokka