一条追踪记录里,同一个工具名出现了六次。这个智能体到底尝试了几次操作?
六,是个很诱人的答案。但它也可能是三次调用、每次留下开始和结束两条记录;可能是两次调用,其中一次遥测数据被重复投递;也可能是六次互不相关的操作,只是恰好用了同一个工具名。
数行数很容易,数尝试次数则需要一套身份模型。这是 AgentInspect 维护者在测试中反复强调的一点:这里讨论的是如何解读执行证据,而不是实现实时重试,也不是承诺"恰好一次"的效果。
给每个标识符安排一个职责
一套可用的词汇是这样的:一次尝试可以发出多条事件;一条事件可能被投递不止一次;一次操作可以跨越多次尝试。这些是关系,不是可以互换的计数器。传输层的重复投递,和应用层的重复执行,必须保持可区分。
记录身份要放在操作被调用的地方。测试中安装的是固定版本:
- npm install --save-exact agent-inspect@6.31.35
然后使用带元数据的 step() 接口。在这个版本里,step.tool() 这个快捷方式只接受名称和函数,不接受第三个元数据参数。
示例里构造了两次读取尝试:第一次抛出"合成临时失败"的错误,第二次成功返回。第一次的错误被主动吞掉,这是测试夹具的刻意行为,不是通用的错误处理建议——它代表的是一条有边界的恢复路径,第一次失败、第二次成功。
这些 ID 是静态的,因为测试跑在隔离的夹具里。真实应用的身份标识需要合适的唯一性和作用域,不能把 fixture-op-1 复用到互不相关的操作上,还指望评估器自己推断出区别。
问规则你真正想问的问题
打开生成的追踪文件后,可以评估两份契约:一份要求最多 1 次尝试,一份要求最多 2 次。对这份源夹具来说,前者以 contract.retry.max-attempts 失败,后者通过。这个结果指向的是与已记录逻辑操作相关联的尝试次数,而不是 JSONL 的总行数。
当前实现会在一次运行内按显式的重试身份分组,优先使用不同的尝试 ID,也支持其他有文档记录的证据形式,包括经过校验的尝试编号。身份缺失或相互冲突,并不等于可以凭一个重复出现的名字就凭空发明一条重试关系。
更重要的工程决策发生在写规则之前:你的应用在哪里定义"逻辑操作"?一个适配器无法可靠地重建你从未记录过的业务边界。
重复投递是个好用的负向对照
配套测试把第二次尝试的终止记录原样复制,追加到源追踪里,然后重新评估同样的契约。这是一个刻意收窄的主张:一条完全相同的重复投递记录,不应该凭空多造出一次尝试。但也不能反推说,所有看起来重复的记录都可以丢掉。
如果同一个声明的身份带着不同的参数、状态或归属出现,那就是需要调查的冲突。直接用 new Map(events.map(e => [e.id, e])) 覆盖,可能把互相矛盾的证据抹掉,只留下最后到达的那一行。所以一套有用的测试集,应该同时包含精确重复和冲突复用,并把两者的预期结果分开。
别把尝试次数升格成效果次数
两次尝试不能证明写了两次,一次超时也不能证明一次都没写,一个成功的响应同样不必然证明接收方观察到了效果。对读取操作来说,这个区别也许只影响延迟分析;但对支付、通知、预订来说,它改变的是整个恢复协议。
元数据里记录了一个 idempotencyKey,只能证明这个键被记录过。要声称目标端对效果做了去重,你需要目标端的行为和范围合适的回执。AgentInspect 的追踪分析不是那个目标端。
这也是为什么重试记账、效果验证和授权应当作为三项独立检查:它们可能用到相关的标识符,但回答的是不同的问题。
如果导出追踪,读回导出表示后还要再跑一遍尝试计数检查。一棵结构合法的 span 树,可能保留了每一个工具名,却丢掉了操作元数据。配套的 OTLP 实验在这份夹具上保住了重试判定,前提是运行状态被单独评估;它同时暴露了恢复之后的一处运行状态不一致。通过一项不变量,不等于语义完全等价。
从一个操作、两次尝试、一次重复投递开始。这个小夹具往往比一条塞满看似合理计数器的庞大追踪更有信息量。
热门跟贴