---
tags: [AI, harness, agent-loop]
阶段: 08-Agent与工程化
难度: ★★★
created: 2026-10-18
related: "[[MCP协议]], [[AI-Agent与工具调用]], [[Agent工作流与编排]]"
---

# Harness与Loop工程

## 定义

**Harness**（运行时外壳）指包裹模型调用、把一次前向调用扩展为可终止的多步任务执行过程的程序，它负责上下文装配、工具调用与执行、循环控制、错误恢复、预算约束与轨迹记录。

形式化地，一个 Harness 是七元组

$$
\mathcal{H}=(\pi,\ \mathcal{T},\ \mathcal{C},\ \mathcal{E},\ \mathcal{R},\ \mathcal{B},\ \mathcal{O}),
$$

其状态转移为

$$
s_{t+1}=F\big(s_t,\ a_t,\ o_t\big),\qquad
a_t\sim\pi\big(\cdot\mid\mathcal{C}(s_t)\big),\qquad
o_t=\mathcal{E}(a_t),
$$

其中各符号含义如下。

| 符号 | 含义 |
|---|---|
| $t$ | 步序号，从 1 开始，一步指一次模型调用及其后续工具执行 |
| $s_t=(x,h_t,b_t)$ | 第 $t$ 步开始时的状态：任务 $x$、消息历史 $h_t$、剩余预算 $b_t$ |
| $a_t$ | 第 $t$ 步的动作，取终止动作或一个工具调用集合 |
| $o_t$ | 工具执行返回的观测，可能包含文本、结构化数据或错误 |
| $\pi$ | 模型策略，包含模型标识、采样参数与提示模板 |
| $\mathcal{T}$ | 工具注册表，保存名称、模式、执行函数与幂等标记 |
| $\mathcal{C}$ | 上下文装配器，把状态映射为一次模型请求的消息序列 |
| $\mathcal{E}$ | 工具执行器，负责并发、超时、重试与结果归一化 |
| $\mathcal{R}$ | 恢复策略，按错误类别决定重试、回填、降级或终止 |
| $\mathcal{B}$ | 预算，包含最大步数 $K$、token 上限、成本上限与墙钟上限 |
| $\mathcal{O}$ | 观测器，把每步写成不可变的轨迹记录 |
| $F$ | 状态转移函数，把动作与观测并入历史并扣减预算 |

术语按首次出现处定义：**步**（step）是一次模型调用加上随之发生的工具执行；**轮**（turn）是用户与系统之间的一次交互，一轮可以包含多步；**轨迹**（trace）是按时间排列的全部请求、响应、工具调用与结果的集合；**span** 是轨迹中带开始时间、结束时间与属性的一个区段，通常对应一次模型调用或一次工具执行；**压缩**（compaction）指在预算内用摘要或截断替换原始历史；**幂等键**（idempotency key）是调用方生成的、用于在重试时识别同一操作的标识；**检查点**（checkpoint）是可恢复的完整状态快照。

## 为什么重要

模型能力是给定常量，实际可达能力由 Harness 决定。同一模型在两种运行时下的任务成功率差异，通常来自四个可定位的环节：上下文装配是否让模型看到完成任务所需的信息；工具错误是否被回填而不是被吞掉；终止条件是否既允许完成任务又阻止无效循环；轨迹是否足以把失败归因到具体一步。这四个环节都不改变模型权重，却直接改变结果分布。

成本随步数呈二次增长。设系统提示与工具模式合计 $P$ 个 token，每步新增的工具结果平均 $\delta$ 个 token，历史不做压缩时，第 $t$ 步的输入长度为 $P+t\delta$，$n$ 步累计输入为

$$
\sum_{t=0}^{n-1}(P+t\delta)=nP+\delta\frac{n(n-1)}{2}.
$$

取 $P=3000$、$\delta=400$、$n=12$，累计输入为 $12\times3000+400\times66=62400$ 个 token，而按"每步 3000"的粗略估计只有 36000。差额来自历史重发，它不产生任何新信息。若把每步输入压到 $P+3\delta=4200$，累计为 50400，节省约 19%，但压缩本身需要额外调用，压缩频率决定净收益，步数越多、单步结果越长，压缩越划算。

没有轨迹就无法归因。一个失败任务可能因为初始上下文缺少文件内容、工具返回了权限错误、模型选择了错误工具、循环在错误的方向上重复，或终止条件提前触发。只看最终答案，这五种原因不可区分；有轨迹时，每一种都对应可检查的字段。

Harness 在本库中的位置是运行时层。[[MCP协议]] 定义了能力如何被发现与调用，本篇定义这些能力如何被调度、约束与记录；[[AI-Agent与工具调用]] 给出单次调用的模式与回填格式，本篇把单次调用扩展为多步循环；[[Agent工作流与编排]] 讨论任务在多个 Agent 之间的分配，本篇讨论单个 Agent 内部的执行机制。对应学习目标中的"能复现"与"会评估"：能实现一个带预算与轨迹的循环，能用轨迹与指标判断一次改动是否有效。

## 原理与推导

### 1 一次循环的完整时序

一步由九个阶段组成，顺序固定，任一步失败都要走恢复分支。

1. 装配上下文：从状态 $s_t$ 生成消息序列，包含系统提示、工具模式、历史与当前任务；同时计算输入长度，若超过预算先触发压缩。
2. 调用模型：按 $\pi$ 的采样参数发起请求，设置请求级超时；模型调用本身也可能失败，需要独立的错误分类。
3. 解析输出：把响应解析为动作。终止动作是纯文本；工具动作包含工具名与参数对象。解析失败按永久错误处理。
4. 策略检查：校验工具是否在白名单、参数是否符合模式、是否需要用户审批、剩余预算是否足够。
5. 执行工具：一个动作可以包含多个调用。无依赖的调用并发执行，有依赖的串行执行；每个调用有独立超时。
6. 归一化结果：把结果转换为文本或结构化内容，限制长度，标注错误类别与是否可重试。
7. 回填与记录：把工具结果追加为消息，把模型请求、工具调用、结果与耗时写入轨迹。
8. 终止判断：按终止谓词决定继续或结束；结束时写入状态与原因。
9. 持久化：刷新轨迹，必要时写检查点，供恢复或评测使用。

终止谓词可以写成

$$
\mathrm{stop}_t=\mathbf{1}[a_t\in\mathcal{A}_{\mathrm{final}}]\ \lor\ \mathbf{1}[t\ge K]\ \lor\ \mathbf{1}[b_t\le 0]\ \lor\ \mathbf{1}[e_t\in\mathcal{E}_{\mathrm{fatal}}],
$$

其中 $\mathbf{1}[\cdot]$ 是示性函数，条件成立取 1，否则取 0；$\mathcal{A}_{\mathrm{final}}$ 是终止动作集合，$K$ 是最大步数，$b_t$ 是剩余预算，$\mathcal{E}_{\mathrm{fatal}}$ 是不可恢复错误集合。四个条件都必须实现：只有模型终止会让循环失去上界；只有步数上限会让预算与成本失控；缺少不可恢复错误判断会让运行时在明确失败后继续消耗。

```text
state ← (task, [system, user], budget)
for step in 1..K:
    view ← assemble(state)                  # 装配与压缩
    response ← model(view)                  # 可能超时或失败
    action ← parse(response)                # 解析失败 → 终止
    if action is final: return answer
    if not policy_ok(action):               # 权限/预算
        state ← state ⊕ rejection
        continue
    results ← execute(action.calls)         # 并发 + 超时 + 重试
    state ← state ⊕ results
    if fatal(results): break
    if budget_exhausted(state): break
return partial_or_failure
```

伪代码中 $\oplus$ 表示把新消息追加到历史，$K$ 为最大步数。

### 2 上下文管理

上下文预算按下式分解：

$$
B_{\mathrm{ctx}}=B_{\mathrm{sys}}+B_{\mathrm{tools}}+B_{\mathrm{hist}}+B_{\mathrm{out}}\le B_{\max},
$$

其中 $B_{\mathrm{sys}}$ 是系统提示，$B_{\mathrm{tools}}$ 是工具模式，$B_{\mathrm{hist}}$ 是历史，$B_{\mathrm{out}}$ 是为输出预留的空间。四项共享一个上限，任何一项增长都会挤压其余三项。常见错误是只为历史设上限，忽略了工具模式在工具较多时可以达到数千 token。

压缩有四类手段，性质不同。

| 手段 | 做法 | 丢失的信息 | 适用 |
|---|---|---|---|
| 工具结果截断 | 保留头部与尾部，中间标注省略字符数 | 中段细节 | 日志、文件、长列表 |
| 历史摘要 | 用模型或规则把旧步骤压缩为要点 | 具体参数与原文 | 步数多的长任务 |
| 丢弃最旧消息 | 保留系统提示与最近 $k$ 条 | 早期约束与失败原因 | 预算极紧的短任务 |
| 结构化替换 | 把大对象替换为标识、行数、字段名 | 内容本身，可按需重取 | 可重新读取的资源 |

截断必须保留错误信息。把失败的工具结果截成空字符串，模型会认为调用成功并继续基于错误前提推理；正确做法是保留错误码与原因，只在长度上压缩。

系统提示的稳定性影响前缀缓存。多数推理服务对完全一致的前缀命中缓存，命中部分的输入按折扣计价，延迟也更低。若系统提示中写入当前时间、随机排序的工具列表或每次变化的任务摘要，前缀每次不同，缓存永不命中。工程上的做法是把系统提示与工具模式固定在消息序列最前部，把时间、检索结果等动态内容放在用户消息或工具结果中。

压缩要按水位触发而不是按溢出触发。设预算利用率为 $\rho_t=B_{\mathrm{used}}/B_{\max}$，在 $\rho_t$ 超过阈值 $\rho^{\ast}$ 时压缩，可以避免在超限后被迫丢弃关键信息。阈值过高会在长工具结果到达时直接超限，过低会频繁压缩并引入额外调用。

### 3 工具执行层

工具执行层是 Harness 与外部世界的唯一接触面，需要处理五件事。

并发。同一动作中的多个调用若无数据依赖，应并发执行，总延迟由最慢的调用决定而不是求和。并发需要上限，否则一个动作生成二十个调用会打满下游。结果按调用标识匹配，与完成顺序无关；部分失败不影响其他调用的结果回填。

超时。每个调用有独立截止时间，且应传递到下游请求。超时后执行器必须放弃等待并释放资源，不能无限阻塞整个循环。超时属于瞬时错误，但对非幂等操作重试会产生重复副作用，因此超时处理与幂等性绑定。

重试。只对瞬时错误重试，采用指数退避加随机抖动，重试次数上限通常为 2 至 3 次。重试的判断依据是错误类别而不是异常类型名；把连接重置与参数错误都归为异常并统一重试，会让永久错误消耗三次预算并延迟失败。

幂等。幂等键由调用方生成，通常取工具名、规范化参数与任务标识的哈希；服务端维护去重表，相同键的重复请求返回首次结果。没有幂等键时，超时重试可能造成重复下单、重复发信、重复扣款。只读工具天然幂等，写操作必须显式声明并实现去重。

沙箱。工具执行应限制文件系统范围、网络出口与资源用量。stdio 形式的 MCP Server 以宿主用户权限运行，安装即授权，因此更需要在容器或受限账户中执行，并清理环境变量中的密钥。沙箱限制的是副作用范围，不能替代权限检查。

结果归一化同样属于执行层。模型只接受文本或结构化内容，执行器应把异常转换为带类别与建议的结构化错误，把超大结果截断，把二进制内容转成引用而不是内联 base64。

### 4 错误分类与恢复

错误分类决定恢复动作，分类维度是"是否可重试"与"是否可由模型修正"。

| 类别 | 判定依据 | 典型例子 | 恢复动作 |
|---|---|---|---|
| 瞬时 | 可重试且操作幂等 | 429、503、连接重置、超时 | 退避重试，上限 2 至 3 次 |
| 永久 | 参数或状态错误 | 400、模式校验失败、文件不存在 | 回填原因，允许模型修正一次 |
| 语义 | 调用成功但结果不可用 | 检索为空、结果相互矛盾 | 换参数、换工具或降级 |
| 策略 | 权限或审批拒绝 | 越权、用户拒绝 | 终止该分支并上报 |
| 上下文 | 超出预算或压缩失败 | 输入超限、摘要失败 | 压缩、拆分任务、换小模型 |
| 内部 | 运行时缺陷 | 未捕获异常、状态不一致 | 终止并保留轨迹 |

恢复策略按成本排序：重试、修正参数、降级、分解任务、人工介入、放弃。重试成本最低但只对瞬时错误有效；修正参数需要把错误原因回填给模型，并限制修正次数，否则模型会在同一错误上反复尝试；降级指换用更简单的工具或更小的模型；分解任务指把失败步骤拆成更小的子任务；人工介入成本最高，适用于不可逆操作。

连续失败需要熔断。设同一工具连续失败次数为 $c$，当 $c\ge 3$ 时应在本轮禁用该工具，并把禁用原因写入上下文；否则模型会持续重试同一个不可用工具，消耗预算且不产生进展。同一动作重复出现也应触发终止：对动作的工具名与规范化参数取哈希，若相同哈希连续出现两次，说明状态没有实质变化。

### 5 可观测性

轨迹的基本单位是 span。一次任务对应根 span，每一步对应一个子 span，每个子 span 下包含模型调用 span 与工具执行 span。span 的字段至少包括标识、父标识、名称、开始时间、结束时间、状态与属性。

```json
{
  "trace_id": "t-20261018-0007",
  "task": "计算 128*3，并查询 MCP 的协议版本号。",
  "model": "example-model-2026-09",
  "status": "ok",
  "steps": [
    {"index": 1, "span": "step",
     "llm": {"input_tokens": 210, "output_tokens": 38, "duration_ms": 640},
     "tool": [{"name": "calc", "arguments": {"a": 128, "b": 3},
               "ok": true, "attempts": 2, "duration_ms": 12}]},
    {"index": 2, "span": "step",
     "llm": {"input_tokens": 260, "output_tokens": 41, "duration_ms": 590},
     "tool": [{"name": "lookup", "arguments": {"key": "mcp_protocol_version"},
               "ok": true, "attempts": 1, "duration_ms": 3}]},
    {"index": 3, "span": "step",
     "llm": {"input_tokens": 305, "output_tokens": 52, "duration_ms": 720}}
  ],
  "total_tokens": 906,
  "cost_usd": 0.0042
}
```

成本按调用累计：

$$
\mathrm{cost}=\sum_{t=0}^{n-1}\left(n^{\mathrm{in}}_t p_{\mathrm{in}}+n^{\mathrm{out}}_t p_{\mathrm{out}}\right),
$$

其中 $n^{\mathrm{in}}_t$ 与 $n^{\mathrm{out}}_t$ 是第 $t$ 次调用的输入与输出 token 数，$p_{\mathrm{in}}$ 与 $p_{\mathrm{out}}$ 是单价。命中缓存的前缀通常单独计价，必须按缓存读写两类 token 分别累计，否则成本会被高估或低估。

需要长期跟踪的指标包括：任务成功率、平均步数与步数分布、工具调用次数、工具错误率、重试率、压缩触发次数、P50 与 P95 延迟、单任务 token 与成本。指标要能按任务类型、模型版本与工具集分组，否则一次模型升级带来的变化会与任务分布变化混在一起。

### 6 确定性与重放

即使温度设为 0，输出也不保证逐位一致。原因有四个：浮点归约顺序、批处理组成、服务端模型版本更新、工具依赖的外部状态。温度 0 只消除随机采样，不消除并行归约的浮点非结合性，也不消除批处理中不同序列长度导致的数值差异。

工程上可控的部分是记录。要复现一次运行，至少需要记录：完整的模型请求，包含系统提示、工具模式、消息序列与采样参数；模型的完整响应，包含工具调用与终止原因；每次工具调用的参数、结果与耗时；运行环境，包含代码版本、模型版本标识与关键配置。只记录最终答案无法复现任何中间决策。

重放分三级，能回答的问题不同。

| 级别 | 记录内容 | 能回答的问题 |
|---|---|---|
| 事件重放 | 完整请求与响应 | 模型当时看到了什么，输出了什么 |
| 决策重放 | 动作序列与参数 | 为什么走这一步，是否换过工具 |
| 全量重放 | 环境快照与外部状态 | 失败能否复现，是否为环境差异 |

评测使用固定任务集与固定工具替身，把外部状态隔离，否则同一任务两次运行的差异无法归因到模型或 Harness。真实运行中需要随机性时，记录随机种子与每次采样的实际输出，用记录值替代重新采样。

### 7 人在环路

审批点是 Harness 的显式阶段，不是界面事件。需要审批的调用应满足至少一个条件：具有破坏性、涉及不可逆的外部副作用、访问超出当前任务授权范围的数据、成本超过阈值。审批界面必须展示工具名、完整参数与预期副作用；只展示工具名会让用户无法判断参数是否越界。

批准结果应绑定到具体调用。批准记录包含工具名、参数哈希与过期时间，参数变化后批准失效；会话级批准只对只读工具适用。审批超时的默认行为是拒绝，而不是自动通过。

中断与恢复需要区分三种语义。停止指不再发起新的模型调用与工具调用，已发出的调用按超时处理；取消指对执行中的调用发送取消信号，已产生的副作用不可撤销；恢复指从检查点继续，必须处理外部状态在中断期间发生的变化，例如目标文件已被修改、订单已被处理。恢复时用幂等键与版本号判断操作是否已生效。

人工响应时间计入预算。若任务有端到端时限，审批等待会挤占模型与工具的时间；异步审批与超时拒绝是必要的，否则一个无人值守的任务会停在审批阶段直到进程被回收。

### 8 终止条件与最大步数

终止条件分五类：成功完成、步数耗尽、预算耗尽、不可恢复错误、用户中止。每类都应产生不同的状态码与不同的后续动作：成功返回答案；步数或预算耗尽返回部分结果与未完成原因；不可恢复错误返回错误类别与轨迹标识；用户中止返回已完成的子目标。

最大步数 $K$ 由任务分布决定，而不是凭经验取整数。取历史轨迹中成功任务的步数分布，令 $K$ 略高于 $P_{95}$，可以覆盖绝大多数成功路径，同时限制尾部成本。$K$ 过小会把本可完成的任务截断，表现为"差一步就成功"；$K$ 过大只会增加失败任务的成本，因为成功任务在完成时已经终止。

最大步数不能替代循环检测。模型可能在两步之间来回切换工具，步数在增加而状态不变。检测方法是对每步的动作集合取规范化哈希，统计连续重复次数；连续两次相同则终止，或强制要求模型给出不同的计划。另一种检测是状态哈希：把历史的消息摘要与工具结果摘要合并取哈希，若哈希重复则说明状态没有推进。

终止时返回部分结果优于返回空。部分结果应包含已完成的子目标、已获得的中间数据与未完成的原因，这些信息对人工接管与后续重试都有价值。

### 9 评测

评测要区分能力与工程两个维度。能力维度看任务是否完成，工程维度看完成它的代价与稳定性。

| 指标 | 定义 | 用途 |
|---|---|---|
| 成功率 | 成功任务数除以任务总数 | 总体能力 |
| pass$^k$ | 同一任务 $k$ 次运行全部成功的比例 | 稳定性 |
| 平均步数 | 成功任务的平均步数 | 效率 |
| 工具错误率 | 失败工具调用数除以总调用数 | 集成质量 |
| 重试率 | 发生重试的调用比例 | 瞬时错误占比 |
| 单任务成本 | 总成本除以任务数 | 经济性 |
| P95 延迟 | 延迟分布的 95 分位 | 用户体验 |

pass$^k$ 的定义为

$$
\mathrm{pass}^k=\frac{1}{N}\sum_{i=1}^{N}\prod_{j=1}^{k}\mathbf{1}\left[\text{任务 }i\text{ 第 }j\text{ 次运行成功}\right],
$$

它衡量稳定性而非平均能力。成功率相同的两个系统，pass$^3$ 可能相差很大；pass$^3$ 较低说明失败集中在少数任务上，且这些失败可以重复触发。

评测报告应给出均值与置信区间。任务数较少时，用 bootstrap 重采样估计区间，避免把一两个任务的差异解释为改进。消融实验一次只改一个因素：去掉压缩、去掉重试、去掉审批、换模型版本，分别报告成功率、步数与成本的变化。指标之间通常存在权衡，例如更强的重试会提高成功率也提高成本，报告必须同时给出两者。

### 10 与把全部逻辑塞进一个提示词的对比

单提示词方案把任务说明、工具描述、输出格式与失败处理全部写入一段文本，模型一次生成完整结果。它在单步任务上成本低、延迟低、实现简单，但在多步任务上缺少四个核心机制：按预算装配的上下文、独立的错误通道、可检验的终止谓词、可回放的轨迹。

| 维度 | 单提示词 | Harness |
|---|---|---|
| 上下文 | 一次性写入全部材料 | 每步按预算装配与压缩 |
| 工具 | 说明文字内嵌，模型输出文本 | 结构化模式，运行时执行与校验 |
| 错误 | 无独立通道，模型自行解释 | 分类、重试、回填与熔断 |
| 终止 | 依赖模型自行停止 | 终止谓词、步数上限与预算 |
| 可观测 | 只有最终输出 | 轨迹、span、token 与成本 |
| 修改 | 改提示词，影响全局 | 改配置或代码，作用域明确 |
| 单位成本 | 一次较大的请求 | 多轮较小的请求 |
| 适用 | 单步转换、无副作用、输入固定 | 多步、有工具、需要审计与恢复 |

选择依据是任务是否需要外部状态。若答案完全由输入文本决定，单提示词更经济；若答案依赖运行时才能获得的数据，或需要执行有副作用的操作，就必须有执行层与循环。混合方案同样成立：先用一次调用判断任务类型，只有需要多步执行的任务才进入 Harness，这可以避免为简单请求支付多轮成本。

Harness 的固定成本必须被任务复杂度抵消。多轮调用意味着重复发送系统提示与工具模式，也意味着更高的尾延迟；当任务平均只需一步时，Harness 的收益为负。判断标准是：成功率的提升是否足以覆盖 token 成本与延迟的增加，这需要第 9 节的指标而不是主观判断。

## 关键直觉

> [!tip] 机制性表述
> Harness 的最小职责是把一次模型前向变成一条可持久化的 $(\text{state},\text{action},\text{observation})$ 记录，并在这条记录序列上定义终止、预算与恢复。模型只负责在给定上下文下选择动作，其余全部由运行时承担；因此运行时的正确性可以用状态机性质检验，而不必依赖模型行为。
>
> 与定义的关系：七元组中的 $\mathcal{C}$ 决定模型看到什么，$\mathcal{E}$ 决定动作如何作用于外部世界，$\mathcal{B}$ 与终止谓词决定过程何时停止，$\mathcal{O}$ 使上述决策可复核。四者缺一，系统就会退化为"带工具描述的一次性提示"。

## 例子与代码

下面实现一个约 140 行的 Harness，只依赖标准库，包含工具注册、循环、上下文截断、错误重试与轨迹记录。模型调用由确定性替身替代，因此无需 API 密钥即可运行；替身只依据已有工具结果的条数决策，便于复现。环境为 Python 3.10 及以上，实测 3.12。

```python
#!/usr/bin/env python3
"""最小 Harness（Python 3.10+，仅标准库）：工具注册、循环、上下文截断、重试、轨迹。"""

import json
import time
from dataclasses import dataclass

SYSTEM = "你是执行任务的助手。可用工具：calc 计算两数乘积，lookup 查询配置项。只输出 JSON。"


@dataclass
class Tool:
    name: str
    description: str
    schema: dict
    fn: object
    idempotent: bool = True
    max_retries: int = 1


class ToolRegistry:
    def __init__(self):
        self.tools = {}

    def register(self, tool):
        if tool.name in self.tools:
            raise ValueError(f"工具重名：{tool.name}")
        self.tools[tool.name] = tool

    def specs(self):
        return [{"name": t.name, "description": t.description, "input_schema": t.schema}
                for t in self.tools.values()]

    def execute(self, name, arguments):
        """返回 (文本结果, 是否成功, 尝试次数)；只对幂等工具的瞬时错误重试。"""
        tool = self.tools.get(name)
        if tool is None:
            return f"未知工具：{name}", False, 0
        last = ""
        for attempt in range(tool.max_retries + 1):
            try:
                result = tool.fn(**arguments)
                return json.dumps(result, ensure_ascii=False), True, attempt + 1
            except (TimeoutError, ConnectionError) as exc:
                last = f"瞬时错误：{exc}"
                if not tool.idempotent:
                    return last + "（非幂等，不重试）", False, attempt + 1
                time.sleep(0.01 * (2 ** attempt))
            except Exception as exc:
                return f"工具失败：{exc}", False, attempt + 1
        return last, False, tool.max_retries + 1


def compact(messages, budget_chars=640, keep_tail=6, tool_cap=120):
    """保留 system 与最近若干条；工具结果先截断，再按总预算丢弃最旧的。"""
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"][-keep_tail:]
    history = [dict(m, content=(m["content"][:tool_cap] + "…[截断]"))
               if m["role"] == "tool" and len(m["content"]) > tool_cap else m
               for m in history]
    while sum(len(m["content"]) for m in system + history) > budget_chars and len(history) > 2:
        history.pop(0)
    return system + history


class Harness:
    def __init__(self, model, registry, max_steps=6, budget_chars=640):
        self.model, self.registry = model, registry
        self.max_steps, self.budget_chars = max_steps, budget_chars

    def run(self, task):
        messages = [{"role": "system", "content": SYSTEM},
                    {"role": "user", "content": task}]
        trace = {"task": task, "status": "max_steps", "steps": []}
        for step in range(1, self.max_steps + 1):
            view = compact(messages, self.budget_chars)       # 每次调用前重新装配
            begin = time.perf_counter()
            action = self.model(view, self.registry.specs())
            record = {"step": step, "action": action["type"],
                      "prompt_chars": sum(len(m["content"]) for m in view),
                      "latency_ms": round((time.perf_counter() - begin) * 1000, 2)}
            if action["type"] == "final":
                messages.append({"role": "assistant", "content": action["text"]})
                trace["steps"].append(record)
                trace["status"], trace["answer"] = "ok", action["text"]
                break
            call = action["call"]
            observation, ok, attempts = self.registry.execute(call["name"], call["arguments"])
            record.update({"tool": call["name"], "arguments": call["arguments"],
                           "observation": observation, "ok": ok, "attempts": attempts})
            trace["steps"].append(record)
            messages.append({"role": "assistant",
                             "content": json.dumps(call, ensure_ascii=False)})
            messages.append({"role": "tool", "content": observation})
        trace["messages"] = messages
        trace["tokens_est"] = sum(len(m["content"]) for m in messages) // 4
        return trace


def make_tools():
    calls = {"calc": 0}

    def calc(a, b):
        calls["calc"] += 1
        if calls["calc"] == 1:                     # 模拟一次瞬时超时
            raise TimeoutError("上游计算服务超时")
        return {"a": a, "b": b, "product": a * b}

    table = {"mcp_protocol_version": "2025-06-18"}
    return [
        Tool("calc", "计算两个整数的乘积。",
             {"type": "object",
              "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
              "required": ["a", "b"]}, calc),
        Tool("lookup", "按键查询配置项。",
             {"type": "object", "properties": {"key": {"type": "string"}},
              "required": ["key"]},
             lambda key: {"key": key, "value": table.get(key, "未找到")}),
    ]


def scripted_model(messages, specs):
    """确定性替身模型，替代真实 API 调用；决策只依赖已有工具结果的条数。"""
    results = [json.loads(m["content"]) for m in messages if m["role"] == "tool"]
    if len(results) == 0:
        return {"type": "call", "call": {"name": "calc", "arguments": {"a": 128, "b": 3}}}
    if len(results) == 1:
        return {"type": "call", "call": {"name": "lookup",
                                          "arguments": {"key": "mcp_protocol_version"}}}
    return {"type": "final",
            "text": f"128*3={results[0]['product']}；MCP 协议版本={results[1]['value']}"}


registry = ToolRegistry()
for tool in make_tools():
    registry.register(tool)

harness = Harness(scripted_model, registry, max_steps=5)
trace = harness.run("计算 128*3，并查询 MCP 的协议版本号。")
print("状态:", trace["status"])
for step in trace["steps"]:
    print(f"step {step['step']} action={step['action']} tool={step.get('tool')} "
          f"attempts={step.get('attempts')} ok={step.get('ok')} "
          f"chars={step['prompt_chars']} latency={step['latency_ms']}ms")
print("答案:", trace.get("answer"))
print("估算 token:", trace["tokens_est"])
```

运行输出如下，耗时为机器相关量，数值会变化，结构与次数稳定。

```text
状态: ok
step 1 action=call tool=calc attempts=2 ok=True chars=73 latency=0.01ms
step 2 action=call tool=lookup attempts=1 ok=True chars=156 latency=0.04ms
step 3 action=final tool=None attempts=None ok=None chars=274 latency=0.01ms
答案: 128*3=384；MCP 协议版本=2025-06-18
估算 token: 75
```

代码分五块，每块对应定义中的一个组件。

`Tool` 与 `ToolRegistry` 对应 $\mathcal{T}$ 与 $\mathcal{E}$。注册表在注册时检查重名，避免后注册的工具覆盖先注册的实现；`specs()` 生成给模型的工具模式；`execute()` 把异常分为瞬时与永久两类，只对瞬时错误且幂等的工具重试，重试间隔按 $0.01\times2^{\text{attempt}}$ 增长。去掉 `idempotent` 判断，写操作在超时后被重试，会产生重复副作用；去掉重试，首个 `calc` 调用直接失败，循环会把超时当作工具不可用。

`compact` 对应 $\mathcal{C}$ 的预算部分。它保留系统提示与最近 6 条消息，把超过 120 字符的工具结果截断并标注，再按总预算 640 字符丢弃最旧的消息。截断标记不能省略，否则模型无法区分"结果为空"与"结果被截断"；只保留最近消息而不保留系统提示，会让模型丢失输出格式约束。

`Harness.run` 对应 $F$ 与 $\mathcal{B}$。循环上界是 `max_steps`，每步先装配再调用，终止动作写入 `answer` 并跳出；工具动作把调用本身与结果都追加为消息，前者让模型知道自己调用过什么，后者提供观测。轨迹在循环内逐步累积，去掉了就无法判断第几步开始偏离；`latency_ms` 用 `perf_counter` 而不是 `time.time`，避免系统时钟调整造成负值。

`make_tools` 构造两个工具，其中 `calc` 第一次调用故意抛出 `TimeoutError`，用于验证重试路径。真实工具不应包含这种状态，测试替身可以。

`scripted_model` 对应 $\pi$ 的替身。它读取历史中的工具结果条数决定下一步动作，因此完全确定。接入真实模型时只替换这一个函数：把 `messages` 与 `specs()` 转换为模型 API 的请求，解析响应中的工具调用与终止文本，其余组件不变。模型调用自身也需要超时与重试，这部分应放在 `scripted_model` 外层的包装函数中，与工具重试分开配置，因为模型调用的退避策略与工具不同。

## 易错点

> [!warning] 以下六条均可在轨迹或运行结果中直接检验。
> 1. 上下文无限增长。每步把完整工具结果追加进历史，输入长度按步数线性增长、累计成本按平方增长，最终触发输入超限或成本失控；应在水位超过阈值时压缩，并对工具结果做带标记的截断。
> 2. 工具异常被吞掉。`except Exception: return ""` 让模型以为调用成功，基于空结果继续推理；应返回结构化的错误类别与原因，并让终止谓词识别连续失败。
> 3. 循环没有上界。只依赖模型输出终止标记，模型一旦重复调用就会无限消耗；应同时实现最大步数、预算上限与动作重复检测，三者不可互相替代。
> 4. 轨迹缺失导致无法复现。只记录最终答案，失败后无法判断是上下文缺失、工具错误还是终止过早；应记录完整请求、响应、工具参数与结果、模型版本与代码版本。
> 5. 对非幂等操作重试。超时后重试写操作会产生重复副作用；应为写操作生成幂等键并在服务端去重，或禁止重试只做失败回填。
> 6. 用文本匹配判断终止。检查输出是否包含 "DONE" 会被解释性文字误触发；应使用结构化动作类型，终止标记只作为解析后的枚举值。

## 关联笔记

- 前置 [[AI-Agent与工具调用]]：工具模式、调用意图与结果回填是该篇主体，本篇把这些对象放进循环并加上预算与轨迹。
- 前置 [[MCP协议]]：工具执行层可以对接本地函数，也可以对接 MCP Client；该篇的错误分层与取消语义直接决定本篇第 4 节的分类。
- 后续 [[Agent工作流与编排]]：多个 Agent 之间的路由与交接建立在本篇的单 Agent 循环之上，终止条件与预算需要在编排层重新组合。
- 后续 [[Agent记忆与上下文]]：本篇的压缩与检查点是记忆机制的下限，跨会话检索记忆在该篇展开。
- 对照 [[模型评估与交叉验证]]：评测方法同源，但 Agent 评测的样本单位是任务而不是样本，指标包含步数与成本，方差来源更多。

## 达标检测

- [ ] 写出 Harness 的七元组与一步的状态转移式，说明 $F$ 至少需要并入哪些信息。
- [ ] 给定 $P=2500$、$\delta=300$、$n=10$，计算不做压缩时的累计输入 token，并与每步固定 2800 的方案比较。
- [ ] 为第 4 节表中的六类错误各举一个例子，说明哪些可重试、哪些应回填给模型、哪些必须终止。
- [ ] 实现一个带最大步数与动作重复检测的循环，验证模型重复同一调用时会在第 3 步终止。
- [ ] 设计一条轨迹的字段，使其能回答"第几步开始偏离"与"失败由哪个工具引起"。
- [ ] 说明温度设为 0 仍不可复现的四个原因，并给出对应的记录字段。
- [ ] 计算一次 12 步任务的成本，已知每步输入与输出 token 数、单价与缓存命中比例，说明缓存部分为何要单独计价。

## 参考来源

- Anthropic, "Building effective agents", 2024 —— 对应第 1 节的工作流与 Agent 区分、第 10 节的适用边界。
- Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models", arXiv:2210.03629, 2022 —— 对应第 1 节推理与行动交替的循环结构。
- Model Context Protocol 规范，modelcontextprotocol.io —— 对应第 3 节的工具调用、结果内容块、超时与取消语义。
- OpenAI Agents SDK 文档 —— 对应第 5 节的轨迹与 span、第 7 节的审批与中断接口。
