企业官网建设流程全解析

如果你同时维护着两三个 AI Agent，大概很快会遇到这种事：A Agent 跑得好好的，想调用 B Agent 的能力，结果发现 B 的地址是写在 A 的配置文件里的，B 一换端口、一换部署环境，A 立刻报错。我和团队前前后后重写过好几版这类协作代码，最后一个叫Agent-Reach的小项目把我们从这个泥潭里拉了出来，也让我对多智能体系统底层应该长什么样有了新的理解。

Agent-Reach不是什么宏大框架，它做的事用一句话讲清楚：在多智能体系统里，让任意一个 Agent 能可靠地触达另一个 Agent 或外部工具，且不要求两边在代码层面互相写死地址。它适合正在自己搭多智能体编排、而不是靠全托管平台解决问题的团队；适合那些 Agent 数量超过三个就开始觉得“处处都在硬编码通信地址”的人；也适合想理解 Agent 与 Agent 之间消息路由、权限控制、心跳续租这些底层机制的人。

这篇文章我会从问题根源讲起，再给出 Agent-Reach 第一版的核心设计，然后是一份可以照着操作的最小部署记录，最后是真实环境里踩过的四类坑和对应的修复排查过程。全程是实际操作里的经验，不带概念堆砌。

1. 智能体孤岛是怎么来的，以及为什么不能靠互相留 HTTP 地址解决

多智能体系统一开始总是很美好：一个 Agent 负责查资料，一个 Agent 负责做规划，一个 Agent 负责调工具。但功能拆分完，真正的麻烦才开始——不同 Agent 之间怎么知道对方的存在？怎么知道一个请求该发给谁？以及谁有权限调用谁？

这三个问题不解决，所谓多智能体协作就只是一堆孤立服务的拼盘。我把这种情况叫“智能体孤岛”：每个 Agent 单独看都很强，互相之间却像隔着一道墙，通信基本靠人工把地址抄进配置。

1.1 硬编码地址带来的连锁灾难

最朴素的做法，就是让 Agent A 直接调用 Agent B 的 HTTP 接口。配置里写B_ENDPOINT=http://agent-b:8080，然后 A 循环请求这个地址。听起来还行，但只要你经历过下面任何一个场景，就会知道这条路走不远：

• B 从一台机器迁移到另一台机器，端口从 8080 变成 9090，你得改 A 的配置并重启 A；
• B 增加了一个新版本，但 A 还是按老 schema 发消息，两边字段对不上，连接不报错、业务全错；
• C 也想调用 B，C 的开发者只能复制一份 A 的连接参数，改了几个字段，于是三个人维护着三份不同的“B 地址真相”；
• B 临时升级，A 没有任何退避机制，直接请求超时；超时后 A 又把同样的请求重发了一遍，B 被重复请求打到崩溃。

这些问题的本质不是“网络连接写得不好”，而是把通信的稳定性建立在静态配置上。只要 Agent 的数量超过三个，这种静态配置的维护成本就是指数级上升的。

1.2 让所有 Agent 在同一个“群聊”里互相吼，也不是答案

有人说，那好办，用消息队列或者广播总线，所有 Agent 都订阅一个 topic，谁有能力谁就来处理。这个思路比硬编码好一点，但会带来新的混乱。

我在早期实验里试过这种方式，最大的问题在于：广播式协作根本不回答“该由谁处理”的问题。业务请求到达之后，如果多个 Agent 都订阅同一个 topic，你需要在每个 Agent 里写一套“我是否应该处理这条消息”的判断逻辑。这个判断逻辑一开始很简单，后来会变得出奇地复杂。比如 Agent B1 和 B2 都声称自己能做“天气查询”，但 B1 只支持返回 JSON，B2 支持自然语言回答，如果消息本身不带调用方的需求偏好，两个 Agent 都会认为“我来处理”。等 B2 处理完，B1 也处理了一遍，消息被消费两次，结果浪费且不一致。

广播总线解决了“地址写死”，却把意图判断的责任推给了每个 Agent，也就是把路由逻辑重新散落到了各个业务角落。真正需要的，是一个单独的角色负责“看请求、做判断、选目标、转发、看结果”——这个角色不能是某个 Agent，它必须是基础设施。

1.3 Agent-Reach 的三件底层事：发现、路由、授权

我们做 Agent-Reach 时定了一条原则：业务 Agent 只负责自己的核心逻辑，通信层的“谁在”“谁能干什么”“这次给谁”全部收拢到一层薄薄的中枢。这层中枢要做的核心事情只有三件：

• 发现（Discovery）：Agent 启动后主动报告自己的能力、访问地址、存活状态。系统不再靠配置文件去记“谁在哪”，而是让 Agent 自己注册。
• 路由（Routing）：当一个 Agent 发出语义请求，中枢根据请求内容匹配到最合适的 Agent。这个匹配是动态的，可以加权重、加优先级、加字段校验。
• 授权（Authorization）：就算 Agent B 能力再强，也不是 A 随便就能调用。Agent-Reach 在路由前先检查调用方身份，不符合授权规则就直接拒绝。

这三件事对应的代码量其实不大，但放在每个 Agent 里自己实现，就会变成整个系统的灾难。Agent-Reach 把它变成一个独立的轻量服务，所有语言都能通过 HTTP 协议接入，核心库用 Go 编写，部署方式只是一个二进制文件加一个配置目录。

提示：如果你的 Agent 总数只有两个，直接用环境变量互调就好，没有必要引入 Agent-Reach。这个项目真正的价值是在第三个 Agent 加入时开始的。

2. 第一版 Agent-Reach 的三个核心概念：能力卡、心跳租约、意图路由

在设计第一版时，我没有急着写路由算法，而是先定义清楚三个数据模型。很多类似的框架失败，不是因为代码写不出来，而是因为这些数据模型一开始就糊里糊涂。Agent-Reach 的三个核心概念，分别是能力卡（Capability Card）、心跳租约（Heartbeat Lease）、意图路由（Intent Routing）。

2.1 能力卡：让 Agent 从“一个地址”变成“一组可描述能力”

传统服务注册中心里，一个服务注册的就是地址。但 AI Agent 和普通微服务有个关键差别：Agent 的价值不在于“它在”，而在于“它能做什么”。所以 Agent-Reach 注册的不是单纯的服务实例，而是一张能力卡。

这里是我项目里一个典型的注册样例：

{ "agent_id": "weather-bot-v2", "display_name": "天气查询Agent", "capabilities": [ { "name": "query_weather", "description": "根据城市名查询实时天气和未来三天预报", "input_schema": { "type": "object", "properties": { "city": { "type": "string" }, "days": { "type": "integer", "minimum": 1, "maximum": 7 } }, "required": ["city"] } } ], "endpoint": "http://weather-bot:8080/call", "authentication": { "type": "token", "token_endpoint": "http://weather-bot:8080/auth" }, "advertisement_ttl": 120, "metadata": { "region": "cn-east", "version": "v2.0.1" } }

agent_id是全局唯一标识；capabilities是这个 Agent 对外提供的所有能力的结构化描述，其中input_schema借鉴了 JSON Schema，让路由层可以提前做参数校验，避免把明显不合法的请求转发给 Agent；endpoint是可调用的实际地址；advertisement_ttl则是这张能力卡的有效时间。

我给每个能力都要求写一个清晰的人类可读描述，这个字段很重要。后面做意图匹配时，description往往比name更管用。比如两个能力一个叫get_weather，另一个叫fetch_climate，光看名字几乎无法判断语义接近程度，但 description 里都提到了“天气”“城市”“预报”，匹配算法就能很容易识别出来。

2.2 心跳租约：没有续租机制，僵尸节点早晚吃掉你的系统

Agent-Reach 里，一张能力卡不是永久生效的。注册后它会获得一个租约，时间就是advertisement_ttl。Agent 必须定期发送心跳续租，否则到达 TTL 后，注册中心会主动把这条记录标记为过期并清理掉。

为什么必须这样做？因为我踩过“节点明明挂了还在路由表里”的坑。之前用普通的服务发现组件，服务下线时如果进程被 kill -9 杀掉，没有机会主动注销。这些“僵尸节点”会一直留在路由表里，请求被转发过去，然后超时，接着继续重试，整个调用链被拉垮。

心跳租约的逻辑很简单：注册中心并不信任“谁声称自己活着”，而是只信任“最近一段时间内我确实听到过它的心跳”。默认心跳间隔设为 30 秒，advertisement_ttl设为 120 秒，也就是允许 Agent 在极端情况下漏掉 3 个心跳周期后才被判定死亡。如果业务要求高可用，可以把心跳间隔缩短到 5 秒，但代价是注册中心收到的心跳请求会变多。对于中小团队，30 秒是一个很好的默认值。

2.3 意图路由：不靠“话题订阅”，而是靠“能力打分”

当 Agent 发出一个请求，比如 “帮我查一下上海明天的天气”，Agent-Reach 不会直接去找某个weather_bot，而是先做一次意图到能力的匹配。匹配分三步走：

第一步，语义层面：把调用方的请求文本和所有注册能力的description、name做匹配，给每个候选能力算出一个文本相关度分。这一步我用的是加权的全文相似度，没有上太重度的模型，因为启动时的速度很重要。对中文文本来说，需要先做分词，再把能力描述和请求文本映射到同一个向量空间。如果团队没有现成 NLP 设施，用最基础的 BM25 也能跑得通，只是对同义词不友好。

第二步，结构层面：把请求中的参数和候选能力的input_schema做一致性校验。比如请求带了city，候选能力却要求location且没有提供别名，这个候选就该被降分，即使语义相关也没用。结构校验能挡住大量“语义看着像，实际调不通”的情况。

第三步，人工优先级：能力卡支持配置priority字段，也可以由管理员在路由表里直接指定某类请求默认走某个 Agent。这个字段不是用来替代前面两步的，而是在两个 Agent 语义相似度打分接近时做仲裁。

这就是 Agent-Reach 第一版的全部路由逻辑：先粗筛，再校验，最后裁决。它刻意不用复杂的规则引擎，因为多智能体系统的路由核心是“快速找到对的人”，而不是“精确推导所有可能性”。

3. 把 Agent-Reach 跑起来：最小网络的完整部署流水账

理论说完，来看看一个最小的 Agent-Reach 网络到底怎么跑起来。我假设你已经有一台 Linux 服务器或者本地 Docker 环境，下面每一步我都是实际验证过的。

3.1 准备目录与配置文件

Agent-Reach 本身是一个 Go 编译的单一二进制。我从 GitHub Releases 页面下载了对应平台的可执行文件后，只需要一个工作目录：

mkdir -p /opt/agent-reach && cd /opt/agent-reach wget https://example.com/downloads/agent-reach-linux-amd64 chmod +x agent-reach-linux-amd64

项目主配置我习惯放在config.yaml。一个最简配置长这样：

server: listen_addr: "0.0.0.0:7800" public_addr: "reach-centrql:7800" storage: type: "memory" retention_hours: 24 heartbeat: default_ttl_seconds: 120 check_interval_seconds: 10

listen_addr是注册中心对外监听地址；public_addr是告诉所有 Agent“你应该用哪个地址来访问我”的广播地址。这个字段在容器化环境里极其容易踩坑，后面我会专门讲。storage第一版只做了内存模式，保留 24 小时内的注册记录。如果想持久化路由表，可以后续接 etcd 或 Redis，但我们第一版特意不做，因为内存模式在中小规模下已经够用，少一个外部依赖就少一层运维负担。

3.2 启动注册中心

启动超简单：

./agent-reach-linux-amd64 -config ./config.yaml

启动日志里会出现一行reach: listening on 0.0.0.0:7800。这就说明注册中心已经跑起来了。它的 HTTP API 长这样：

• PUT /v1/agents—— 注册或更新能力卡；
• POST /v1/agents/{agent_id}/heartbeat—— 发送心跳；
• DELETE /v1/agents/{agent_id}—— 主动下线；
• POST /v1/route—— 发起一次意图路由请求。

注意，这个注册中心本身是无状态的。重启之后所有注册记录消失，所以 Agent 侧必须实现启动重连。实际项目中我让每个 Agent 在启动时先等几秒，等注册中心起来了再注册，而不是一失败就退出。

3.3 接入第一个 Agent：注册能力和给回调加监听

接入 Agent 只需要做两件事：启动时把能力卡发给注册中心；启动一个 HTTP 服务接收 Agent-Reach 转发的调用请求。下面是一个最小化的 Python 示例，使用标准库，不依赖任何框架：

import json import time import threading import urllib.request from http.server import HTTPServer, BaseHTTPRequestHandler AGENT_ID = "weather-bot-v2" REACH_SERVER = "http://reach-center:7800" capability_card = { "agent_id": AGENT_ID, "display_name": "weather-bot", "capabilities": [ { "name": "query_weather", "description": "根据城市名查询实时天气", "input_schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, } ], "endpoint": "http://weather-bot:8080/call", "advertisement_ttl": 120, } def register(): req = urllib.request.Request( f"{REACH_SERVER}/v1/agents", data=json.dumps(capability_card).encode(), headers={"Content-Type": "application/json"}, method="PUT", ) urllib.request.urlopen(req) def heartbeat(): while True: req = urllib.request.Request( f"{REACH_SERVER}/v1/agents/{AGENT_ID}/heartbeat", data=b"{}", headers={"Content-Type": "application/json"}, method="POST", ) try: urllib.request.urlopen(req) except Exception: pass time.sleep(30) class Handler(BaseHTTPRequestHandler): def do_POST(self): length = int(self.headers.get("Content-Length", 0)) payload = json.loads(self.rfile.read(length)) city = payload.get("city", "上海") result = {"agent": AGENT_ID, "city": city, "weather": "晴, 24°C"} self.send_response(200) self.send_header("Content-Type", "application/json") self.end_headers() self.wfile.write(json.dumps(result).encode()) def start_http(): server = HTTPServer(("0.0.0.0", 8080), Handler) server.serve_forever() if __name__ == "__main__": register() threading.Thread(target=heartbeat, daemon=True).start() start_http()

这段代码的关键点在于：能力卡里的endpoint用的是${AGENT_ID}:8080这种服务名，而不是127.0.0.1:8080。因为在 Docker 跨容器场景里，如果填127.0.0.1，A 容器里的路由请求到了 B 容器内部，B 的进程监听着没问题，但如果注册中心只把地址当成字符串返回，调用方去访问127.0.0.1:8080，访问的其实是调用方自己的容器。这个问题我在第四节里专门说。

3.4 发起跨 Agent 调用并验证

另一个 Agent 要查询天气时，只需要向 Agent-Reach 的/v1/route发送一条请求：

curl -X POST http://reach-center:7800/v1/route \ -H "Content-Type: application/json" \ -d '{"intent_text": "上海明天天气如何？", "params": {"city": "上海"}, "requester": "planner-agent"}'

注册中心会返回一个路由结果：

{ "agent_id": "weather-bot-v2", "endpoint": "http://weather-bot:8080/call", "matched_capability": "query_weather", "confidence": 0.87 }

拿到这个结果后，调用方再向endpoint发起实际业务请求。整体是一个“先路由、再直连”的模型，也就是 Agent-Reach 只负责任务路由决策，不承担实际的业务数据转发。这样做的好处是减少了一层代理性能损耗，也避免了回调数据在注册中心堆积。坏处是调用方和目标方必须处于同一个可直连网络。对于内部系统来说这完全够用；如果要跨公网，后面可以再接一层网关。

3.5 最容易忽略的配置项：TTL 和心跳周期

跑通之后别急着走，检查两个配置。第一，确认advertisement_ttl与心跳间隔比例合理。我之前把 TTL 设成了 30 秒、心跳间隔也是 30 秒，结果因为一次 GC 暂停导致心跳晚到了几百毫秒，注册中心直接把 Agent 标记下线，等了整整一个 TTL 才恢复。这个比例至少应该是 3:1，我默认用TTL=120s / heartbeat=30s。

第二，确认网络里的每个 Agent 都能解析注册中心广播的public_addr。容器里经常出现注册中心向 Agent 返回一个无法从调用方容器访问的地址，这个错误在最小部署里不会立刻暴露，一旦跨集群就必现。

4. 真实环境里踩过的四类坑，修复过程比功能开发还值得复盘

Agent-Reach 写出来后，我没有立刻推广，而是在一个内部项目上先跑了三个月。这三个月基本是在“踩坑 -> 看日志 -> 修复 -> 再踩另一个坑”的循环里度过的。我挑四个印象最深的记录下来，这些问题八成是你也会遇到的。

4.1 坑一：注册列表一切正常，跨容器调用却全部超时

现象很怪：Agent 成功注册，心跳正常，路由也能返回正确的 Agent 地址，但只要真正发起业务调用，请求就超时。一开始我怀疑是防火墙问题，排查了半天，最后发现路由返回的地址是http://127.0.0.1:8080/call，而调用方是另外一个容器。

排查链路是这样的：

1. 先看注册中心存的能力卡：发现 endpoint 确实是http://127.0.0.1:8080/call，这是在开发机上调试时留下的。
2. 在调用方容器里手动curl http://127.0.0.1:8080/call，不出所料，连接被拒绝，因为 8080 端口在调用方容器里根本没有进程监听。
3. 在目标 Agent 容器里查监听日志，一切正常。
4. 把能力卡里的 endpoint 改成容器服务名http://weather-bot:8080/call，重新注册，问题消失。

这个坑的教训是：能力卡里的 endpoint 必须填其他 Agent 真正能访问的地址，而不是 Agent 自己本地认为的地址。容器里默认填127.0.0.1，本质上是把“我自己能连自己”当成了“所有人都能连我”。在多 Agent 环境里，endpoint 的填法应该遵循“从注册中心视角，请求方网络视角，能通性验证”三原则。

4.2 坑二：跨 Agent 调用之后，上下文“失忆”了

天气查询这种无状态调用还好，等接入了任务型 Agent，问题立刻出现：我把一个重要任务的task_id放在业务请求的 JSON body 里，同时把另一个字段conversation_id放在 HTTP header 里，结果目标 Agent 在处理时，一会儿从 body 里取任务 ID，一会儿从 header 里取会话 ID，两边一旦出现网络代理或消息队列介入，元数据就乱掉。

排查后发现，根本原因是 Agent-Reach 的/v1/route在设计时已经把 HTTP header 作为“链路元数据”的承载体，但业务代码却混合使用了 header 和 payload 传递上下文。在一个链路里，跨节点传递的信息只能有一个明确的“信封”。我们后来约定：所有与业务链路相关的元数据（task_id、conversation_id、trace_id）统一放在 HTTP header 的X-Reach-Meta-前缀下，业务参数只放 body。这样 Agent 的处理逻辑只需要检查 header 就能拿到链路上下文，不会再出现一半数据跟着 header 走、一半数据跟着 body 走的撕裂状态。

4.3 坑三：权限边界形同虚设，注册中心成了“开放式对讲机”

Agent-Reach 第一版的核心是“发现、路由”，权限只是简单做了一层 token 校验：Agent 只要持有注册中心下发的 token，就能调用任意其他 Agent。这带来一个很严重的问题：项目里的 Agent 分属不同信任级别。比如一个负责写周报的 Agent，理论上不应该有权限调用生产环境部署的数据库查询 Agent。

一开始我完全没管这事，直到看到某个内部 Agent 在调试时误调用了另一个 Agent 的重置功能，导致状态被清空。修复方案分两步：

第一步，在能力卡里增加allow_requesters字段，用来声明“我允许哪些调用方调用我”：

{ "agent_id": "database-query-agent", "allow_requesters": ["planner-agent", "admin-agent"], "capabilities": [...] }

第二步，在 Agent-Reach 注册中心里增加授权检查逻辑：每次/v1/route请求都必须带上调用方身份，路由前先检查该身份是否在目标能力卡的allow_requesters白名单内。不在则直接返回 403，而不是乱配。

这个改动让权限模型从“谁能访问注册中心”下降到了“谁能访问具体能力”，粒度完全不一样。

4.4 坑四：两个 Agent 抢同一个意图，路由命中落到错误的一方

有一回我把一个“查询天气”的需求接入系统，结果注册中心把请求路由给了另一个专门做“天气播报文案生成”的 Agent，虽然语义相近，但调用方其实只是想要结构化天气数据。问题出在两个能力描述在文本相似度上太高，query_weather和generate_weather_report都包含“天气”“查询”“预报”这些词。

我把这种问题叫“能力混淆”。解决方式不是调模型，而是给路由加结构化和优先级双重裁决：

• 请求里的params若包含city并且没有report_style，则候选能力中缺少report_style字段的query_weather得分更高；
• 若调用方在请求里明确写target_style: "narrative"，则直接路由到生成型 Agent 并跳过文本相似度比较；
• 在路由表里，我给query_weather设了一个更高的人工优先级，这样有歧义时默认走结构化接口。

事后我把这种冲突收集成“能力混淆清单”，每次新 Agent 注册时，先检查它的能力描述和现有能力是否有过高的相似度，有则提示开发人员调整描述或增加input_schema中判别性字段。这个检查机制，强烈建议所有接 Agent-Reach 的团队都加上。

5. 生产化之前最该补的三块短板：可观测性、动态路由、信任模型

跑通、踩坑、修复之后，Agent-Reach 在我们的内部项目里已经能稳定工作。但离生产化还有三块短板，我在这里给出我认为最值得投入的方向和具体做法。

5.1 可观测性：让每次路由决策都留下“决策日志”

多智能体系统最让人头疼的就是“这个请求为什么去了那个 Agent”。没有路由决策日志，排查只能用“靠猜”。我后来在 Agent-Reach 里为每次/v1/route请求增加了一条结构化日志，内容包括：

• 请求的intent_text、params、requester；
• 候选能力列表及它们的原始匹配分；
• 经过input_schema校验后的调整分；
• 人工优先级设置；
• 最终选中的 Agent 和理由码。

这样每次路由后，我都能在日志里看到“因为什么原因选中了谁”。另外我加了一个带时序的指标：reach_route_decision_seconds，用来统计路由决策耗时。如果发现耗时突然上涨，多半是能力卡数量太多导致相似度计算变慢，这时需要引入索引或者把注册中心从内存模式迁移到支持索引的存储。

5.2 动态路由：给新版本 Agent 做流量灰度

生产环境里最常用的运维动作是“升级 Agent”。如果没有动态路由机制，升级就是停机更换地址，风险极高。Agent-Reach 后来支持了在注册中心预设路由权重：

route_policy: - condition: capability: query_weather candidates: - agent_id: weather-bot-v2 weight: 20 - agent_id: weather-bot-v3-beta weight: 80

这个策略的意思是，当query_weather命中时，20% 的流量进入 v2，80% 进入 v3-beta。灰度发布因此变得非常轻量：先注册新版本，调整权重到 10%，观察错误率和延迟，再逐步放大。

我强烈建议把路由权重改成支持从存储动态更新，而不是改配置重启。Agent-Reach 提供了/v1/policies的 HTTP 接口来更新策略，灰度时我用一条 curl 就能完成一次流量切换，比改代码重新发布快太多。

5.3 信任模型：从“共享 token”走向“能力卡签名”

前面提到的权限白名单只是基础版。如果 Agent 分布在多个团队甚至多个组织，共享 token 意味着拿到 token 的任何人都可以冒充任意 Agent。更进一步的做法是让每个 Agent 拥有一对公私钥，注册能力卡时用私钥签名，注册中心验证签名后再接受这张卡。这样攻击者即使拿到了能力卡内容，也无法伪造一张“假 Agent”的能力卡。

具体设计可以是：在能力卡的顶层增加signature字段，sig 的内容是所有核心字段按固定次序拼接后的哈希，再用 Agent 私钥签名。注册中心在注册和心跳续租时都校验签名。签发私钥的时机一般放在 CI/CD 流水线里，由部署系统生成，不会出现在源码仓库。

这个改动初期会带来一些密钥管理的麻烦，但对多团队场景是值得的。比如我们的外部合作方接入系统时，我只给了他们一套生成私钥的流程，后续所有协作都基于签名信任，再也没有因为 token 泄露导致的问题。

最后再分享一个我验证 Agent-Reach 是否正常工作的土办法：每次改完路由策略，我会故意注册一个“只会返回错误结果”的坏 Agent，再把它在策略里的权重设为零，然后向注册中心发送一批测试意图，检查是否有任何一条请求被路由到它。如果有，说明路由策略没有真正生效。这个“坏 Agent 探针”成本极低，但能非常直观地暴露路由表、缓存、策略热加载之间的不一致问题。我在 Agent-Reach 上跑这个探针的半年里，至少抓到过三次缓存未失效的 bug，算是整个项目里性价比最高的测试手段。