企业官网建设流程全解析

Agent-Reach 是我手头正在推进的一个内部项目代号。核心要解决的问题一句话就能说清楚：让大模型智能体不只会在对话框里聊得头头是道，而是真正触达企业内部的业务系统、数据库和第三方 API，把“会说”变成“能办”。这中间缺的并不是大模型的能力，而是一层稳定、可控、能被审计的“触达层”。这篇文章会把 Agent-Reach 从设计思路、核心组件到实测踩坑全部摊开讲，给同样在搭智能体平台的同学当个参考。

先交代一下背景。我所在的小组负责公司内部的智能助手平台，一开始大家都很兴奋，觉得接个大模型 API 就能解决一切，真正做下去才发现，模型对话能力强不等于业务能落地。用户问“帮我查一下昨天订单为什么还没发货”，模型就算再聪明，如果它不知道去哪查订单、没有权限调订单系统的接口、不知道接口返回的数据结构，答案就只能是“请您联系客服”。这就是 Agent-Reach 出现的直接原因：给智能体补上触达业务系统的那双手。

1. 项目定位与设计拆解

1.1 Agent-Reach 到底是什么

Agent-Reach 不是一个聊天机器人，也不是一个业务流程引擎，它是一层专门负责“让智能体触达真实系统”的中间件。你可以把它理解成智能体和公司内部所有系统之间唯一的入口。它做四件事：统一暴露业务能力、统一做权限校验、统一记录每一次触达行为、统一处理重试和故障。

举个例子。公司里有一个订单查询接口，原来可能是给 Web 前端用的，路径、参数、鉴权方式各不相同。Agent-Reach 做的不是把这个接口直接丢给大模型，而是把它封装成一个“工具”，工具的调用方式、参数约束、返回格式都由 Agent-Reach 管理。智能体遇到用户问题，先判断需要哪个工具，然后向 Agent-Reach 发起调用请求，由 Agent-Reach 完成实际的 HTTP 请求、数据解析、异常兜底，再把结果返回给智能体。

这样设计的好处是：业务系统不需要为大模型做任何改造，智能体也不需要知道内部网络的细节。两边都只和 Agent-Reach 打交道。

1.2 为什么“触达”反而成了瓶颈

大模型本身没有手脚，这是常识。但很多人忽略了另一件事：就算给大模型接了工具调用能力，没有一套完整的触达机制，生产环境照样跑不起来。我见过不少团队直接把业务接口文档粘贴给模型，让模型去猜测参数，结果就是一上线就暴露出各种问题。

第一，每个业务接口的鉴权方式不一样。有的是用内部 token，有的是 OAuth2，有的要靠网关签名。智能体不可能为每种鉴权方式都写一遍逻辑，就算写了，换一个系统又得重来。

第二，接口返回的数据量不可控。一次查询可能返回几十个字段，其中大部分模型用不上。如果不做裁剪，大模型的上下文很快就被无关数据塞满，回答质量直线下降。

第三，安全问题。给模型开放 API 调用权限，意味着模型可能被诱导去调用危险接口，比如删除数据、修改配置。没有任何管控直接把这类能力开放出去，等于给系统埋雷。

这三个问题共同指向一个结论：触达不是“能不能调到接口”的问题，而是“怎么安全、稳定、可控地调接口”的问题。Agent-Reach 就是围绕这个结论设计的。

1.3 为什么选择中间层而不是直连

当时也有同事提议，说干脆让每个智能体直接拿着 API Key 去调业务接口，省掉一层转发，延迟还低。这个方案听起来简单，但我在评估之后还是否定了。

直连模式的第一个问题是无法统一埋点。你根本不知道某个智能体在什么时间调了什么接口、传了什么参数、返回了什么结果。一旦出了问题，连“是不是模型乱调用导致”都查不清。第二个问题是权限管理失控。每个智能体都有一堆 API Key，密钥散落在各处，回收和轮换都是灾难。第三个问题是重复建设。每接入一个智能体，都要重新对接一遍业务系统，工作量随着智能体数量线性增长。

中间层虽然多了一次网络调用，但换来了统一的入口。所有触达行为都经过同一个地方，权限在那里校验，日志在那里沉淀，限流和熔断也在那里做。这个取舍我觉得非常值。类比一下，公司里不可能每个员工都直接进财务系统改数据，总得有一个报销流程或审批人，Agent-Reach 干的就是这件事。

2. 核心架构与关键组件

2.1 四大组件：网关、注册中心、执行引擎、审计中心

Agent-Reach 的逻辑架构不复杂，核心就是四个部分。

API 网关负责接收来自智能体的请求，统一处理认证、限流、路由。智能体调用工具时，请求不是直接打到业务接口，而是先到网关。网关校验调用方身份，确认它有权限使用某个工具，再转发给执行引擎。

工具注册中心是 Agent-Reach 的“目录”。业务系统接入时，需要把能对外提供的能力在这里登记，登记内容包括工具名称、描述、参数定义、返回结构、调用地址、超时时间、幂等性等。这个中心的价值在于让“触达”变成标准化流程，而不是每次临时对接。

执行引擎是真正干活的地方。它根据注册中心里的工具定义，把标准化的工具调用转换成对具体业务系统的实际请求，然后解析响应、处理异常、做数据裁剪，最后把干净的结果返回给智能体。

审计中心记录所有触达日志。谁在什么时间用了哪个工具，参数是什么，结果是什么，耗时多少，有没有报错，全部落库。这部分是我最坚持的，没有审计的触达层等于没做。

2.2 工具注册中心：为什么用 JSON Schema

工具注册中心里最关键的是工具描述格式。我们最终选用了 JSON Schema 来定义每个工具的入参和出参。这个选择不是拍脑袋，而是因为当前主流大模型的函数调用功能原生支持 JSON Schema 格式，兼容性最好。

一个工具的注册定义看起来是这样的：

{ "name": "query_order", "description": "根据订单ID查询订单基本信息，包括状态、金额、收货地址。当用户询问订单进度、物流信息、支付状态时使用。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单编号，例如 SO20240001" }, "include_items": { "type": "boolean", "description": "是否返回订单明细，默认false" } }, "required": ["order_id"] } }

这里的名称和描述非常关键。模型不会读接口文档，它只会根据这段描述来判断“什么时候该用这个工具、该怎么传参数”。所以描述里不能只写“查询订单”，而要写出模型在什么场景下会联想到它。后面我会专门讲这个坑。

2.3 安全边界：默认拒绝与最小权限

权限设计上，我们采用了默认拒绝原则。所有工具默认不对任何智能体开放，必须在注册时显式声明哪些智能体或哪些角色可以使用。就算用户对智能体说“帮我把订单金额改掉”，如果智能体没有调用修改类工具的权限，Agent-Reach 会直接返回权限不足。

敏感操作还加了二次确认机制。比如智能体想发起一笔退款，Agent-Reach 会把操作详情以卡片形式推送给用户确认，用户点击确认后才会真正执行。这一设计看起来多了一步交互，却挡住了大量误操作和潜在的提示注入攻击。

我推荐所有做智能体平台的同学都把这一条写进第一版设计里，而不是上线后再补。补权限管控会非常痛苦，因为业务方已经习惯了直连的便利，你再要求他们改造，阻力会大很多。

2.4 超时、重试与幂等控制

执行引擎里有一组参数，上线前必须想清楚。

超时时间我们统一设置为 5 秒。业务系统正常情况下接口响应都在 1 秒内，超过 5 秒大概率是出问题了。这个时候与其让智能体一直等着，不如直接返回“查询超时”，让模型告诉用户稍后再试。

重试只对幂等接口开启。比如查询订单，重复查几次结果都一样，这种可以重试一次。但创建工单、发起支付这类接口，一旦重试就可能重复下单，必须设置为失败后直接返回错误，由用户决定是否再试。我们给每个工具定义里加了一个idempotent字段，执行引擎根据这个字段决定重试策略。

熔断也做了。某个业务系统的错误率连续 30 秒超过 50%，执行引擎会直接熔断该系统的所有工具调用，避免因为一个下游服务故障拖垮整个智能体平台。这个和微服务里的熔断器是一个思路。

3. 实操过程：从零搭建 Agent-Reach

3.1 第一步：把业务能力封装成标准化工具

实际操作中，我们第一个接入的是订单查询服务。这个服务本身是内部的一个 HTTP API，参数很简单，给一个订单号，返回订单状态和金额。

我写了一个简单的 FastAPI 服务来模拟这个过程。

from fastapi import FastAPI import uvicorn app = FastAPI() @app.get("/tools/query_order") def query_order(order_id: str): # 实际场景这里会调用下游订单系统 if order_id.startswith("SO"): return { "status": "success", "data": { "order_id": order_id, "order_status": "已发货", "amount": 199.00 } } return { "status": "error", "code": "ORDER_NOT_FOUND", "message": "订单不存在，请检查订单号" } if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=8000)

这个工具在 Agent-Reach 里的注册信息就要把前面说的 JSON Schema 填好，然后调用注册中心的 API 提交。这里有一个容易忽略的细节：工具返回的结构要尽量扁平化。嵌套层级太深，模型解析起来容易出错，而且返回内容也会更占 token。

只返回模型真正需要的信息。很多内部接口字段几十个，我们只映射了status、amount、order_status这几个。等模型确实需要更多信息时，再提供另一个工具来查询明细。

3.2 第二步：让大模型学会触达

工具注册好了，接下来要让模型知道这个工具的存在。这一步通过把工具定义传给模型完成。以 OpenAI 兼容接口为例，请求里带上tools参数，模型在需要时会返回tool_calls。

核心流程是这样的：

from openai import OpenAI client = OpenAI(base_url="", api_key="") tools = [ { "type": "function", "function": { "name": "query_order", "description": "根据订单ID查询订单基本信息。当用户询问订单进度、物流信息、支付状态时使用。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单编号，例如 SO20240001" } }, "required": ["order_id"] } } } ] # 第一轮请求 response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "你会收到用户的业务问题，请选择合适的工具获取真实信息后再回答。"}, {"role": "user", "content": "帮我查一下 SO20240001 这个订单到哪了"} ], tools=tools, tool_choice="auto" ) # 如果模型返回 tool_calls，说明它选择了调工具 if response.choices[0].message.tool_calls: tool_call = response.choices[0].message.tool_calls[0] # 调用 Agent-Reach 里的实际执行入口 result = invoke_agent_reach(tool_call.function.name, tool_call.function.arguments) # 把工具结果作为新的消息传回给模型 messages.append(response.choices[0].message) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result }) # 第二轮请求，让模型基于真实结果回答用户 final_response = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools ) print(final_response.choices[0].message.content)

这个流程体感上有几个要点。第一，tool_choice我们用的是"auto"，除非对场景非常确定，否则不要用"required"强制模型调用工具。第二，工具结果作为role: "tool"的消息回传时，必须带上对应的tool_call_id，不然 API 会报错。第三，最终回答一定要基于工具返回的真实数据生成，可以在第二轮请求的 prompt 里加一句“请基于工具返回的数据回答，不要编造信息”。

3.3 第三步：把一次触达串成完整链路

单体工具调通之后，就要考虑链路追踪了。我们的做法是引入一个trace_id，从用户发起提问开始生成，贯穿智能体、Agent-Reach 网关、执行引擎，一直到下游业务系统。

每一次触达行为都会记录到审计库里，表结构大概是这样的：

CREATE TABLE agent_reach_logs ( id BIGINT AUTO_INCREMENT PRIMARY KEY, trace_id VARCHAR(64) NOT NULL, agent_id VARCHAR(64) NOT NULL, user_id VARCHAR(64) NOT NULL, tool_name VARCHAR(128) NOT NULL, request_params JSON, response_data JSON, status VARCHAR(32), error_code VARCHAR(128), latency_ms INT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_trace_id (trace_id), INDEX idx_tool_name (tool_name) );

这个表建完之后，价值立刻体现出来了。有一次线上用户反馈说“智能体胡说八道”，我查了一下日志，发现智能体调用了一个已经下线的工具版本，返回的是缓存里的旧数据。如果没这个日志，排查会非常痛苦。

审计日志还可以用于统计工具的使用频率、哪些工具经常报错、哪些场景模型喜欢选错工具。这些数据反过来指导我们优化工具描述和提示词，形成正向循环。

3.4 上线前的参数核验

我列了一个清单，每次上线新工具前都要对照过一遍。

超时设置是否合理。内部接口一般 5 秒，第三方接口可以放宽到 8 秒，但不能无限等。重试是否只对幂等接口开启。凡是名字里带 update、delete、create、send 的，默认不允许自动重试。

限流配额是否配置。我们按智能体维度做限制，比如某个智能体每分钟最多调用某个工具 50 次，防止一个失控的对话把下游系统打挂。敏感操作是否确认了审批链路。新增一个涉及资金、隐私、删除类的工具，必须走人工审批才能发布。

这个清单看起来琐碎，但每条都是生产环境真实踩坑换来的。智能体最大的特点是你无法预判用户会用什么方式触发工具调用的组合，所以必须把边界设好。

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

4.1 工具描述写不好，模型永远选错工具

有一个真实案例。我们接入了一个客户管理系统的“创建跟进记录”工具，最初描述只写了“create_follow_up_record，用于创建跟进记录”。结果在线运行时，用户说“帮我记一下这个客户明天要续约”，模型却选择了另一个“查询客户详情”的工具，因为它在语义上觉得“记一下”和“详情”有关联。

优化后的描述改成：

create_follow_up_record 当用户想要新增一条客户跟进记录、备注、提醒待办事项时使用。包括但不限于这些表述：记一下、备注一下、添加一条跟进、提醒我、后续安排。

模型选工具的正确率一下子上来了。工具描述里要明确写出它的“触发场景”，而不是只写“它是什么”。这跟人理解指令一样，给别人安排活，你得告诉他什么时候做这件事，比只告诉他这件事叫什么有用得多。

4.2 参数幻觉：模型传了一个不存在的字段

这是做过智能体的人都会遇到的问题。模型在生成工具参数时，偶尔会“自我发挥”。比如我们的订单接口只需要order_id，模型却额外给了customer_id，甚至把order_id写成了orderNo。

解决这个问题的核心是两层。第一层，在 JSON Schema 里把字段名写清楚，并在description里给出示例值。示例值非常重要，模型对示例的遵循度远比我们想象中高。第二层，在执行引擎里加参数硬校验。我们使用 pydantic 对入参做模型校验，不合法就直接返回错误，而不是把错误请求发给下游系统。

校验不通过时的返回信息也要设计得友好一些。直接给模型返回“参数错误，缺少 order_id”这种结构化信息，模型看到之后会自动纠正参数再试一次。这一点体验很好，底层原因是大模型的推理能力足够强，只要给它明确反馈，它能够自我修复。

4.3 上下文爆炸：一个工具返回十层嵌套

另一个高频问题是工具返回数据太大。有一次接了一个客户合同查询工具，下游把整份合同文本都返回了，光这一个工具的结果就占了三万多 token。模型上下文窗口再怎么大也经不住这样消耗，而且大量无关文本还会干扰模型对用户核心问题的判断。

我们后来总结出的原则是：工具返回结果必须按需设计，能不返回的字段一律不返回。能返回摘要的不要返回全文，能用一行的不用十行。如果确实需要获取完整内容，再单独拆一个工具让模型按需调用。这本质上是在给模型“减负”，让它把注意力放在推理而不是处理噪音上。

还有一个技巧，工具返回时做一个简单的“截断”处理。超出一定字符数的内容自动变成“数据过长，已截断，可调用 detail 工具查询”，这样既控制 token 消耗，也保留继续深入查询的路径。

4.4 工具错误信息设计：别让链路断在报错里

刚开始接第三方系统时，只要下游返回非 200 状态码，执行引擎就把爬虫异常直接抛出，模型拿到一串看不懂的报错堆栈，回答就会变成“系统异常，请稍后再试”。这种体验非常差。

后来我把工具返回改成了统一的三段式：status、code、message。无论成功失败，都返回一个结构化的 JSON。下游系统挂了，返回给模型的是：

{ "status": "error", "code": "UPSTREAM_TIMEOUT", "message": "订单系统响应超时，请稍后重试" }

模型拿到这个错误后，能够做两件事。第一，判断这是可重试的临时故障，回答用户“系统繁忙，我帮您再试一次”。第二，不把这种系统级错误误包装成业务错误。结构化错误信息让模型在异常场景下也有了腾挪空间，这一点对智能体的可用性提升非常大。

项目做到现在，我最深的体会是：Agent-Reach 的技术难度并不是最高的，真正难的是在每一个细节上都替模型想到位。你替模型把工具描述写清楚，它就少选错一次；你替它把错误信息设计友好，它就能多自我修复一次；你替它把审计日志记全，出了问题你就能快速定位。智能体触达能力的上限，不取决于大模型的智商，而取决于你这层触达层的设计是否足够细腻。

如果后面你也要做类似的项目，我的建议是先把安全边界和审计做在前面，工具一个个接不用急，稳比快重要得多。Agent-Reach 之后我们计划扩展多智能体之间的触达能力，让不同智能体之间也能通过注册中心互相发现和调用，那将是另一套更讲究治理逻辑的玩法，等落地了再单独写一篇分享。