企业官网建设流程全解析

我过去大半年一直在做 AI Agent 相关的落地项目，有一个感受特别深：模型能力早就不是瓶颈了，真正卡脖子的是——Agent 明明配置了一堆工具和知识，它却"看不见、够不着、不会用"。后来我给自己的项目写了一套叫 Agent-Reach 的观测工具，专门用来量化 Agent 对工具、指令和上下文资源的"触达能力"，解决的就是"有资源但用不上"这个老大难问题。这套工具帮我们排查出了好几个隐藏很深的问题，比如工具排序导致的关键能力被冷落、上下文超长导致有效信息被模型忽略等等。今天就拿这个项目和实际案例聊聊，Agent 项目的触达率到底怎么测、怎么优化，以及一套可以照着复用的落地思路。

1. 为什么 Agent 项目里"有了"不等于"够得着"

1.1 三个最常见的触达失灵现场

先说一个很典型的场景。我们有个客服工单 Agent，绑了 CRM 客户查询、工单创建、邮件发送、知识库检索、订单状态查询等七八个工具，系统提示词里还专门写了"涉及客户信息时请优先调用 CRM 查询工具"。结果实测下来，模型有相当高的概率不去调用 CRM 工具，而是直接根据对话里出现的客户名称编一个答案，或者绕道去查知识库里的文档。这还不是个例，我后来接触了不少做 Agent 的团队，大家反馈的问题出奇地一致，归纳起来就是下面这三类。

第一类叫工具触达失灵。工具清单太长，或者工具描述写得不够明确，模型在每一次决策时都需要在大几十个工具描述里做筛选，注意力被稀释，最后经常选中一个"看起来差不多"但实际不合适的工具。第二类叫上下文触达失灵。系统提示词里塞了长篇大论，包括公司背景、业务规则、话术规范、安全边界，几千字下来，真正关键的约束可能被模型忽略，它更倾向于关注对话末尾的用户消息和最近的几条历史记录。第三类叫知识触达失灵。RAG 检索出来的文档片段确实进了上下文窗口，但模型不一定真的"读到"了，尤其当检索片段排在上下文中后部的时候，被引用的概率会明显下降。

这个感受我想很多做过复杂 Agent 的人都懂。我们通常把精力花在怎么设计工具、怎么调 prompt、怎么优化检索，却很少去度量一件事：Agent 到底有没有真的触达它应该触达的那些东西？没有度量，就没有优化方向，问题只能在上线后以用户投诉的形式暴露出来。

1.2 从 RAG 到 Agent，问题位置换了

最早大家做 RAG 的时候，关注的核心指标是检索召回率和上下文相关性，因为那时候人还在链路中间，召回结果好不好，人扫一眼就知道。但到了 Agent 时代，模型自己决定下一步干什么，决定权从人手里移交给了模型，问题性质就变了。RAG 时代我们担心的是"检索到的相不相关"，Agent 时代我们担心的是"模型到底参考了什么、调用了什么、忽略掉了什么"。这些东西在传统指标里是看不见的——你的工具注册得再好，上下文组织得再清晰，只要模型没有实际触达，效果就是零。

我当时就是被这个问题反复折磨，才决定做一个专门度量触达率的工具，也就是 Agent-Reach。它的出发点很朴素：每个 Agent 运行的会话里，模型每一次做工具调用决策时，都存在一个"按理说应该选什么工具"的期望答案，而实际选了什么是观测到的真实答案。二者一对照，就能算出触达率。同理，系统提示词里每条关键指令、上下文中每个知识片段，都可以定义"期望被模型关注"和"实际被模型关注"的关系，从而量化出指令遵循覆盖率、上下文利用度等指标。

这是整个工具的核心逻辑，也是我觉得很多 Agent 项目最缺的一层观测能力。下面详细展开。

2. Agent-Reach 的指标定义：把"触达"变成可量化数字

2.1 核心指标：工具触达率（Reach Rate）

Agent-Reach 最核心的指标是工具触达率，英文就叫 Reach Rate。它解决的是这样一个问题：当 Agent 面临一个需要调用工具的任务时，它有没有调用那个"正确且应当被调用"的工具。

计算口径我分成两层。第一层是候选集触达率，定义是：在一次工具调用决策中，如果当前任务意图命中了某个工具的职责范围，那么这个工具就属于"期望工具集"。实际调用结果如果命中了期望工具集里任意一个工具，就算触达成功。公式是：

[ ReachRate = \frac{实际调用命中期望工具集的次数}{期望工具集出现的总次数} \times 100% ]

这个口径用一个具体例子会非常好理解。一个订单查询任务，期望工具集是order_query和order_search，因为这两个工具都能查订单状态。如果模型调用了order_query，触达成功；如果模型调用了knowledge_base去文档里翻订单说明，那不算触达成功，因为知识库不是订单状态的权威数据源。第二层是精确触达率，比候选集触达更严格，要求实际调用必须命中期望工具集里的"最佳工具"，而不是任何一个兜底工具。这样能防止 Agent 用泛化工具蒙混过关，适合用来衡量路由精度。

在实际使用中，我会同时看这两个数字。候选集触达率告诉你模型有没有用对工具类型，精确触达率告诉你模型有没有在同类工具里选到最优的那个。两者组合起来，工具侧的健康度就非常清晰了。

2.2 辅助指标：指令遵循覆盖率与上下文利用度

光看工具触达还不够，因为 Agent 的很多行为并不体现为工具调用，而是体现为对指令的遵循程度以及对上下文内容的采信程度。Agent-Reach 里还有两个重要的辅助指标。

第一个是指令遵循覆盖率。做法是把系统提示词按照语义切成一条条可判定的指令原子，比如"涉及客户敏感信息时不得直接透露完整手机号""当用户表达退款意愿时，必须先引导用户确认订单号"。然后逐条检查这个会话里模型的实际行为是否符合指令要求。符合记为 1，不符合记为 0，最后统计覆盖率。这里的关键在于判定过程是半自动的，模式化的指令可以通过规则自动判定，模糊的指令需要借助另一个评测模型来打标。

第二个是上下文利用度。这个指标度量模型有没有真正读到上下文里那些关键信息片段。常见的做法是给注入上下文里的每个知识片段打上标签，比如"客户专有名词解释""库存状态数据""历史工单处理结果"，然后在模型生成结果后判断它有没有引用这些片段。一个粗糙但有效的判断方法是做叫"语义命中检测"，看模型输出里是否出现了与知识片段高度重合的实体、数字或者结论。上下文利用度 = 实际被引用的知识片段数 / 注入的全部知识片段数。这个数字通常低得惊人，我第一次跑出来只有 20% 多，当时就明白了为什么 Agent 老是答非所问。

我把这几个指标放在一张表里说明一下，方便对口径有直观理解。

阈值是我自己项目里压出来的经验值，不同业务形态会有差异，但整体趋势可以参考。

2.3 指标计算与判定的关键细节

把指标定义清楚之后，真正的难点在于"期望工具集"怎么来。Agent-Reach 用了两路并行的方式来构建期望答案。一路是离线分析：把历史会话里的人工标注结果、最终正确结果反推、以及业务规则映射表汇合起来，构建一个意图到工具的静态路由字典。另一路是在线评测：每次请求会同时让一个评测模型根据"对话历史+任务意图+工具描述"，独立推断出应该调用哪个工具，并且强制要求评测模型只能从注册工具集里选择，不允许自由发挥。两路结果一致时，直接作为期望答案；两路冲突时，标记为模糊样本，进入人工抽样复核流程。

这里有个重要细节：期望答案的定义不可以依赖真实模型本身。如果你让 GPT-4 既做 Agent 又做自己的评测官，它会倾向于认为自己的选择是对的，触达率会虚高。所以评测模型建议选择不同的模型，并且在评测时把工具描述作为输入的一部分，但不要暴露真实模型实际调用结果，这样才能保证独立判定。这也是 Agent-Reach 设计里一个比较关键的原则，后面在实践时特别容易踩坑。

还有一个细节是意图类型的粒度。期望工具集不是全局统一的，而是按意图类型拆分的。比如用户问"订单到哪了"，期望工具集是order_query和logistics_trace；用户问"我要退货"，期望工具集是return_apply和return_policy_check。如果所有请求共用一套期望工具集，算出来的触达率没有任何指导意义。所以在设计标签体系时，意图分类要先做好，这一步直接影响后续所有指标的质量。

3. 落地实现：Agent 侧采集与分析引擎的拆解

3.1 观测层设计：不改 Agent 策略，只做旁路采集

项目落地的第一原则是 Agent-Reach 不干预 Agent 本身的决策流程。你不需要改动模型调用的策略，不需要改工具执行逻辑，只做一个旁路的观测层，把所有关键决策事件记录下来。

具体来说，我会在两个位置挂采集点。第一个位置是工具注册表。每个工具被调用前后都会触发一个事件钩子，我在钩子里记录：当前会话 ID、调用时间戳、触发轮次、被选中的工具名、候选工具列表（也就是当时注册的所有工具）、模型给出的工具调用参数、以及工具执行结果的状态码。第二个位置是上下文组装器。Agent 每一轮发送给模型的消息内容，在发送前都会被快照一份，包括系统提示词、历史消息、检索片段、工具返回结果等。快照不会放进线上请求，只用于事后分析。

这段采集逻辑我后来写成了一个 Python 装饰器，接入非常简单，核心代码如下：

import functools import time import uuid def reach_trace(agent_id, session_id, candidates): def decorator(func): @functools.wraps(func) async def wrapper(*args, **kwargs): start = time.time() tool_name = func.__name__ try: result = await func(*args, **kwargs) status = "success" except Exception as exc: result = str(exc) status = "error" finally: trace_event = { "event_type": "tool_invocation", "agent_id": agent_id, "session_id": session_id, "tool_name": tool_name, "candidates": candidates, "args": kwargs, "status": status, "latency_ms": round((time.time() - start) * 1000, 2), "timestamp": time.time(), } # 写入本地缓冲队列，异步批量上报 reach_collector.emit(trace_event) return result return wrapper return decorator

装饰器本身不做任何业务判断，纯粹记录事件。这种设计有几点考虑：一是把观测逻辑和业务逻辑彻底解耦，线上接入时风险低；二是即使采集端出问题也不影响主链路，因为所有事件都先进内存队列，异步批量上报，不会阻塞工具执行。

3.2 分析引擎：期望触达与真实触达的对照逻辑

采集到的原始事件只是素材，真正要算出触达率，还需要一个分析引擎来做事件对齐和归因。分析引擎的处理流程我拆成四步。

第一步是会话重组。把同一个 session_id 下的所有 tool_invocation 事件按时间戳排序，还原出完整的工具调用链。第二步是意图标记。对每一个对话轮次，用事先训练好的意图分类器或者规则匹配器，给该轮次打上意图标签，比如"订单查询""退换货申请""物流追踪"。第三步是期望工具集匹配。根据意图标签去查意图-工具路由表，得到该轮次理论上应该使用的工具集合。这里还要考虑轮次上下文——比如用户第一轮说"我要退货"，第二轮补充了订单号，那么第一轮和第二轮其实都属于同一个任务单元，期望工具集要合并计算。第四步是对照判定。把实际调用工具和期望工具集对比，输出触达与否的布尔值，同时记录未命中时的实际落点，方便后续分析。

这里有一个值得注意的归因细节：同一个意图如果在多个会话里反复出现，模型第一次调用了错误工具，后续轮次才纠正过来，那触达率应该怎么算？Agent-Reach 的判定口径是：只要该任务单元内最终成功调用了期望工具，就计为触达成功；如果任务单元结束时仍未调用期望工具，才计为触达失败。这个口径更贴近业务结果——用户不关心第一下有没有选错，只关心最终有没有办成事。但如果你的目的是排查路由质量问题，那可以再细分一个"首轮精确触达率"指标，把每一次决策单独拎出来看。

分析引擎跑完之后会生成一份结构化的结果，我通常在 Elasticsearch 里存一份原始数据，在 ClickHouse 里存一份聚合后的指标数据，然后用一个简单的 Web 面板做可视化展示。对大多数项目来讲，不需要一开始就上重型数仓，一个 ClickHouse 单实例加一个 Grafana 或者自带的报表页面就够用了。

3.3 数据链路与存储格式

数据链路从采集到展示分成四段，我会简要说明每一段的职责。

• 采集段：Agent 进程内部的 SDK，负责产生事件快照，写入本地队列。
• 传输段：一个轻量级的 Go 或者 Python 上报服务，从队列里批量取事件，压缩后发到中心服务。
• 存储段：中心服务做了两级存储，原始事件流入消息队列再进数据仓库，指标结果直接写指标库。
• 展示段：面板服务从指标库读取聚合数据，展示各意图的触达率趋势、工具冷热榜、指令遵循情况。

完整的 trace 事件我定义成统一的 JSON 格式，各字段如下：

{ "event_id": "evt_8f3a2b", "agent_id": "customer_service_v3", "session_id": "sess_9d12cc", "turn_index": 7, "task_unit_id": "task_3a01", "intent": "order_query", "expected_tools": ["order_query", "logistics_trace"], "actual_tool": "logistics_trace", "tool_args": {"order_id": "SO-2024-0812"}, "context_snapshot": { "system_prompt_hash": "h_8091ff", "history_tokens": 4200, "retrieved_chunks": ["chunk_xx", "chunk_yy"], "total_context_tokens": 8600 }, "reach_verdict": "hit", "precision_verdict": "miss", "timestamp": 1723416001 }

有了这个统一结构，后面做任何维度的分析都比较顺手。比如我可以按expected_tools里是否包含某个工具来筛选出所有"本该用 CRM 查询但没用到"的会话，也能按precision_verdict等于 miss 的条件找出所有被泛化工具截胡的案例。

4. 一个实践案例：客服工单 Agent 的触达盲区排查

4.1 项目背景与接入前的现象

拿一个比较有代表性的案例来说。我合作过的一个团队做一个电商客服工单 Agent，功能覆盖订单查询、退换货处理、物流催单、发票开具、售后知识问答。工具注册了十一个，系统提示词写了大概两千字，里面详细描述了每个工具的使用场景还有各种业务红线。上线前团队对效果挺有信心，因为单测用例都过了，工具调用的链路看起来也通。结果灰度一跑，真实用户会话里差评率比预期高出不少，运营侧最集中的反馈是"客服答非所问""给了不准确的退款政策"。

团队一开始怀疑是模型指令遵循能力不行，换了更强的模型，效果有提升但没根治。后来他们接入 Agent-Reach，跑了一周数据，才把真正的问题暴露出来。这里我把三个有代表性的发现展开说一下。

4.2 接入 Agent-Reach 后发现的三个问题

第一个问题出在工具触达率上，而且不是整体低，是特定意图下特别低。按意图拆分之后看，订单查询意图的候选集触达率有 91%，但退换货意图的精确触达率只有 41%。进一步看原始 trace 发现，模型相当高频地选择了knowledge_base工具而不是return_apply工具。原因也不难找——在这套系统的工具注册表里，knowledge_base排在工具列表的第三位，描述是"查询售后政策、退换货说明、常见问题"，而return_apply排在第七位，描述是"创建退换货申请单"。模型面对"我要退货"这样的请求时，识别到了"退换货"这个关键词，但在工具选择阶段被knowledge_base的描述吸引走了，于是先去查文档，查完文档之后也不一定继续调用return_apply，很可能直接基于文档内容编一个答复给用户。这就是典型的因工具路由精度不足导致的业务功能失效。

第二个问题是上下文利用度极低。从 trace 里可以看到，系统提示词和动态检索片段加在一起，每轮平均要往模型里塞八千到一万个 token。但分析引擎统计下来，实际被模型输出引用的关键知识片段只有 27%。更麻烦的是，被引用片段大多集中在上下文的前 20% 位置，也就是说模型拿到了大量信息，但真正"读进去"的非常有限。还有一类片段是"客户等级信息"，系统在上下文里注入了VIP客户标识，但模型的处理结果里完全没有体现 VIP 专属售后通道的差异。这个问题的根源在于上下文组织方式不合理，所有信息平铺直叙、权重平均，没有把关键约束和信息放在足够醒目的位置。

第三个问题是指令遵循覆盖率的盲区。规则里有一条"客户申请退款时必须优先引导确认订单号，不得直接创建退款单"，但覆盖率只有 68%。查 trace 发现，如果用户在第 3 轮之前就已经把订单号提供过了，模型会在系统提示词没有明确说明"已提供订单号可跳过确认"的情况下，仍然机械地执行确认流程，让用户重复提供订单号，体验很差。这是个很有意思的盲区：指令本身没有错，但缺少条件分支的设计，模型只能按字面意思理解，导致过度遵循。

4.3 基于 Reach 数据做的调整与结果对比

针对这三个问题，我们分别做了调整。工具触达率的问题，做法是对工具描述做了权重排序，把高频业务工具往前放，同时在工具描述里增加更明确的触发条件例句，比如return_apply的描述改成了"当用户表达退货、换货、申请售后时，必须优先调用本工具创建申请单，不要先查文档，除非用户明确询问政策条款"。上下文利用度的问题，做法是重构了上下文组装逻辑：系统提示词开头 500 字内放最核心的业务红线，动态知识片段统一用 XML 标签包裹并前置摘要行，每次最多注入 5 个片段而不是全量塞入，避免信息过载。指令遵循覆盖率的问题，做法是把那条退款指令改写成了带条件分支的版本："若用户尚未提供订单号，则先引导确认订单号；若已提供，则直接进入退款单创建流程"。

调整之后再跑一周，效果对比如下。

最直观的业务变化是用户侧差评率降了差不多一半，工单处理时长也明显缩短。我想强调的是，这些优化动作没有一个是碰模型参数的，全靠触达率数据指出的方向。这也是 Agent-Reach 这类工具最大的价值——它把那些模糊的"效果不好"翻译成了具体的、可修正的位置。

5. 接入 Agent-Reach 的实操步骤与配置细节

5.1 环境准备与接入前置要求

如果你在自己的 Agent 项目里也想用这套思路做触达率观测，不一定要用我这份代码，但整体接入步骤是通用的。第一步是确认你的 Agent 框架支持在工具调用前后挂钩子。如果你用的是 LangChain、LlamaIndex、Dify 这类框架，它们基本都提供回调机制或者中间件机制，可以在工具执行器前后插桩。如果完全是自研的调度循环，那就更简单了，直接在调用工具的函数外层包一层装饰器就行。

第二步是准备好意图分类体系和工具路由字典。这是整个指标体系的基石。不需要一开始做得特别复杂，先用规则加少量人工标注把高频意图覆盖掉，比如订单查询、退换货、物流催单、发票问题这些核心场景。每个意图对应至少一个期望工具。如果某个意图对应多个工具，就按优先级排序，排第一的是最佳工具。

第三步是搭建一个最基础的数据上报服务。本地开发阶段，我建议先写一个 JSON 文件日志，把 trace 事件直接追加写到磁盘里，跑通链路后再替换成正式的采集服务。这样可以把问题隔离在 Agent 侧，避免一开始就背上数据基础设施的复杂度。

5.2 Python SDK 接入示例

下面给一份完整的最小接入代码，适合集成到一个已有 FastAPI 服务或者异步 Agent 进程里。核心是三个组件：一个采集器、一个装饰器、一个上报线程。

import asyncio import json import queue import threading import time class ReachCollector: def __init__(self, endpoint=None, batch_size=32): self.queue = queue.Queue() self.endpoint = endpoint # 上报地址，本地调试可为空 self.batch_size = batch_size self._start_worker() def emit(self, event: dict): self.queue.put(event) def _start_worker(self): def worker(): while True: batch = [] while len(batch) < self.batch_size: try: item = self.queue.get(timeout=2) batch.append(item) except queue.Empty: break if not batch: continue if self.endpoint: self._post(batch) else: # 调试阶段直接落盘 with open("reach_events.jsonl", "a") as f: for ev in batch: f.write(json.dumps(ev) + "\n") threading.Thread(target=worker, daemon=True).start() def _post(self, batch): # 这里用 httpx 或 requests 异步 POST 到中心服务 pass reach_collector = ReachCollector() def reach_trace(intent_provider, candidates_provider): def decorator(func): @functools.wraps(func) async def wrapper(*args, **kwargs): session_id = kwargs.get("session_id", "unknown") intent = intent_provider(kwargs) candidates = candidates_provider() start = time.time() try: result = await func(*args, **kwargs) status = "success" except Exception as exc: result = str(exc) status = "error" trace_event = { "event_type": "tool_invocation", "session_id": session_id, "turn_index": kwargs.get("turn_index", -1), "intent": intent, "expected_tools": infer_expected_tools(intent), "actual_tool": func.__name__, "candidates": candidates, "status": status, "latency_ms": round((time.time() - start) * 1000, 2), "timestamp": time.time(), } reach_collector.emit(trace_event) return result return wrapper return decorator

使用的时候就像下面这样挂在工具函数上即可。

@reach_trace( intent_provider=lambda kw: classify_intent(kw.get("user_message", "")), candidates_provider=lambda: list(available_tools.keys()), ) async def return_apply(user_message: str, session_id: str = "", order_id: str = ""): # 实际的退换货申请逻辑 ...

整个接入过程不会触碰 Agent 的决策逻辑，代码评审时也很好讲清楚。这是这套方案在工程化方面比较舒服的地方。

5.3 面板指标解读与基线设定

数据上报之后，分析面板上最先要盯的是三张视图。第一张是"意图维度触达率热力图"，横轴是意图类型，纵轴是工具名称，单元格颜色表示命中率。这张图能迅速暴露"哪个意图总是路由到错误工具"的问题。第二张是"上下文利用度时间序列"，观察每次迭代上下文变化后，知识引用率是上升还是下降，用来指导上下文组织方式的调整。第三张是"未触达会话抽样列表"，点进去可以看到完整的对话记录和 trace，直接判断触达失败的归因是模型问题、工具描述问题还是期望工具集定义问题。

关于基线设定，我建议按意图而不是按整体来定。订单查询这种简单场景，基线可以定得高一点，比如候选集触达率 90% 以上；退换货这种多步骤场景，基线可以定在 70% 左右。基线设置完之后，每次修改工具描述、调整工具顺序、升级模型版本，都要回看基线有没有被打破。Agent-Reach 也支持基线对比功能，把当前版本和历史版本的指标曲线叠在一起，这样模型的升级或者系统提示词的改动，对触达率的影响就是可观测的了。

6. 接入后踩过的坑：误报、采样偏差与基线漂移

6.1 误报：Agent 用组合方式达成了同样目的

触达率指标跑起来之后，第一个大坑是误报。最典型的场景是：模型没有调用期望工具，但它通过调用其他工具加推理，最后给出了同样的正确结果。比如一次订单查询任务，期望工具集里只有order_query和logistics_trace，但模型调用了knowledge_base查订单状态说明文档，然后结合用户消息里的订单号推断出"运输中"这个状态。从业务结果看，它是正确的；从触达率看，它被记了一次 miss。

这种误报如果直接算进指标，会严重误导优化方向。我在实际处理时有两个策略。第一个是增加结果级校验：对于工具型任务，不只看调用了什么工具，还要看任务结果是否正确。如果结果正确且实际调用链路可以合理解释正确结果的产生，就改为"替代路径命中"，不记入触达失败。第二个是定期人工抽样复核 trace，检查那些标注为 miss 的样本里有多少其实是替代路径合理的，然后回来调整期望工具集的定义范围。这个过程会周期性地修正指标口径，让指标系统自身不断进化。

还有一个相关的问题是：模型调用了正确工具，但把参数传错了，导致工具返回错误结果。这个在触达率口径里算 hit，但业务上是失败的。所以我把工具调用结果状态单独立了一个指标叫"执行成功率"，用来捕捉这类"触达了但执行失败"的情况。只看触达率不看执行成功率，同样会被误导。两个指标一起看，才能区分问题出在路由层还是参数层。

6.2 采样偏差与统计口径问题

另一个很容易掉进去的坑是采样偏差。假设你的 Agent 在某个生产周期里跑了大量简单请求，比如用户只问一句"你们发什么快递"，系统直接给了一句标准回答，不需要任何工具调用。这种会话如果全部计入分母，会稀释触达率，因为无工具会话不算"期望工具集出现"的场景，但它们会拉低会话整体质量的平均水平吗？不会，但它们会进入另一类的统计口径问题。

我的处理方法是给分析引擎增加一个过滤条件，只分析那些"期望工具集非空"的会话。这样触达率的分子分母都限定在有工具需求的样本里，数据才具备真实可比性。同理，指令遵循覆盖率的计算也只统计与指令相关的行为片段，无关会话不纳入统计。这个看似简单的过滤规则，落地时很容易被忽略，尤其是数据面板自动出图时，往往会给你看一个全量平均数字，那个数字基本没有指导作用。

采样偏差还体现在轮次维度。同一个会话里，第 1 轮和第 6 轮的触达难度不一样——越到后面上下文越长，模型注意力更分散，触达率天然会下降。如果不区分轮次，只看总触达率，可能掩盖"早期触达正常、后期触达崩掉"的问题。我会按轮次区间做分段统计，比如 1-2 轮、3-4 轮、5 轮以上，分别看触达率，这样能定位到是上下文增长导致的问题还是别的因素。

6.3 模型升级与提示词重构带来的基线漂移

最后一个坑比较隐蔽，叫基线漂移。Agent 项目迭代频繁，每周可能都在改工具描述、调系统提示词、甚至升级底层模型。每次改动都可能让触达率指标的含义发生变化，因为期望工具集和工具描述文本都变了。比如某一次迭代后，你新加了一个工具refund_status_query，它的职责覆盖了原来order_query的一部分场景，那么order_query的期望工具集范围就变了。如果不重新生成期望路由字典，触达率会突然出现大面积 miss，但实际业务并没有变差——只是你没把新工具加进期望集而已。

应对基线漂移的办法，一是每次改完工具表或提示词以后，跑一个回归集。我会维护一份几百条真实脱敏会话的回归样本，改动完成后用 Agent-Reach 重放这些会话，看触达率有没有异常波动。二是路由字典要做版本管理，每次变更都打标签，这样算指标时可以回溯到对应版本。三是指标趋势看相对变化而非绝对值，比如"升级新模型后，在固定回归集上触达率从 72% 涨到 80%"，这种对照要比单独看某一天的绝对值可靠得多。

还有一个和模型相关的漂移要注意：不同版本模型对工具描述的理解方式会变，同样的工具描述，在 GPT-4o 上触达率 85%，换到其他模型上可能只有 55%。这不一定是新模型差，而是新模型对文本风格更敏感。遇到这种情况，光看数字不可靠，需要抽 trace 看真实的调用模式，再针对性调整工具描述的语气和结构。

我个人在实际操作中最深的体会是：Agent-Reach 这类工具本质上不是一键诊断的银弹，而是把"观测—假设—验证"这个循环跑起来的加速器。它不会替你做优化决策，但它能把你从反复试错的迷雾里拉出来，告诉你问题到底出在哪一层、哪一个具体位置。如果你也在做 Agent 项目，尤其是有多个工具、多步决策的复杂场景，我强烈建议哪怕先不搞完整的数据平台，也要把 trace 日志按这里说的格式先记起来。等数据积累到一定量级，你会发现那些原本靠感觉判断的问题，都能变成清清楚楚的数字，优化动作也有的放矢了。