平时开车的人都知道行车记录仪不是拿来好看的。它是把全程路况录下来防止事后各执一词也方便在事故发生后回放现场。LLM智能体的开发调试其实也是一回事你让Agent自己去调用工具、查数据库、生成总结跑完一次流程可能很顺畅也可能全程“鬼打墙”。更难受的是传统日志只能告诉你调了哪个函数、花了多少毫秒却说不清楚上下文里到底装了什么、这是第几次重试、模型是基于哪一条消息才做出错误决定的。最近我在做Agent类项目时把这一套思路补齐了。项目代号叫11-AgentTrace核心就是给LLM智能体装一台“行车记录仪”把每一次决策、每一轮工具调用、前后文状态变化都结构化地录下来。它能够回放、对比、审计也能用来定位那些“看起来像是抽风”的实际行为。如果你正在做智能体开发、Agent应用运维或模型效果评测这篇文章大概能帮你省掉不少查日志、猜原因的力气。1. 先聊清楚为什么LLM智能体比传统程序更需要“行车记录仪”1.1 传统日志在Agent场景下有三个盲区传统后端服务为什么好排查因为每一次请求基本是“参数进去、结果出来”的确定性过程。你只要记下request_id、响应码、耗时、异常堆栈十有八九能还原问题现场。但Agent应用完全不是这个画风它有三个盲区是普通日志覆盖不了的。第一状态不在变量里而在对话上下文里。模型什么时候决定调用某个工具、调用之后又怎么利用返回结果这些判断依据全部存在于prompt消息序列中。传统logger只会告诉你“调用成功”或“调用失败”不会告诉你“模型在工具返回了3000个字符之后只读了前200个字符就做了决定”。这样的信息一旦当时没记录事后就很难再补。第二输出非确定。同一个用户问题配上同一个系统提示词模型两次生成的结果都可能不同。你遇到“第一次错、第二次对、第三次又错”如果没有逐帧记录那就只能凭运气复现。普通日志的“快照”模式缺少足够细粒度的过程信息无法回答“当时它到底先看到了什么”。第三上下文太长会被截断。Agent系统里这种情况经常发生检索工具带回了大量文档模型窗口被撑爆系统悄悄截断了一部分内容然后模型基于残缺信息做了判断。这属于典型的“系统性摆烂”可传统日志里根本不会有“截断了哪一段”的记录。所以Agent可观测性这件事本质上不是把日志打得更密而是要把“决策现场”给保留下来。这正好就是行车记录仪的逻辑它不关心你平时开车如何只关心出事故那一刻谁能提供完整证据链。1.2 一次“无法复现”的故障可能消耗整个下午我做过的Agent项目里最容易让人上头的故障表现是智能体第一步调了商品检索工具第二步想基于结果做汇总结果汇总内容里混进了一个完全不存在的商品ID。用户截图过来问怎么回事你打开服务日志只看到工具调用正常、返回正常、生成正常全程无异常。但你没法回答“为什么模型会编造一个没有的商品ID”。后来我把整个过程录下来才发现问题出在第二步构造prompt时一个历史消息里的旧商品ID被模板错误地带了进来。模型不是瞎编它只是“看到了不该看到的东西”。这种事光靠加日志很难发现因为出错的地方不是某一行的逻辑而是多次工具调用之间的上下文累积。另一类典型场景是多智能体协作。主Agent并行派了几个子Agent去处理不同子任务结果某一条中间结果被错配到了另一个分支。前端只看到最终回答牛头不对马嘴后端只看到两个子任务都执行成功。这时如果有一份trace回放把子任务的父级关系、消息传递顺序都摆出来问题基本一眼就能定位。行车记录仪拿来干嘛的就是这种时刻用来“翻旧账”的。1.3 审计、计费和安全的“买单”逻辑除了调试还有一层现实需求是审计。智能体一旦被允许操作数据库、发邮件、改订单状态你不仅要确认它“今天干了什么”还要在“用户质疑、领导追责、合作方投诉”的时候拿得出可信记录。尤其是Agent偶尔会有“自主发挥”的行为没有完整trace你就只能摊手。另一个容易被忽略的维度是成本归因。Agent应用的单次任务可能消耗几万甚至几十万token如果模型在某个工具调用上反复失败、反复重试费用会非常难看。而你想知道“这笔钱到底烧在哪个环节”必须依靠带token统计和调用链关系的记录。最后是安全问题。智能体经常接触敏感信息用户手机号、订单内容、内部文档。你记录了一切同时也要保证这些记录本身不会成为泄密点。AgentTrace在采集阶段就必须做脱敏和筛选而不是等数据落了库再补救。这就像行车记录仪虽然有视频但也没有把所有画面都实时上传到公开网络只会先在本地留存按需提取。2. 我把它拆成了四个核心能力2.1 链路追踪Trace、Span、Event三层模型如果只有“一行行日志”那还不够。AgentTrace的第一层能力是把一次Agent运行当成一个Trace把其中每个环节当成Span再把细颗粒度的动作当成Event。用开车来类比一次完整行程是Trace从一个路口到另一个路口是Span经过路口时打了左转灯、按了喇叭是Event。三层分开记录之后你可以从整趟行程下钻到某一个路段再下钻到某个瞬间的动作。一条典型的LLM调用Span大概长这样{ trace_id: tr_9f1a2b, span_id: sp_8c3d4e, parent_span_id: sp_root, type: llm, name: planner, status: ok, latency_ms: 1234, tokens: { input: 3241, output: 512 }, cost_usd: 0.00316, meta: { model: deepseek-chat, temperature: 0.2, retries: 1 } }为什么不用统一日志替代因为普通日志是扁平的没有父子关系。而Agent的决策树天然是嵌套的主Agent生成计划、子Agent执行计划、子Agent再调工具、工具返回结果、模型总结。只有把层级关系记录下来才能做“点击进入某一层查看它下面的所有子操作”这种排查方式。2.2 回放让Agent也能“再开一遍那段路”记录只是第一步真正的价值在于回放。AgentTrace的第二个能力是按照已记录的trace离线重建当时的执行现场然后重新调用模型或工具把整个Agent流程再跑一遍。回放的设计思路并不复杂先按parent_span_id和started_at把span重排成一条可执行链然后把每条消息的原始内容还原出来包括system prompt、历史用户消息、工具返回结果最后在收到“执行”指令时从第一步开始按顺序重放。重放过程中工具调用不再真正去触碰外部系统而是直接返回记录中的工具输出。这样一来你可以在不影响真实环境的前提下反复修改prompt、修改上下文、修改工具返回结果观察Agent会在哪个环节发生行为变化。很多人会误以为回放百分百复现。实际做不到完全一致因为LLM有随机性。但回放的意义不是“一次不差”而是缩小范围它可以把问题从“整条链路都看不清”缩小到“是哪一条消息、哪一个工具结果导致判断偏移”。只要你能稳定地在回放环境中触发一次错误接下来修bug就变得可控了。2.3 成本与延迟画像Agent应用的性能问题往往不是单次调用慢而是“链路太长、重复调用太多”。AgentTrace把每个Span的token用量、耗时、成本都记录下来后就可以从几个维度做汇总。分析维度统计口径能发现的问题按流程单个Trace的调用次数、token占比、成本占比是否存在循环调用、冗余工具调用按模型不同模型在相同环节的延迟、成本模型选型是否合理按用户/会话同一用户多条Trace的成本分布是否出现重试风暴、恶意刷量我实测中遇到过一个典型情况一个Agent任务只做了三次工具调用表面看没啥异常但其中第二次“查数据库”调了同一个SQL语句12次。原因是对应工具在返回结果不符合预期时Agent自己决定重试而重试逻辑没有设置上限。没有成本画像这种问题会在月底账单出来时才被发现有了画像当天就能看到“check_db这个span占用了整个任务72%的token”。2.4 审计和权限留痕除了调试和成本安全审计也需要AgentTrace。具体做法是把“敏感操作”单独记录成特定类型的事件比如update_order、send_mail、delete_record。这类事件必须包含操作人或session、目标对象ID、操作结果、原始请求片段但不应该包含完整敏感内容。审计的核心原则是在采集端做脱敏而不是在展示端做脱敏。如果数据库里已经存储了明文手机号后续再怎么加权限控制都存在风险。正确做法是记录时就把字段值替换成掩码只保留前后两位或者直接只存不可逆哈希。对API Key这类密钥需要做到“绝不落盘”日志里只记录key的指纹或别名。密钥一旦进了日志哪怕只出现一次也要立刻轮换。这是做Agent观测时最容易被忽略的安全红线。3. 落地起来其实只要四张表AgentTrace的技术实现剖析3.1 存储设计只建四张核心表很多团队一想到观测系统就恨不得上个大数据平台。其实最早期版本不需要那么重。AgentTrace的存储层我从一开始就控制在四张表跑起来完全够用CREATE TABLE trace ( id BIGSERIAL PRIMARY KEY, trace_id TEXT UNIQUE NOT NULL, session_id TEXT, user_id TEXT, agent_name TEXT, status TEXT, started_at TIMESTAMPTZ, ended_at TIMESTAMPTZ, total_tokens INTEGER, total_cost_usd NUMERIC, error_summary TEXT ); CREATE TABLE span ( id BIGSERIAL PRIMARY KEY, trace_id TEXT NOT NULL, span_id TEXT UNIQUE NOT NULL, parent_span_id TEXT, span_type TEXT, span_name TEXT, model_name TEXT, status TEXT, latency_ms INTEGER, input_tokens INTEGER, output_tokens INTEGER, cost_usd NUMERIC, started_at TIMESTAMPTZ, ended_at TIMESTAMPTZ ); CREATE TABLE event ( id BIGSERIAL PRIMARY KEY, trace_id TEXT NOT NULL, span_id TEXT NOT NULL, seq INTEGER, event_type TEXT, event_key TEXT, payload_json JSONB, happened_at TIMESTAMPTZ ); CREATE TABLE artifact ( id BIGSERIAL PRIMARY KEY, span_id TEXT NOT NULL, kind TEXT, object_key TEXT, mime_type TEXT, byte_size BIGINT, created_at TIMESTAMPTZ );之所以不要设计太多表是因为Agent的调用类型太杂很难用强类型字段一一覆盖。不如用JSONB字段保存结构化payload查询时用GIN索引灵活性远高于堆一堆专门表。tool返回的大段文本、图片、pdf内容则存到artifact表只保留对象存储地址不要把几十KB内容塞进SQL字段里。3.2 插桩方式优先选“框架回调”别到处埋点技术选型上最容易犯的错是每个工具函数里手动加日志代码。短期看没问题代码一多就会漏。而且一旦有人忘了在某个新工具里加埋点整条链路就断了一截。正确做法是优先利用框架已有的回调机制。LangChain、LangGraph这类框架都有callback handler只要实现一个observer类把on_llm_start、on_llm_end、on_tool_start、on_tool_end等事件转发给AgentTrace采集端即可。这种方式侵入性最小连业务代码都不用改。如果项目没有用现成框架那也建议把所有LLM调用收敛到一个统一client封装里在这个封装上做拦截。下面是我在自研Agent里用过的装饰器写法def traced_tool(name: str): def decorator(fn): functools.wraps(fn) async def wrapper(*args, **kwargs): span_id await tracer.start_span( trace_idcurrent_trace_id(), span_typetool, namename, input_signaturebuild_signature(args, kwargs) ) try: result await fn(*args, **kwargs) await tracer.end_span(span_id, statusok, outputresult) return result except Exception as e: await tracer.end_span(span_id, statuserror, errorstr(e)) raise return wrapper return decorator这个思路的核心是“统一出入口”不是靠每个业务开发者的自觉而是靠框架级、client级的约定去兜底。事件先发到本地内存buffer异步批量写入后端避免同步写库拖慢Agent主流程。3.3 重放引擎把“当时的现场”搬回来重放引擎不是简单地“再做一次请求”而是要对现场做可控修改。我把它拆成四步第一步载入trace把所有span和event还原成一张树形调用图。调用图要标明父子关系而不是按时间线平铺。这样你才能知道“哪个子任务失败之后父任务做了什么决策”。第二步重建上下文。从span里提取完整的系统提示词、用户消息历史、工具定义、工具返回结果按原始顺序组装成一个新的消息列表。这是重放是否可信的基础。第三步选择回放策略。全量回放会非常慢通常我会只回放“出错路径相关的子树”。比如在某个工具调用之后Agent出现了幻觉输出那么从该工具返回之前的状态开始回放就足够判断问题了。第四步输出对比结果。把新生成的token序列、工具调用序列、最终回答摘要和原始trace做diff软件会标出哪些步骤出现了偏差。如果输入完全相同、输出依然不一致再考虑是不是存在外部变量。这一步价值很大它把“模糊的Agent行为差异”变成了“可定位的步骤差异”。3.4 采集端常见的两个“不能做”第一不能把日志打到stdout然后指望事后解析。标准输出没有结构、没有缓冲区量大以后很容易丢事件更无法表达父子关系。采集端应该是一个独立writer直接从业务进程的内存队列里读事件批量写数据库或对象存储。第二不能把工具请求和响应原封不动地交给存储。哪怕是写“测试环境”也总能遇到意外。只要有一次把完整的API Key或用户手机号写进trace那套系统再漂亮都白搭。我的做法是给采集SDK配一套脱敏规则关键词命中就用掩码替换URL里的query参数按key白名单保留其余一律丢弃。4. 我在排查过程中踩过的几个坑4.1 被吞掉的“隐藏错误”Agent应用里最大的坑不是报错而是“看起来没报错”。比如一个工具内部抛了异常被Agent框架捕获后当成工具返回文本的一部分模型还可能据此回复“好的已处理完毕”。用户看起来成功实际功能完全没生效。AgentTrace遇到这种情况不要只记录工具返回的字符串也要记录原始异常对象和错误类型。更关键的是要让模型在错误发生时看到明确提示而不是让它自己去猜测工具输出是不是正常结果。我在实践中会给工具返回增加一个结构化包裹{ok: false, error_code: DB_TIMEOUT, message: ...}并在prompt里强制模型发现非ok状态时必须停止继续操作。4.2 上下文截断造成的“系统性摆烂”有一段时间我服务的Agent经常出现“回答得很流畅但完全跑题”的情况。排查了很久最后打开trace才发现检索阶段一次性把30个文档塞进上下文窗口不够系统只保留了前一半后面几个文档被截断了。关键数据恰恰在后半段。后面我在AgentTrace里给每个span增加了一个标记truncated: true/false同时记录截断前的token数和截断后的token数。只要看到某个span的input_tokens接近模型上限就自动触发告警。问题从“玄学”变成了一个可量化的指标。4.3 多Agent并行时的时序窜位当主Agent同时启动多个子Agent时日志事件会交错出现。如果不同子Agent之间没有独立的trace_id回放时就会看到一堆乱序事件根本分不清谁是谁。解决办法是每个子Agent必须有独立trace_id同时通过parent_span_id指回主Agent的对应span。回放引擎排序时不能只依赖时间戳要采用“树深度优先 父子关系”排序。另外要注意并发模型下的上下文传播Python里用contextvars传递trace_id比手动改全局变量可靠得多。4.4 回放结果不一致不代表系统有bug很多次我把温度设为0信心十足地做回放结果模型还是给出不同答案。第一反应是“回放引擎有bug”后来发现并不是。主要原因有两个一是很多模型服务并不保证温度0就是严格确定性输出量化、批处理、随机种子都会影响结果二是回放和原始执行之间即使消息文本相同向量检索的排序也可能有微小变化排序一变模型关注的重点就变了。所以我在AgentTrace里会把“回放不一致”本身当作诊断信号如果某一步在回放中反复变化说明这一步对外部输入非常敏感需要优先优化上下文组装而不是非要逼模型输出一致。5. 给想上AgentTrace的团队几条个人建议5.1 先跑通单Agent不要一上来就做平台我希望你听进去的第一条建议是不要一开始就搭建什么“Agent可观测平台”。先给单个Agent接入trace记录一次完整运行确认能回答“它每一步做了什么”就够了。四张表、一个SDK、一个简单回放脚本三天内能做通。平台扩容、权限体系、大屏那是中期以后的事过早设计只会拖慢落地速度。5.2 把离线回放当作刚需而不只是锦上添花凡是做过Agent评估的人都会同意online跑测试又慢又贵。离线回放的价值在于你可以用录制好的trace批量跑不同prompt版本快速对比哪个prompt更稳定。它天然就是一套回归测试基础设施。我甚至用录制下来的失败trace来自动生成评测用例每次发版前跑一遍确保同样的问题不会悄悄地回归。5.3 留好数据保留策略别把所有trace都存成永久记录Agent trace会非常占空间尤其是工具返回大文本和图片。我目前的做法是三分法最近3天全量保留、最近30天保留结构化摘要和关键span、超过30天只保留trace_id、session_id和错误码。这个策略需要的存储量会很有限同时也能满足大多数排查和审计需求。真要追查一个月前的细节问题至少还能通过摘要判断从哪一天开始出现问题。5.4 一个让我改变最大习惯的使用方式装完AgentTrace之后我最大的变化不是多了一个排查工具而是改变了排查思路。以前遇到Agent表现异常第一反应是改prompt或换模型现在第一反应是先打开trace回放看它到底在哪一步读到了什么。很多时候问题根本不是模型不好而是上下文里混入了旧信息或者工具返回内容超出了prompt的预期格式。先看到现场再动手改这是做Agent工程之后最重要的一条经验。如果你手头正在被Agent调试折磨我真心建议你从今天开始给一次完整运行做录制。不需要太长一个失败案例就够了。先能把trace回放出来再谈优化效果。等你哪天真遇到“用户投诉但完全不知道发生了什么”的时候你一定会感谢自己当时装了这台行车记录仪。
给LLM智能体装“行车记录仪”：AgentTrace实现决策链路追踪与回放
平时开车的人都知道行车记录仪不是拿来好看的。它是把全程路况录下来防止事后各执一词也方便在事故发生后回放现场。LLM智能体的开发调试其实也是一回事你让Agent自己去调用工具、查数据库、生成总结跑完一次流程可能很顺畅也可能全程“鬼打墙”。更难受的是传统日志只能告诉你调了哪个函数、花了多少毫秒却说不清楚上下文里到底装了什么、这是第几次重试、模型是基于哪一条消息才做出错误决定的。最近我在做Agent类项目时把这一套思路补齐了。项目代号叫11-AgentTrace核心就是给LLM智能体装一台“行车记录仪”把每一次决策、每一轮工具调用、前后文状态变化都结构化地录下来。它能够回放、对比、审计也能用来定位那些“看起来像是抽风”的实际行为。如果你正在做智能体开发、Agent应用运维或模型效果评测这篇文章大概能帮你省掉不少查日志、猜原因的力气。1. 先聊清楚为什么LLM智能体比传统程序更需要“行车记录仪”1.1 传统日志在Agent场景下有三个盲区传统后端服务为什么好排查因为每一次请求基本是“参数进去、结果出来”的确定性过程。你只要记下request_id、响应码、耗时、异常堆栈十有八九能还原问题现场。但Agent应用完全不是这个画风它有三个盲区是普通日志覆盖不了的。第一状态不在变量里而在对话上下文里。模型什么时候决定调用某个工具、调用之后又怎么利用返回结果这些判断依据全部存在于prompt消息序列中。传统logger只会告诉你“调用成功”或“调用失败”不会告诉你“模型在工具返回了3000个字符之后只读了前200个字符就做了决定”。这样的信息一旦当时没记录事后就很难再补。第二输出非确定。同一个用户问题配上同一个系统提示词模型两次生成的结果都可能不同。你遇到“第一次错、第二次对、第三次又错”如果没有逐帧记录那就只能凭运气复现。普通日志的“快照”模式缺少足够细粒度的过程信息无法回答“当时它到底先看到了什么”。第三上下文太长会被截断。Agent系统里这种情况经常发生检索工具带回了大量文档模型窗口被撑爆系统悄悄截断了一部分内容然后模型基于残缺信息做了判断。这属于典型的“系统性摆烂”可传统日志里根本不会有“截断了哪一段”的记录。所以Agent可观测性这件事本质上不是把日志打得更密而是要把“决策现场”给保留下来。这正好就是行车记录仪的逻辑它不关心你平时开车如何只关心出事故那一刻谁能提供完整证据链。1.2 一次“无法复现”的故障可能消耗整个下午我做过的Agent项目里最容易让人上头的故障表现是智能体第一步调了商品检索工具第二步想基于结果做汇总结果汇总内容里混进了一个完全不存在的商品ID。用户截图过来问怎么回事你打开服务日志只看到工具调用正常、返回正常、生成正常全程无异常。但你没法回答“为什么模型会编造一个没有的商品ID”。后来我把整个过程录下来才发现问题出在第二步构造prompt时一个历史消息里的旧商品ID被模板错误地带了进来。模型不是瞎编它只是“看到了不该看到的东西”。这种事光靠加日志很难发现因为出错的地方不是某一行的逻辑而是多次工具调用之间的上下文累积。另一类典型场景是多智能体协作。主Agent并行派了几个子Agent去处理不同子任务结果某一条中间结果被错配到了另一个分支。前端只看到最终回答牛头不对马嘴后端只看到两个子任务都执行成功。这时如果有一份trace回放把子任务的父级关系、消息传递顺序都摆出来问题基本一眼就能定位。行车记录仪拿来干嘛的就是这种时刻用来“翻旧账”的。1.3 审计、计费和安全的“买单”逻辑除了调试还有一层现实需求是审计。智能体一旦被允许操作数据库、发邮件、改订单状态你不仅要确认它“今天干了什么”还要在“用户质疑、领导追责、合作方投诉”的时候拿得出可信记录。尤其是Agent偶尔会有“自主发挥”的行为没有完整trace你就只能摊手。另一个容易被忽略的维度是成本归因。Agent应用的单次任务可能消耗几万甚至几十万token如果模型在某个工具调用上反复失败、反复重试费用会非常难看。而你想知道“这笔钱到底烧在哪个环节”必须依靠带token统计和调用链关系的记录。最后是安全问题。智能体经常接触敏感信息用户手机号、订单内容、内部文档。你记录了一切同时也要保证这些记录本身不会成为泄密点。AgentTrace在采集阶段就必须做脱敏和筛选而不是等数据落了库再补救。这就像行车记录仪虽然有视频但也没有把所有画面都实时上传到公开网络只会先在本地留存按需提取。2. 我把它拆成了四个核心能力2.1 链路追踪Trace、Span、Event三层模型如果只有“一行行日志”那还不够。AgentTrace的第一层能力是把一次Agent运行当成一个Trace把其中每个环节当成Span再把细颗粒度的动作当成Event。用开车来类比一次完整行程是Trace从一个路口到另一个路口是Span经过路口时打了左转灯、按了喇叭是Event。三层分开记录之后你可以从整趟行程下钻到某一个路段再下钻到某个瞬间的动作。一条典型的LLM调用Span大概长这样{ trace_id: tr_9f1a2b, span_id: sp_8c3d4e, parent_span_id: sp_root, type: llm, name: planner, status: ok, latency_ms: 1234, tokens: { input: 3241, output: 512 }, cost_usd: 0.00316, meta: { model: deepseek-chat, temperature: 0.2, retries: 1 } }为什么不用统一日志替代因为普通日志是扁平的没有父子关系。而Agent的决策树天然是嵌套的主Agent生成计划、子Agent执行计划、子Agent再调工具、工具返回结果、模型总结。只有把层级关系记录下来才能做“点击进入某一层查看它下面的所有子操作”这种排查方式。2.2 回放让Agent也能“再开一遍那段路”记录只是第一步真正的价值在于回放。AgentTrace的第二个能力是按照已记录的trace离线重建当时的执行现场然后重新调用模型或工具把整个Agent流程再跑一遍。回放的设计思路并不复杂先按parent_span_id和started_at把span重排成一条可执行链然后把每条消息的原始内容还原出来包括system prompt、历史用户消息、工具返回结果最后在收到“执行”指令时从第一步开始按顺序重放。重放过程中工具调用不再真正去触碰外部系统而是直接返回记录中的工具输出。这样一来你可以在不影响真实环境的前提下反复修改prompt、修改上下文、修改工具返回结果观察Agent会在哪个环节发生行为变化。很多人会误以为回放百分百复现。实际做不到完全一致因为LLM有随机性。但回放的意义不是“一次不差”而是缩小范围它可以把问题从“整条链路都看不清”缩小到“是哪一条消息、哪一个工具结果导致判断偏移”。只要你能稳定地在回放环境中触发一次错误接下来修bug就变得可控了。2.3 成本与延迟画像Agent应用的性能问题往往不是单次调用慢而是“链路太长、重复调用太多”。AgentTrace把每个Span的token用量、耗时、成本都记录下来后就可以从几个维度做汇总。分析维度统计口径能发现的问题按流程单个Trace的调用次数、token占比、成本占比是否存在循环调用、冗余工具调用按模型不同模型在相同环节的延迟、成本模型选型是否合理按用户/会话同一用户多条Trace的成本分布是否出现重试风暴、恶意刷量我实测中遇到过一个典型情况一个Agent任务只做了三次工具调用表面看没啥异常但其中第二次“查数据库”调了同一个SQL语句12次。原因是对应工具在返回结果不符合预期时Agent自己决定重试而重试逻辑没有设置上限。没有成本画像这种问题会在月底账单出来时才被发现有了画像当天就能看到“check_db这个span占用了整个任务72%的token”。2.4 审计和权限留痕除了调试和成本安全审计也需要AgentTrace。具体做法是把“敏感操作”单独记录成特定类型的事件比如update_order、send_mail、delete_record。这类事件必须包含操作人或session、目标对象ID、操作结果、原始请求片段但不应该包含完整敏感内容。审计的核心原则是在采集端做脱敏而不是在展示端做脱敏。如果数据库里已经存储了明文手机号后续再怎么加权限控制都存在风险。正确做法是记录时就把字段值替换成掩码只保留前后两位或者直接只存不可逆哈希。对API Key这类密钥需要做到“绝不落盘”日志里只记录key的指纹或别名。密钥一旦进了日志哪怕只出现一次也要立刻轮换。这是做Agent观测时最容易被忽略的安全红线。3. 落地起来其实只要四张表AgentTrace的技术实现剖析3.1 存储设计只建四张核心表很多团队一想到观测系统就恨不得上个大数据平台。其实最早期版本不需要那么重。AgentTrace的存储层我从一开始就控制在四张表跑起来完全够用CREATE TABLE trace ( id BIGSERIAL PRIMARY KEY, trace_id TEXT UNIQUE NOT NULL, session_id TEXT, user_id TEXT, agent_name TEXT, status TEXT, started_at TIMESTAMPTZ, ended_at TIMESTAMPTZ, total_tokens INTEGER, total_cost_usd NUMERIC, error_summary TEXT ); CREATE TABLE span ( id BIGSERIAL PRIMARY KEY, trace_id TEXT NOT NULL, span_id TEXT UNIQUE NOT NULL, parent_span_id TEXT, span_type TEXT, span_name TEXT, model_name TEXT, status TEXT, latency_ms INTEGER, input_tokens INTEGER, output_tokens INTEGER, cost_usd NUMERIC, started_at TIMESTAMPTZ, ended_at TIMESTAMPTZ ); CREATE TABLE event ( id BIGSERIAL PRIMARY KEY, trace_id TEXT NOT NULL, span_id TEXT NOT NULL, seq INTEGER, event_type TEXT, event_key TEXT, payload_json JSONB, happened_at TIMESTAMPTZ ); CREATE TABLE artifact ( id BIGSERIAL PRIMARY KEY, span_id TEXT NOT NULL, kind TEXT, object_key TEXT, mime_type TEXT, byte_size BIGINT, created_at TIMESTAMPTZ );之所以不要设计太多表是因为Agent的调用类型太杂很难用强类型字段一一覆盖。不如用JSONB字段保存结构化payload查询时用GIN索引灵活性远高于堆一堆专门表。tool返回的大段文本、图片、pdf内容则存到artifact表只保留对象存储地址不要把几十KB内容塞进SQL字段里。3.2 插桩方式优先选“框架回调”别到处埋点技术选型上最容易犯的错是每个工具函数里手动加日志代码。短期看没问题代码一多就会漏。而且一旦有人忘了在某个新工具里加埋点整条链路就断了一截。正确做法是优先利用框架已有的回调机制。LangChain、LangGraph这类框架都有callback handler只要实现一个observer类把on_llm_start、on_llm_end、on_tool_start、on_tool_end等事件转发给AgentTrace采集端即可。这种方式侵入性最小连业务代码都不用改。如果项目没有用现成框架那也建议把所有LLM调用收敛到一个统一client封装里在这个封装上做拦截。下面是我在自研Agent里用过的装饰器写法def traced_tool(name: str): def decorator(fn): functools.wraps(fn) async def wrapper(*args, **kwargs): span_id await tracer.start_span( trace_idcurrent_trace_id(), span_typetool, namename, input_signaturebuild_signature(args, kwargs) ) try: result await fn(*args, **kwargs) await tracer.end_span(span_id, statusok, outputresult) return result except Exception as e: await tracer.end_span(span_id, statuserror, errorstr(e)) raise return wrapper return decorator这个思路的核心是“统一出入口”不是靠每个业务开发者的自觉而是靠框架级、client级的约定去兜底。事件先发到本地内存buffer异步批量写入后端避免同步写库拖慢Agent主流程。3.3 重放引擎把“当时的现场”搬回来重放引擎不是简单地“再做一次请求”而是要对现场做可控修改。我把它拆成四步第一步载入trace把所有span和event还原成一张树形调用图。调用图要标明父子关系而不是按时间线平铺。这样你才能知道“哪个子任务失败之后父任务做了什么决策”。第二步重建上下文。从span里提取完整的系统提示词、用户消息历史、工具定义、工具返回结果按原始顺序组装成一个新的消息列表。这是重放是否可信的基础。第三步选择回放策略。全量回放会非常慢通常我会只回放“出错路径相关的子树”。比如在某个工具调用之后Agent出现了幻觉输出那么从该工具返回之前的状态开始回放就足够判断问题了。第四步输出对比结果。把新生成的token序列、工具调用序列、最终回答摘要和原始trace做diff软件会标出哪些步骤出现了偏差。如果输入完全相同、输出依然不一致再考虑是不是存在外部变量。这一步价值很大它把“模糊的Agent行为差异”变成了“可定位的步骤差异”。3.4 采集端常见的两个“不能做”第一不能把日志打到stdout然后指望事后解析。标准输出没有结构、没有缓冲区量大以后很容易丢事件更无法表达父子关系。采集端应该是一个独立writer直接从业务进程的内存队列里读事件批量写数据库或对象存储。第二不能把工具请求和响应原封不动地交给存储。哪怕是写“测试环境”也总能遇到意外。只要有一次把完整的API Key或用户手机号写进trace那套系统再漂亮都白搭。我的做法是给采集SDK配一套脱敏规则关键词命中就用掩码替换URL里的query参数按key白名单保留其余一律丢弃。4. 我在排查过程中踩过的几个坑4.1 被吞掉的“隐藏错误”Agent应用里最大的坑不是报错而是“看起来没报错”。比如一个工具内部抛了异常被Agent框架捕获后当成工具返回文本的一部分模型还可能据此回复“好的已处理完毕”。用户看起来成功实际功能完全没生效。AgentTrace遇到这种情况不要只记录工具返回的字符串也要记录原始异常对象和错误类型。更关键的是要让模型在错误发生时看到明确提示而不是让它自己去猜测工具输出是不是正常结果。我在实践中会给工具返回增加一个结构化包裹{ok: false, error_code: DB_TIMEOUT, message: ...}并在prompt里强制模型发现非ok状态时必须停止继续操作。4.2 上下文截断造成的“系统性摆烂”有一段时间我服务的Agent经常出现“回答得很流畅但完全跑题”的情况。排查了很久最后打开trace才发现检索阶段一次性把30个文档塞进上下文窗口不够系统只保留了前一半后面几个文档被截断了。关键数据恰恰在后半段。后面我在AgentTrace里给每个span增加了一个标记truncated: true/false同时记录截断前的token数和截断后的token数。只要看到某个span的input_tokens接近模型上限就自动触发告警。问题从“玄学”变成了一个可量化的指标。4.3 多Agent并行时的时序窜位当主Agent同时启动多个子Agent时日志事件会交错出现。如果不同子Agent之间没有独立的trace_id回放时就会看到一堆乱序事件根本分不清谁是谁。解决办法是每个子Agent必须有独立trace_id同时通过parent_span_id指回主Agent的对应span。回放引擎排序时不能只依赖时间戳要采用“树深度优先 父子关系”排序。另外要注意并发模型下的上下文传播Python里用contextvars传递trace_id比手动改全局变量可靠得多。4.4 回放结果不一致不代表系统有bug很多次我把温度设为0信心十足地做回放结果模型还是给出不同答案。第一反应是“回放引擎有bug”后来发现并不是。主要原因有两个一是很多模型服务并不保证温度0就是严格确定性输出量化、批处理、随机种子都会影响结果二是回放和原始执行之间即使消息文本相同向量检索的排序也可能有微小变化排序一变模型关注的重点就变了。所以我在AgentTrace里会把“回放不一致”本身当作诊断信号如果某一步在回放中反复变化说明这一步对外部输入非常敏感需要优先优化上下文组装而不是非要逼模型输出一致。5. 给想上AgentTrace的团队几条个人建议5.1 先跑通单Agent不要一上来就做平台我希望你听进去的第一条建议是不要一开始就搭建什么“Agent可观测平台”。先给单个Agent接入trace记录一次完整运行确认能回答“它每一步做了什么”就够了。四张表、一个SDK、一个简单回放脚本三天内能做通。平台扩容、权限体系、大屏那是中期以后的事过早设计只会拖慢落地速度。5.2 把离线回放当作刚需而不只是锦上添花凡是做过Agent评估的人都会同意online跑测试又慢又贵。离线回放的价值在于你可以用录制好的trace批量跑不同prompt版本快速对比哪个prompt更稳定。它天然就是一套回归测试基础设施。我甚至用录制下来的失败trace来自动生成评测用例每次发版前跑一遍确保同样的问题不会悄悄地回归。5.3 留好数据保留策略别把所有trace都存成永久记录Agent trace会非常占空间尤其是工具返回大文本和图片。我目前的做法是三分法最近3天全量保留、最近30天保留结构化摘要和关键span、超过30天只保留trace_id、session_id和错误码。这个策略需要的存储量会很有限同时也能满足大多数排查和审计需求。真要追查一个月前的细节问题至少还能通过摘要判断从哪一天开始出现问题。5.4 一个让我改变最大习惯的使用方式装完AgentTrace之后我最大的变化不是多了一个排查工具而是改变了排查思路。以前遇到Agent表现异常第一反应是改prompt或换模型现在第一反应是先打开trace回放看它到底在哪一步读到了什么。很多时候问题根本不是模型不好而是上下文里混入了旧信息或者工具返回内容超出了prompt的预期格式。先看到现场再动手改这是做Agent工程之后最重要的一条经验。如果你手头正在被Agent调试折磨我真心建议你从今天开始给一次完整运行做录制。不需要太长一个失败案例就够了。先能把trace回放出来再谈优化效果。等你哪天真遇到“用户投诉但完全不知道发生了什么”的时候你一定会感谢自己当时装了这台行车记录仪。
