Harness与Loop工程
定义
Harness(运行时外壳)指包裹模型调用、把一次前向调用扩展为可终止的多步任务执行过程的程序,它负责上下文装配、工具调用与执行、循环控制、错误恢复、预算约束与轨迹记录。
形式化地,一个 Harness 是七元组
其状态转移为
其中各符号含义如下。
| 符号 | 含义 |
|---|---|
| 步序号,从 1 开始,一步指一次模型调用及其后续工具执行 | |
| 第 步开始时的状态:任务 、消息历史 、剩余预算 | |
| 第 步的动作,取终止动作或一个工具调用集合 | |
| 工具执行返回的观测,可能包含文本、结构化数据或错误 | |
| 模型策略,包含模型标识、采样参数与提示模板 | |
| 工具注册表,保存名称、模式、执行函数与幂等标记 | |
| 上下文装配器,把状态映射为一次模型请求的消息序列 | |
| 工具执行器,负责并发、超时、重试与结果归一化 | |
| 恢复策略,按错误类别决定重试、回填、降级或终止 | |
| 预算,包含最大步数 、token 上限、成本上限与墙钟上限 | |
| 观测器,把每步写成不可变的轨迹记录 | |
| 状态转移函数,把动作与观测并入历史并扣减预算 |
术语按首次出现处定义:步(step)是一次模型调用加上随之发生的工具执行;轮(turn)是用户与系统之间的一次交互,一轮可以包含多步;轨迹(trace)是按时间排列的全部请求、响应、工具调用与结果的集合;span 是轨迹中带开始时间、结束时间与属性的一个区段,通常对应一次模型调用或一次工具执行;压缩(compaction)指在预算内用摘要或截断替换原始历史;幂等键(idempotency key)是调用方生成的、用于在重试时识别同一操作的标识;检查点(checkpoint)是可恢复的完整状态快照。
为什么重要
模型能力是给定常量,实际可达能力由 Harness 决定。同一模型在两种运行时下的任务成功率差异,通常来自四个可定位的环节:上下文装配是否让模型看到完成任务所需的信息;工具错误是否被回填而不是被吞掉;终止条件是否既允许完成任务又阻止无效循环;轨迹是否足以把失败归因到具体一步。这四个环节都不改变模型权重,却直接改变结果分布。
成本随步数呈二次增长。设系统提示与工具模式合计 个 token,每步新增的工具结果平均 个 token,历史不做压缩时,第 步的输入长度为 , 步累计输入为
取 、、,累计输入为 个 token,而按"每步 3000"的粗略估计只有 36000。差额来自历史重发,它不产生任何新信息。若把每步输入压到 ,累计为 50400,节省约 19%,但压缩本身需要额外调用,压缩频率决定净收益,步数越多、单步结果越长,压缩越划算。
没有轨迹就无法归因。一个失败任务可能因为初始上下文缺少文件内容、工具返回了权限错误、模型选择了错误工具、循环在错误的方向上重复,或终止条件提前触发。只看最终答案,这五种原因不可区分;有轨迹时,每一种都对应可检查的字段。
Harness 在本库中的位置是运行时层。MCP协议 定义了能力如何被发现与调用,本篇定义这些能力如何被调度、约束与记录;AI-Agent与工具调用 给出单次调用的模式与回填格式,本篇把单次调用扩展为多步循环;Agent工作流与编排 讨论任务在多个 Agent 之间的分配,本篇讨论单个 Agent 内部的执行机制。对应学习目标中的"能复现"与"会评估":能实现一个带预算与轨迹的循环,能用轨迹与指标判断一次改动是否有效。
原理与推导
1 一次循环的完整时序
一步由九个阶段组成,顺序固定,任一步失败都要走恢复分支。
- 装配上下文:从状态 生成消息序列,包含系统提示、工具模式、历史与当前任务;同时计算输入长度,若超过预算先触发压缩。
- 调用模型:按 的采样参数发起请求,设置请求级超时;模型调用本身也可能失败,需要独立的错误分类。
- 解析输出:把响应解析为动作。终止动作是纯文本;工具动作包含工具名与参数对象。解析失败按永久错误处理。
- 策略检查:校验工具是否在白名单、参数是否符合模式、是否需要用户审批、剩余预算是否足够。
- 执行工具:一个动作可以包含多个调用。无依赖的调用并发执行,有依赖的串行执行;每个调用有独立超时。
- 归一化结果:把结果转换为文本或结构化内容,限制长度,标注错误类别与是否可重试。
- 回填与记录:把工具结果追加为消息,把模型请求、工具调用、结果与耗时写入轨迹。
- 终止判断:按终止谓词决定继续或结束;结束时写入状态与原因。
- 持久化:刷新轨迹,必要时写检查点,供恢复或评测使用。
终止谓词可以写成
其中 是示性函数,条件成立取 1,否则取 0; 是终止动作集合, 是最大步数, 是剩余预算, 是不可恢复错误集合。四个条件都必须实现:只有模型终止会让循环失去上界;只有步数上限会让预算与成本失控;缺少不可恢复错误判断会让运行时在明确失败后继续消耗。
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
伪代码中 表示把新消息追加到历史, 为最大步数。
2 上下文管理
上下文预算按下式分解:
其中 是系统提示, 是工具模式, 是历史, 是为输出预留的空间。四项共享一个上限,任何一项增长都会挤压其余三项。常见错误是只为历史设上限,忽略了工具模式在工具较多时可以达到数千 token。
压缩有四类手段,性质不同。
| 手段 | 做法 | 丢失的信息 | 适用 |
|---|---|---|---|
| 工具结果截断 | 保留头部与尾部,中间标注省略字符数 | 中段细节 | 日志、文件、长列表 |
| 历史摘要 | 用模型或规则把旧步骤压缩为要点 | 具体参数与原文 | 步数多的长任务 |
| 丢弃最旧消息 | 保留系统提示与最近 条 | 早期约束与失败原因 | 预算极紧的短任务 |
| 结构化替换 | 把大对象替换为标识、行数、字段名 | 内容本身,可按需重取 | 可重新读取的资源 |
截断必须保留错误信息。把失败的工具结果截成空字符串,模型会认为调用成功并继续基于错误前提推理;正确做法是保留错误码与原因,只在长度上压缩。
系统提示的稳定性影响前缀缓存。多数推理服务对完全一致的前缀命中缓存,命中部分的输入按折扣计价,延迟也更低。若系统提示中写入当前时间、随机排序的工具列表或每次变化的任务摘要,前缀每次不同,缓存永不命中。工程上的做法是把系统提示与工具模式固定在消息序列最前部,把时间、检索结果等动态内容放在用户消息或工具结果中。
压缩要按水位触发而不是按溢出触发。设预算利用率为 ,在 超过阈值 时压缩,可以避免在超限后被迫丢弃关键信息。阈值过高会在长工具结果到达时直接超限,过低会频繁压缩并引入额外调用。
3 工具执行层
工具执行层是 Harness 与外部世界的唯一接触面,需要处理五件事。
并发。同一动作中的多个调用若无数据依赖,应并发执行,总延迟由最慢的调用决定而不是求和。并发需要上限,否则一个动作生成二十个调用会打满下游。结果按调用标识匹配,与完成顺序无关;部分失败不影响其他调用的结果回填。
超时。每个调用有独立截止时间,且应传递到下游请求。超时后执行器必须放弃等待并释放资源,不能无限阻塞整个循环。超时属于瞬时错误,但对非幂等操作重试会产生重复副作用,因此超时处理与幂等性绑定。
重试。只对瞬时错误重试,采用指数退避加随机抖动,重试次数上限通常为 2 至 3 次。重试的判断依据是错误类别而不是异常类型名;把连接重置与参数错误都归为异常并统一重试,会让永久错误消耗三次预算并延迟失败。
幂等。幂等键由调用方生成,通常取工具名、规范化参数与任务标识的哈希;服务端维护去重表,相同键的重复请求返回首次结果。没有幂等键时,超时重试可能造成重复下单、重复发信、重复扣款。只读工具天然幂等,写操作必须显式声明并实现去重。
沙箱。工具执行应限制文件系统范围、网络出口与资源用量。stdio 形式的 MCP Server 以宿主用户权限运行,安装即授权,因此更需要在容器或受限账户中执行,并清理环境变量中的密钥。沙箱限制的是副作用范围,不能替代权限检查。
结果归一化同样属于执行层。模型只接受文本或结构化内容,执行器应把异常转换为带类别与建议的结构化错误,把超大结果截断,把二进制内容转成引用而不是内联 base64。
4 错误分类与恢复
错误分类决定恢复动作,分类维度是"是否可重试"与"是否可由模型修正"。
| 类别 | 判定依据 | 典型例子 | 恢复动作 |
|---|---|---|---|
| 瞬时 | 可重试且操作幂等 | 429、503、连接重置、超时 | 退避重试,上限 2 至 3 次 |
| 永久 | 参数或状态错误 | 400、模式校验失败、文件不存在 | 回填原因,允许模型修正一次 |
| 语义 | 调用成功但结果不可用 | 检索为空、结果相互矛盾 | 换参数、换工具或降级 |
| 策略 | 权限或审批拒绝 | 越权、用户拒绝 | 终止该分支并上报 |
| 上下文 | 超出预算或压缩失败 | 输入超限、摘要失败 | 压缩、拆分任务、换小模型 |
| 内部 | 运行时缺陷 | 未捕获异常、状态不一致 | 终止并保留轨迹 |
恢复策略按成本排序:重试、修正参数、降级、分解任务、人工介入、放弃。重试成本最低但只对瞬时错误有效;修正参数需要把错误原因回填给模型,并限制修正次数,否则模型会在同一错误上反复尝试;降级指换用更简单的工具或更小的模型;分解任务指把失败步骤拆成更小的子任务;人工介入成本最高,适用于不可逆操作。
连续失败需要熔断。设同一工具连续失败次数为 ,当 时应在本轮禁用该工具,并把禁用原因写入上下文;否则模型会持续重试同一个不可用工具,消耗预算且不产生进展。同一动作重复出现也应触发终止:对动作的工具名与规范化参数取哈希,若相同哈希连续出现两次,说明状态没有实质变化。
5 可观测性
轨迹的基本单位是 span。一次任务对应根 span,每一步对应一个子 span,每个子 span 下包含模型调用 span 与工具执行 span。span 的字段至少包括标识、父标识、名称、开始时间、结束时间、状态与属性。
{
"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
}
成本按调用累计:
其中 与 是第 次调用的输入与输出 token 数, 与 是单价。命中缓存的前缀通常单独计价,必须按缓存读写两类 token 分别累计,否则成本会被高估或低估。
需要长期跟踪的指标包括:任务成功率、平均步数与步数分布、工具调用次数、工具错误率、重试率、压缩触发次数、P50 与 P95 延迟、单任务 token 与成本。指标要能按任务类型、模型版本与工具集分组,否则一次模型升级带来的变化会与任务分布变化混在一起。
6 确定性与重放
即使温度设为 0,输出也不保证逐位一致。原因有四个:浮点归约顺序、批处理组成、服务端模型版本更新、工具依赖的外部状态。温度 0 只消除随机采样,不消除并行归约的浮点非结合性,也不消除批处理中不同序列长度导致的数值差异。
工程上可控的部分是记录。要复现一次运行,至少需要记录:完整的模型请求,包含系统提示、工具模式、消息序列与采样参数;模型的完整响应,包含工具调用与终止原因;每次工具调用的参数、结果与耗时;运行环境,包含代码版本、模型版本标识与关键配置。只记录最终答案无法复现任何中间决策。
重放分三级,能回答的问题不同。
| 级别 | 记录内容 | 能回答的问题 |
|---|---|---|
| 事件重放 | 完整请求与响应 | 模型当时看到了什么,输出了什么 |
| 决策重放 | 动作序列与参数 | 为什么走这一步,是否换过工具 |
| 全量重放 | 环境快照与外部状态 | 失败能否复现,是否为环境差异 |
评测使用固定任务集与固定工具替身,把外部状态隔离,否则同一任务两次运行的差异无法归因到模型或 Harness。真实运行中需要随机性时,记录随机种子与每次采样的实际输出,用记录值替代重新采样。
7 人在环路
审批点是 Harness 的显式阶段,不是界面事件。需要审批的调用应满足至少一个条件:具有破坏性、涉及不可逆的外部副作用、访问超出当前任务授权范围的数据、成本超过阈值。审批界面必须展示工具名、完整参数与预期副作用;只展示工具名会让用户无法判断参数是否越界。
批准结果应绑定到具体调用。批准记录包含工具名、参数哈希与过期时间,参数变化后批准失效;会话级批准只对只读工具适用。审批超时的默认行为是拒绝,而不是自动通过。
中断与恢复需要区分三种语义。停止指不再发起新的模型调用与工具调用,已发出的调用按超时处理;取消指对执行中的调用发送取消信号,已产生的副作用不可撤销;恢复指从检查点继续,必须处理外部状态在中断期间发生的变化,例如目标文件已被修改、订单已被处理。恢复时用幂等键与版本号判断操作是否已生效。
人工响应时间计入预算。若任务有端到端时限,审批等待会挤占模型与工具的时间;异步审批与超时拒绝是必要的,否则一个无人值守的任务会停在审批阶段直到进程被回收。
8 终止条件与最大步数
终止条件分五类:成功完成、步数耗尽、预算耗尽、不可恢复错误、用户中止。每类都应产生不同的状态码与不同的后续动作:成功返回答案;步数或预算耗尽返回部分结果与未完成原因;不可恢复错误返回错误类别与轨迹标识;用户中止返回已完成的子目标。
最大步数 由任务分布决定,而不是凭经验取整数。取历史轨迹中成功任务的步数分布,令 略高于 ,可以覆盖绝大多数成功路径,同时限制尾部成本。 过小会把本可完成的任务截断,表现为"差一步就成功"; 过大只会增加失败任务的成本,因为成功任务在完成时已经终止。
最大步数不能替代循环检测。模型可能在两步之间来回切换工具,步数在增加而状态不变。检测方法是对每步的动作集合取规范化哈希,统计连续重复次数;连续两次相同则终止,或强制要求模型给出不同的计划。另一种检测是状态哈希:把历史的消息摘要与工具结果摘要合并取哈希,若哈希重复则说明状态没有推进。
终止时返回部分结果优于返回空。部分结果应包含已完成的子目标、已获得的中间数据与未完成的原因,这些信息对人工接管与后续重试都有价值。
9 评测
评测要区分能力与工程两个维度。能力维度看任务是否完成,工程维度看完成它的代价与稳定性。
| 指标 | 定义 | 用途 |
|---|---|---|
| 成功率 | 成功任务数除以任务总数 | 总体能力 |
| pass | 同一任务 次运行全部成功的比例 | 稳定性 |
| 平均步数 | 成功任务的平均步数 | 效率 |
| 工具错误率 | 失败工具调用数除以总调用数 | 集成质量 |
| 重试率 | 发生重试的调用比例 | 瞬时错误占比 |
| 单任务成本 | 总成本除以任务数 | 经济性 |
| P95 延迟 | 延迟分布的 95 分位 | 用户体验 |
pass 的定义为
它衡量稳定性而非平均能力。成功率相同的两个系统,pass 可能相差很大;pass 较低说明失败集中在少数任务上,且这些失败可以重复触发。
评测报告应给出均值与置信区间。任务数较少时,用 bootstrap 重采样估计区间,避免把一两个任务的差异解释为改进。消融实验一次只改一个因素:去掉压缩、去掉重试、去掉审批、换模型版本,分别报告成功率、步数与成本的变化。指标之间通常存在权衡,例如更强的重试会提高成功率也提高成本,报告必须同时给出两者。
10 与把全部逻辑塞进一个提示词的对比
单提示词方案把任务说明、工具描述、输出格式与失败处理全部写入一段文本,模型一次生成完整结果。它在单步任务上成本低、延迟低、实现简单,但在多步任务上缺少四个核心机制:按预算装配的上下文、独立的错误通道、可检验的终止谓词、可回放的轨迹。
| 维度 | 单提示词 | Harness |
|---|---|---|
| 上下文 | 一次性写入全部材料 | 每步按预算装配与压缩 |
| 工具 | 说明文字内嵌,模型输出文本 | 结构化模式,运行时执行与校验 |
| 错误 | 无独立通道,模型自行解释 | 分类、重试、回填与熔断 |
| 终止 | 依赖模型自行停止 | 终止谓词、步数上限与预算 |
| 可观测 | 只有最终输出 | 轨迹、span、token 与成本 |
| 修改 | 改提示词,影响全局 | 改配置或代码,作用域明确 |
| 单位成本 | 一次较大的请求 | 多轮较小的请求 |
| 适用 | 单步转换、无副作用、输入固定 | 多步、有工具、需要审计与恢复 |
选择依据是任务是否需要外部状态。若答案完全由输入文本决定,单提示词更经济;若答案依赖运行时才能获得的数据,或需要执行有副作用的操作,就必须有执行层与循环。混合方案同样成立:先用一次调用判断任务类型,只有需要多步执行的任务才进入 Harness,这可以避免为简单请求支付多轮成本。
Harness 的固定成本必须被任务复杂度抵消。多轮调用意味着重复发送系统提示与工具模式,也意味着更高的尾延迟;当任务平均只需一步时,Harness 的收益为负。判断标准是:成功率的提升是否足以覆盖 token 成本与延迟的增加,这需要第 9 节的指标而不是主观判断。
关键直觉
机制性表述
Harness 的最小职责是把一次模型前向变成一条可持久化的 记录,并在这条记录序列上定义终止、预算与恢复。模型只负责在给定上下文下选择动作,其余全部由运行时承担;因此运行时的正确性可以用状态机性质检验,而不必依赖模型行为。
与定义的关系:七元组中的 决定模型看到什么, 决定动作如何作用于外部世界, 与终止谓词决定过程何时停止, 使上述决策可复核。四者缺一,系统就会退化为"带工具描述的一次性提示"。
例子与代码
下面实现一个约 140 行的 Harness,只依赖标准库,包含工具注册、循环、上下文截断、错误重试与轨迹记录。模型调用由确定性替身替代,因此无需 API 密钥即可运行;替身只依据已有工具结果的条数决策,便于复现。环境为 Python 3.10 及以上,实测 3.12。
#!/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"])
运行输出如下,耗时为机器相关量,数值会变化,结构与次数稳定。
状态: 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 对应 与 。注册表在注册时检查重名,避免后注册的工具覆盖先注册的实现;specs() 生成给模型的工具模式;execute() 把异常分为瞬时与永久两类,只对瞬时错误且幂等的工具重试,重试间隔按 增长。去掉 idempotent 判断,写操作在超时后被重试,会产生重复副作用;去掉重试,首个 calc 调用直接失败,循环会把超时当作工具不可用。
compact 对应 的预算部分。它保留系统提示与最近 6 条消息,把超过 120 字符的工具结果截断并标注,再按总预算 640 字符丢弃最旧的消息。截断标记不能省略,否则模型无法区分"结果为空"与"结果被截断";只保留最近消息而不保留系统提示,会让模型丢失输出格式约束。
Harness.run 对应 与 。循环上界是 max_steps,每步先装配再调用,终止动作写入 answer 并跳出;工具动作把调用本身与结果都追加为消息,前者让模型知道自己调用过什么,后者提供观测。轨迹在循环内逐步累积,去掉了就无法判断第几步开始偏离;latency_ms 用 perf_counter 而不是 time.time,避免系统时钟调整造成负值。
make_tools 构造两个工具,其中 calc 第一次调用故意抛出 TimeoutError,用于验证重试路径。真实工具不应包含这种状态,测试替身可以。
scripted_model 对应 的替身。它读取历史中的工具结果条数决定下一步动作,因此完全确定。接入真实模型时只替换这一个函数:把 messages 与 specs() 转换为模型 API 的请求,解析响应中的工具调用与终止文本,其余组件不变。模型调用自身也需要超时与重试,这部分应放在 scripted_model 外层的包装函数中,与工具重试分开配置,因为模型调用的退避策略与工具不同。
易错点
以下六条均可在轨迹或运行结果中直接检验。
1. 上下文无限增长。每步把完整工具结果追加进历史,输入长度按步数线性增长、累计成本按平方增长,最终触发输入超限或成本失控;应在水位超过阈值时压缩,并对工具结果做带标记的截断。
2. 工具异常被吞掉。
except Exception: return ""让模型以为调用成功,基于空结果继续推理;应返回结构化的错误类别与原因,并让终止谓词识别连续失败。3. 循环没有上界。只依赖模型输出终止标记,模型一旦重复调用就会无限消耗;应同时实现最大步数、预算上限与动作重复检测,三者不可互相替代。
4. 轨迹缺失导致无法复现。只记录最终答案,失败后无法判断是上下文缺失、工具错误还是终止过早;应记录完整请求、响应、工具参数与结果、模型版本与代码版本。
5. 对非幂等操作重试。超时后重试写操作会产生重复副作用;应为写操作生成幂等键并在服务端去重,或禁止重试只做失败回填。
6. 用文本匹配判断终止。检查输出是否包含 "DONE" 会被解释性文字误触发;应使用结构化动作类型,终止标记只作为解析后的枚举值。
关联笔记
- 前置 AI-Agent与工具调用:工具模式、调用意图与结果回填是该篇主体,本篇把这些对象放进循环并加上预算与轨迹。
- 前置 MCP协议:工具执行层可以对接本地函数,也可以对接 MCP Client;该篇的错误分层与取消语义直接决定本篇第 4 节的分类。
- 后续 Agent工作流与编排:多个 Agent 之间的路由与交接建立在本篇的单 Agent 循环之上,终止条件与预算需要在编排层重新组合。
- 后续 Agent记忆与上下文:本篇的压缩与检查点是记忆机制的下限,跨会话检索记忆在该篇展开。
- 对照 模型评估与交叉验证:评测方法同源,但 Agent 评测的样本单位是任务而不是样本,指标包含步数与成本,方差来源更多。
达标检测
- [ ] 写出 Harness 的七元组与一步的状态转移式,说明 至少需要并入哪些信息。
- [ ] 给定 、、,计算不做压缩时的累计输入 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 节的审批与中断接口。