Agent-Reach：智能体可达性与生产稳定性实战指南

从外部看起来，Agent-Reach 这个名字有点抽象——Agent 好理解，Reach 就容易让人想歪，有人以为是某个触达用户的营销组件，有人以为是做网络可达性探测的工具。我最初拿到这个项目定位时，其实也花了一段时间才把“智能体可达性”这个概念真正落地成可执行的工程方案。简单说，Agent-Reach 要解决的是一个问题：一个智能体在复杂生产环境里，到底能不能稳定、完整、高质量地“够到”它完成任务所需的目标——包括该调的工具、该检索到的知识、该记住的上下文、该走完的流程。如果你正在做 agent 类应用的上线运维、评测体系设计，或者正在被“demo 跑得好好的、一上生产就翻车”折磨，这篇文章应该能给你一些可以直接抄作业的思路。

1. 我为什么会被“Agent-Reach”这个题目拽住

1.1 一套看起来没毛病的 agent 系统，上线第一周就出事故

事情是这样的。我们之前上线过一个面向内部业务人员的问答与工单处理助手，底层是一个大模型 agent，接了十几个内部系统的工具接口，支持查库存、查订单、提交审批、生成周报这类操作。开发的时候很顺利，测试集里跑了几十条用例，工具调用基本都能落到正确参数上，回答也像模像样。结果上线第一周，用户反馈就开始出现诡异的状况：同一个问题，上午能查出来，下午就报“工具调用失败”；有些老订单数据明明在系统里，agent 却说查不到；更离谱的是，用户让 agent 把一段较长的背景说明结合订单信息生成摘要，agent 只处理了后半段，前半段内容像被凭空忘掉了。

一开始我们按常规思路排查，怀疑是模型版本变化、prompt 被污染、接口鉴权失效，逐一核对都没发现根本性问题。后来我把所有失败样本拉出来，按调用环节打标签，才发现问题根本不在模型理解能力上，而在于 agent 和外部环境之间的“连接通道”出了问题：工具 schema 变更后 agent 还在按老格式传参、检索接口返回了结果但关键信息被埋没在超长上下文里、上下文窗口被早期对话占满导致后续重要内容被截断。这些问题的共性，就是 agent 的 reach——它“够不到”该够到的东西。

1.2 “Reach”为什么会成为智能体系统的隐形瓶颈

传统软件系统里，“可达性”通常指网络层面，比如某个服务端口能不能连通。但智能体应用的可达性不一样，它至少包含四层含义：工具接口层面能不能正确调用、知识检索层面能不能召回关键信息、上下文记忆层面能不能持续容纳重要内容、任务编排层面能不能把多步骤流程完整走通。任何一环断了，用户感知到的就是“这个 agent 不好用”。

更麻烦的是，这四层之间还会互相影响。上下文塞太满，检索结果被截断，工具参数解析就出错；工具调用连续失败，agent 会把错误信息当成正常上下文继续推理，越错越远。最开始我们靠人工看日志来定位，一个失败案例少说花二十分钟，而且很多问题只在特定数据组合下才出现，复现都非常费劲。所以我才萌生了一个想法：与其在事故后疲于奔命，不如直接在系统里做一个横切层，持续度量 agent 在各个关键环节的“可达程度”，并用统一的分数和标签把问题暴露出来。这个横切层，就是 Agent-Reach 的雏形。

1.3 Agent-Reach 项目给自己定的三个目标

项目启动时，我给自己定了三个目标，后续所有设计都围绕这三个目标展开：

第一，可度量。不能只停留在“好用不好用”的感性判断，要能把每个 agent 任务的四个可达性维度量化成指标，并且指标计算规则可解释、可追溯。

第二，可定位。维度分数降低时，系统要能自动关联到具体的环节和样本，比如“工具调用成功率下降 15%，其中 80% 失败集中在订单接口，主要原因是参数格式从下划线改成了驼峰”。不能只告诉你有问题，不告诉你怎么修。

第三，可回归。每次调整 prompt、工具定义、检索策略后，要能自动跑一遍历史沉淀的“问题样本集”，验证修复有效且不引入新的回归。agent 系统的改动向来牵一发动全身，没有回归机制，根本不敢动。

这三个目标定下来之后，后面所有技术选型和工作拆解都变得非常顺。下面我详细拆一下 Agent-Reach 的整体设计和各个模块的落地细节。

2. Agent-Reach 的整体框架：把不可名状的问题拆成四个能算的分

2.1 四个量化维度怎么定出来的

在设计埋点之初，我翻了大量线上失败样本，最终确认所有失败都可以归因到四个环节：工具调用、知识检索、上下文保持、计划执行。每个环节对应一个维度，我给它们起了内部代号：TC（Tool Call，工具调用）、RH（Retrieval Hit，检索命中）、MC（Memory Carry，上下文保持）、PC（Plan Completion，计划完成）。

这四个维度的定义如下：

这四维还可以拆出二级指标。比如 TC 可以拆成“工具参数校验通过率”“工具调度成功率”“工具响应可用率”；RH 可以拆成“召回命中率”“引用正确率”“关键属性覆盖率”；MC 可以拆成“关键信息保留率”“上下文截断率”“遗忘召回率”；PC 可以拆成“子任务完成率”“跳步率”“重试次数”。

有了这些二级指标，下一步才能谈怎么合成一个总分数。

2.2 reach_score 总分怎么算

Agent-Reach 给每个任务输出一个综合可达性分数 reach_score，范围 0 到 1。计算方式是加权求和：

reach_score = 0.35 * TC + 0.25 * RH + 0.25 * MC + 0.15 * PC

权重不是拍脑袋定的，而是基于我们线上业务的实际特征：工具调用是最核心的瓶颈点，权重最高；知识检索和上下文保持其次；计划完成维度因为在我们场景中相对简单，先给 15% 的权重。如果你正在设计类似系统，我的建议是先跑两周纯数据积累，把各类失败样本的频率统计出来，然后用频率占比作为初始权重，比凭空预设更合理。

二级指标合成一级指标时也要注意一个问题：到底用算术平均还是几何平均？我一开始用的是算术平均，后来发现一个问题——只要大多数二级指标还行，某个单项差也能拿到好看的一级分数。这个缺陷在 agent 场景里很致命，因为任何一个环节断了，整个任务实际上就是失败的。后来我改成“单点否决 + 算术平均混合”：关键二级指标如果低于阈值，一级指标直接封顶 0.3；其余情况才参与算术平均。举个例子，工具参数校验通过率为 0，说明 agent 已经无法跟系统正常对话了，这时候调度成功率再高也没用，TC 就不应该高于 0.3。

2.3 采集链路：不侵入 agent 主流程的旁路观测

Agent-Reach 的第二个关键决策是采集方式。一开始有同事建议直接改 agent 的推理主循环，把埋点逻辑写进每个工具调用前后。我否掉了这个方案，原因是 agent 的应用代码迭代很频繁，直接侵入会把观测逻辑和业务逻辑耦合在一起，后面升级工具或者改 prompt 都会变得非常痛苦。

最终我们采用的是旁路观测模式。agent 框架会输出完整的事件流，包括用户消息、模型调用、工具调用、检索结果、中间推理等，我们写了一个 event collector 把这些事件以统一结构体接收下来，再在独立的分析逻辑里计算所有指标。这样 agent 主程序里几乎不需要改动，最多在工具定义里加一两个透传参数用来关联请求 ID。

采集链路的具体结构大致是：

1. agent 运行时每产生一个关键事件，就把事件内容发到本地的 event buffer。
2. buffer 按 100 条一批或者 5 秒间隔批量上报到 Agent-Reach 的分析服务。
3. 分析服务把事件按 task_id 聚合，按时间顺序重放，重新计算每个维度的得分。
4. 结果写入时序数据库和对象存储，前面用于 Dashboard 实时展示，后者用于离线分析。

这套结构的核心优势是：事件已经发生了，Agent-Reach 只是事后把现场重放一遍。对 agent 本身的性能影响很小，也不会因为观测系统的 bug 反过来污染业务数据。实际跑下来，单任务额外耗时平均不到 50 毫秒，完全可以接受。

3. 四个核心模块的落地细节

3.1 工具路由与参数对齐模块：从“能不能调通”到“是不是按现在的规则调通”

工具调用可达性是 Agent-Reach 里最先做的模块，也是踩坑最多的模块。我们内部把它分成三个检查点：工具选择正确率、参数格式合法率、调用结果可用率。

工具选择正确率相对简单，把 agent 实际选择的工具和标注的期望工具做比对即可。真正麻烦的是参数格式合法率。大型系统最大的痛点是同一个接口的 schema 经常变：字段改名、类型变化、枚举值更新、必填项增减，而 agent 模型训练时的知识里还停留在旧版本。上线第一周的大量失败就发生在这一层：agent 按照旧文档给新接口传参，导致接口识别不了。

Agent-Reach 的做法是每天自动抓取各系统最新的 OpenAPI schema，给每个工具生成一个 schema 指纹，包括字段名、类型、枚举、必填约束等。当在线请求发生工具调用时，实时校验 agent 传出的参数是否满足最新 schema，不满足就把偏差字段记录下来。有一段时间 Dashboard 上频繁出现“expire_time 字段不存在，疑似旧版 schema 记忆”的告警，顺着字段名去查，才发现确实是某个系统两周前把字段改名成 expire_at，agent 的 prompt 里给的还是旧示例。这个模块的价值就在这里——把“接口调不通”这样一个模糊问题，变成了“哪个字段、什么时候引入的变更、需要改哪个配置文件”，定位成本直线下降。

调用结果可用率则处理另一种情况：工具调用本身返回了 HTTP 200，但错误码提示业务上失败，比如查库存的接口返回了一个代表“门店已关店”的错误编码。这种日志如果不解析业务错误码，光看状态码，就会被误判为成功。Agent-Reach 维护了一个业务错误码字典，把每个错误码映射到可读的原因和处置建议，在 Dashboard 上直接展示。这块需要维护同学跟各系统负责人确认语义，工作量不小，但非常值。

3.2 召回质量探针：检索“有结果”不等于“命中了关键答案”

检索命中可达性是第二个模块。我们最初犯过一个认知错误：以为只要检索接口没有返回空集，RH 就算正常。后来发现大量“有结果但答错”的样本：检索返回了 10 条结果，真正包含答案的那条排在第 11 位；或者答案确实在结果里，但关键属性在生成阶段没被模型引用。

Agent-Reach 因此在检索链路里增加了三层探针：

第一层是召回覆盖探针。在每个检索请求发出前，先对用户问题做实体识别，提取出关键实体或约束条件，比如“订单号”“日期范围”“客户名”。检索完成后检查这些关键条件有没有出现在召回结果的标题或内容片段中。如果订单号根本没出现在任何一条结果里，基本可以判断召回漏了。

第二层是排序失效探针。如果关键信息出现了，但位置靠后，而最终 agent 并没有用这条信息，则标记为“排序失效”。这种情况常见于混合检索里向量召回和关键词召回的权重新旧配置不一致，导致最相关的文档被挤到后面。

第三层是引用一致性探针。在最终回答生成后，把回答中的事实要点和检索结果的原文做一遍语义匹配，检查所有关键数字、名称、时间点是否真的能从召回内容里找到依据。这一步是离线异步做的，不影响在线响应时间，但对定位“幻觉型答错”特别有效。实测下来，这个探针抓到的“有召回但用了错误片段”的问题，占比比我们想象的高不少。

3.3 上下文占用监控：为什么 agent 越聊越“傻”

上下文保持可达性通常是最容易被忽视的模块，因为它不产生显式的报错。用户不会看到“工具调用失败”，只会感觉 agent 的回复质量越来越差。

这里先说一个背景：很多 agent 的上下文窗口看起来很大，但实际真正能有效利用的计算预算没那么高。对话轮数一多、检索结果一长、工具返回历史一多，关键信息就会被挤出有效范围。Agent-Reach 的 MC 模块会做三件事：

第一，跟踪每个关键信息片段在上下文中出现的位置和占用的 token 数。我们在任务开始时会对用户的核心需求做标记，比如“有一个订单号 A-2024-035 需要查询”，然后实时计算这个片段在每一轮对话后是否仍然保留在上下文中，以及在最后生成前处于上下文的前 30%、中间 40% 还是末尾 30%。有过 NLP 经验的人可以类比为滑动窗口里的关键 token 保留率。

第二，检测上下文截断事件。当我们发现 token 使用量接近窗口上限，或者在调用模型接口返回的 usage 数据里看到 truncation 标志时，就记录一次截断事件，并分析被截断掉的内容里有没有之前标记过的关键信息。

第三，做一个“选择性失忆”测试。从这个 agent 的真实历史任务里抽取一批“关键信息点”，在每一轮生成前向前端发一次探测请求，看看在给定当前上下文的条件下，模型能否正确复述这些点。不能复述的，就认为发生了遗忘。这个测试本身也会消耗一点 token，所以我们只对长对话和高价值任务启用，默认 5 轮以内的短任务不跑。

这个模块上线后抓到的经典案例是：用户在第 1 轮提供了一个 2000 字的业务背景说明，中间隔了 6 轮查询和检索，第 8 轮让 agent 结合背景生成总结时，agent 完全没有引用背景，反而自己重新理解了一遍，方向和原文完全相反。监控日志显示，那段背景在第 4 轮就已经因为工具返回内容大量累积而被挤出上下文了。没有 MC 模块，这种问题极难发现。

3.4 任务链路断裂点追踪：看清多步任务死在哪个环节

最后一个核心模块是多步骤任务的链路追踪。agent 处理复杂任务时会拆解成多个子步骤，子步骤往往还依赖前一步的工具返回结果。我们遇到过一些“整体成功率看着还行，但复杂任务成功率一塌糊涂”的场景，排查起来特别费力。

Agent-Reach 的做法是把每一次多步任务的状态机画出来。当然这里不会渲染成图，我们用一个结构化的 step 链记录：

1. 任务的初始计划是什么，含每个子步骤的描述。
2. 每一步的输入从哪里来、期望的输出是什么。
3. 实际执行时，这一步的工具调用是否成功，返回结果是否满足下一步的输入要求。
4. 如果某一步失败或跳步，记录失败类型：参数不当、上游结果缺失、模型判断提前终止、还是超时。

在分析界面里，我们把这些信息渲染成一个按步骤排列的表格，每行显示步骤名、状态、耗时、失败原因。异常样本一眼就能看出断点在哪个位置。

有个真实案例很典型：一次财务报表生成任务，第 2 步需要先汇总本月订单数据，第 3 步再根据汇总结果做环比分析。由于第 2 步返回的数据字段名称和预期不一致，agent 在第 3 步直接选择了“不调用分析工具”，而是凭空生成了一段环比结论。链路追踪清楚地把第 3 步标记为“因上游字段异常导致模型主动降级”，并且把第 2 步的字段偏差也一并关联出来。这种跨步骤的根因定位，靠逐条看日志几乎不可能完成。

4. Agent-Reach 在真实业务里跑出的三个典型结论

4.1 参数 schema 版本漂移：吃掉了一半的工具调用成功率

Agent-Reach 跑通之后，我们做的第一件大事就是对历史一个月的线上事件做全量重放。结论非常扎心：工具调用成功率低不是模型能力问题，而是系统维护跟不上。

统计结果里，43% 的工具调用失败来自参数格式和最新 schema 不匹配。其中绝大多数不是 agent 不会传参，而是它参考的工具示例文档已经过时了。我们的 prompt 里嵌入的是两个月前从某个系统导出的一份静态 JSON 示例，恰好那个系统在一个月前升级了接口。agent 严格按 prompt 里的旧格式传参，系统自然不认。

这个结论直接改变了我们的运维流程。以前是“接口升级后，手动更新 prompt 里的示例”，现在 Agent-Reach 会每天自动比对 schema 指纹，一旦发现版本变化，就在系统的变更清单里生成一条待办，提醒是否需要在 prompt 或工具描述里同步更新。仅这一个流程调整，工具调用成功率在两周内提升了约 20 个百分点。

4.2 检索 top5 返回了正确答案，但 agent 引用的是 top8

第二个有意思的发现是检索排序和引用之间的错位。我们原本以为检索结果只要包含正确答案，回答就不会太差。但 Agent-Reach 的引用一致性探针抓出一批案例：正确答案在检索结果里排第 5 位到第 8 位，而 agent 在生成时偏偏引用了排在第 2 位但语义相近、实际数据错误的另一条结果。

分析这个现象的原因，可能有两种。一种是在构建检索 prompt 时，我们给模型的要求是“优先参考排列靠前的结果”，模型确实照做了，但排序本身不够好，把错误结果顶到了前面。另一种是模型的注意力被更靠前的结果吸引，没有继续往下看。两种原因在日志里都能看到分叉点：第一种的批量错误表现出明显的排序相关性；第二种则比较随机，和结果的文本长度、措辞风格有关。

Agent-Reach 在报告中把这两类分别标记为“排序失效”和“注意力偏移”，给检索团队提供了非常明确的优化方向。后来我们在检索结果注入前加了一个“关键信息预检”步骤，对 topN 结果先做一轮关键实体检查，把明显不相关或者信息缺失的结果降权，再交给生成模型，问题大幅缓解。

4.3 上下文截断引起“选择性失忆”，而且用户不会察觉到

第三个结论来自 MC 模块。我们原以为上下文问题只出现在超长对话里，然而数据表明，对话仅进行到第 5 轮左右，早期关键信息被截断的概率已经达到 8% 左右；到第 10 轮，这个数字接近 25%。

更麻烦的是，这类问题不会以报错形式呈现。用户不会收到失败提示，只会觉得 agent“怎么越聊越傻”。有些用户会重复提问，有些用户直接放弃使用。Agent-Reach 在告警规则里专门配置了一条：当 MC 分数低于 0.6 且任务类型属于“摘要综合类”时，自动把该任务标记为高风险并推送给人工复核名单。这个规则上线后，我们至少提前发现了两起即将引发客诉的案例，把 agent 的回答在交付前拦截下来了。

5. 从指标到改进：我跑通的一套四步处置闭环

5.1 第一步：先判断是 schema 问题还是 prompt 问题

Agent-Reach 的告警会带着结构化原因标签，所以处置流程可以做得非常机械化。拿到一个低分任务，我的第一个判断点是：问题出在工具调用还是知识检索。

如果是工具调用问题，立刻打开该任务的参数校验明细。看看失败原因是“字段不存在”“类型不匹配”还是“必填项缺失”。字段不存在几乎都是 schema 和 prompt 不同步，处理办法是更新 prompt 里的工具示例，或者在工具调用前加一层参数自动转换。类型不匹配则常见于从数据库取出的整数被自动转成了字符串，需要在工具定义里增加类型说明。必填项缺失则要重点检查 agent 的信息提取能力，必要时在 prompt 里补充“这些步骤中需要注意从对话中提取以下字段”。

如果是检索问题，先看是召回覆盖失败还是排序失效。召回覆盖失败要回到检索策略上，可能是向量索引只覆盖了部分数据源；排序失效则要检查混合检索的权重配置和 rerank 模型。这里有一个实操经验：不要一上来就调大模型 prompt，要先让数据管道符合预期，再考虑模型侧优化。

5.2 第二步：建立一条“分级路由 + 知识裁剪”的检索策略

在处置检索类问题时，我做了三个改动：

一是把检索源按照置信度分级。例如订单数据以数据库查询结果为准，知识库文章以向量检索结果为准，外部文档以关键词召回为准。不同来源的结果不能混在一个大池子里直接排序，要先按来源分组，再给每组一个可信权重。

二是对检索结果做关键信息预检。在把结果交给生成模型前，写了一个小判断逻辑：从用户问题里提取实体，检查实体在每条候选结果中是否存在。越早出现、出现次数越多、和查询约束匹配度越高，排序权重就越高。这一步的成本很低，但能明显降掉“top5 答错”类问题。

三是知识裁剪。如果检索结果总 token 数超过生成模型窗口预算的 40%，就会启用摘要压缩，只保留每篇文档的标题、核心数字和结论句，其余详细内容折叠起来。这一步明显减小了上下文溢出风险，也间接保护了 MC 维度。

5.3 第三步：给长对话加“关键信息锚定”机制

针对上下文截断导致的选择性失忆，我给 agent 加了一个关键信息锚定机制。思路和人在处理长会议纪要时做高亮批注是一样的：在每轮对话结束时，用一个小模型从当前上下文里抽取“本轮新增的关键事实点”，存到一个独立的关键信息存储里。

到生成阶段，系统会把关键信息存储的内容和当前上下文一起注入生成请求，并放在最靠前的位置。这样即使原始对话片段被截断，关键事实仍然能保留下来。代价是增加了一定的 token 消耗，换取的是长对话场景下的 MC 分数显著提升。以我们的业务数据来看，MC 分数从 0.55 提升到了 0.79，这个投入非常值得。

需要提醒的是，这个机制要控制关键信息存储的体积，否则又会导致新的上下文膨胀。我给每条关键事实点的上限是 32 个 token，每轮最多抽取 5 条，超出部分丢弃。这个阈值可以根据你的模型窗口和业务复杂度调整。

5.4 第四步：把每一次修复都沉淀进回归样本集

Agent-Reach 的第四步处置逻辑很朴素：任何修复，都要能通过历史失败样本的回归测试。我们把每次线上出现的低分任务都自动加入一个待标注池，每周挑出有代表性的 50-100 条，人工标注期望行为和失败环节，形成增量测试集。

每次对 prompt、工具定义、检索策略或上下文机制做变更时，都必须跑一遍这个测试集，对比变更前后的 reach_score 分维度变化。有一个口号我一直在团队里强调：不能只看总分涨没涨，要看是不是靠牺牲 A 维度换 B 维度涨。比如某些压缩策略可能会让 MC 涨，但代价是 RH 下降，因为压缩过程丢了关键信息。回归报告里会同时展示四个维度的涨跌，以及失败样本清单，这样每次变更的代价都一目了然。

这套回归机制坚持跑了三个月以后，Agent-Reach 的周报里几乎不会再出现“旧问题复发”的记录了。凡是修过的坑，都变成了测试集的一部分，再想踩回去都难。

6. 一些使用边界和踩坑提醒

6.1 这个方案不太适合的场景

Agent-Reach 不是万能的。在开发过程中，我明确感知到它有以下几个边界：

第一，如果 agent 的核心任务是纯生成型，比如写诗、写文案、开放域聊天，那么“工具调用”“检索命中”这类维度基本不适用，reach_score 会失真。这类场景应该把重点放在输出质量和安全性评测上，而不是可达性。

第二，如果 agent 系统的调用链非常短，比如单轮问答、单次工具调用，那么搭建一整套四维监控体系是有点重的。二三十个工具的规模，直接看日志加几个告警就能覆盖，没必要上完整框架。Agent-Reach 的复杂度适合工具数量在五十个以上、任务链路有至少三步依赖、且多人协作维护的场景。

第三，异常事件采样率不足时，分析结果会误导决策。Agent-Reach 最初只对失败的请求做分析，后来发现很多“看似成功但质量差”的样本反而被漏掉了。后来我们把分析对象扩大成全量样本，只对失败告警做了采样率控制。这样做确实会增加存储和计算成本，但分析结论的可靠性高了很多。

6.2 建设这个系统时踩过的三个坑

第一个坑是事件 schema 设计得过于严格。一开始我们规定所有事件必须包含 20 个字段，结果上游 agent 框架升级后，有两个字段被改名，整套采集链路直接断掉。后来我把事件结构改成了“核心字段 + 扩展字段”模式，核心字段只保留必须的 ID、时间、类型、负载，其余信息全部塞进扩展字段。字段命名也不再强校验，扩展字段在分析侧按需解析。这套松耦合设计让 Agent-Reach 经受住了后续各种框架迭代。

第二个坑是权重参数没有版本管理。reach_score 的权重调过几次后，历史报告和新报告的分数没法直接对比了。后来我把所有权重配置纳入版本管理，每次改动都记录生效时间和影响范围，报告也按配置版本分组对比。这个习惯虽然开始麻烦，但长期维护时非常必要。

第三个坑是忽略了业务错误码的语义多样性。同一个“失败”可能由完全不同的事件序列导致，但都表现为数字码。比如库存系统返回一个“1001”，不同门店含义完全不同，简单映射常常出错。后来我们针对每个业务系统建了单独的语义解析规则，并邀请业务方参与维护映射表，准确率才提上来。

6.3 后续我们正在扩展的方向

目前 Agent-Reach 还处在“观测和定位”阶段，下一步我打算往“自动修复”方向推一步。比如针对 schema 漂移问题，正在尝试做一个自动提示词更新器：检测到字段变更后，自动改写工具描述中的示例参数并提交预览，人工一键确认后生效。针对上下文截断问题，也在试验一个动态压缩策略，根据任务的重要程度动态调整压缩阈值，而不是全场景使用固定的 40% 上限。这些目前还在测试环境里跑，暂时没有足够的完整数据支撑分享，等跑稳了再写一篇专门的汇报。

如果你也在做 agent 类应用，并且正在被“时好时坏、定位困难”的问题困扰，从这四个维度入手去做度量，大概率不会走偏。我把 Agent-Reach 的整体思路和关键落地细节都写在这里了，希望能帮你少踩几个我踩过的坑。每个项目的上下文不同，数据管道、工具协议、模型能力都不一样，你完全可以拿这套框架做裁剪：先只做工具调用事件采集，跑两周数据，看看失败样本集中在哪个环节，再决定要不要补上其他模块。很多时候，一点点的可观测性改进带来的收益，会远超你的预期。