Agent Harness

主题

第十二章 可观测性、轨迹与评测运营 ​

生产环境中的 Agent 需要记录跨模型、工具、环境、授权策略和人协作的执行链。可观测性的目标是重建可审计的因果关系：系统看到了什么，依据哪项授权执行了什么，改变了哪些状态，又凭什么判断任务完成。提示词和最终回复不足以回答这些问题，模型私有思维也不必作为审计对象。

1. 轨迹是事件图 ​

以仓库任务 TASK2048 为教学例子：模型提出测试请求，授权策略作出决定，执行器返回测试日志，验证器把结果绑定到补丁版本。若其间发生委派或保存检查点，这些事件也要关联到同一次任务。模型轮次、工具请求、授权与审批、执行与观察、产物、检查点、委派、验证和外部提交因而构成基本事件类型。稳定 ID、依赖关系和产物引用把它们连起来；大型输出外置，轨迹保留摘要、哈希与定位符。

text
TraceEvent {
  run_id, span_id, parent_id, type, timestamp
  actor, model, tool, policy_version
  input_refs[], output_refs[]
  state_before, state_after
  cost, latency, status, error_class
}

并行工具、异步输入或多 Agent 协作都会使轨迹成为部分有序图，单 Agent 也不例外。可恢复任务应以检查点和副作用账本为依据。日志、审计与模型上下文要分别管理权限和保留规则：上下文可压缩，普通运维日志可采样，审计记录则需防篡改并保留关键关联。这是逻辑边界，不要求一律分库，物理隔离按风险与恢复需求决定。

2. 指标分四层 ​

业务层看任务价值、人工节省和错误损失；任务层看完成率、部分完成、升级率和稳定性；运行层看工具调用、重试、上下文、成本与关键路径时延；安全层看越权请求、审批、注入、数据流违规和恢复。这样分层后，问题不容易被平均值掩盖。

仅看平均成功率不够。要按任务族、风险、模型、Harness 版本、工具、仓库规模和上下文长度做分片，并同步观察 pass@k 与 pass^k。Anthropic Agent Evals 这两个指标的差异会暴露：一次最好成绩适合衡量探索能力，持续稳定表现才接近生产体验。

3. 失败分类先于优化 ​

失败至少可拆成任务规范、上下文选择、推理计划、工具选择、工具执行、环境、权限、验证器、协调、外部依赖和模型能力。如果把所有失败都记成 agent_failed，团队最终只能靠改提示词猜测，难以及时收敛。

归因应追到“最早可纠正事件”，而不是只盯最后一个报错。测试失败可能来自错误 patch，也可能来自依赖未安装；过早完成也可能因为完成契约缺失，而不一定是模型“没认真”。应允许多标签和置信度，并保留人工纠正记录。

4. Eval 是持续运营系统 ​

评测集要持续从生产事故、人工升级、低置信度轨迹、能力边界和安全红队样本补充。能力评测（capability eval）用于找出尚未掌握的任务，回归评测（regression eval）用于守住已掌握能力；高通过率的能力题应转成回归题。Anthropic Agent Evals

每个任务应保存输入快照、评分规则、环境摘要、可见性和退役原因，有参考解时一并登记。Harness 变更应与稳定基线重复比较，报告置信区间、成本和关键切片。

评测结果还要区分三个层次：契约与状态机检查，验证拒绝、取消和恢复等规则；行为评测，观察是否读取必要证据、调用验证器；业务终态评测，检查产物或目标环境是否满足验收。Google 2026-09-09 的工程文强调行为与端到端评测互补，并提醒复杂任务可能有多条正确路径，不应锁死工具序列。行为评测实践 调用了测试工具，只能证明发生过调用，仍须核对测试针对的是哪个版本。

组件对照也能辅助归因。一项 2026-09-17 的研究固定执行循环，改变规划、动作接口和上下文管理，发现收益随模型和窗口预算变化；其四个模型与限定消融设置不足以证明某种工具或规划方案普遍最优。Harness 组件实证研究 v1 这是作者报告的实验，不能当作本书已复现结果。

5. 在线监控与离线评测闭环 ​

text
production traces
  → privacy filtering
  → failure clustering
  → curated eval candidates
  → independent labeling
  → regression/capability suites
  → candidate harness evaluation
  → canary → production

线上反馈不应未经校验就自动写回提示词或记忆，否则攻击样本和偶发偏好会被固化。采集、筛选、标注与发布应有各自责任。用户满意度也不是唯一奖励信号：Agent 可能通过迎合、隐藏风险或省去必要确认抬高短期评分。

6. Trace replay 的边界 ​

模型调用与外部世界并不总能完整重放。可靠的回放（replay）要固定输入、模型快照、采样参数、工具版本和环境镜像；对不可重放 API，需要使用录制响应或模拟器。replay 的目标是定位差异，而不是装作绝对复现。

隐私和安全同样关键。轨迹里可能有源码、个人身份信息（PII）、token 和模型生成的恶意内容。进入分析平台前要先做分类、脱敏、租户隔离和最小保留；研究者访问 held-out 与生产数据必须经过审计。

7. 运营仪表盘 ​

一个可用的运营仪表盘应能回答：哪类任务失败最多；失败从哪个层开始；哪个版本引入退化；自动完成是否真的降低了人工总成本；成本上升来自模型、上下文还是重试；哪些权限请求最常被拒；哪些 verifier 最不稳定。

最终，可观测性服务的不是“好看”的 trace UI，而是事故恢复、工程归因和受控进化这三个闭环。没有可用轨迹，Harness 只能靠 anecdote 演进；没有独立 eval，轨迹优化又容易变成对历史样本过拟合。

8. 一条工具完成事件的示例 ​

事件结构应支持大型输出外置、敏感字段分级和供应商原始数据的独立引用。以下是教学示意，ID 与哈希已简化，不是本书实跑记录；它只表示可观察结果。

json
{
  "event_id": "evt_01J8Z7",
  "run_id": "run_TASK2048_A3",
  "span_id": "tool_017",
  "parent_span_id": "turn_006",
  "type": "tool.completed",
  "timestamp": "2026-08-27T09:31:14.223Z",
  "actor": "runtime:codex",
  "tool": {"canonical": "repo.test", "provider": "exec_command", "version": "4"},
  "policy_decision": "pd_8821",
  "input": {"ref": "artifact:sha256:11ad...", "classification": "internal"},
  "output": {"ref": "artifact:sha256:90bf...", "exit_code": 1},
  "state": {"workspace_before": "git:8f31b6e", "workspace_after": "git:dirty:4e19..."},
  "latency_ms": 18241,
  "cost": {"compute_usd": 0.012},
  "status": "error",
  "error_class": "TEST_FAILURE",
  "vendor_payload_ref": "secure-artifact:sha256:772e..."
}

event_id 支持去重，父事件用于导航，工作区哈希关联被检查的版本。policy_decision 只是查找授权决定的键；要核验执行是否遵循该决定，还需受保护的记录绑定动作参数、执行身份、资源版本、策略版本与结果。原始输出可能包含源码或密钥，应限制访问；普通运营角色只看到必要摘要和定位符。

9. Trace 完整性与采样 ​

高流量平台往往想采样，但 effect、policy、approval、checkpoint、verification、commit 这类事件不能像普通调试日志那样随机丢弃。应按重要性分层：审计骨架全量保留；大输出只保留 hash，并按风险控制原文留存；性能 span 可以按任务量和异常率自适应采样。

对固定观察窗口内已终止的运行，可报告 具备全部必需事件及有效产物引用的运行数 / 已终止运行数，但必须另行对账期初未闭合与本期新建运行，列出仍在进行、超时未闭合和已终止的数量。否则崩溃后没有终止事件的任务会从分母消失，虚高完整率。还应统计孤立事件、重复事件、引用不可读和依赖异常；按保留规则合法删除的产物要留退役记录，并区分“保留期内证据完整”与“原文仍可重放”。

例如只保留成功运行的完整日志，就会系统性删去最需要定位的失败轨迹。应在合法保留期内保留失败、安全告警、人工接管和未知错误的关键证据；普通成功任务的调试细节再按任务族抽样，同时执行数据最小化。关键事件全量保留不等于永久保存所有原始内容。

10. Eval 生命周期与污染控制 ​

生产问题进入评测前，要经过候选、复现、清洗、标注和负责人审批。开发集用于调试；验证集用于比较并选择候选模型、Harness 或配置，不能按候选表现临时挑选试题；密封测试集只在预定时机进行独立终测；已频繁暴露或饱和的任务转入回归集或退役。各集合应分别管理用途、访问权限和版本，并不要求不同物理目录。

保留集（held-out）是未直接用于生成或训练的宽泛称呼，其中用于选择候选或修复诊断的部分承担验证集职责，不等于密封终测。密封集由独立服务按事先确定的访问次数、反馈粒度与停止规则使用，标签和隐藏检查不向候选开放。即使只返回通过与失败，多轮自适应反馈也会泄漏信息；一旦用于修复，就应记录暴露并重新界定用途，不能继续宣称它是未接触的独立终测。

11. 从指标到行动 ​

每个告警都要绑定责任人和处置流程。未知工具错误突增时，先限制相关运行配置，排查服务故障、接口结构和版本，再决定是否回退；错误完成率上升时，先查完成契约与验证器；成本上升则分别检查模型请求、上下文、工具重试和人工等待。

如果仪表盘只能显示红色曲线，但跳不过去看代表性 trace、版本差异和受影响任务，它就不算运营系统。反过来，trace UI 若只能看到每个 token，却回答不了“哪个版本引发生产错误”，它也只是调试看板的玩具。

12. 可观测性的边界 ​

更完整的日志不代表更安全。源码、客户数据、工具输出和 prompt injection 内容会在 trace 平台变成高价值资产。默认采集字段白名单、用途限制、租户隔离、保留期和删除流程要与可观测性体系同时设计。高敏任务可只保存结构化 outcome，并保留加密原文引用，由受控流程临时解密。

可观测性最终服务于责任：谁在什么版本、什么授权和什么环境下做了什么，系统如何知道结果正确，失败后如何恢复。它不应被用来推断或展示模型不可验证的内部心理状态。

公开阅读版本

Copyright © 2026 Lenshood