w wyl123ly 的博客
MD

Harness与Loop工程

35 KB 2026.10.18 原文件

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

终止谓词可以写成

其中 是示性函数,条件成立取 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 节的审批与中断接口。