这两年做AI Agent落地我最大的感觉是模型越来越聪明落地却越来越心虚。规划器能写出一套逻辑上很像样的多步计划可真让Agent去执行往往第二步就断了——参数没填全、工具权限不够、依赖的上游结果根本不存在。Agent-Reach这个项目就是我把“智能体执行链路可达性”单独拎出来做的一套分析方案。它不负责教模型怎么规划而是负责在规划之后、执行之前回答一个关键问题这条动作路径到底走不走得通。为什么单独做这件事因为大部分Agent框架都默认“模型能生成计划计划就能执行”可现实里一个动作能不能被执行取决于状态、工具、数据、权限四类条件同时成立。Agent-Reach的核心就是把这种依赖关系显式建模用静态校验加模拟执行的方式提前把“不可达”的路径拦下来。这篇文章我会完整拆解这套方案的设计思路、核心实现、落地过程中踩过的坑以及从单Agent扩展到多Agent时需要注意什么。适合正在做Agent产品、经常被“计划跑不通”困扰的工程师参考。1. Agent-Reach到底解决什么问题1.1 为什么规划器总在“画饼”先说个非常典型的现场。你让Agent去处理一个售后工单“用户说账号被锁了帮我查原因并解锁。”LLM给出的计划大概是先查工单详情再查账号状态然后执行解锁最后给用户发通知。从自然语言角度看这个计划完美。但从工程角度看它什么都没保证。查工单需要工单号工单号哪里来账号状态需要数据库查询权限当前Agent有没有解锁这个动作是强权限操作回调审核通过了没有发送通知前解锁结果是否需要确认这就是我常说的“规划器画饼执行器背锅”。Agent-Reach的出发点很简单把每个动作的前置条件、权限要求、副作用结果显式化像编译器检查类型一样去检查计划链路。早期团队对这种方案是有犹豫的觉得多一层分析会拖慢响应。但实际跑下来你会发现慢这一两百毫秒远比你让Agent在执行到第三步时失败然后反复重试、回滚、清理脏数据要便宜得多。而且可达性分析结果还能回填到模型上下文里直接提升下一轮规划的质量。1.2 Agent-Reach的定位执行前的可达性校验层Agent-Reach不是重写一套Agent框架而是夹在“规划器”和“执行器”中间的一个校验层。它可以被设计成同步接口也可以做成异步服务。整体流程是模型先生成计划计划被解析成结构化动作序列Agent-Reach拿到当前系统快照和动作定义执行可达性分析输出一份报告报告里标记出每个步骤是否可执行、依赖是否满足、潜在冲突是什么。我在内部把它定义为三个能力一是可达性分析判断动作链路在逻辑上是否闭合二是依赖校验检查动作之间的数据依赖先后关系三是冲突检测识别状态冲突、资源竞争和权限不足。这三个能力组合起来基本覆盖了我在实际项目里遇到的大多数“计划看起来没问题但跑不动”的情况。需要注意的是这套校验层做的不是形式化验证。形式化验证在Agent场景里目前还太重状态空间爆炸问题很难处理。Agent-Reach更接近一种“工程化可达性检查”它用确定性的规则和轻量模拟把明显不可行的路径提前排除掉把可行性概率高的路径交还给执行器。1.3 五个最典型的“不可达”场景我在实践里总结了五种高频不可达场景做Agent-Reach的头两天就在对着这五个场景设计用例。第一种是状态不可达。执行到某个环节时要求前置状态成立但前置状态从未被任何动作建立。比如“已审批”这个字段计划里没有哪个动作会把它置为true后续的“打款”动作就永远不可能满足前置条件。第二种是工具不可达。计划引用了工具但当前环境里根本没有注册这个工具或者工具已下线、版本不兼容。这种情况在长尾工具链里特别常见模型可能从历史记忆里“编”出一个不存在的工具。第三种是权限不可达。动作本身存在状态也满足但执行主体没有对应权限。典型的就是普通客服Agent尝试执行“删除订单”这类高危操作。第四种是数据依赖不可达。一个动作需要上一个动作产出的结构化数据但计划顺序颠倒了或者上游动作的结果类型对不上。第五种是资源不可达。多个Agent并发执行时共享资源被占满比如同一个用户的工单同时被两个Agent处理单看每个Agent的计划都能走通放在全局看就死锁了。Agent-Reach这五个场景做下来给我最大的启发是不可达问题不是模型的“幻觉”问题而是系统工程问题。模型负责生成意图工程系统负责兜底可执行性。把责任边界划清楚问题才有解。2. 核心设计拆解四个维度的可达性分析2.1 从导航软件理解状态可达“可达性”这个概念最好用导航来类比。你让导航给一条从A到B的路线导航不会先让你开车上路再说而是先看路网拓扑、看封路信息、看限行规则最后才给出可行路线。如果某条路根本不通它就直接换一条。Agent规划也是同样的道理。状态空间就是路网每个动作就是一段路前置条件就是这段路的通行规则工具就是路上的交通工具。Agent-Reach做的就是把“路网”和“通行规则”建模出来在模型给出路径之后先跑一遍虚拟通行检查。这一层越扎实执行器的路就越顺。但Agent场景和导航有个关键区别路网是相对静态的而Agent的状态空间是动态的、时刻变化的。所以Agent-Reach不能只在计划生成时做一次静态分析还要结合系统当前的真实快照做动态模拟。这也是我在设计时反复权衡后确定的架构方向。2.2 四维模型状态、工具、资源、权限在代码层面我把一个动作的可达性拆成四个维度的检查用一张表说明会更直观。维度要回答的问题典型检查项失败后果状态可达前置状态是否满足字段存在性、取值、flag状态动作执行时报参数错误工具可达动作对应的工具是否存在可用工具注册表、版本、入参schema运行时找不到工具权限可达执行主体是否有权操作角色、资源级ACL、审批状态被鉴权系统拦截资源可达共享资源是否可竞争得到并发锁、配额、单用户互斥全局死锁或超时这个四维模型是后续所有分析代码的骨架。最开始我只做了“状态可达”和“工具可达”后发现权限和资源两个维度才是线上问题的大头尤其是权限很多Agent框架根本不检查全靠执行器报403才知道挂了。这里有个很重要的设计决策每次执行可达性分析时状态、工具、权限都要用“当前系统快照”不能用模型规划时假设的旧状态。比如Agent规划时认为订单状态是“待支付”实际用户在执行前几秒已经支付了如果还用旧状态分析结果就是误导。2.3 为什么先静态校验再动态模拟Agent-Reach的执行路径分成两段先静态、后动态。静态阶段不执行任何动作只做结构检查包括动作是否存在、参数schema是否匹配、权限角色是否满足、数据依赖顺序是否合理。这个阶段速度快成本低能拦截掉大约六成的问题。动态阶段则会对动作序列做一次“模拟执行”。注意这里的模拟不是真的调用外部API而是把每个动作的副作用按契约应用到本地状态副本上。比如“创建工单”这个动作的副作用是生成ticket_id并写入状态那我就在副本里模拟这个效果后续动作读取ticket_id时就能检查到。为什么先静态后动态因为动态模拟依赖静态分析提供的基础设施比如动作契约、状态字段映射、副作用表达式没有这些模拟就是空中楼阁。另一方面如果所有问题都靠动态模拟去发现状态空间组合爆炸会把你拖死。静态先粗筛动态再精查性价比最高。3. 实操把一个Agent计划跑通可达性分析3.1 定义状态与动作契约要落地Agent-Reach第一步不是写分析器而是定契约。我在项目里用的是非常朴素的结构化方案状态是一个扁平的字典动作是一个声明式契约。# 当前系统状态快照 STATE { user_id: 10086, account_locked: True, ticket_id: None, unlock_approved: False, notify_target: userexample.com, } # 工具注册表 TOOLS { fetch_ticket_detail: { description: 查询工单详情, preconditions: [ticket_id is not None], effects: [ticket_owner current_user], permission: support_agent, }, unlock_account: { description: 解锁指定账号, preconditions: [unlock_approved is True, account_locked is True], effects: [account_locked False, unlock_executed True], permission: support_manager, }, }写契约的时候最容易犯的错是偷懒把preconditions写成自然语言。我建议所有条件都用可解析的表达式字符串甚至直接用AST表达式这样分析器才能真正执行判断而不是拿正则去碰运气。生产环境里不要用eval我后面会在问题排查里专门说这个坑。权限字段我特意在工具契约里单独列出来因为Agent的权限模型和人的权限模型不太一样。Agent通常被授予“在特定状态下执行特定动作”的临时权限而不是简单的角色。所以Agent-Reach在权限检查里会加一层“上下文条件”比如unlock_account不仅要求support_manager角色还要求当前工单属于该Agent负责的范围。3.2 依赖收集与前置条件检查的完整流程状态和契约定义好之后分析流程就清晰了。我把它拆成四步。第一步解析计划。模型返回的计划要先转成结构化动作序列每个动作带上工具名和参数引用。参数引用很重要因为模型可能写的是“从上一步结果中取ticket_id”而不是具体的值。第二步构建依赖图。遍历动作序列找出每个动作读取了哪些状态字段、写入了哪些状态字段形成数据依赖边。比如“创建工单”写入ticket_id“查工单详情”读取ticket_id那前者就是后者的前置依赖。第三步拓扑排序。依赖图必须是无环的如果有环说明计划逻辑出了问题。我在这一步会输出一个可执行顺序后续模拟执行严格按这个顺序走。第四步逐动作检查并模拟状态转移。对每个动作先查前置条件表达式在当前状态副本上是否成立再查权限最后应用副作用更新状态副本进入下一个动作。def check_plan_reachability(plan, state, tools, roles): current_state dict(state) violations [] for step in plan: tool tools.get(step[tool]) if tool is None: violations.append({type: tool_unreachable, step: step}) break for cond in tool.get(preconditions, []): if not eval_expression(cond, current_state): violations.append({ type: state_unreachable, step: step, reason: f前置条件不满足: {cond} }) break if not check_permission(roles, current_state, tool.get(permission)): violations.append({ type: permission_unreachable, step: step, reason: f缺少权限: {tool.get(permission)} }) break # 模拟副作用 current_state apply_effects(current_state, tool.get(effects, [])) step[resolved_state] dict(current_state) return current_state, violations这段代码看起来简单但它是整个Agent-Reach的引擎核心。生产版本里我不会用eval_expression直接对字符串做eval而是把条件表达式解析成语义树再求值。副作用同样用结构化的赋值表达式描述避免对状态字典做任意修改。3.3 模拟执行与可达性报告模拟执行跑完之后Agent-Reach输出一份结构化报告。这是执行器和后续排查的重要依据。报告长这样{ plan_id: plan_20250317_001, reachable: false, steps: [ { index: 1, tool: fetch_ticket_detail, reachable: true, checked_at: 2025-03-17T10:00:00Z }, { index: 2, tool: unlock_account, reachable: false, reason: state_unreachable: unlock_approved is False, suggestions: [先执行审批动作, 向管理员发起审批请求] } ], blocked_at: 2 }这个报告有两点很关键。第一是blocked_at字段它标出第一个不可达动作的下标执行器可以直接从那里停止不用白跑后面的动作。第二是suggestions字段我建议每个工具契约里都带上失败时的修复建议模型拿到这个建议后可以做针对性重规划比让模型自己瞎猜有效得多。我还做了一件小事把分析的中间状态存下来每一步动作执行完之后的state副本都保留。线上如果出问题可以直接回溯是哪个动作把状态引到了错误分支。这相当于给Agent执行加了“黑匣子”排查效率提升非常明显。3.4 把分析结果回填给Agent上下文Agent-Reach的价值不只是拦截错误它还能反哺规划。我的做法是把报告里不可达的原因和建议拼接成一小段结构化提示词回填给LLM让它下一轮规划时避开同样的坑。比如报告里说“unlock_account前置条件不满足缺少unlock_approvedTrue”回填的时候就告诉模型当前状态里unlock_approved为False解锁动作不可用请在计划里先添加一个发起审批的动作。你可以把Agent-Reach理解成“带反馈的规划辅助器”它和主Agent循环是双向互动的。这个回填机制我强烈建议每个做Agent的同学都试一下。它不需要改动模型也不需要重新训练只是把系统侧的确定性信息注入到上下文里就能显著减少重复规划失败的次数。4. 常见问题与排查技巧实录4.1 现象一报告说可达线上还是挂了这是我把Agent-Reach接入线上后遇到的第一个大问题。明明报告显示每个动作的前置条件都满足真实执行却在一个外部API上超时偶尔还会返回结构完全不同的数据。后来定位到原因我的状态模型里没有把外部系统的运行状态纳入进来。外部API是否可用、响应schema是否变化这些属于“工具实际运行状态”和本地业务状态是两回事。Agent-Reach能判断本地状态满不满足条件但判断不了外部系统是不是抽风。解决办法是给“工具可达”加一层健康状态维度。我在工具注册表里扩展了availability字段定时更新外部工具的探活结果。如果工具当前不健康可达性分析直接判定该步骤不可达或者提示执行器走降级分支。这个问题的教训是可达性模型要明确边界本地状态、外部系统状态、权限状态必须分开建模混在一起会导致误判。4.2 现象二动作之间循环依赖模拟执行死循环有一次线上Agent响应特别慢查日志发现Agent-Reach的分析进程卡在一个很简单的计划上。原因是模型生成的动作序列里有循环依赖动作A需要动作B的结果动作B又引用动作A的输出依赖图没做拓扑排序就直接模拟执行结果状态一直更新不完。现在的代码里我强制要求先做拓扑排序检测到环就直接停止分析并把环上的动作信息上报给重规划器。重规划器的处理策略有两种一是把这两个动作合并成一个复合动作减少中间状态的依赖二是要求模型重新生成计划但要明确告诉它“A和B存在循环引用需要调整顺序或改变数据流”。4.3 现象三单Agent可达多Agent系统不可达最开始Agent-Reach只支持单个Agent的独立分析上线后没多久就发现一个问题两个Agent同时处理同一个用户的不同工单各自的可达性分析都通过了但全局执行时互相抢占资源最后谁都没跑成。这个问题的根因是资源可达性没有建模。我在四维模型里补上resource字段每个动作声明它占用的资源key比如user_id10086就是一把全局锁。分析时不仅要看本地状态还要看资源锁列表里当前有没有其他Agent占用了这个key。如果有就标记为“资源冲突”并给出等待或重试的策略。我在实践里对资源冲突的处理是不做真锁而是用乐观并发检查。Agent准备执行前申请资源如果冲突就进等待队列等待队列加上超时时间超时后重规划。毕竟Agent场景里等太久不如换条路。4.4 快速排查表我整理了一份高频问题速查表每次Agent执行链路出问题先对着表过一遍。现象可能原因排查重点解决建议报告可达但执行失败外部工具状态未纳入模型工具健康探活扩展工具availability字段分析卡死依赖图有环拓扑排序检测环上报重规划或合并动作权限偶尔拦截上下文权限条件缺失当前工单范围、操作人权限检查加上下文条件多Agent互相阻塞资源key冲突共享用户、共享订单资源锁列表等待队列参数引用Resolve失败参数来源节点缺失上一步副作用未生效严格按拓扑顺序模拟这张表不是硬规则每个团队的状态模型不一样排查优先级可能会有偏移但大方向是通用的。5. 工程落地从脚本到常驻服务5.1 最小可用版本怎么做如果你只想快速试一下Agent-Reach的思路不用一开始就上大系统。我建议第一版做三件事定义最核心的五个动作契约写一个本地状态快照跑通最基本的可达性检查脚本。工具用一个简单的Python函数加载不引入外部依赖。我第一版大概花了半天代码量也就几百行。关键是这半天能让你快速感受到“可达性分析到底能拦住什么问题”。我当时用六个真实工单场景去跑有一半的计划在第二步就被拦下来了。这个体感比任何PPT都管用。最小版本里不需要复杂的规则引擎就用表达式字典加线性遍历即可。先把闭环跑通再谈优化。5.2 拆成常驻服务后的收益从脚本改成常驻服务是我在接入第三个业务线之后才做的。触发点是多个业务方都有分析需求而且状态快照的获取方式不一样如果每次分析都是临时拼装代码会乱成一团。改成常驻服务后我把Agent-Reach做成一个独立的分析中间件对外暴露两个接口一个是check_plan接收计划、状态快照和工具注册信息返回可达性报告另一个是update_tool_status用于上报外部工具的实时状态。这个改造最大的收益是把“规则变化”收敛在一个服务里。比如需要新增一个合规检查条件我只需要改Agent-Reach服务的规则包所有接入的业务线自动生效。相比把逻辑散落在各个Agent里维护成本降了一个量级。5.3 扩展方向事件补偿与重规划Agent-Reach目前做的是“执行前分析”但真正的线上系统一定会有“执行中意外”。我的扩展方向是把可达性分析结合到执行事件流里每一步动作执行完都重新计算剩余路径的可达性。如果某个步骤的执行结果和模拟时不一致立刻触发补偿或重规划。补偿策略是另一个大话题我这里只说和Agent-Reach相关的部分重规划触发时新的计划同样要过一遍可达性分析形成“分析-执行-反馈-再分析”的正向循环。这一步是Agent系统从“演示可用”走向“生产可用”的关键也是我接下来几个月重点投入的方向。6. 一些经验之谈做这件事的取舍6.1 不要追求100%的可达性预测网上很多人聊Agent评测、Agent稳定性总想用形式化验证把所有问题都兜住。我的看法是在目前的大模型应用阶段100%的可达性预测是可遇不可求的。状态空间过大外部系统不确定性强形式化验证的成本会高到业务无法接受。Agent-Reach的定位是“高性价比兜底”它能拦住最明显的七八成问题剩下的事情交给执行监控和重规划。做工程不是写论文收益和成本的比更重要。6.2 数据质量和契约比算法更关键我在迭代中发现Agent-Reach的分析效果好不好七成取决于动作契约的质量只有三成取决于分析算法。如果工具的preconditions和effects写得不准确再精巧的模拟执行都是错的。所以我的建议是优先建立“契约评审”机制每个动作契约都要经历两轮评审一轮是技术评审看字段和表达式是否合规另一轮是业务评审看前置条件和副作用是否和真实业务逻辑一致。这个流程看起来重但能省掉后面大量的排查时间。6.3 最后的实操建议如果只让我从这段实践里留一条建议我会说把可达性分析结果做成一条一条的checklist回填到Agent的上下文里让它带着明确的“已知可行项”去规划下一步。这个动作看似简单但我测试下来原有规划失败率可以降低三四成。最开始我也觉得多填这些内容会稀释模型对核心目标的注意力但实际效果恰恰相反。模型真正缺少的不是目标而是对“当前系统里哪些事已经就绪”的确定信息。Agent-Reach恰恰能补上这一块。如果你也在被Agent计划跑不通的问题折磨我建议你从今天起给每个工具动作补上preconditions和effects两个字段然后做一个最粗糙的状态模拟。等你看到第一个被提前拦截的失败路径你就知道这套思路值不值得继续投入了。