做Agent开发做得越久越发现一个尴尬的事实大家都很会写Agent但很少有人说清楚自己手上这个Agent到底“能到哪”。这里的“能到哪”不是指它能回答多少问题而是它在一个真实任务里能走多远、会触发哪些行为、在什么条件下彻底卡死。我做的这个项目Agent-Reach就是专门回答这个问题的——给Agent做一次行为空间的全景扫描输出一份可达性报告帮你弄清楚它能力强在哪里、边界在哪里、为什么会突然抽风。适合正在做LLM Agent应用、多智能体系统以及那些被自家Agent的玄学行为折磨到怀疑人生的人。Agent-Reach这个名字拆开看就很直白Agent Reachability智能体可达性分析。核心思路是我这些年在实战里反复踩坑后总结出来的评价一个Agent不能只看它的最终输出整个行动过程才是真正值得研究的东西。只有把Agent的每次运行过程记录下来分析它在状态空间里实际到达过的位置才有可能把那些隐藏在长尾case里的问题挖出来。这篇博文就来聊聊我是怎么设计这个项目的、具体怎么用、以及在落地过程中踩过的那些值得记录的坑。1. Agent-Reach要解决什么问题1.1 做Agent开发时最头疼的三个问题先说说我为什么想要做这么个东西。过去两年我一共上手过三个Agent项目一个是电商客服助手一个是内部知识库问答还有一个是多Agent协作的工单系统。开发过程中暴露出来的问题惊人地一致总结下来大概就三类。第一类是死循环和静默失败。ReAct循环搭好之后Agent在某个边界情况下来回调用同一个工具或者调用完工具之后直接不出结果就结束——代码层面没报错日志看起来也正常但任务就是没完成。最麻烦的是这种问题还不是必现的换一个用户提问的措辞可能就触发了。第二类是改动回归。今天优化了一个提示词顺手修掉了一个case结果过两天发现原本跑得好好的另一个case挂了。你根本说不清是哪一次改动破坏的因为Agent的行为空间太大靠人脑去推断因果关系已经远远不够了。第三类是能力边界不透明。给Agent接了五个工具它到底哪个工具用得好、哪个工具几乎不用、哪个工具在什么状态下会瞎用我心里一点数都没有。靠人工构造测试用例去覆盖成本极高而且永远觉得自己在盲人摸象。这些问题的本质其实是同一个Agent的行为空间太大大到靠人的直觉和手工测试根本覆盖不全。我需要一种手段能自动把已经发生过的行为路径记录下来把大量失败的轨迹聚合起来告诉我问题到底出在哪个状态节点上。这也是Agent-Reach最早期的原型动机。1.2 “Reach”这个词到底想表达什么“可达性”Reachability是图论和自动机理论里的经典概念。简单说就是给定一个初始状态、一组状态转移规则问“哪些状态是可能到达的”。放到Agent语境里就是给定一个系统提示词、一个用户目标、一组工具定义问“Agent在运行过程中可能到达哪些中间状态、哪些终态”。我举个生活例子帮没接触过图论的读者理解。假设奶茶店来了一个新店员你安排他去接待顾客。作为店长你最关心的不是他今天有没有卖出奶茶那是最终输出而是他在面对以下这些状态时的反应顾客问“有没有无糖选项”、顾客说“我要等很久吗”、顾客投诉“上一杯做错了”、收银机突然死机。每一个状态都对应着店员可能做出的不同动作而所有状态和动作连起来就是这位店员的行为空间。Agent-Reach做的事情就是把这个行为空间画出来给你看。用上的时候你会觉得这个概念特别自然。没有这套视角之前你看Agent的运行就是一条一条日志有了图视角之后你看到的是整个行为空间里哪些区域被Agent跑过了、哪些区域从来没被触达过、哪些区域的路径又深又臭又反复。1.3 这个项目适合谁来用我整理了一下实际场景下面这几类人用Agent-Reach的收益是最大的。第一类是把Agent接了很多外部工具的人。工具越多分支越复杂权限边界越模糊。你给Agent配了一个发邮件的工具它到底在什么情况下会发邮件是用户明确要求才发还是它自以为应该发就发了这种问题不通过行为轨迹分析很难定位下来。第二类是用LangGraph这类图框架搭Agent的人。框架本身能帮你编排流程但编排完之后节点之间真实的行为分布是个黑盒。我遇到过很多人跑来问“为什么我的Agent在某个节点上反复横跳”这种问题拿Agent-Reach跑一遍立刻就能看到那个节点上的回环边。第三类是做多Agent协作系统的人。多个Agent之间互相发消息谁能收到、谁能处理、谁会把消息吞掉这种消息触达矩阵单靠日志很难统计。Agent-Reach可以用统一的trace_id跨Agent串起来把整个协作过程映射成一张多Agent共享的行为图。2. 核心设计思路把Agent的每次行动变成一张可达图2.1 三个核心抽象状态、动作、轨迹既然要做可达性分析第一步就得想清楚Agent的“状态”到底怎么定义。这是整个项目中最关键也最容易被搞砸的设计决策。一开始我试过把完整对话历史当作状态来记录。结果很快就发现一个严重问题状态空间爆炸得根本没法看。一个稍复杂的Agent对话历史稍微一长每次关键分支产生的上下文组合数量就是天文数字。而且很多状态在语义上其实是等价的比如“用户在问退款进度还没提供订单号”和“用户在问物流进度还没提供订单号”这两者作为状态对于分析Agent的行为能力来说本质上是同一个节点。所以Agent-Reach采用的做法是把每轮LLM调用前后的上下文快照做一次语义归约。具体实现是取当前消息列表的关键部分、当前待执行的工具调用、当前可用的工具集合这三样信息压成一个上下文向量再用embedding模型做语义聚类。相似度超过阈值的上下文就归并成一个状态节点。这套思路跑下来一个原本可能有几万个原始状态的任务最终会被压缩成几十到几百个有分析价值的状态节点——这个数量级才是人能看懂、机器能分析的。动作的定义相对简单。一次工具调用是一条边直接回复用户并结束是一次终态动作调用了某个服务但抛异常也是一次特殊动作。每条边的权重是这个动作在这个状态下被实际执行过的次数。轨迹就是一条从初始状态到终止状态的路径。Agent在真实环境里跑一百次就会留下一百条轨迹一百条轨迹在共享的状态节点上交汇、分流最终形成一张带权重的有向图。分析Agent本质上就是分析这张图。2.2 可达性分析算的是什么账拿到图之后Agent-Reach要回答的是四个层面的问题。第一层是可到达性哪些状态被访问过、哪些状态理论上可能出现但从未出现。访问不到的状态有两种原因要么是Agent能力不够导致它永远走不到那一步要么是前置条件在数据里就没人触发过。这两种原因的鉴别方式不太一样后面会讲。第二层是卡死点。存在一批状态Agent进入之后能做出的动作极其有限或者动作做完了却无法进入下一个有效状态。这种卡死点在行为图上表现为高入度、低出度的节点很多失败轨迹都汇聚到这里就断了。第三层是终止状态分布。一次Agent运行最后是怎么结束的是正常回复、主动放弃、工具超时、还是触发最大轮数被强制中断。把一百次运行的终态画成饼图你会发现有些Agent的失败率高得离谱但这在平时看单条日志时很难形成全局感知。第四层是状态转移的成功率。从状态S出发到状态T这条边被走了很多次但到了T之后能继续走下去的比例有多高如果比例很低说明S和T之间存在某种语义断层。计算这些指标有一个核心难点Agent的转移并不是确定性的。工具调用的结果来自外部真实世界LLM的下一步决策又带随机性同样的状态可能通向不同的下一跳。我的处理策略是分层建模对于确定性动作比如工具输入输出是固定映射的用BFS做完整的枚举展开对于LLM决策动作用多次rollout采样来逼近。默认每轮采样20条轨迹然后把两部分的展开结果合并成一张估算可达图。这个方案不是精确解但工程上完全够用。2.3 为什么是图而不是日志有人可能会问普通日志不也一样能记录Agent干了什么吗为什么非要整一张图出来我自己的体会是日志是线性结构你只能顺着时间轴一条一条往下看。但Agent的问题往往是结构性的——十几条不同的轨迹最后都撞到同一个失败状态这种事用日志根本没法定量发现。日志能告诉你“这里报错了”但没法告诉你“所有报错的路径占多少比例、它们的共同前缀是什么”。图结构天然擅长表达汇合和分流。同一个失败状态前面汇聚了多种路径说明这个失败点是系统性的一个高权重的工具调用之后连接着大面积的死胡同说明这个工具的使用策略有问题。Agent-Reach在内存里维护一个全局图每次运行完任务后轨迹增量归并到图上最终可以导出成GraphJSON格式也可以渲染成交互式可视化页面。我做过的最有价值的操作之一就是拉着一张渲染好的行为图指着上面某个节点跟团队成员说“所有失败的case最后都停在这问题就出在这。”——那一次讨论的效率比看十页日志高得多。3. 实操过程从零开始跑一次Agent可达性分析3.1 安装与初始化Agent-Reach目前以Python包的形式分发依赖的东西不多核心就三个一个embedding模型用于状态语义归约一个图存储后端默认是Neo4j也可以改用SQLite以及你要接入的Agent框架对应的SDK。安装命令很简单pip install agent-reach[all]安装完成后在Agent的主进程入口初始化项目import agent_reach as reach reach.init( projectshopping_agent, store./sessions, embed_modeltext-embedding-3-small, reach_threshold0.92 )这里有个参数值得重点解释一下reach_threshold就是前面说的状态归约阈值。我把两个上下文向量做余弦相似度计算超过0.92就视为同一个状态。这个值调低会得到更少、更抽象的状态节点调高会保留更多细节但节点数会变多。我的建议是新手先按0.90到0.93起手看生成的报告再逐步调整。3.2 给Agent装探针Agent-Reach提供了两种打点方式对应不同的接入场景。第一种方式是装饰器。适合你已经写好了自己的Agent逻辑直接在每个工具函数上手动标记即可import agent_reach as reach reach.trace_action(search_products) def search_products(keyword: str): # 模拟一个商品搜索工具 return es_search(keyword) reach.trace_action(create_refund) def create_refund(order_id: str, reason: str): ...第二种方式是自动补丁。适合你用的是LangChain、LlamaIndex这类成熟框架不想改动内部代码直接用一行代码挂载全局探针reach.patch_openai() # 自动包装OpenAI SDK调用的打点 reach.patch_langchain() # 自动包装LangChain的chain调用和tool调用这两种方式我都实际用过。装饰器方式最可控你可以精确控制哪些函数需要打点、哪些参数需要记录、哪些返回值需要截断自动补丁方式胜在省事几分钟就能给存量项目加上全套追踪能力缺点是会记录到一些你不关心的内部调用导致报告里的噪音多一些。我目前的建议是新项目直接用装饰器老项目先用自动补丁跑起来看效果再逐步裁剪。3.3 跑一次任务并生成报告探针挂好之后正常跑Agent的任务循环行为数据会源源不断写入本地session目录。跑完一批任务后在命令行执行agent-reach analyze --session-dir ./sessions --output report.html这个命令会做四件事读取所有轨迹数据、做语义归约构建行为图、计算各类可达性指标、生成一个独立的HTML报告文件。报告的主要内容包括一张交互式DAG图、状态列表每个节点标注了入度出度、访问次数、失败率、终止状态分布饼图以及一份自动聚类后的失败路径清单。我拿之前那个电商客服Agent来举个例子。第一次跑完报告后数字非常扎眼状态数量一共87个看起来不算多但其中有11个状态的出度是0也就是Agent走进这11个状态后就没下文了。进一步看失败路径聚合发现大量的失败轨迹都汇聚到一个叫“等待用户补充订单号”的状态上占比32%。这个状态的含义是用户在问退款进度但Agent手头没有订单号不知道应该反问用户索要订单号就那么在原地兜圈子直到最大轮数被打断。这个case在手工测试里几乎不可能被覆盖到但Agent-Reach用一次批量跑测就把它捞出来了。3.4 报告里的核心指标怎么读报告里最值得关注的几个指标我列成了表格便于参考指标含义我在实践中怎么用它状态覆盖率实际访问状态数 / 估算可达状态空间大小覆盖率偏低说明Agent不擅长探索需要优化指令引导终态分布成功、放弃、超时、异常四类终止的比例放弃比例高通常是上下文理解问题超时多通常是工具卡死失败路径聚类所有失败轨迹按共同前缀聚合出的类别直接决定你下一个修复任务该排到哪个节点上动作可达矩阵每个状态下各候选动作被执行过的次数发现“配了工具但根本没被用过”的配角工具回环边占比图中指向已访问状态且重复过多次的边回环边居高不下就是死循环的前兆要重点排查我特别想说一下“动作可达矩阵”因为它帮我发现过一个很隐蔽的毛病。当时系统里接了一个“天气查询”工具我本以为Agent会在用户提到天气时才调用它。结果矩阵显示这个工具在“用户咨询配送时间”的状态下居然被调用过很多次——Agent可能把“外面下雨会不会影响送货”这类问题错误地路由到了天气工具上。这种跨状态滥用工具的行为靠看日志是绝对发现不了的。4. 落地时踩过的坑与排查技巧4.1 状态空间爆炸了怎么办我第一次把Agent-Reach用在内部知识库Agent上时报告生成到一半内存直接快被打爆了。一看日志状态数量暴到了几万个。原因有两个一是这个Agent本身有十几个工具路径天然就多二是当时我把上下文快照设置成了全量对话历史每轮对话的变化都会产生近乎新的状态。这个坑我后来用三招填平了。第一招是“只记录决策相关的上下文”就是归约时只取最近四轮的消息摘要而不是全量历史。这符合LLM决策的特点——决定下一步动作时真正起作用的是最近的上下文窗口。第二招是“控制每个状态的扩展边数”默认每个状态最多展开20条出边超出就做随机采样避免某些高分支状态把图冲爆。第三招是在归约前嵌入模型选一个轻量款。用一个大的向量模型跑几百上千个状态嵌入是没问题的但状态多到花式成本立刻就压不住了。4.2 异步调用采集不到轨迹有一个版本我拿它去追踪一个重度使用Async的Agent结果发现报告里轨迹数量少得可怜好几类工具调用完全没被采集到。排查之后发现根源在于全局探针patch的是OpenAI SDK的同步方法而这个Agent是走异步入口调用LLM的两个路径根本不重叠。我最后是用两层方式解决。第一层在Agent的主循环里维护一个contextvars变量作为trace_id这样异步任务切换也不会丢失上下文关联第二层底层直接给httpx这个网络库做了transport插桩统一拦截所有走HTTP的LLM调用这样同步和异步入口就都能被覆盖而且顺带把普通REST工具调用都记录了下来。这之后采集就稳定了。这个经验后来也被我写进了项目的FAQ里。4.3 敏感数据污染状态图的问题这是个必须严肃对待的问题。Agent在运行过程中工具调用参数和返回值里很可能夹带着用户隐私、内部token、API密钥等敏感信息。这些信息一旦被Agent-Reach记录进状态图轻则污染分析结果重则造成数据泄露事故。Agent-Reach内置了一个脱敏机制正则匹配疑似密码、token、key等格式的字符串并替换成占位符同时允许你在装饰器里显式标注敏感参数。我建议只要是要上生产环境的Agent脱敏措施一个都不能省。控制台里可以临时输出敏感值方便调试但凡是落盘到session目录里的内容一律过一遍脱敏器再写。4.4 排查速查表我把这半年里用户问得最多、我自己也踩过的问题整理成了一张速查表排障效率会高很多。现象大概率原因解决动作报告里完全没有轨迹探针挂载时机太晚Agent库已被实例化在import Agent框架之前先执行reach.init图上只有一个孤零零的节点embedding模型接口报错归约失败查看日志里的embedding调用记录检查网络或API key状态节点过多或过少reach_threshold设置不匹配节点过多就调低阈值节点过少就调高每次微调0.02工具参数记录为空装饰器包装在async函数上时的误用改用transport插桩方式或把装饰器挂在同步包装层报告生成时进程崩溃数据量超出内存上限缩小样本集或把归档的旧session清空只保留最近批次可视化页面打开是白屏报告HTML依赖CDN资源无法离线加载用agent-reach analyze --local-assets 生成全内嵌报告5. 在真实项目里Agent-Reach还能扩展出哪些玩法5.1 拿它当测试用例生成器用分析行为图和失败路径的副产品是一批高质量的测试用例。Agent-Reach可以把所有未成功终止的失败轨迹自动转成“回归测试种子”——每条失败轨迹都包含完整的初始输入和前置状态你只要把它的prompt和上下文快照保存下来就成了一条可复现的回归case。我实际用过这个能力补过测试集。以前手工构造用例绞尽脑汁也就写了30多条还都是些常规happy path。用Agent-Reach跑完一次生产日志回放之后自动生成了124个边界case其中绝大多数是我想破脑袋也编不出来的真实用户query和边界状态组合。把这些case灌回测试流水线之后后续每次改prompt或换模型回归出来的问题量级清晰了不少。5.2 多Agent协作时的触达矩阵你说两个Agent协作比如一个调度主Agent一个执行Agent那“主Agent发出的消息执行Agent到底有没有正确处理”这个问题比看上去要难回答。Agent-Reach做多Agent追踪时会给每个Agent各挂一套探针然后用同一个trace_id跨Agent串起一条完整链路。最终生成的图里节点上标注了Agent实例ID边则对应一条跨Agent消息或一个内部调用。侦探一下这是我最近在工单系统上做的一个尝试。跑了几百个工单流程后发现调度Agent发给执行Agent的格式化指令里有一种状态更新消息的格式和执行Agent内部解析器的预期不一致导致10%左右的工单执行完没有回传结果。靠人工看日志的话基本不可能从几千条消息里统计出这个比率但行为图上一看就特别明显有一条边权重很高但下游终态分布里有一块明显的死区。5.3 行为图diff回归对比的利器最后说一个我正在推进的方向行为图差异对比。现在每次改prompt、换模型、加新工具我都会导出两份行为图做diff直接看哪些节点是新增的、哪些节点消失了、哪些边的权重发生了大幅变化。有了这个之后“我改了一个prompt到底影响了哪些行为分支”这个问题就有了相对确定的回答。目前diff子命令已经在开发当中。我一开始会拿它来做每次小版本发布之前的回归对比把改动涉及的节点差异拉成一张清晰的清单让评审流程有据可依也希望它能成为一个大家都愿意长期用的检查习惯。我自己把Agent-Reach用在几个项目上的整体感受是它让Agent的开发从“写代码-看日志-猜原因”的混沌状态变成了“建图-看指标-定位问题-回归对比”的工程化循环。尤其对多工具、多分支、多Agent协作这类复杂系统这种视角几乎是刚需。如果你想试我建议别追求一步到位先挑一个你最头疼的小场景挂上探针跑个几十条轨迹看看生成的行为图是什么样的。那一眼下去很多以前没想明白的问题的轮廓其实就已经出来了。
做Agent开发做得越久越发现一个尴尬的事实大家都很会写Agent但很少有人说清楚自己手上这个Agent到底“能到哪”。这里的“能到哪”不是指它能回答多少问题而是它在一个真实任务里能走多远、会触发哪些行为、在什么条件下彻底卡死。我做的这个项目Agent-Reach就是专门回答这个问题的——给Agent做一次行为空间的全景扫描输出一份可达性报告帮你弄清楚它能力强在哪里、边界在哪里、为什么会突然抽风。适合正在做LLM Agent应用、多智能体系统以及那些被自家Agent的玄学行为折磨到怀疑人生的人。Agent-Reach这个名字拆开看就很直白Agent Reachability智能体可达性分析。核心思路是我这些年在实战里反复踩坑后总结出来的评价一个Agent不能只看它的最终输出整个行动过程才是真正值得研究的东西。只有把Agent的每次运行过程记录下来分析它在状态空间里实际到达过的位置才有可能把那些隐藏在长尾case里的问题挖出来。这篇博文就来聊聊我是怎么设计这个项目的、具体怎么用、以及在落地过程中踩过的那些值得记录的坑。1. Agent-Reach要解决什么问题1.1 做Agent开发时最头疼的三个问题先说说我为什么想要做这么个东西。过去两年我一共上手过三个Agent项目一个是电商客服助手一个是内部知识库问答还有一个是多Agent协作的工单系统。开发过程中暴露出来的问题惊人地一致总结下来大概就三类。第一类是死循环和静默失败。ReAct循环搭好之后Agent在某个边界情况下来回调用同一个工具或者调用完工具之后直接不出结果就结束——代码层面没报错日志看起来也正常但任务就是没完成。最麻烦的是这种问题还不是必现的换一个用户提问的措辞可能就触发了。第二类是改动回归。今天优化了一个提示词顺手修掉了一个case结果过两天发现原本跑得好好的另一个case挂了。你根本说不清是哪一次改动破坏的因为Agent的行为空间太大靠人脑去推断因果关系已经远远不够了。第三类是能力边界不透明。给Agent接了五个工具它到底哪个工具用得好、哪个工具几乎不用、哪个工具在什么状态下会瞎用我心里一点数都没有。靠人工构造测试用例去覆盖成本极高而且永远觉得自己在盲人摸象。这些问题的本质其实是同一个Agent的行为空间太大大到靠人的直觉和手工测试根本覆盖不全。我需要一种手段能自动把已经发生过的行为路径记录下来把大量失败的轨迹聚合起来告诉我问题到底出在哪个状态节点上。这也是Agent-Reach最早期的原型动机。1.2 “Reach”这个词到底想表达什么“可达性”Reachability是图论和自动机理论里的经典概念。简单说就是给定一个初始状态、一组状态转移规则问“哪些状态是可能到达的”。放到Agent语境里就是给定一个系统提示词、一个用户目标、一组工具定义问“Agent在运行过程中可能到达哪些中间状态、哪些终态”。我举个生活例子帮没接触过图论的读者理解。假设奶茶店来了一个新店员你安排他去接待顾客。作为店长你最关心的不是他今天有没有卖出奶茶那是最终输出而是他在面对以下这些状态时的反应顾客问“有没有无糖选项”、顾客说“我要等很久吗”、顾客投诉“上一杯做错了”、收银机突然死机。每一个状态都对应着店员可能做出的不同动作而所有状态和动作连起来就是这位店员的行为空间。Agent-Reach做的事情就是把这个行为空间画出来给你看。用上的时候你会觉得这个概念特别自然。没有这套视角之前你看Agent的运行就是一条一条日志有了图视角之后你看到的是整个行为空间里哪些区域被Agent跑过了、哪些区域从来没被触达过、哪些区域的路径又深又臭又反复。1.3 这个项目适合谁来用我整理了一下实际场景下面这几类人用Agent-Reach的收益是最大的。第一类是把Agent接了很多外部工具的人。工具越多分支越复杂权限边界越模糊。你给Agent配了一个发邮件的工具它到底在什么情况下会发邮件是用户明确要求才发还是它自以为应该发就发了这种问题不通过行为轨迹分析很难定位下来。第二类是用LangGraph这类图框架搭Agent的人。框架本身能帮你编排流程但编排完之后节点之间真实的行为分布是个黑盒。我遇到过很多人跑来问“为什么我的Agent在某个节点上反复横跳”这种问题拿Agent-Reach跑一遍立刻就能看到那个节点上的回环边。第三类是做多Agent协作系统的人。多个Agent之间互相发消息谁能收到、谁能处理、谁会把消息吞掉这种消息触达矩阵单靠日志很难统计。Agent-Reach可以用统一的trace_id跨Agent串起来把整个协作过程映射成一张多Agent共享的行为图。2. 核心设计思路把Agent的每次行动变成一张可达图2.1 三个核心抽象状态、动作、轨迹既然要做可达性分析第一步就得想清楚Agent的“状态”到底怎么定义。这是整个项目中最关键也最容易被搞砸的设计决策。一开始我试过把完整对话历史当作状态来记录。结果很快就发现一个严重问题状态空间爆炸得根本没法看。一个稍复杂的Agent对话历史稍微一长每次关键分支产生的上下文组合数量就是天文数字。而且很多状态在语义上其实是等价的比如“用户在问退款进度还没提供订单号”和“用户在问物流进度还没提供订单号”这两者作为状态对于分析Agent的行为能力来说本质上是同一个节点。所以Agent-Reach采用的做法是把每轮LLM调用前后的上下文快照做一次语义归约。具体实现是取当前消息列表的关键部分、当前待执行的工具调用、当前可用的工具集合这三样信息压成一个上下文向量再用embedding模型做语义聚类。相似度超过阈值的上下文就归并成一个状态节点。这套思路跑下来一个原本可能有几万个原始状态的任务最终会被压缩成几十到几百个有分析价值的状态节点——这个数量级才是人能看懂、机器能分析的。动作的定义相对简单。一次工具调用是一条边直接回复用户并结束是一次终态动作调用了某个服务但抛异常也是一次特殊动作。每条边的权重是这个动作在这个状态下被实际执行过的次数。轨迹就是一条从初始状态到终止状态的路径。Agent在真实环境里跑一百次就会留下一百条轨迹一百条轨迹在共享的状态节点上交汇、分流最终形成一张带权重的有向图。分析Agent本质上就是分析这张图。2.2 可达性分析算的是什么账拿到图之后Agent-Reach要回答的是四个层面的问题。第一层是可到达性哪些状态被访问过、哪些状态理论上可能出现但从未出现。访问不到的状态有两种原因要么是Agent能力不够导致它永远走不到那一步要么是前置条件在数据里就没人触发过。这两种原因的鉴别方式不太一样后面会讲。第二层是卡死点。存在一批状态Agent进入之后能做出的动作极其有限或者动作做完了却无法进入下一个有效状态。这种卡死点在行为图上表现为高入度、低出度的节点很多失败轨迹都汇聚到这里就断了。第三层是终止状态分布。一次Agent运行最后是怎么结束的是正常回复、主动放弃、工具超时、还是触发最大轮数被强制中断。把一百次运行的终态画成饼图你会发现有些Agent的失败率高得离谱但这在平时看单条日志时很难形成全局感知。第四层是状态转移的成功率。从状态S出发到状态T这条边被走了很多次但到了T之后能继续走下去的比例有多高如果比例很低说明S和T之间存在某种语义断层。计算这些指标有一个核心难点Agent的转移并不是确定性的。工具调用的结果来自外部真实世界LLM的下一步决策又带随机性同样的状态可能通向不同的下一跳。我的处理策略是分层建模对于确定性动作比如工具输入输出是固定映射的用BFS做完整的枚举展开对于LLM决策动作用多次rollout采样来逼近。默认每轮采样20条轨迹然后把两部分的展开结果合并成一张估算可达图。这个方案不是精确解但工程上完全够用。2.3 为什么是图而不是日志有人可能会问普通日志不也一样能记录Agent干了什么吗为什么非要整一张图出来我自己的体会是日志是线性结构你只能顺着时间轴一条一条往下看。但Agent的问题往往是结构性的——十几条不同的轨迹最后都撞到同一个失败状态这种事用日志根本没法定量发现。日志能告诉你“这里报错了”但没法告诉你“所有报错的路径占多少比例、它们的共同前缀是什么”。图结构天然擅长表达汇合和分流。同一个失败状态前面汇聚了多种路径说明这个失败点是系统性的一个高权重的工具调用之后连接着大面积的死胡同说明这个工具的使用策略有问题。Agent-Reach在内存里维护一个全局图每次运行完任务后轨迹增量归并到图上最终可以导出成GraphJSON格式也可以渲染成交互式可视化页面。我做过的最有价值的操作之一就是拉着一张渲染好的行为图指着上面某个节点跟团队成员说“所有失败的case最后都停在这问题就出在这。”——那一次讨论的效率比看十页日志高得多。3. 实操过程从零开始跑一次Agent可达性分析3.1 安装与初始化Agent-Reach目前以Python包的形式分发依赖的东西不多核心就三个一个embedding模型用于状态语义归约一个图存储后端默认是Neo4j也可以改用SQLite以及你要接入的Agent框架对应的SDK。安装命令很简单pip install agent-reach[all]安装完成后在Agent的主进程入口初始化项目import agent_reach as reach reach.init( projectshopping_agent, store./sessions, embed_modeltext-embedding-3-small, reach_threshold0.92 )这里有个参数值得重点解释一下reach_threshold就是前面说的状态归约阈值。我把两个上下文向量做余弦相似度计算超过0.92就视为同一个状态。这个值调低会得到更少、更抽象的状态节点调高会保留更多细节但节点数会变多。我的建议是新手先按0.90到0.93起手看生成的报告再逐步调整。3.2 给Agent装探针Agent-Reach提供了两种打点方式对应不同的接入场景。第一种方式是装饰器。适合你已经写好了自己的Agent逻辑直接在每个工具函数上手动标记即可import agent_reach as reach reach.trace_action(search_products) def search_products(keyword: str): # 模拟一个商品搜索工具 return es_search(keyword) reach.trace_action(create_refund) def create_refund(order_id: str, reason: str): ...第二种方式是自动补丁。适合你用的是LangChain、LlamaIndex这类成熟框架不想改动内部代码直接用一行代码挂载全局探针reach.patch_openai() # 自动包装OpenAI SDK调用的打点 reach.patch_langchain() # 自动包装LangChain的chain调用和tool调用这两种方式我都实际用过。装饰器方式最可控你可以精确控制哪些函数需要打点、哪些参数需要记录、哪些返回值需要截断自动补丁方式胜在省事几分钟就能给存量项目加上全套追踪能力缺点是会记录到一些你不关心的内部调用导致报告里的噪音多一些。我目前的建议是新项目直接用装饰器老项目先用自动补丁跑起来看效果再逐步裁剪。3.3 跑一次任务并生成报告探针挂好之后正常跑Agent的任务循环行为数据会源源不断写入本地session目录。跑完一批任务后在命令行执行agent-reach analyze --session-dir ./sessions --output report.html这个命令会做四件事读取所有轨迹数据、做语义归约构建行为图、计算各类可达性指标、生成一个独立的HTML报告文件。报告的主要内容包括一张交互式DAG图、状态列表每个节点标注了入度出度、访问次数、失败率、终止状态分布饼图以及一份自动聚类后的失败路径清单。我拿之前那个电商客服Agent来举个例子。第一次跑完报告后数字非常扎眼状态数量一共87个看起来不算多但其中有11个状态的出度是0也就是Agent走进这11个状态后就没下文了。进一步看失败路径聚合发现大量的失败轨迹都汇聚到一个叫“等待用户补充订单号”的状态上占比32%。这个状态的含义是用户在问退款进度但Agent手头没有订单号不知道应该反问用户索要订单号就那么在原地兜圈子直到最大轮数被打断。这个case在手工测试里几乎不可能被覆盖到但Agent-Reach用一次批量跑测就把它捞出来了。3.4 报告里的核心指标怎么读报告里最值得关注的几个指标我列成了表格便于参考指标含义我在实践中怎么用它状态覆盖率实际访问状态数 / 估算可达状态空间大小覆盖率偏低说明Agent不擅长探索需要优化指令引导终态分布成功、放弃、超时、异常四类终止的比例放弃比例高通常是上下文理解问题超时多通常是工具卡死失败路径聚类所有失败轨迹按共同前缀聚合出的类别直接决定你下一个修复任务该排到哪个节点上动作可达矩阵每个状态下各候选动作被执行过的次数发现“配了工具但根本没被用过”的配角工具回环边占比图中指向已访问状态且重复过多次的边回环边居高不下就是死循环的前兆要重点排查我特别想说一下“动作可达矩阵”因为它帮我发现过一个很隐蔽的毛病。当时系统里接了一个“天气查询”工具我本以为Agent会在用户提到天气时才调用它。结果矩阵显示这个工具在“用户咨询配送时间”的状态下居然被调用过很多次——Agent可能把“外面下雨会不会影响送货”这类问题错误地路由到了天气工具上。这种跨状态滥用工具的行为靠看日志是绝对发现不了的。4. 落地时踩过的坑与排查技巧4.1 状态空间爆炸了怎么办我第一次把Agent-Reach用在内部知识库Agent上时报告生成到一半内存直接快被打爆了。一看日志状态数量暴到了几万个。原因有两个一是这个Agent本身有十几个工具路径天然就多二是当时我把上下文快照设置成了全量对话历史每轮对话的变化都会产生近乎新的状态。这个坑我后来用三招填平了。第一招是“只记录决策相关的上下文”就是归约时只取最近四轮的消息摘要而不是全量历史。这符合LLM决策的特点——决定下一步动作时真正起作用的是最近的上下文窗口。第二招是“控制每个状态的扩展边数”默认每个状态最多展开20条出边超出就做随机采样避免某些高分支状态把图冲爆。第三招是在归约前嵌入模型选一个轻量款。用一个大的向量模型跑几百上千个状态嵌入是没问题的但状态多到花式成本立刻就压不住了。4.2 异步调用采集不到轨迹有一个版本我拿它去追踪一个重度使用Async的Agent结果发现报告里轨迹数量少得可怜好几类工具调用完全没被采集到。排查之后发现根源在于全局探针patch的是OpenAI SDK的同步方法而这个Agent是走异步入口调用LLM的两个路径根本不重叠。我最后是用两层方式解决。第一层在Agent的主循环里维护一个contextvars变量作为trace_id这样异步任务切换也不会丢失上下文关联第二层底层直接给httpx这个网络库做了transport插桩统一拦截所有走HTTP的LLM调用这样同步和异步入口就都能被覆盖而且顺带把普通REST工具调用都记录了下来。这之后采集就稳定了。这个经验后来也被我写进了项目的FAQ里。4.3 敏感数据污染状态图的问题这是个必须严肃对待的问题。Agent在运行过程中工具调用参数和返回值里很可能夹带着用户隐私、内部token、API密钥等敏感信息。这些信息一旦被Agent-Reach记录进状态图轻则污染分析结果重则造成数据泄露事故。Agent-Reach内置了一个脱敏机制正则匹配疑似密码、token、key等格式的字符串并替换成占位符同时允许你在装饰器里显式标注敏感参数。我建议只要是要上生产环境的Agent脱敏措施一个都不能省。控制台里可以临时输出敏感值方便调试但凡是落盘到session目录里的内容一律过一遍脱敏器再写。4.4 排查速查表我把这半年里用户问得最多、我自己也踩过的问题整理成了一张速查表排障效率会高很多。现象大概率原因解决动作报告里完全没有轨迹探针挂载时机太晚Agent库已被实例化在import Agent框架之前先执行reach.init图上只有一个孤零零的节点embedding模型接口报错归约失败查看日志里的embedding调用记录检查网络或API key状态节点过多或过少reach_threshold设置不匹配节点过多就调低阈值节点过少就调高每次微调0.02工具参数记录为空装饰器包装在async函数上时的误用改用transport插桩方式或把装饰器挂在同步包装层报告生成时进程崩溃数据量超出内存上限缩小样本集或把归档的旧session清空只保留最近批次可视化页面打开是白屏报告HTML依赖CDN资源无法离线加载用agent-reach analyze --local-assets 生成全内嵌报告5. 在真实项目里Agent-Reach还能扩展出哪些玩法5.1 拿它当测试用例生成器用分析行为图和失败路径的副产品是一批高质量的测试用例。Agent-Reach可以把所有未成功终止的失败轨迹自动转成“回归测试种子”——每条失败轨迹都包含完整的初始输入和前置状态你只要把它的prompt和上下文快照保存下来就成了一条可复现的回归case。我实际用过这个能力补过测试集。以前手工构造用例绞尽脑汁也就写了30多条还都是些常规happy path。用Agent-Reach跑完一次生产日志回放之后自动生成了124个边界case其中绝大多数是我想破脑袋也编不出来的真实用户query和边界状态组合。把这些case灌回测试流水线之后后续每次改prompt或换模型回归出来的问题量级清晰了不少。5.2 多Agent协作时的触达矩阵你说两个Agent协作比如一个调度主Agent一个执行Agent那“主Agent发出的消息执行Agent到底有没有正确处理”这个问题比看上去要难回答。Agent-Reach做多Agent追踪时会给每个Agent各挂一套探针然后用同一个trace_id跨Agent串起一条完整链路。最终生成的图里节点上标注了Agent实例ID边则对应一条跨Agent消息或一个内部调用。侦探一下这是我最近在工单系统上做的一个尝试。跑了几百个工单流程后发现调度Agent发给执行Agent的格式化指令里有一种状态更新消息的格式和执行Agent内部解析器的预期不一致导致10%左右的工单执行完没有回传结果。靠人工看日志的话基本不可能从几千条消息里统计出这个比率但行为图上一看就特别明显有一条边权重很高但下游终态分布里有一块明显的死区。5.3 行为图diff回归对比的利器最后说一个我正在推进的方向行为图差异对比。现在每次改prompt、换模型、加新工具我都会导出两份行为图做diff直接看哪些节点是新增的、哪些节点消失了、哪些边的权重发生了大幅变化。有了这个之后“我改了一个prompt到底影响了哪些行为分支”这个问题就有了相对确定的回答。目前diff子命令已经在开发当中。我一开始会拿它来做每次小版本发布之前的回归对比把改动涉及的节点差异拉成一张清晰的清单让评审流程有据可依也希望它能成为一个大家都愿意长期用的检查习惯。我自己把Agent-Reach用在几个项目上的整体感受是它让Agent的开发从“写代码-看日志-猜原因”的混沌状态变成了“建图-看指标-定位问题-回归对比”的工程化循环。尤其对多工具、多分支、多Agent协作这类复杂系统这种视角几乎是刚需。如果你想试我建议别追求一步到位先挑一个你最头疼的小场景挂上探针跑个几十条轨迹看看生成的行为图是什么样的。那一眼下去很多以前没想明白的问题的轮廓其实就已经出来了。
