Agent Harness 入门教程

这门课要解决什么问题

很多人第一次做 Agent，都会从“调一次模型 API”开始：

const answer = await model.chat('帮我分析这份数据');

这在 demo 里没问题。真正的 Agent 任务通常是这样的：

分析近 30 天的风险事件，找出 Top 10 实体，给出证据引用，最后把结论通知负责人。

这个任务包含：

1. 多轮推理。
2. 多次工具调用。
3. 上下文增长。
4. 数据库查询。
5. 引用校验。
6. 通知动作。
7. 权限和人审。
8. 成本、耗时和审计。

把这些工程问题组织起来的运行时，就是 Agent Harness。

先记住几个概念

从一个真实任务开始

任务：

分析近 30 天的风险事件，输出 Top 10 实体和证据引用。

如果直接把所有数据塞给模型：

30 亿行事件
  -> 全部放入 prompt
  -> 上下文超限
  -> 成本失控
  -> 关键约束被稀释

这显然不可行。

正确做法是：

1. 建一个 session。
2. 组装 prompt，明确只输出 Top 10。
3. 模型决定调用查询工具。
4. 工具先查聚合表。
5. 返回 10 个实体和 evidenceWindowIds。
6. 结果写回上下文。
7. 模型继续分析。
8. 输出结构化 JSON。
9. validator 校验引用。
10. 如果需要通知负责人，生成 action proposal，再进入审批和执行。

这就是 Agent Harness 的核心循环。

完整执行链路

流程图加载中…

这条链路里，每一步都可能出错：

Agent Harness 工程师的工作，就是把这些风险逐层收口。

为什么不能只靠 Prompt

Prompt 可以告诉模型：

每个结论必须引用证据。

但模型仍可能：

1. 编一个不存在的 windowId。
2. 忽略“最多 10 个实体”。
3. 把“没查到”写成“没有风险”。
4. 输出一段自由文本，系统无法解析。

所以生产系统需要四层约束：

Prompt 是引导，不是安全边界。

为什么不能把所有数据给模型

上下文越长，成本越高，但质量不一定更好。

一个典型事故链：

工具返回 10 万行
  -> 上下文膨胀
  -> 关键约束被稀释
  -> 触发 compaction
  -> 摘要丢任务状态
  -> 模型重复查询

正确做法是给模型：

1. 结论。
2. 稳定引用。
3. 数据覆盖状态。
4. 未解决问题。

不是原始世界。

例如：

{
    "summary": {
        "topRiskEntityCount": 10
    },
    "refs": [
        {
            "entityId": "entity-9182",
            "evidenceWindowIds": ["win-1001"]
        }
    ]
}

工具结果有两条去向

一次 tool call 会产生两类结果：

这两条不能混。

如果把日志和原始 payload 也塞进上下文，会直接放大成本。如果把业务结果只写日志，模型又无法继续推理。

外部动作必须经过校验

模型可以建议“通知负责人”，但不能直接执行。

正确链路：

模型输出
  -> 结构化 proposal
  -> schema / 引用 / 权限校验
  -> 人审或自动策略
  -> Action Executor
  -> terminal result
  -> audit

这样即使模型输出错误，最多只会得到一个被拒绝的 proposal，而不是不可审计的外部副作用。

模块地图

后续文档按工程演进顺序展开。08 到 11 更贴近实际业务落地，12 和 13 是后置的工程收尾能力：

新人学习路径

第一步：能画出完整链路

过关标准：

能解释用户请求如何变成 run，模型如何调用工具，工具结果如何进入上下文，输出如何被校验，动作如何被审计。

第二步：能定位一次失败

你需要能回答：

1. 是模型慢，还是工具慢？
2. 是 prompt 模糊，还是 tool schema 不严？
3. 是上下文膨胀，还是压缩丢了状态？
4. 是引用伪造，还是 validator 没检查？
5. 是动作未幂等，还是取消没传播？

第三步：能加一个安全工具

一个新工具上线前，至少要确认：

1. 输入有 schema。
2. 输出有上限。
3. 错误有稳定 code。
4. 有 timeout。
5. 有权限策略。
6. 有观测事件。
7. 是否需要人审。

常见故障排查

上线前检查

1. run 有唯一 owner。
2. prompt 有版本。
3. 工具有 schema、预算和 timeout。
4. 上下文有裁剪和压缩策略。
5. 输出有 schema 和引用校验。
6. 外部动作有幂等和人审。
7. 有模型 usage 和 tool 观测。
8. 取消能传播到模型、工具和动作。
9. 代码执行有真实沙箱。
10. 失败可以通过 runId 还原。

一页总结

Agent Harness 的核心不是“多调几次模型”，而是控制复杂度：

一个任务，一个 run。
一个工具调用，一个预算。
一个结果，一次校验。
一个动作，一个审计。

先把这条主线跑通，再进入后续模块。