企业官网建设流程全解析

Agent-Reach：让AI智能体真正“够得着”外部世界的触达层设计

先聊个真实场景。我之前花了两周时间调一个客户支持Agent，提示词写了几百行，RAG检索也调得挺准，模型本身用的是当时最强的那一档。结果一上线就露馅：Agent在对话里明明说了“好的，我帮您查一下订单状态”，实际却根本没有调用订单接口，回了一条编造的状态；偶尔调了接口，又因为权限token过期返回401，Agent把报错信息原样丢给用户。说到底，我很早就理解了一个道理——大模型再聪明，它的能力边界不在“脑子里”，而在“手够得着多远”。这也是我后来开始认真研究Agent-Reach这类智能体触达层设计的原因。

Agent-Reach这个概念可以理解为一套让Agent主动发现、连接、调用并验证外部工具与数据源的基础框架。它解决的不是“怎么让Agent思考”，而是“怎么让Agent真的能做成事”。如果你正在做AI Agent、自动化工作流，或者想把大模型接进业务系统，这篇文章想把我在实践里验证过的那套触达层设计思路完整拆给你看：包括架构怎么搭、最小实现怎么写、上线后会踩哪些坑、以及触达质量到底该怎么量化。这不是什么标准答案，但都是我实际跑过、修过、优化过的路径。

1. Agent的“触达层”：最容易被低估，却最决定成败的一层

1.1 一个“会思考但不会行动”的Agent案例

先说个很典型的失败案例。当时我们做一个会议纪要Agent，目标是让它听完录音之后自动做三件事：提取待办事项、给相关人发邮件、在日历上安排跟进会议。第一版我们所有的精力都花在了提示词工程上，让模型输出漂亮的JSON待办列表。结果模型确实强，结构化提取准确率95%以上。然后呢？提取完就完了，邮件不会自动发，日历不会自动建，所有的待办列表最后还是要人手工复制到飞书/钉钉里去执行。这不是模型笨，而是我们的Agent根本没有任何“手脚”——它不持有邮箱API的凭证，不知道日历服务在哪，没有任何方法把“发邮件”这个意图转成一个真实的HTTP请求。这就是缺失触达层的典型症状。

我当时把这套东西想明白之后，就把Agent的能力拆成两个正交的维度看：规划能力（Planning）和执行能力（Reaching）。前者是模型层面的推理、拆解、决策；后者是系统层面的连接、调用、确认。市面上绝大多数Agent项目，不管宣传得多神，真正拉开差距的往往不是规划，而是执行——也就是它的“触达”能覆盖多少外部资源、有多稳。

1.2 触达层到底包含了哪些东西

我自己的定义里，Agent-Reach这套触达层至少要包含下面四件事：

• 连接器（Connectors）：把外部工具、API、数据库、文件系统、甚至物理设备抽象成Agent可以调用的统一接口。没有连接器，Agent就是个纯聊天的模型。
• 能力发现（Capability Discovery）：Agent在接手一个任务时，得知道自己“有什么工具可用”。就像一个人新入职，得先知道公司有哪些系统、哪些权限、谁负责什么，才能干活。
• 调用路由与执行（Execution & Routing）：知道要调什么，还得能正确地调。鉴权、参数映射、超时、重试、分页，都是这一层的事。
• 结果验证（Verification）：调用完之后，不能假设“请求发出去了就是成功了”。得确认返回的内容合法、完整、且Agent能理解。

这四件事合起来，才构成一个完整的触达层。你去看很多Agent项目，往往只做了第1件的一部分，直接跳到了“让模型多轮调用”，中间缺了一堆东西，所以跑起来总有种“智商在线但手脚残废”的错位感。

1.3 “Agent-Reach”这个名字想强调的设计转变

我给这层起名叫Reach，其实是想强调一个观念切换：不要把外部能力看成固定的、写死的API列表，而要把它看成Agent可以动态“够到”的扩展空间。**够不着，等于不存在。**如果你的Agent只能喝到上下文窗口里的数据，它再有创造力也改变不了任何现实状态。反过来，你的Reach越大、越稳，同样的模型权重就能干越多的实事，你的Agent从“玩具”变成“生产力工具”的那一步，靠的就是这个触达层。

2. Agent-Reach的架构骨架：连接器注册中心与统一触达链路

2.1 连接器注册中心：所有外部资源的“黄页”

触达层的第一步是建立一个注册中心（Registry），它本质上是所有外部连接器的目录。每个连接器在注册时，要提供一段结构化的描述，包括名字、用途、参数、返回结构、鉴权方式。这段描述后期会直接作为“工具说明书”给大模型看，所以写得越规范，模型就越少瞎猜。

一个典型的连接器注册项长什么样？我习惯用JSON描述。比如一个日历查询工具：

{ "name": "calendar_list_events", "description": "查询指定日期范围内的日历日程，返回事件ID、标题、时间、参与人列表。", "connector_type": "rest", "endpoint": "https://api.internal.calendar/v1/events", "method": "GET", "auth": { "type": "oauth2", "scopes": ["calendar:read"] }, "params": { "start_date": {"type": "string", "format": "YYYY-MM-DD", "required": true}, "end_date": {"type": "string", "format": "YYYY-MM-DD", "required": true} }, "success_criteria": { "field": "code", "expected": 0 }, "timeout_seconds": 10, "retry_policy": {"max_attempts": 2, "backoff": "exponential"} }

这个JSON就是连接器和Agent之间的“合同”。我在实际项目里还会加两个字段：一个是idempotent（是否幂等），后面讲重试策略时你会知道为什么这字段很重要；另一个是result_schema，描述返回结果的结构，方便Agent后续做解析和决策。

2.2 能力发现：不能让Agent在“不知道有锤子”的情况下去钉钉子

能力发现听起来玄乎，其实核心就是：在合适的时机，把合适的工具描述放进Agent的上下文。这里面最大的坑是“全部塞进去”。当一个注册中心里有几百个连接器时，把所有工具描述都塞给大模型，既费Token，又会稀释模型对核心指令的注意力，准确率直线下降。

我采用的方案是分层能力发现：

• 第一层：静态分类。每个连接器注册时打上业务域标签（如：财务、人力、CRM、基础设施），Agent根据任务意图做粗筛。这一步可以用一个轻量级模型或规则匹配完成，不烧Token。
• 第二层：语义检索。把工具描述向量化存入本地向量库，用任务描述做相似度检索，召回Top 5-10个相关工具。实际效果比纯关键词匹配好很多，因为模型的任务描述往往口语化（比如“帮我看看大家谁还没填周报”），而工具名是工程化的（report_submission_status_query）。
• 第三层：验证召回。召回的候选工具要过一遍参数约束校验，不满足必填参数条件的直接丢弃，避免模型选了一个“能看但不能真调”的工具。

这一套跑下来，模型真正看到的工具列表稳定在10个以内，调用准确率比“全量塞上下文”版本明显提升，Token消耗也降了一大截。

2.3 调用路由与结果归一化：把20种返回格式变成一种

连接器的“后端”千奇百怪：有的返回JSON，有的返回XML，有的返回纯文本，有的返回二进制。如果让大模型直接面对这种混乱，它会经常解析出错。我在触达层里加了一层归一化（Normalization）：所有连接器的返回都统一转成一个标准结构，至少包含三块：

• status：成功/失败/部分成功
• data：核心业务数据，统一转成JSON对象或数组
• meta：耗时、分页游标、剩余配额、原始请求ID等元信息

这层为什么要放到路由里做，而不是让每个连接器自己做？因为统一标准需要集中管控。如果每个连接器各自定义“成功”的含义，后期做审计、指标统计、重试策略都会变得非常痛苦。我的经验是：宁可花一周写一套归一化协议，也不要在三个月后面对20种乱七八糟的返回格式做应急处理。

归一化之后的返回，还要做一次“减负”再交给大模型。很多API返回里带着大量无意义字段（比如环境标签、内部trace、冗余嵌套），直接把完整JSON丢给模型，一是浪费上下文，二是干扰判断。我会在归一化阶段顺手把result_schema之外的字段剥掉，只保留Agent决策真正需要的那些数据，这也算一种“触达层的上下文管理”。

3. 从零实现一个最小可用的Agent-Reach

3.1 技术选型：为什么是Python + FastAPI + 标准Function Calling

我想先解释下选型逻辑。Python的优势很直接——生态里大模型SDK、向量库、连接器库基本都是Python优先，迭代效率最高。FastAPI用来做连接器注册中心的控制面，主要是因为它的OpenAPI支持太方便了，注册中心本身能自动生成一份API文档，给运维和审计提供了一个现成的看板。至于模型侧，我选的是OpenAI兼容的Function Calling协议来做工具调用，因为这套协议目前兼容性最好，无论是直接用商用模型，还是切换到本地部署的模型服务，接口风格都能延续。

有人可能会问：为什么不用LangChain这类框架？我实际对比过一轮，结论是轻量场景可以用，但当你要精细控制“触达层”的每个环节时，框架的抽象常常变成阻碍。自定义一套足够的灵活度，而且逻辑透明，出了问题可以直接追到某一层。

3.2 最小连接器：HTTP、文件、命令三类工具的落地实现

我先实现三个最小连接器，覆盖三类最常用的触达对象：外部HTTP服务、本地文件系统、本地命令执行。这三类加在一起，已经能完成相当多的真实任务了。

先写基础的连接器基类：

from abc import ABC, abstractmethod class Connector(ABC): name: str description: str params_schema: dict idempotent: bool = False @abstractmethod async def invoke(self, params: dict, context: dict) -> dict: """执行实际调用，返回归一化结果""" pass @abstractmethod async def validate_params(self, params: dict) -> list[str]: """参数校验，返回错误信息列表，空表示通过""" pass

HTTP连接器。这里要特别注意两点：一是超时必须有默认值，二是错误处理要捕获网络异常而不是直接让它抛出。因为Agent调用工具时，一个裸异常会让模型不知所措，归一化的错误信息反而能让模型做出正确的弥补动作。

import httpx from typing import Optional class HttpConnector(Connector): def __init__(self, name, endpoint, method="GET", headers=None, timeout_seconds=10): self.name = name self.endpoint = endpoint self.method = method self.headers = headers or {} self.timeout_seconds = timeout_seconds async def invoke(self, params: dict, context: dict) -> dict: try: async with httpx.AsyncClient(timeout=self.timeout_seconds) as client: response = await client.request( self.method, self.endpoint, params=params.get("query"), json=params.get("body"), headers=self.headers ) payload = response.json() if response.headers.get("content-type", "").startswith("application/json") \ else {"raw": response.text} return { "status": "success" if response.status_code < 400 else "error", "data": payload, "meta": {"http_status": response.status_code, "request_id": response.headers.get("x-request-id")} } except httpx.TimeoutException as exc: return {"status": "error", "data": None, "meta": {"error_type": "timeout", "detail": str(exc)}} except httpx.RequestError as exc: return {"status": "error", "data": None, "meta": {"error_type": "network", "detail": str(exc)}}

文件连接器。这里我额外做了一层安全限制——只能访问白名单目录，这是Agent触达本地文件系统时最容易被忽略的安全点。否则Agent在用户输入引导下可以读任意文件，风险极大。事实上我后来在真实部署里，即使加了白名单，还是不推荐让Agent直接碰文件系统，能用API就用API，文件连接器只作为兜底。

import aiofiles, os class FileConnector(Connector): def __init__(self, name, allowed_dir: str): self.name = name self.allowed_dir = os.path.abspath(allowed_dir) self.idempotent = True async def invoke(self, params: dict, context: dict) -> dict: path = os.path.abspath(params["path"]) if not path.startswith(self.allowed_dir): return {"status": "error", "data": None, "meta": {"error_type": "permission", "detail": "路径超出白名单范围"}} import os.path if not os.path.exists(path): return {"status": "error", "data": None, "meta": {"error_type": "not_found", "detail": f"文件不存在: {path}"}} async with aiofiles.open(path, "r", encoding="utf-8") as f: content = await f.read() return {"status": "success", "data": {"content": content[:50000]}, "meta": {"path": path, "bytes": len(content)}}

命令连接器是我最谨慎的一个，也是最容易被滥用的一个。实际生产环境里，我会通过白名单命令+参数校验把Agent的能力限定在可预测范围内，比如只允许执行git status、df -h这类只读命令，写操作一律走专门的发布系统。下面的示例展示了基本结构：

import asyncio, shlex class CommandConnector(Connector): def __init__(self, name, allowed_commands: list[str]): self.name = name self.allowed_commands = allowed_commands self.idempotent = False async def invoke(self, params: dict, context: dict) -> dict: cmd = params["command"] if cmd not in self.allowed_commands: return {"status": "error", "data": None, "meta": {"error_type": "command_not_allowed", "detail": f"{cmd} 不在白名单内"}} process = await asyncio.create_subprocess_shell( cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE ) stdout, stderr = await process.communicate() return { "status": "success" if process.returncode == 0 else "error", "data": {"stdout": stdout.decode()[:20000], "stderr": stderr.decode()[:5000]}, "meta": {"returncode": process.returncode} }

3.3 让Agent学会“触达”：系统提示词与Function Calling双保险

连接器本身并不能让Agent“会用”，还得有一条Agent与触达层之间的协议通道。现在主流做法是Function Calling（也叫Tool Calling），核心思路是：系统提示词里声明有哪些工具可用，模型在生成回复时如果判断需要调用外部资源，就会输出一个结构化的“工具调用请求”，而不是直接生成最终回答。我们这边在提示词层面再加一道“双保险”，防止模型在特殊情况下不按协议走。

我在系统提示词里固定加这么一段：

当你认为需要查询外部信息、修改外部状态或操作其他系统资源时，必须通过available_tools发起工具调用。一次可以并行调用多个工具。工具调用结束后，你才能基于真实返回结果生成回答。严禁在没有调用工具的情况下编造外部状态。如果工具调用失败，你需要明确告诉用户“这个操作暂时没有成功”，而不是伪装成成功。

这段看起来简单，但真实效果出乎意料地好。很多Agent翻车不是因为模型不够强，而是因为它不知道“什么时候该去够外部资源，什么时候可以直接回答”。你把边界规则写清楚，模型的表现会立刻上一个台阶。

Function Calling的调用循环我写成这样：

from openai import OpenAI def run_agent(user_input: str, available_tools: list[dict], client: OpenAI, max_rounds: int = 6): messages = [{"role": "user", "content": user_input}] for round_index in range(max_rounds): response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "system", "content": SYSTEM_PROMPT}] + messages, tools=available_tools, tool_choice="auto" ) message = response.choices[0].message if message.tool_calls: messages.append(message) # 记录模型的工具调用意图 for tool_call in message.tool_calls: result = adapter.invoke(tool_call.function.name, tool_call.function.arguments) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result, ensure_ascii=False) }) continue # 没有工具调用，说明模型认为已经可以回答 return message.content return "达到最大轮次限制，停止。"

这个循环看起来直白，但有一个细节我花过不少时间调：工具调用的中间消息里，一定要带上每个tool_call对应的id，模型和工具结果之间的关联就是靠这个id维持的。如果你把多个工具返回值混在一个tool消息里发给模型，大部分模型会开始犯迷糊。

3.4 本地跑通一条完整链路：从自然语言到真实操作

把上面几块拼起来后，我用一个真实场景验证：让Agent去“查一下本地/tmp/reports目录下昨天的销售摘要文件，然后根据内容整理成一段汇报文字”。

这条链路完整走一遍是这样：

1. Agent拿到用户输入后，触发能力发现，召回file_read这个工具。
2. 模型发起file_read调用，参数是{"path": "/tmp/reports/sales_20250210.txt"}。
3. 触达层校验路径在白名单内，读取文件内容，归一化返回给模型。
4. 模型读到了内容里的核心数字，自动生成一段汇报。
5. 期间如果文件不存在，触达层返回not_found错误，模型会根据错误信息提示用户确认文件名是否写对，而不会直接编造一个文件内容。

第一次跑通这个链路时，我最大的感触是：让模型多轮调用工具并不难，难的是让每一轮调用都有清晰、干净、可供模型推理的返回。触达层的价值不在“能调”，而在“调一次就清清楚楚告诉模型发生了什么”。

4. 我在真实环境中踩过的触达深坑

4.1 “工具调用成功了，但什么都没发生”：无效成功

这是接触Agent-Reach后我遇到的第一个诡异问题。有一次Agent调用了一个创建工单的API，返回值是200，日志里也是一片绿。结果业务方反馈：工单系统里根本没有这个单。查了半天，原来是目标系统有个隐含规则：工单必须附带一个非空的customer_id，而我们的Agent传的参数里这个词恰好为空，系统静默丢弃了请求，但HTTP层返回200。这就是典型的无效成功：协议层面成功了，业务层面什么都没发生。

解法是我在注册中心里给每个连接器加上success_criteria字段，用来做业务级成功判断。比如“创建工单”的判定条件就不只是http_status == 200，还必须检查返回体中ticket_id非空、state == "created"。触达层会在归一化时执行这个判定，把“HTTP成功但业务失败”改写成明确的status: "error"，模型收到后就能正确向用户解释，并触发下一步补救（比如换一个正确的customer_id重试，或者向用户确认信息）。这个字段的排查价值特别大，建议每一个写操作连接器都配上。

4.2 权限黑洞：容器内能连通，容器外一片权限报错

我把一套Agent-Demo部署进Kubernetes之后，出现了很经典的一类故障：本地开发时Agent调用内部系统的API一切正常，但容器化后频繁报401。查下来发现，容器环境里的客户端根本没配置service account的token注入，而本地是开发者的个人token。代码一模一样，环境变量不一致，触达层直接瘫痪。

还有一个更隐蔽的：有些内部系统基于来源IP做白名单，容器出网IP是浮动NAT池，一次请求的源IP和下一次不同，导致同一套token一会儿有效一会儿无效。这类“权限黑洞”很难通过看日志立刻发现，我现在的做法是：在触达层的meta里强制记录鉴权上下文快照（用的哪种凭证、凭证过期时间、目标系统返回的具体错误码），一旦出问题，排查效率高得多。另外，生产环境部署Agent前，做一次“全工具连通性巡检”应该被列入上线的checklist，而不是等用户触发了才暴露。

4.3 返回体太大，模型的主上下文被撑爆

有段时间我让一个Agent做数据分析，它调用一个报表API成功返回了，但那份报表有数千行明细。Agent把整份结果都塞进上下文之后，模型开始表现得“注意力涣散”：后续指令执行不完整，甚至开始重复自己说过的话。分析上下文容量后发现，工具返回占了总上下文量的85%，留给模型推理的空间所剩无几。

后来我做了三件事：第一，在连接器层统一做返回截断，前列字段明显超限就直接截断，并在meta里标注已截断；第二，对超大的返回结果，不是全部丢给模型，而是先经过一层摘要预处理——用一个小模型把长文本压缩成结构化摘要（“总计xx、环比xx、TOP3异常项xx”）再进入主上下文；第三，设置工具返回的Token预算（比如单次工具返回不超过上下文总预算的30%），超了就自动触发摘要流程。这做法的核心原则是：触达层不仅要把数据拿到，还要加工成适合模型决策的形态。

4.4 一次重试，用户收到了两封邮件：幂等设计的账

这是个很常见的生产事故。Agent调“发送通知邮件”的API，因为目标邮件服务慢，触达层超时重试了一次。结果用户收到了两封一模一样的邮件。这是非幂等操作被盲目重试的典型后果。后来我梳理了注册中心里所有写操作连接器，按幂等性分了三类，并设计了相应的重试策略：

具体到实现，HTTP连接器会自动检查idempotent字段。是幂等操作，超时后按指数退避重试；非幂等操作，触达层不重试，直接给模型返回一个“由于超时，操作是否完成未知，需要向用户确认”的状态。这个“未知状态”非常重要，它让模型学会了用自然语言向用户求证，而不是闷头再调一次。那两封重复邮件的教训之后，我对所有Agent新增了一条验收项：每一个非幂等工具都必须设计明确的“结果未知”分支。

4.5 时区、编码、分页：三个不起眼的隐性杀手

最后这部分全是细节但都很致命。时区方面，一次Agent把“明早9点的会议”解析成了UTC时间存进去，结果所有人看到的是北京时间的下午5点。触达层在调用日历API时，必须显式声明时区，并让时间参数带有offset信息，而不是交付一个裸的ISO字符串。编码方面，有些老旧系统返回GBK编码的中文，直接按UTF-8解码会乱码，Agent基于乱码内容做判断，结果全错。我在连接器层加了一个编码探测逻辑，识别的优先顺序是JSON Content-Type头声明的charset > 响应头meta > 内容特征探测。分页方面更是重灾区：列表类接口往往只返回第一页，Agent不知道还有第二页，导致统计结果严重偏差。解决方案是归一化时把分页字段固化为meta.pagination，同时把“是否可能还有后续页”也明确告诉模型，模型就能自己决定要不要继续翻页。

5. 触达质量该用什么衡量：我是这样给Agent-Reach定指标的

5.1 触达覆盖率：你的Agent到底“够得着”多少东西

覆盖率是我考核触达层的关键指标之一，计算公式是：业务需要的操作总数 / 已通过触达层标准连接器暴露的操作总数。比如一个售后服务Agent，业务上需要50种能力（查订单、改地址、申请退款、查物流、联系客服……），其中45种已经通过连接器暴露，覆盖率就是90%。剩下的10%会让Agent在某些场景下“心有余而力不足”，要么建议用户转人工，要么给出替代路径。我把这10%列成“触达缺口清单”，每两周跟业务方盘一次，看哪些缺口值得优先连接。这个指标最大的价值是让“Agent能不能干活”从一句感觉变成一张表，每个季度都能看到覆盖率在提升，也方便向上汇报投入产出。

5.2 端到端成功率：从自然语言意图到真实操作完成的完整链路

覆盖率代表广度，成功率代表质量。我定义的端到端成功率不是“模型正确输出工具调用”的比例，而是从用户输入开始，到目标操作真实完成且返回结果有效为止的完整链路成功率。中间任何一环失败（能力发现漏召回、参数校验失败、鉴权失败、超时、业务级无效成功）都算失败。我们有过一个真实数据对比：只看“模型工具调用格式正确率”时，指标在95%以上，很漂亮；一改成端到端成功率，立刻掉到73%。这22个百分点的差距，全都在触达层里。所以我现在汇报指标时，永远用端到端成功率，那些分环节的指标只作为定位问题的诊断维度。

失败原因要有门类统计。我们的数据里，鉴权失败、参数错误、超时、后端5xx这几类占了绝大多数。每一类都有针对性的优化路径：

• 鉴权失败：加缓存和预刷新，避免token过期导致的偶发失败。
• 参数错误：多半是能力发现阶段对该工具的描述不够准确，模型用错了字段。优化方向是改写工具描述，让它和真实业务语义对齐。
• 超时：调整连接器的超时阈值，或检查目标系统性能瓶颈。
• 后端5xx：这种一般不是Agent的问题，要做的是故障降级——返回状态明确提示“服务暂不可用”，并引导用户换时间再试。

5.3 触达时延与超时预算

Agent触达的时延体验直接影响用户对“智能”的感知。我定了一组超时预算：单次工具调用默认超时10秒，这10秒被切分成三份——网络连接（2秒）、等待响应（7秒）、内容处理（1秒）。超过预算会自动取消本次调用并进入失败分支。整个Agent单轮任务的触达总预算控制在30秒内，超过则主动向用户说“我需要一些时间进一步处理，稍后再给你结果”。这比让用户干等一个一分钟的转圈要好得多。

还有一个容易被忽略的：并行调用。当模型判断需要获取多个信息源时，让它并行发起工具调用，而不是串行等一个再调下一个。我们做一个竞品分析Agent时，原本要串行调4个平台的数据接口，总共耗时40多秒；改成并行后压到11秒，体验提升一个量级。Function Calling协议本身支持在一次回复里输出多个tool_calls，触达层用asyncio.gather并发执行就行，不需要改协议。

5.4 规模化后的可运维性：从10个工具到1000个工具

最后这节是给把Agent-Reach用于生产环境的同行看的。连接器少的时候，注册中心可以直接用内存里的一个字典，一个人维护绰绰有余。当连接器数量增长到几百上千个，事情就变了。我现在的做法是：注册中心本身作为一个独立的存储服务，所有元数据放数据库，并对外提供API用于连接器的注册、更新、下线和模糊查询。每个连接器有版本号，升级时不搞“热切换直接覆盖”，而是先注册新版本，灰度流量验证后再切全量。我们把出问题的连接器单独标记为“degraded”，它会从能力发现的结果中被暂时剔除，不再被Agent召回。

另外，触达日志必须有。每次工具调用的入参、出参、耗时、鉴权上下文、归一化状态，全部落审计日志。这套日志既是排查问题的依据，也是后续做触达质量分析的原始数据。我见过一些项目把工具调用日志当普通debug信息，只保留一两天，结果出了事故无从追溯，非常可惜。现在我会把触达日志保留至少90天，关键业务链路甚至可以更长。

整个Agent-Reach的设计和落地，其实就是在解决一件看起来很简单但真正做到位很难的事：让AI在现实世界里不仅“会想”，而且“能办成事”。我测试过不同规模的模型，也换过不同的连接方式，最终沉淀下来的核心认知就是——触达层的设计质量，往往比模型本身的选型更能决定一个Agent项目是否值得投入生产。写这篇内容的初衷，也是希望正在做Agent的朋友们不要只盯着提示词和模型参数，多花一点精力在“手脚”上，你会得到非常值得的回报。触达层的每一次优化，最终都会变成用户的真实体感：更快、更稳、更可靠。