方法级 trace 看不出第几轮:给 Agent 补一层轮次维度

读完你会得到什么

一套能自己复刻的接法:把每轮变成 trace 上的一层,本轮调了什么工具、参数是什么、工具回了什么,都能直接读出来。

配套的验证是两组对照:接了之后看得见,不接就看不见。工程代码不公开,但设置条件都在文里,照着重搭一遍不费事。

一句结论:框架给的 span 是方法调用粒度,调用过模型、调用过工具 它都有,第几轮、为什么选这个工具 它没有。缺的这层得自己补。

一、假设一个改地址的客服助手

假设一个客服助手,接三条工具:查订单地址、改地址、给用户发通知。一次典型任务跑三轮:查到旧地址,改成新地址,发通知。

数据库里的地址改对了,用户收到的通知里却是旧地址。这类事故的量级不小,真实案例里一次约 60 单受影响。(这是一个构造场景,用来复现这类事故的形态。业务量级只有一个数据点,其余都在可复刻的设置里。)

麻烦的地方在这里:服务层代码里没有循环,就是一次 client.prompt().call()。三轮是模型跑出来的,所以「第 3 轮」这个位置断点打不到,日志里也只有一句「已发送」。

二、先看框架给了什么

这套设置跑一遍,trace 里会出现四种 span:

复制代码
okhttp.requests
gen_ai.client.operation
spring.ai.advisor
spring.ai.chat.client

数量对得上:一次任务四次模型调用,三圈工具调用,每条请求都有对应的 span。

维度对不上。这四条里没有一条能说出第3轮调了 notifyUser,参数里是旧地址。gen_ai.client.operation 只说明模型被调用过;spring.ai.advisor 只说明工具执行器跑过。哪一轮、那轮想干什么,只能拿时间戳去猜。

这段不是推测。对照组用例就是干这个的:注册观测器,跑完任务,把收到的 span 名单输出出来,再断言里面没有任何一条带轮次信息。跑一遍测试就能看到那串名单。

三、轮次能挂在哪

先说两个挂了不行的位置,省得重走:

Advisor 不行。它包住的是 一次 ChatClient 调用,而工具循环在调用内部跑完 ------ 一次调用里可能有三轮,Advisor 只看得见一次。

包装 ChatModel 也不行。循环在更内层,包装层同样只收到一次。

可以的是工具调用管理器(ToolCallingManager 的 executeToolCalls):每一轮执行一次,是唯一的分轮点。装饰它,每轮开一个 span:

java 复制代码
Observation observation = Observation.start("agent.round", registry)
        .lowCardinalityKeyValue("agent.round.index", String.valueOf(round))
        .highCardinalityKeyValue("agent.round.tools", requestedTools(response))
        .highCardinalityKeyValue("agent.round.args", requestedArgs(response));

四个属性,各自回答一个问题:

属性 例子 定位时回答
agent.round.index 3 第几轮
agent.round.tools notifyUser 这轮要调什么
agent.round.args {"userId":"u1","message":"...旧地址..."} 参数从哪来
agent.round.result 已发送 工具回了什么

四、补上之后

同一个脚本重跑,实测三个 agent.round span,index 依次 1、2、3。第 3 轮的 tools 是 notifyUser,args 里带着旧地址;第 2 轮的 tools 是 updateAddress,参数是新地址。

「哪一轮把旧值发出去了」这个问题,从需要推测变成一眼可见。

能引用的真实数字:一次任务 = 3 轮工具执行 + 4 次模型调用(三轮之后还有一次收尾),用到的工具 3 个,1 读 2 写。这几个数在测试里断言过,脚本改了就会红。

五、两个坑

单参的 ChatClient.builder 会把自己的观测器关掉。

ChatClient.builder(chatModel) 这个重载内部把 ObservationRegistry 写死成 NOOP,顺带用默认的工具调用管理器。表现是:自己注册了 handler,跑完一条 span 都收不到,而且不报错。

反编译能看到那个常量:

scss 复制代码
DefaultChatClientBuilder(ChatModel);
   2: getstatic  io/micrometer/observation/ObservationRegistry.NOOP

要显式装配,把 registry 和工具调用管理器一起传进去:

java 复制代码
ChatClient client = new DefaultChatClientBuilder(
        chatModel, registry, null, null,
        ToolCallingAdvisor.builder().toolCallingManager(tracedManager))
        .defaultAdvisors(toolAdvisor)
        .defaultTools(tools)
        .build();

假上游的队列空着会阻塞,表现成读超时。

搭脚本化上游时漏了一条响应,请求发出去没人应答,客户端等了两分钟才超时。报错是 Request failed 加 SocketTimeoutException,跟「剧本没排」一点关系都看不出来。

这条是实测踩出来的。判据是看上游收到的请求数:收了两条就没动静,说明第三条在等剧本,不是网络问题 ------ 光看报错只会以为是网络。

六、边界

  • 轮次按「工具执行」计数:纯对话任务没有工具调用,一轮 span 都不会有,这套东西对它无效
  • 每轮一个 span,轮次多时的量级成本没测,未验证
  • 只覆盖同步调用;流式路径的 observation 行为不同,未验证
  • 没有接真实 tracing 后端(Zipkin / OTLP),只在内存里断言
  • 事故是构造的,业务量级只有 60 单一个数据点

七、怎么接进现有项目

三步,不依赖任何仓库:

  1. 写一个装饰器实现工具调用管理器,把默认实现包起来,在 executeToolCalls 前后起停一个 Observation,属性按上面的四个填
  2. 装配 ChatClient 时显式传 ObservationRegistry 和这个装饰器 ------ 走单参重载会静默退回 NOOP
  3. 把 registry 接到现有 tracing 后端(Zipkin / OTLP 都行),轮次就是普通 span,不需要自定义 UI

验证方式建议按对照写:同一个脚本跑两遍,一遍接装饰器、一遍不接。前者的 trace 里应该有 N 个轮次 span,后者的断言是「一条都没有」------ 后者才是这条改动真正的价值证明。

相关推荐
框架那些事儿10 分钟前
深入 Pi 源码:一个优秀的 Agent,是如何管理上下文的?
人工智能·ai编程·全栈
数据库小学妹15 分钟前
数据库容量规划:四个数与扩容触发线
运维·数据库·后端
AAA修煤气灶刘哥15 分钟前
DSH Super-agent 双层架构:如何兼顾后台执行与持续响应
人工智能·后端·设计模式
泡海椒20 分钟前
jquick-pdf 资源使用率报表模板:政务云集群水位的图表版与表格版怎么选
后端
用户50800705462820 分钟前
1元机器到手后,我拿它跑了一套微服务测试环境
后端
阿里云大数据AI技术22 分钟前
Hologres jev 能帮业务做什么?7 个场景,一句提问
人工智能
武子康27 分钟前
H3-World 扩展跳跃与开门:新动作怎样进入训练数据?
大数据·人工智能·算法
郭生27 分钟前
dedecms等php类cms静态生成速度慢或超时原因及解决方法
后端
Gopher_HBo27 分钟前
Go pprof:五个字段,凭什么管住六种剖析?
后端