Agent触达能力治理：从LangChain到Agent-Reach的Reach架构设计

1. 从一个翻车场景说起：Agent 为什么会"够不着"？

先讲一个我真实经历过的项目复盘。

去年我在做企业内部的文档智能助手，当时大模型能力已经很能打了，团队核心成员对 LangChain 这类编排框架也熟。但上线之后用户反馈最多的不是"回答不对"，而是"这个助手根本帮不上忙"。用户的典型吐槽是：

我问它"帮我查一下上个月华东区的合同回款率"，它回复我"我暂时无法访问您的合同系统，建议您登录后手动查看"。

这句话本身没有错，但它把一个本该由 Agent 解决的问题，变成了一个用户自我服务的问题。用户觉得这个助手"够不着"真实需求——它知道很多知识，却没有一条通路抵达企业内部的数据和业务系统。

这就是 Agent 项目里最常见、也最容易被低估的问题：能力边界和触达路径。模型再聪明，如果触达不到工具、数据和环境，它就只是一个高级玩具。一个真正的智能体，核心评价指标不应该是"多会聊天"，而应该是"多能干活"——也就是它的触达能力（Reach）。

这就是我这次要分享的项目Agent-Reach想解决的事情。它不是一个具体的聊天机器人，也不是一个完整的大模型应用，而是一层"触达治理"框架：帮你在构建 Agent 时，显式地定义每一个能力点的触达半径、触达路径、降级策略与兜底动作。让智能体真正做到"能触达的一定触达、触达不到的诚实告知、可以桥接的优雅桥接"。

这篇文章我会拆解 Agent-Reach 的整体设计、核心实现、参数选择和踩坑实录。适合正在做 AI Agent、智能客服、企业 Copilot、文档助手、数据分析助手的开发者，以及所有被"模型很强但落地拉胯"折磨过的技术负责人。

2. 整体设计：Agent-Reach 的三层触达架构

2.1 先定义清楚：什么是 Agent 的"触达半径"

我在做 Agent-Reach 之前，先做了一件看起来很简单、实际上很关键的事——把"触达"这个词拆清楚。Agent 对外部世界的访问，本质上是三种类型：

• 知识触达：模型内部参数里已经有的知识，不需要外部调用。比如"什么是复利"。
• 工具触达：通过 API、函数、SDK 访问外部系统。比如查询订单状态、调用计算器、执行 SQL。
• 环境触达：Agent 能对运行环境施加的操作。比如创建文件、发送邮件、操作浏览器。

每一种触达都有半径差异。知识触达半径最浅，一答即达；工具触达依赖于接口可用性、鉴权、网络链路；环境触达则涉及权限边界和安全策略。

Agent-Reach 的核心思想，是把这三种触达统一抽象成一个"可达性评估模型"——每个触达点都有一个 score，表示这个 Agent 在当前时刻有多大概率成功完成这次触达动作。这个 score 不是拍脑袋定的，它是由下游系统状态、接口鉴权状态、历史成功率、超时记录共同算出来的。

生活化类比一下：你把 Agent 想象成一个坐办公室的实习生。这位实习生能不能完成你交办的任务，取决于三个因素：他知不知道怎么做（知识触达）、他有没有对应系统的账号密码（工具触达）、他的工位有没有权限进入存放资料的机房（环境触达）。Agent-Reach 做的就是给这位实习生做一张"权限地图"，把哪些能直接做、哪些需要申请、哪些根本做不了，全部标注清楚。

2.2 三层架构：触达层、决策层、执行层

Agent-Reach 的整体架构我拆成了三层，每层只负责一件事，边界非常清晰：

第一层：触达层（Reach Layer）

这一层维护一份能力注册表（Capability Registry）。注册表里声明了 Agent 所有可能的触达点，包括：

• 触达点 ID（例如query_contract）
• 触达类型（knowledge / tool / environment）
• 调用方式（HTTP、本地函数、数据库连接）
• 鉴权要求（无鉴权 / API Key / OAuth）
• 超时阈值
• 期望返回结构

之所以要建注册表，是因为大多数 Agent 项目失控的根源就是"能力没有一个统一清单"。一旦工具数量超过 20 个，Agent 的决策就变得混乱，经常在一个工具上反复重试，或者选错工具。能力注册表相当于给 Agent 一份"明确可用的技能列表"，而不是让它像个无头苍蝇一样在一个超大 function calling 列表里瞎选。

第二层：决策层（Decision Layer）

这一层负责回答一个问题：面对一个用户请求，当前 Agent 应该直接调用、桥接调用、还是放弃调用？

决策层会从注册表里取出所有候选触达点，结合实时状态（工具健康度、鉴权是否有效），计算一个 reach_score。然后根据 score 阈值分档：

• reach_score >= 0.8：直接走标准触达流程
• 0.4 <= reach_score < 0.8：尝试桥接（比如主接口失败后切换备接口）
• reach_score < 0.4：不尝试调用，直接走兜底话术

这一层的设计初衷是避免 Agent 在低成功率触达上盲目浪费时间和 tokens。实测下来，多数 Agent 项目性能糟糕不是模型不行，而是把大量推理时间消耗在"反复尝试一个注定失败的接口"上。

第三层：执行层（Execution Layer）

执行层是我认为 Agent-Reach 与普通 Agent 框架差异最大的一层。它不只负责把工具调起来，还要负责兜底编排。具体包括：

• 按决策层选定的路径发起调用
• 监控超时和重试次数
• 捕获异常并把异常转化为结构化反馈
• 若主路径失败，自动触发桥接路径
• 所有路径均失败时，生成"诚实型失败响应"——不编造数据，明确告知用户限制和替代建议

这一层是"触达治理"的执行落地。你可以不写这层，Agent 也会"尝试"调用工具，但那个尝试是模糊的、黑盒的、不可观测的。写成执行层之后，每次失败都有迹可循、有账可查。

2.3 为什么我不建议直接用 LangChain 默认的 Tool 机制

这个问题我纠结过很久。LangChain 的@tool装饰器非常方便，几行代码就能把函数暴露给模型。但我在项目里最终选择在 LangChain 之上再加一层 Agent-Reach，原因有三个。

第一，LangChain 的 tool 机制没有原生的"可达性评估"。默认情况下 Agent 会尝试调用所有可用工具，失败了就报错或者让模型硬编一个结果。Agent-Reach 把"可达性"作为一个显式的、可量化的状态引入了决策流程。

第二，LangChain 的 fallback 机制偏向于"换一个模型或换一个接口重试"，但它没有触达点的"桥接"概念。Agent-Reach 里，同一个业务动作可能有多个物理触达点（比如查订单状态，可以走订单 API，也可以走数据库直查），这些触达点之间的切换逻辑需要单独管理。

第三，可观测性。默认 tool 调用日志非常粗糙——谁调用谁、参数是什么、结果是啥。Agent 一旦复杂起来，排查问题全靠缘分。Agent-Reach 的注册表和执行层天然生成结构化日志，每个触达动作都有 trace_id，问题定位效率提升不是一点半点。

3. 核心实现：能力注册表、可达性打分与兜底动作

3.1 工程结构和核心数据结构

Agent-Reach 我用的技术栈是 Python + Pydantic + FastAPI，模型接入层兼容 OpenAI SDK 和各大国产模型平台。工程目录大致如下：

agent_reach/ ├── registry/ │ ├── capability.py # 触达点数据模型 │ └── registry_store.py # 注册表初始化与持久化 ├── decision/ │ ├── scorer.py # 可达性打分器 │ └── router.py # 触达路由决策 ├── execution/ │ ├── executor.py # 统一执行器 │ ├── bridge.py # 桥接路径管理 │ └── fallback.py # 兜底动作编排 ├── protocols/ │ ├── http_protocol.py # HTTP 触达协议 │ ├── sql_protocol.py # 数据库触达协议 │ └── local_protocol.py # 本地函数触达协议 ├── llm/ │ ├── agent.py # 对接大模型的 Agent 入口 │ └── prompts.py # 触达决策提示词模板 └── logs/ └── trace.py # 结构化触达日志

关键的数据模型是触达点。我定义了这样一个 Pydantic 模型：

from enum import Enum from typing import Any, Callable, Optional from pydantic import BaseModel, Field class ReachType(str, Enum): KNOWLEDGE = "knowledge" TOOL = "tool" ENVIRONMENT = "environment" class AuthType(str, Enum): NONE = "none" API_KEY = "api_key" OAUTH = "oauth" class Capability(BaseModel): id: str = Field(..., description="触达点唯一标识") name: str = Field(..., description="触达点名称，如 查询合同") reach_type: ReachType auth_type: AuthType = AuthType.NONE timeout_seconds: float = Field(default=5.0, ge=0.5, le=60) max_retries: int = Field(default=2, ge=0, le=5) success_threshold: float = Field(default=0.7, ge=0.0, le=1.0) handler: Optional[Callable] = Field(default=None, description="实际执行函数") bridge_candidates: list[str] = Field(default_factory=list, description="桥接触达点 ID 列表")

这里每字段的设置都不是随便拍的。timeout_seconds默认 5 秒是我在大量接口调用中统计出来的中位数——太短容易误伤慢接口，太长会让用户等待焦虑。success_threshold默认 0.7，意味着某触达点历史成功率低于 70% 就不建议直接尝试，优先走桥接，这个值你可以根据业务调整。

3.2 可达性打分器：怎么把一个触达点量化成 0~1 的分数

这是 Agent-Reach 的核心计算逻辑。我一开始想过用机器学习模型来预测触达成功率，后来发现这个场景用简单加权就够了——因为触达失败的原因高度集中，无非是网络不通、鉴权过期、参数错误、系统异常四类。

评分公式我设计为：

reach_score = 0.40 * auth_factor + 0.30 * health_factor + 0.20 * latency_factor + 0.10 * history_factor

四个因子的含义和来源：

• auth_factor：0 或 1。当前鉴权是否有效。每次触达前检查 API Key 是否过期、Token 是否在有效期内。这个因子权重最高，因为鉴权失败是"系统性失败"，一旦触发，所有调用都白搭。
• health_factor：0~1。触达点的健康度。基于最近 10 次调用的成功率计算。假设 10 次里成功了 8 次，health_factor 就是 0.8。
• latency_factor：0~1。基于接口最近的平均响应时间。延迟越低，因子越接近 1。设置一个分位数映射函数，比如平均延迟 200ms 以内为 1，超过 3 秒为 0。
• history_factor：0~1。这个触达点在当前业务语义下被调用的历史成功率。与 health_factor 的区别是，health_factor 看的是"接口本身"健康状况，history_factor 看的是"接口在处理这类请求时的成功率"。举例：查询订单接口本身很健康，但查询已删除订单时总是报错，那针对"查询已删除订单"这个语义，history 就要降分。

代码实现不复杂：

class ReachScorer: def __init__(self, health_window: int = 10): self.health_window = health_window # 触达点ID -> 最近N次调用结果的环形缓冲 self.history: dict[str, deque] = defaultdict(lambda: deque(maxlen=health_window)) def record(self, capability_id: str, success: bool, latency_ms: float): self.history[capability_id].append({ "success": success, "latency_ms": latency_ms, }) def score(self, capability: Capability, auth_valid: bool, semantic_key: str) -> float: auth_factor = 1.0 if auth_valid else 0.0 health_factor = self._health(capability.id) latency_factor = self._latency(capability.id) history_factor = self._semantic_history(semantic_key) return 0.40 * auth_factor + 0.30 * health_factor + 0.20 * latency_factor + 0.10 * history_factor

这里有一个重要的设计细节——semantic_key。同一个触达点在不同语义场景下的表现可能差异巨大，比如"查询订单"的接口处理"查询已发货订单"和历史订单时的成功率完全不一样。所以我给每个触达请求都计算了一个语义键（语义键由触达点 ID + 请求参数的关键分类字段组成），历史记录按语义键独立维护。这样做的好处是，Agent 不会因为某个接口在某类请求上失败率高，就完全弃用这个接口——它可能只是不擅长处理那类请求而已。

3.3 路由决策：什么时候直接执行、什么时候桥接、什么时候放弃

有了 reach_score，下一步就是路由。我定义了三个区间，对应三种决策：

def decide(self, capability: Capability, score: float, available_bridges: list[str]) -> RouteDecision: if score >= capability.success_threshold: return RouteDecision(route="DIRECT", reason="score_high") if score >= 0.4 and available_bridges: return RouteDecision(route="BRIDGE", reason="score_medium_bridge_available") return RouteDecision(route="ABSTAIN", reason="score_low_no_bridge")

这里我想特别强调ABSTAIN这个决策。大多数 Agent 框架里没有"放弃"这个选项——模型的 prompt 会逼迫它"无论如何都要给用户一个结果"。但 AI Agent 产品最致命的问题不是"我不行"，而是"假装行"。用户在客服场景被一个自信满满的答案误导，损失和体验损失远大于"这会儿查不到，稍后再试"。

所以 Agent-Reach 的设计原则是：触达确定性优先于回答完整性。宁可让 Agent 对用户说"我现在查不到，但是你可以去 XX 系统自己看，我也可以等你授权后重试"，也不让它编造一个合同编号。

ABSTAIN不是什么都不做，它会触达执行层的兜底动作。兜底动作至少提供三类输出：

1. 结构化失败响应——告诉用户失败原因（超时、鉴权过期、数据不存在）
2. 替代路径建议——如果系统里有可以获取相似信息的其他触达点，推荐给用户
3. 授权引导——如果是权限问题，告诉用户怎么开通权限后重试

3.4 执行层的兜底编排：桥接、降级、超时熔断

执行层是整个 Agent-Reach 里最体现工程细节的部分。我拆成三个子机制来讲。

桥接机制（Bridge）。桥接的本质是：同一个业务目标，有多条物理通路。我在注册表里给每个触达点声明了bridge_candidates。假设主触达点是"订单 API 查询"，桥接候选是"数据库只读用户直查"。当主触达点健康度下降时，执行层自动切换到桥接通路。这个机制救了不知道多少回——有一次订单 API 因为上游系统发布新版本导致响应极慢，Agent 的桥接路径直查数据库，照样把准确结果返回给了用户。

但这里有一个大坑：两个触达点返回的数据结构可能不一样。订单 API 返回的是嵌套 JSON，数据库查出来是关系表的行列结构。所以我做了 Schema Normalizer，在配置里声明每种触达点返回结构的映射关系，桥接之后统一转成标准输出格式。

降级策略（Degradation）。降级和桥接不同。桥接是"换一条路到达同一个目的地"，降级是"降低目标规格，先给用户一个不完整但可用的结果"。比如原本要查"合同明细 + 回款状态 + 客户联系方式"，当部分触达点失败时，降级策略允许 Agent 只返回"合同明细"但明确标注"回款状态和联系方式暂未获取"。

降级策略的本质是保住最低用户体验。这让我想到一个生活场景：你在饭点去餐厅，招牌菜卖完了，好餐厅会告诉你哪些菜还能做，而不是让你干等。Agent 降级就是在做一样的事。

超时熔断（Circuit Breaker）。Agent 最大的隐形成本不是 API 费用，是用户在等待时流失的耐心。我给每个触达点设置了超时阈值，并且实现了熔断器。熔断器的状态机非常简单：

• 正常状态（CLOSED）：请求正常放行
• 熔断状态（OPEN）：连续失败超过 5 次时，短时间内直接拒绝所有打到该触达点的请求，不浪费任何时间
• 半开状态（HALF_OPEN）：熔断 10 秒后放一个试探请求，成功则恢复，失败则继续熔断

熔断器的参数failure_threshold=5和recovery_timeout=10都是我实测调出来的。失败阈值太小容易误伤偶发抖动，太大则熔断没有意义。10 秒的恢复时间对多数内部系统来说，刚好是一波重启完成的时间。

3.5 接入大模型：让 LLM 学会"承认够不着"

现在说 Agent-Reach 如何和 LLM 协作。很多 Agent 产品的问题是模型和工具的边界模糊——模型既在生成回复，又在硬编工具结果。Agent-Reach 的做法是把触达决策从模型手里剥离出来。

流程是这样：

1. 用户输入先进入 LLM 的意图识别阶段，模型输出结构化意图，包括intent_type和required_capabilities列表。
2. required_capabilities不是直接执行，而是进入 Agent-Reach 的决策层做可达性评估。
3. 决策层返回三类结果：可直接执行（EXECUTE）、需桥接（BRIDGE）、不可达（ABSTAIN）。
4. LLM 只负责基于决策结果生成最终回复。如果决策是 ABSTAIN，Prompt 里明确限制——不允许编造触达结果，只能使用兜底动作提供的信息。

这里需要特别设计 Prompt。我用的 System Prompt 片段如下：

你是智能助手的前端表达层。你的职责是根据触达决策结果组织语言回复用户，你本身不能声称你执行了任何数据查询或系统操作。 触达决策结果有三种： 1. EXECUTE：触达成功，请基于返回的真实数据回答用户。 2. BRIDGE：主路径失败但桥接成功，你可以回答，但需在回复中说明数据来源切换，例如"该信息经由备用渠道获取"。 3. ABSTAIN：数据不可达。你必须向用户如实说明暂时无法获取信息，可以引导用户前往系统内查看或建议稍后重试，严禁编造任何数据、编号或状态值。

这个 Prompt 设计的关键是"角色剥离"——模型是表达层，Agent-Reach 是触达层。不要让模型既当运动员又当裁判。实测下来，加上这个约束后，模型编造数据的频率大幅下降，因为它在架构层面就没有"瞎编数据后假装查询"的机会。

4. 实操全记录：给文档助手装上 Agent-Reach

4.1 落地场景与目标拆解

我把 Agent-Reach 用在一个企业内部的营销文档助手上。这个助手的核心使用场景有三个：

1. 销售问"给我找去年 Q4 的某产品线介绍 PPT 模板"
2. 运营问"帮我统计上周投放活动的整体数据"
3. 管理者问"目前知识库里关于新客户 onboarding 的文档有哪些"

在没有 Agent-Reach 之前，这个助手就是一个套了 RAG 的聊天机器人——能回答知识库里的信息，但触达不到销售资料管理系统的元数据和投放数据数据库。用户问数据类问题，它只能给一堆"建议你打开某某报表"的废话。

上 Agent-Reach 之后，我给它注册了 6 个触达点：

capabilities = [ Capability( id="search_knowledge_docs", name="搜索知识库文档", reach_type=ReachType.TOOL, auth_type=AuthType.API_KEY, timeout_seconds=3.0, handler=knowledge_search_handler, ), Capability( id="query_sales_asset_meta", name="查询销售资料元数据", reach_type=ReachType.TOOL, auth_type=AuthType.OAUTH, timeout_seconds=5.0, handler=sales_asset_query_handler, ), Capability( id="query_campaign_metrics", name="查询投放活动数据", reach_type=ReachType.TOOL, auth_type=AuthType.API_KEY, timeout_seconds=8.0, handler=campaign_metrics_handler, ), Capability( id="query_campaign_metrics_db", name="数据库直查投放活动数据", reach_type=ReachType.TOOL, auth_type=AuthType.API_KEY, timeout_seconds=10.0, handler=campaign_metrics_db_handler, bridge_candidates=[], ), ]

注意query_campaign_metrics和query_campaign_metrics_db的桥接关系。在注册表里，我在query_campaign_metrics.bridge_candidates里填了["query_campaign_metrics_db"]。这样当报表 API 超时或者健康度下降时，Agent 会尝试数据库直查。

4.2 关键代码走读：路由与桥接的实际交互

整个调用链的核心在executor.py。我简化了一个版本：

class ReachExecutor: def __init__(self, registry: CapabilityRegistry, scorer: ReachScorer, bridge_manager: BridgeManager): self.registry = registry self.scorer = scorer self.bridge_manager = bridge_manager def execute(self, capability_id: str, payload: dict, semantic_key: str) -> ReachResult: capability = self.registry.get(capability_id) auth_valid = self._check_auth(capability) score = self.scorer.score(capability, auth_valid, semantic_key) decision = self._decide(capability, score, capability.bridge_candidates) trace_id = generate_trace_id() start_time = time.monotonic() if decision.route == "DIRECT": result = self._invoke_safely(capability, payload, trace_id) elif decision.route == "BRIDGE": result = self._invoke_bridge(capability, payload, trace_id) else: result = self._build_abstain(capability, score) latency_ms = (time.monotonic() - start_time) * 1000 self.scorer.record(capability_id, result.success, latency_ms) self._log_trace(trace_id, capability_id, decision.route, score, latency_ms, result) return result

这个函数就是执行层的枢纽。你可以看到，每次触达都记录 trace、更新打分器的历史数据。

_invoke_safely里做了三件关键的事：

def _invoke_safely(self, capability: Capability, payload: dict, trace_id: str) -> ReachResult: for attempt in range(capability.max_retries + 1): try: raw = capability.handler(payload) normalized = self._normalize_output(capability, raw) return ReachResult(success=True, data=normalized) except TimeoutError: if self._circuit_breaker.is_open(capability.id): break continue except AuthError: self._circuit_breaker.open(capability.id) return ReachResult(success=False, error="auth_expired", error_type="AUTH") except Exception as exc: self._circuit_breaker.record_failure(capability.id) return ReachResult(success=False, error="max_retries_exceeded", error_type="TIMEOUT")

细节说明：超时重试的次数不是越多越好。我设了max_retries=2，因为对于 5 秒超时的触达点，3 次尝试意味着最多 15 秒——这已经是用户等待的极限了。鉴权错误则直接熔断不重试，因为 Token 过期后重试 10 次也是同样的结果，不如直接报错触发上游刷新 Token 流程。

4.3 参数选择的实际调优记录

项目过程中，我对几个关键参数做了多轮调优。这部分经验值得单独拿出来说。

首先是timeout_seconds的选取。最初我统一设 10 秒，想着"宽一点总比超时强"。结果发现 Agent 下游的用户反馈"这个助手反应好慢"——因为系统设计是串行的：意图识别（2 秒）→ 可达性评估（0.1 秒）→ 工具调用（最长 10 秒）→ LLM 生成回复（3 秒），最坏情况要 15 秒以上。

后来我把超时改为分级策略：知识库检索 3 秒、元数据查询 5 秒、报表数据查询 8 秒。这样大多数查询的端到端响应时间控制在 6 秒以内，报表类最重查询也不会超过 12 秒。

其次是success_threshold。默认 0.7 在真实场景里偏低了。文档助手这种工具型 Agent，用户对准确率极其敏感，一次错误数据就可能让用户弃用。我把阈值提到 0.85，意味着低于 85% 成功率就进入桥接或放弃流程。代价是有些时候明明接口是好的，但因为历史抖动被桥接绕开，多花了 1~2 秒。这个代价我觉得值。

最后是熔断器的参数。failure_threshold=5是基于一次真实故障调的：营销报表系统的上游数据源切换，导致查询接口连续报错 10 分钟。如果没有熔断，Agent 会在那 10 分钟里不断拿头撞墙，每个用户都卡到超时。有了熔断，5 次失败后直接短路，后续请求 1 毫秒内返回不可达，用户的等待时间从 10 秒降到 1 秒。

4.4 实测效果对比

我把这版 Agent-Reach 的文档助手上线后，拿几个核心指标做了前后对比：

数据类问题有效回答率从 31% 涨到 84%，核心原因就是桥接机制的功劳——报表 API 频繁抖动时，数据库直查接管了大量请求。响应时间下降则主要来自熔断器：大量本会卡到超时的请求，现在 1 秒内就给出兜底反馈。

5. 常见问题与排查技巧实录

5.1 明明注册了触达点，Agent 就是不调用

这是最高频的问题。排查思路按顺序来：

第一步，确认注册表加载成功。我在registry_store.py里加了一个初始化校验函数，启动时会打印每个触达点的注册状态。有时候是配置了@tool装饰器但忘了放进注册表，Agent 当然看不到。

第二步，确认语义键匹配。Agent-Reach 的可达性评估依赖semantic_key。如果意图识别阶段生成的semantic_key和注册表里的不一致，评分会全落到 history_factor 上，导致分数异常低，最终被路由到 ABSTAIN。我遇到过一个案例：用户问"回款率"，意图识别模块把它映射到了query_contract触达点，但历史记录里query_contract在"回款率"语义下的成功率极低，因为合同接口本身不返回回款状态。正确做法是添一个query_payment_status触达点，而不是硬复用合同接口。

第三步，检查路由日志。Agent-Reach 的每个决策都有 trace，包括决策原因reason。如果你看到score_medium_bridge_available，说明评分进入桥接区，但桥接目标可能也没配置对。检查桥接候选列表，确认目标触达点存在且鉴权有效。

5.2 工具返回 200 但结果是空数据

这种问题最迷惑人。接口本身是通的，Reach 层认为触达成功，但返回的 data 是空列表。用户这边看到的结果是"助手一本正经地说没有相关数据"。

我的排查经验分两层：

第一层，看数据的 Schema 映射。很多时候接口返回的不是你期望的字段名。比如接口返回{ "items": [] }，但代码里读的是result.data.records，一配错就永远是空。

第二层，把这个触达点的history_factor看了一下。Agent-Reach 会记录"语义键"级别的结果。如果某个语义键下最近 N 次都返回空，说明这个语义对应的下游数据源本身就没数据——不是触达链路断，是数据真没有。这种情况 Agent 应该输出"没有查到相关记录"而不是"我无法访问"。

还有一个隐蔽场景：接口返回空是因为请求参数没传对。比如查询"上一季度数据"，前端传的是当前日期但没有做季度偏移，接口认为你在查未来数据所以返回空。这种 bug 隐藏在业务逻辑里，Agent-Reach 查不出来，只能靠你多维度校验入参。

5.3 模型幻觉导致"假装触达"

即便有了角色剥离的 Prompt，我还是遇到过幻觉——某些模型会无视 System Prompt 约束，在生成回复时自行编造数据库字段和查询动作描述。

这个问题我的处理方式是双保险。第一道保险是上述 Prompt 约束。第二道保险是响应后校验：拿到 LLM 的最终回复后，在输出层做一个简单校验，检查回复中是否包含了触达结果中的真实数据字段值。如果回复里出现了一个触达结果中根本不存在的合同编号或金额数字，拦截并重生成。

校验逻辑不复杂：

def validate_response(llm_text: str, reach_result: ReachResult) -> bool: if reach_result.success: real_values = extract_real_values(reach_result.data) fabricated = detect_numbers_not_in(llm_text, real_values) if fabricated: log_warning("llm fabricated data", fabricated) return False return True

这种"数据围栏"的做法很有效。它本质上是从结果侧封锁了幻觉产生的路径，比单纯靠模型自觉靠谱得多。

5.4 超时重试导致下游系统重复提交

这个问题在支付、订单类操作中尤其严重。如果你的触达点是"创建工单"这种非幂等操作，一旦超时重试，用户在下游系统里可能看到两个工单。

Agent-Reach 的解决办法是引入幂等键。每次触达在 payload 里附带一个request_id，下游系统消费时记录这个 ID，重复请求直接返回之前的结果。如果你的下游系统不支持幂等，那么在执行层的配速上就非常保守：非幂等操作的max_retries直接设 0，宁可让一次操作失败，也不能产生脏数据。

我之前就把这个坑踩实了。上线初期给"创建工单"接口设置了max_retries=2，结果有用户反馈工单重复创建了 3 次。排查后立刻把该触达点的重试改为 0，并加了幂等键支持。此后没再出现类似问题。

6. 一些踩坑后的心得与后续计划

6.1 警惕"万能 Agent"的诱惑

做 Agent-Reach 期间我最大的体会是：Agent 的能力边界不是模型决定的，是你给它搭的路由决定的。团队曾经拿到一个大参数量的模型，觉得"模型更强了，应该能自己搞定更多事情了"。结果发现它依然够不着那些本该够得着的系统——因为没有注册表、没有路由、没有桥接，模型再聪明也只能在知识触达维度发力。

这就像给一个天才配一台没有网线、没有硬盘的电脑，天才也只能在内存里自己跟自己玩。Agent-Reach 的意义就是把网线插上、硬盘挂上、权限开好，让模型的能力真正输出到业务系统。

6.2 触达半径不是越大越好

这个原则我是在被安全团队教育之后深刻理解的。最初我把触达点的范围设置得很宽，想着"多给 Agent 一些通路，它就能处理更多问题"。结果有次 Agent 在回复中透露了内部数据库的某个字段名，虽然没泄露具体数据，但安全评审直接打了回来。

后来我引入了最小触达原则：每个 Agent 场景只注册它完成核心任务所需要的触达点，不做任何无关联的扩展。文档助手不需要触达财务系统、不需要触达员工通讯录、不需要写入权限。半径收窄之后，安全隐患减少，路由决策也更快——候选集小了，打分和排序的计算消耗自然低。

6.3 下一步计划：让触达评分更智能化

目前 Agent-Reach 的可达性评分是加权公式，透明、可调试，但上限有限。下一步我在做两件事：

第一，把触达历史数据沉淀下来，做一个基于时序特征的预测模型。接口的健康度不只看最近 10 次的成功率，还应该看趋势——比如最近 10 次虽然在成功，但响应延迟在快速攀升，这往往是即将出问题的信号。时序特征能提前识别这种"渐衰模式"。

第二，增加跨 Agent 的能力共享。目前每个 Agent 实例维护自己的注册表和历史记录，这会导致 A 机器人和 B 机器人在处理同一个触达点时各自为战。我准备做一个中心化的触达状态服务，多个 Agent 共享一份管理数据，这样"A 已经发现某接口在抖动"这个信息可以立刻传导给 B，提前走桥接。

老实说，Agent-Reach 还远不完美。它做不到的事情很多：它不能替你把某个系统从 0 到 1 打通 API，不能替你说服下游团队开放鉴权，也不能解决数据本身质量差的问题。它解决的问题只有一个，但我觉得是最关键的一个——让你清楚地知道你的 Agent 到底能触达什么、不能触达什么，以及当它触达不到的时候，如何体面地承认并给出替代方案。

这个问题的答案，决定了你的智能体是一个"演示利器"还是一个"生产力工具"。