企业官网建设流程全解析

带了几套 AI Agent 项目上线之后，我最大的感触是：大模型其实不缺思考能力，缺的是“够东西”的能力。这里的够东西，指的是稳定地触达外部系统——查订单要调接口，翻库存要读数据库，发通知要走审批流。只要这一步做得琐碎，Agent 的智商立刻被拉回及格线，因为它一半的心思都花在猜该调谁的 API、凭证藏在哪、超时了怎么办上。这半年我一直在做一件事：把所有 Agent 对外的触达能力收拢到一个统一的中间层里，项目代号叫 Agent-Reach。

如果你正在做 LLM 应用，经常被工具调用、权限鉴权和超时重试这些杂事缠住，那么这篇实战复盘应该能帮上忙。我会从为什么值得做这一层，到协议如何设计、权限如何收敛、代码怎么落地，再到上线两周的实测数据和踩坑记录，完整走一遍。整体思路不复杂，但里面的取舍和坑，都是文档里不会写的。

1. Agent-Reach 是怎么冒出来的：Agent 的“最后一百米”问题

1.1 大模型能思考，却够不着系统

我们团队最早的三套 Agent，都是各管各的。客服 Agent 需要查订单，销售 Agent 需要查客户资产，运营 Agent 需要拉报表。每套 Agent 都直接拿着对应系统的 API 文档，在代码里拼接口、拼鉴权、拼重试。三个月后再看，谁也不敢轻易动，因为每个 Agent 背后的调用方式都不一样，出问题只能一家一家去翻日志。

这个状态我称之为“最后一百米”问题：模型的推理能力再强，只要触达系统这一步是松散的，整体稳定性就跟着松散。具体表现大概有几种：

• 密钥和凭证散落在提示词、环境变量、代码仓库里，做安全审查基本靠肉眼。
• 同一个后端系统被三个 Agent 各自接了一遍，请求格式不统一，后端同学被问得头大。
• Agent 调用失败之后会“发挥主观能动性”反复重试，把下游接口打得直冒烟。
• 老板问“这几个 Agent 今天调了多少次接口、成功多少”，我们居然答不上来。

这个痛点不是少写几行代码的问题，而是系统能不能支撑 Agent 从 Demo 走向生产的问题。我当时定了一个目标：让 Agent 只负责描述意图，把工具发现、权限校验、请求转发、限流重试全部下沉到一个独立组件。这个组件就是 Agent-Reach 的雏形。

1.2 现有工具链很强，但胶水代码还是得自己写

可能有人第一反应是，LangChain 的工具调用已经很成熟了，为什么还要自己搭一套？我也用过，确实方便，只要定义好 decorator，大模型就能自动选择工具。但它解决的是“框架内部怎么组织工具”，没有解决“组织的边界和控制权握在谁手里”的问题。

我踩过几个比较实际的地方：

• 框架绑定比较紧。今天用 LangChain，明天换别的编排框架，工具层基本要跟着推翻重来。
• 企业内部的系统，像审批中心、工单平台、私有化数据库，现成 SDK 里根本没有适配，最后还是得自己写胶水层。
• 对“权限模型怎么设计”“用户维度怎么隔离”“审计日志怎么留”这套治理问题，工具框架基本不管。它默认你环境里的凭据是安全的，但做生产系统的人都知道，默认是危险的。

业界后来也出了 MCP 这样的统一协议思路，方向我是认可的。但统一协议解决的是“通信格式标准化”，服务端连接器的注册发现、用户鉴权映射、多环境配置管理，这些工程环节仍然要团队自己搭。

所以我做 Agent-Reach 的核心决策是：做一个与模型解耦的触达层。上层无论是用 GPT 还是开源模型，无论是 LangChain 还是直接裸写 function calling，都不影响这一层的稳定工作。解耦这件事，在使用初期看不到好处，等你要换模型或者加 Agent 的时候，好处会非常明显。

2. 统一触达协议与权限模型：Agent-Reach 的骨架

2.1 触达请求长什么样：一套轻量协议

Agent-Reach 的第一个设计任务，不是写代码，而是定协议。所有 Agent 的触达请求都必须走同一个格式，中间层只认这一种信封。我们的信封大概长这样：

{ "request_id": "reach-7f3a12c9-45", "op": "call", "target": { "kind": "http", "namespace": "oms", "name": "get_order" }, "arguments": { "order_id": "SO-20250312-001", "fields": ["status", "assignee"] }, "timeout_ms": 5000, "max_result_tokens": 2048, "caller": { "agent": "customer-service-v2", "user": "u_zhangwei" } }

这里面的字段都不是随便定的。kind 表示触达方式，是走 HTTP、SQL、搜索引擎还是内部 RPC，不同 kind 对应中间层里不同的连接器实现。namespace 表示归属系统，避免不同业务线里的“get_order”撞车。timeout_ms 和 max_result_tokens 是两层保护：前者限制一次调用的时长，后者限制返回结果的大小，防止模型上下文窗口被一次请求撑爆。

caller 字段是我特意放在请求头里的，因为 Agent 本身没有“身份”，真正的身份是背后的用户和场景。权限校验必须同时认两层：这个 Agent 能不能用这个工具，当前用户能不能访问这个数据。只认 Agent 或者只认用户，都会漏一块。

那为什么不用更复杂的协议？因为协议一旦做得太重，连接器的开发成本就高了。Agent-Reach 的定位是轻量转发加治理，不是要重新发明一个跨平台规范。能用一个 JSON 说清楚的事情，就不要引入额外的二进制序列化，这能让以后接新工具方的门槛降到最低。

2.2 权限收敛到中间层：Agent 永远不碰密钥

我在设计 Agent-Reach 时定了一条铁律：Agent 手里永远不存密钥。现实中有很多 Agent 项目，为了快速上线，直接把 API Key 写在系统提示词里，让模型自己去查。这条路非常短视，因为提示词注入攻击防不胜防。一旦提示词或者日志被带外引用，拿到 Key 的攻击者就能直接操作后端系统，而且你还不知道泄露发生在哪个环节。

Agent-Reach 的做法是：用户通过 SSO 或者 OAuth 完成第三方系统授权，拿到的 token 统一存放在中间层的凭据仓库里。Agent 在触达系统中任何一个工具时，只需要提供请求里的 caller 信息。中间层拿到 caller 之后，在权限表里查 Agent 和用户是否有权使用这个工具，然后才用仓库中的密钥去调用后端。

这样即使某一次模型被诱导着发起了恶意触达，权限边界依然是收敛的。攻击者利用的只是当前 Agent 的授权范围，而不是一把能打开所有门的万能钥匙。这个思路本质上是把“信任边界”从模型侧转移到了系统侧，模型变得再不可控，外层系统也还有一道独立闸门。

权限模型我们还做了两件比较细的事情。一是最小权限映射，每个 Agent 只能看到 namespace 里给它配置过的工具，而不是连全部目录都暴露给模型。二是环境隔离，dev 环境里的连接器配置和 prod 完全分离，dev 里测出一百次错误，也不会影响生产数据。这个用惨痛的教训换来的习惯，后面在踩坑部分我会再展开。

2.3 触达结果如何约束：防止上下文被一次调用撑爆

很多 Agent 项目做工具调用时，只关心“调不调得通”，不关心“返回多少”。但在真实生产环境里，一个 SQL 查询返回 8 万行，一个搜索接口返回 200 条记录，是非常常见的情况。如果把这些原始数据全部塞给模型，上下文窗口马上会被挤爆，后续任务直接失去处理能力。

Agent-Reach 在协议层默认做了结果约束。每个触达请求都可以声明 max_result_tokens，中间层返回结果时按这个上限做截断和摘要。如果一次调用返回的内容超过了限制，返回体里会带一个 truncated 标记，同时输出前几条样例和总条数。这样设计是有意的：模型不是需要看到全部数据，它只需要知道“总共有多少、长什么样、接下来怎么取更多”。

有人担心截断会让模型丢失信息，实际使用下来反而更稳定。因为大模型处理超长返回时，注意力会被无关信息稀释，更容易忽略关键字段。而给一个干净摘要，模型判断反而更准。这就像给人类看 80 页报表，不如给一张只包含关键指标的一页纸来得有效。

3. Agent-Reach 的落地实现：从协议到代码

3.1 工程整体结构与模块职责

讲完协议，来看工程是怎么搭的。Agent-Reach 的核心代码量不大，但模块边界要清晰，我把项目结构分成了这样：

agent-reach/ reachagent/ # 核心中间件代码 protocol.py # 请求/响应模型，截断逻辑 registry.py # 连接器注册与发现中心 executor.py # 调用编排：鉴权、限流、超时、重试 auth.py # 用户态与机器态权限映射 connectors/ http_connector.py sql_connector.py search_connector.py configs/ # 环境配置与工具映射 tests/ # 连接器和执行器的集成测试

核心流程很清晰：Agent 发一个 ReachRequest 进来，先经过 auth 校验，再走限流检查，然后从 registry 找到对应连接器，连接器真正执行外部调用，最后把结果包装成 ReachResponse 返回给 Agent。这条路是所有触达请求的唯一通路，没有例外。

这种设计的另一个好处是测试。因为所有调用都收口了，你不需要针对每个 Agent 去模拟外部依赖，只需要测好连接器这一层。我们后来把线上出过的每个事故都转化成了回归测试用例，整体维护成本降到很低。

3.2 用 Pydantic 把协议钉死：参数校验和审计两不误

协议层面我用 Pydantic 做了严格校验，这样请求一进来，非法结构在最早一层就被拦截。示例代码大概是这样的：

from pydantic import BaseModel, Field from typing import Any, Optional class ReachTarget(BaseModel): kind: str namespace: str name: str class ReachRequest(BaseModel): request_id: str op: str = "call" target: ReachTarget arguments: dict[str, Any] = Field(default_factory=dict) timeout_ms: int = Field(5000, ge=100, le=30000) max_result_tokens: int = Field(2048, le=8192) caller_user: str caller_agent: str

注意 timeout_ms 和 max_result_tokens 的上下限约束。timeout_ms 最小 100ms，防止有人乱传一个 1ms 的超时，让连接器还没开始就结束；最大 30 秒，防止单次调用无限拖住整个 Agent 会话。max_result_tokens 上限设到 8192，这是给那种确实需要读取较大数据集的场景留的，但也不会允许它无限大。

Pydantic 模型不仅在运行时做校验，在审计日志里也很好用。每次请求进来，直接把 model_dump 存一份，就得到了结构化完整的调用记录。后面要做成本核算或者安全回溯，都不用再去解析原始报文。

3.3 注册中心：连接器只认约定，不认硬编码

连接器的注册和发现，我用了一个非常轻量的注册中心。每个连接器都实现同一个抽象基类：

from abc import ABC, abstractmethod class BaseConnector(ABC): @abstractmethod async def invoke(self, req: ReachRequest, auth_ctx: "AuthContext") -> "ReachResult": ...

注册中心维护一张表，键是 (kind, namespace, name) 三元组，值是对应的连接器实例。这样 agent 在请求里只要声明 target，中间层就能在 O(1) 时间内完成定位：

class Registry: def __init__(self): self._connectors = {} def register(self, kind: str, namespace: str, name: str, connector: BaseConnector): key = (kind, namespace, name) self._connectors[key] = connector def resolve(self, target: ReachTarget) -> BaseConnector: key = (target.kind, target.namespace, target.name) connector = self._connectors.get(key) if connector is None: raise ToolNotFound(f"{key} 未注册") return connector

这套设计的价值在于：新增一个工具不用改中间层代码，只需要往注册中心添加一个连接器实例。我们后来接企业微信群机器人、接内部流程引擎，都是加配置而不是写新框架。注册中心没有做复杂的服务发现，因为中间层实例数量不多，直接内存维护加启动时加载配置已经够了。如果以后规模大了，再把这张表迁移到 Redis 或者配置中心也不难。

3.4 执行器编排：鉴权先于一切，重试要分场景

执行器是整个 Agent-Reach 的核心，等于是把“鉴权、限流、找连接器、超时控制、重试策略”这五件事按正确顺序串起来。伪代码大概是这样：

async def execute(self, req: ReachRequest) -> ReachResponse: # 1. 权限检查必须在任何外部调用之前 await self.auth.assert_can_call(req) # 2. 限流检查，全局限流和 Agent 级限流都过一遍 await self.limiter.check(req) # 3. 通过注册中心定位真实的连接器 connector = self.registry.resolve(req.target) try: result = await asyncio.wait_for( connector.invoke(req, auth_ctx), timeout=req.timeout_ms / 1000 ) except asyncio.TimeoutError: if self.retry_policy.should_retry(req): return await self.execute(req) # 重试 return self.build_timeout_response(req) return build_response(req, result)

次序上的讲究是：鉴权一定要排在限流前面。因为如果先查限流，一个没有权限的恶意请求也可能把配额给消耗掉，正常用户反而被挡在后面。这是一种防滥用设计，看似顺序问题，实则是安全模型的一部分。

重试策略我们没有一刀切。对于 GET 这类只读请求，判断为幂等，可以重试；对于创建订单、发起审批这类写操作，默认不重试，或者只重试一次并明确提示用户“需要确认”。理由很直白，写操作一旦重复执行，可能产生两条订单或者两个审批流，这种错误比超时本身严重得多。并且所有重试都附带原始 request_id，这样下游系统可以做幂等识别。

3.5 连接器配置与多环境隔离

连接器不是纯代码，很多对接信息是配置。我们给 HTTP 类连接器设计了非常直观的配置格式：

namespaces: oms: inventory: kind: http endpoint: https://api.internal.example/stock/{sku} method: GET auth_profile: sso_oms_service timeout_ms: 3000

配置文件里我刻意不存密钥，只存 auth_profile 的引用。真实的 token 是从密钥管理系统动态取出来的。这样即使配置文件被别人拿到，也只是拿到一堆引用，拿不到真实凭证。

多环境隔离方面，我们为 dev、staging、prod 维护了独立的配置目录。Agent-Reach 启动时根据部署环境加载对应目录，互相之间没有交叉。曾经有同事图省事，把 prod 配置直接复制到 dev 里调试，导致 dev 环境真的把一条测试数据写到了生产库。自那之后，配置目录加了一层环境标签校验，不是当前环境的文件一律拒绝加载。

4. 上线两周后的实测数据与踩坑记录

4.1 量化体现：延迟和成功率的变化

Agent-Reach 上线两周后，我把接入前后的数据拉了一张对比表。这个表不是做展示用的，是我们内部复盘的真实口径：

延迟下降的主要来源不是中间层本身有多快，而是它做了三件直连模式下做不到的事：连接池复用、结果摘要裁剪、预热缓存。直连模式下每个 Agent 自己维护连接，相当于各家自建自来水厂；中间层相当于统一做了水厂和管网，成本自然会降。

成功率提升则主要靠统一限流和重试策略。以前某个 Agent 把下游接口打崩，会连带其他 Agent 也失败；现在限流发生在公共层，某一路突发流量会被挡在中间层，而不是直接打透到业务系统。单 Agent 接入新工具的耗时的下降，对我来说反而是最惊喜的，因为这意味着团队交付效率有了直接改善。

4.2 坑一：重试风暴比超时本身更可怕

上线第五天，我们遇到了一次典型事故。有个 Agent 在调用订单服务时，下游因为数据库慢查询导致接口超时。Agent 端的固定重试规则触发，多个 Agent 同时开始重试，瞬间把下游更慢查询的接口打得更慢，形成恶性循环。

表面上看是“下游性能问题”，实际上是我在重试策略设计上偷懒了。修复方式分了三层：

• 全局限流优先：在 Agent-Reach 层面对每个 namespace 设置最大并发和 QPS，超过阈值直接返回“忙”状态，不向真实系统发起请求。
• 退避加抖动：重试间隔写成阶梯式的指数退避，并且加入随机抖动，避免多个请求在同一个时间点扎堆重试。
• 强制幂等头：所有转发请求都携带原始 request_id，下游可以用它做去重。

这个事故让我意识到一个道理：重试逻辑绝不能只写在 Agent 的提示词或者编排层，必须由中间层统一接管。Agent 在重试上是“只顾自己不顾全局”的，只有公共层才能做全局视角的运维。

4.3 坑二：SQL 结果整包塞给大模型，上下文被撑爆

另一个印象很深的坑来自 BI Agent。它通过 SQL 连接器查询销售明细表，SQL 连接器当时实现得比较简单，直接把查询结果全部返回。有一个 Agent 连着查了几张宽表，每张表返回几万行，模型上下文直接被挤爆，后面的任务连续报错，而且很难从日志里看出原因。

后来在 SQL 连接器里加了硬性约束：

• 强制追加 LIMIT，默认只返回前 100 行，并且禁止无 WHERE 条件的全表查询。
• 返回结果统一做摘要：总数、列名、前 5 行样例，总长度控制在几百个字符以内。
• 如果 Agent 确实需要分析更多数据，它只能分批调用，比如显式指定 offset 和 limit。

这个设计本质上是“把大结果切碎给模型”。刚开始有业务方担心效果会打折扣，实测下来反而更精准，因为模型不会被海量原始记录带着跑偏。现在 SQL 连接器已经成为 Agent-Reach 里最被依赖的组件之一。

4.4 问题排查速查表

接过两个月线上问题之后，我把最常见的现象整理成了一张速查表，新同学排查问题时直接对照：

我建议凡是做 Agent-Reach 这一层的团队，从第一天就把 trace 链路打通。每个触达请求都生成一个 request_id，并且贯穿中间层转发和下游调用全过程。这个 ID 是排障的灵魂，没有它出了事只能靠猜。

5. Agent-Reach 的经验沉淀与后续扩展思路

5.1 三个我认为最重要的设计取舍

第一，约定优先于代码。协议定清楚，连接器按协议实现，Agent 侧按协议对接，三方只要守住约定，中间层可以怎么改都行。我们后期重构过好几次内部实现，Agent 侧几乎零感知。这让我更加确信，中间件的价值首先是契约，其次才是功能。

第二，中间层必须是一道墙而不是一个透明管道。有些人把中间件做成“双开门”，只管转发不去校验，这样看似高效，实则把风险全堆到了端点上。Agent-Reach 从一开始就把鉴权和限流放在执行流程的最前面，甚至牺牲一点点延迟也在所不惜。安全能力要是不能在业务入口拦截，后续补漏的成本会指数级上升。

第三，不过度抽象。连接器种类我只保留了 HTTP、SQL、搜索这三类，遇到非常特殊的系统再单独扩展。有同事提过要不要做一个通用的“任意脚本连接器”，让 Agent 能执行任意代码。这个提案被我否了，因为那等于给 Agent 开了一个万能后门，权限模型会瞬间失效。能用白名单解决的问题，绝对不要引入灰色通道。

5.2 后续可以怎么扩展 Agent-Reach

Agent-Reach 目前的形态已经稳定服务了三套业务 Agent，但后续可以扩展的方向我也一直在想：

一是往事件驱动走。现在触达都是“Agent 发请求，中间层同步返回”，未来可以支持异步事件：Agent 注册一个订阅，然后去干别的事，中间层有变化时再主动推送结果。这对长耗时任务比较有意义。

二是接入更多的编排框架。我们已经为 LangChain 写了简单的 tool adapter，以后如果团队引入了别的框架，做一个统一适配器就行，触达层不需要动。

三是做影响分析报表。Agent-Reach 积累了所有 Agent 对业务系统的调用日志，这些数据聚合成报表后，可以很清楚地看到哪个系统被调得最狠、哪个 Agent 在跑无效任务、哪些工具实际上已经没人用了。这类反馈对产品决策非常有用。

最后再分享一个我认为性价比最高的小技巧：把 Agent-Reach 的审计日志单独存一份，保留 90 天以上。平时没有人会天天翻它，但一旦出现安全问题、合规审查，或者某个 Agent 的调用行为变得诡异，这份日志就是最有用的证据。日志从项目第一天就开始存，成本远比事后补录低得多。这就是我在整个 Agent-Reach 工程里最想强调的一点：触达能力越强，越要留好每一笔账。