做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( project="shopping_agent", store="./sessions", embed_model="text-embedding-3-small", reach_threshold=0.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可能把“外面下雨会不会影响送货”这类问题错误地路由到了天气工具上。这种跨状态滥用工具的行为，靠看日志是绝对发现不了的。

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 排查速查表

我把这半年里用户问得最多、我自己也踩过的问题整理成了一张速查表，排障效率会高很多。

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协作这类复杂系统，这种视角几乎是刚需。如果你想试，我建议别追求一步到位，先挑一个你最头疼的小场景，挂上探针跑个几十条轨迹，看看生成的行为图是什么样的。那一眼下去，很多以前没想明白的问题的轮廓，其实就已经出来了。