企业官网建设流程全解析

“Agent-Reach”这个名字看起来像是某个框架，但对我来说，它更像那段在深夜调试智能体互调时被骂醒的一课。做AI应用的人现在都有一个共同的感受：单个Agent已经不难写了，难的是让一堆Agent能互相找到、听懂、并安全地把活儿干完。Agent-Reach就是我这个阶段给自己写的一套轻量接入与调度协议，它解决的问题非常具体——Agent的触达。让一个Agent能够稳定、可靠、可观测地调用另一个Agent，就像在任何场景下都能拨通电话，而不是靠喊。

如果你正在做一个平台上挂了七八个Agent的项目，或者你正准备把订单、客服、审核之类的Agent串起来，这篇文章应该能帮你少踩不少坑。我尽量把设计思路、协议细节、接入步骤以及排查经验都写清楚，偏实操，代码可以直接改来用。

1. 为什么需要Agent-Reach：从Agent孤岛到统一触达

1.1 Agent数量一多，最先崩的往往不是模型

大家总以为Agent项目跑不稳是模型理解力不行。但在实际生产中，我见过太多案例：单测每个Agent都很好，一上多Agent协作，就变成“相互找不着、互相等死”。

我去年接了一个项目，团队维护着三个业务Agent：一个做售后客服，一个查订单状态，一个做合规审核。最初每个Agent都是独立的HTTP接口，客服Agent查订单时要拼一个订单查询服务的URL，订单Agent查完要把结果塞回客服上下文。代码倒是能跑，但问题层出不穷：客服Agent调订单Agent时超时，订单Agent返回的字段名客服Agent不认，合规Agent要审核时不知道调用的来源是哪个会话，出问题只能靠翻日志猜。

这其实就是Agent孤岛。每个人都能写Agent，但Agent之间没有统一的“触达方式”。

Agent-Reach的出发点就是把这个场景理顺：每个Agent只需要做一件事，使用统一协议声明自己是谁、能干什么、调用参数长什么样，然后由一个轻量网关负责触达、转发、鉴权、追踪。Agent之间不需要知道彼此内网地址，也不需要各自解析对方的返回格式。

1.2 Agent-Reach不是API网关，也不是消息队列

很多人一听就问我：这不就是API网关吗？最多算个消息队列吧。我觉得对，但也不对，关键在于Agent之间的通信有几个普通网关不会处理的问题。

普通API网关解决的是“路径到服务的转发”，它不关心服务的语义。你调用一个REST接口时，不需要在body里带上“当前对话的完整上下文”，也不需要告诉网关“如果这次调用返回的信息不足以决策，你允许我再调另一个Agent”。

Agent通信有几个特殊点：

• 消息里必须带上会话上下文，同一个用户问“上一单怎么样了”，后续Agent需要知道“上一单”指的是哪单。
• 工具调用的结果不能只返回字符串，还需要标注这个结果来自哪个工具、可信度如何、是否需要二次确认。
• 多Agent链路里要有明确的调用深度和预算，否则A调B、B调C、C又调A，直接死循环。

Agent-Reach把这些点并进协议里，而不是简单做一个HTTP代理。核心不是转发，而是“可达性”——每个Agent在使用统一协议后，可以在任意时间被人、被其他Agent、被外部系统稳定地触达。

2. Agent-Reach整体架构与核心模块拆解

2.1 四个核心模块：注册、网关、上下文、观测护栏

我实现Agent-Reach时把整个系统拆成了四个模块，对应四个必须解决的任务。

第一个是注册中心。每个Agent在启动时把自身的“能力描述”上报上去，比如这个Agent叫“order_query”，版本1.3.0，能力是“根据用户id和订单号查询订单状态”，需要的输入是user_id和order_id。注册中心不存业务数据，只存Agent的元信息和健康状态。这样网关在调用前就能通过能力描述找到正确的Agent，不用写死路由。

第二个是可达网关。这是所有请求的统一入口。调用方不管是通过HTTP还是SDK，都往网关发一条invoke请求。网关负责找到Agent实例、检查权限、执行重试、执行超时、把结果返回。普通API网关到这里就结束了，但Agent-Reach的网关还多做一件事：它允许返回结果里携带“工具调用建议”。举例来说，客服Agent判断用户需要改地址，但改地址不是它的能力，它可以在回复里告诉网关“这个请求建议转给address_change”，网关会继续路由，而不是把这个建议原样抛回给用户。

第三个是会话上下文存储。Agent之间的调用必须是上下文连通的。Agent-Reach用session_id把整条会话串起来，每次调用的传入参数、返回结果、使用的工具、耗时会追加到上下文里。不同Agent可以读取上下文里最近N轮状态，避免“订单Agent查到结果后，客服Agent不知道这是响应哪个问题”。这一块我用了轻量的内存存储加JSON序列化，消息量大的时候可以平移到Redis，但核心数据结构在设计时就和底层存储解耦了。

第四个是观测与护栏。Agent链路的排查难度比普通服务高一截，因为一个问题可能跨了三个服务，还夹了一层模型推理。Agent-Reach要求每一次invoke都生成一个trace_id，网关会把链路信息以结构化日志输出。护栏这块则包含调用深度限制、权限校验、敏感字段脱敏。合规Agent被调用时，网关会检查调用方是否有权限拿到用户数据，而不是无条件转发。

2.2 协议选型：为什么我最终选了JSON-RPC风格

最开始我考虑过直接用OpenAI风格的Chat Completions协议来让Agent互调，因为看起来精简。后来放弃了，原因很实际：Agent互调请求里不止有一个用户问题，还可能有工具结果、Agent内部状态、用户身份、会话历史。把所有这些塞进messages数组，会导致每个Agent都要自己解析一层非标准字段。

Agent-Reach最终采用了一套偏JSON-RPC风格的协议。每个请求统一是：

{ "jsonrpc": "2.0", "method": "invoke", "params": { "agent": "order_query", "payload": { "user_id": "u_123", "order_ids": ["2024001"] }, "context": { "session_id": "s_abc", "customer_tier": "vip", "history_window": 10 } }, "id": "req_001" }

这里最关键的字段是payload和context分离。payload里放这次调用真正需要的数据，context里放会话级的共享信息。这么做的好处是：Agent不需要也不应该把所有历史对话都塞进每个接口，它只用读context指定的片段。如果后续要扩展多轮记忆，只改context结构，不用改每个Agent的入参。

工具结果回填也是协议里重要的一环。Agent调用另一个Agent后，得到的不只是一段文字，还可能是一个结构化的工具结果：

{ "agent": "order_query", "result": { "status": "SHIPPED", "ship_date": "2024-06-01" }, "tool_name": "query_order", "trace_id": "trc_001" }

tool_name字段用来告诉调用方这个结果来自哪个能力，这样客服Agent可以把“查订单”和“查物流”的结果区分开，而不是笼统当成一段自然语言。这一点在构建复杂Agent时非常有用。

我建议任何做多Agent的人先别急着写业务代码，第一件事就是把协议定下来。协议定了，后面所有Agent的接入成本才会降下来。Agent-Reach的核心价值就在这里：不是靠某个神奇的AI中间件解决问题，而是靠一层干净、明确、可追溯的接口契约。

3. 实操：把第一个Agent接入Agent-Reach

3.1 环境准备与SDK依赖

下面这部分用Python来实现，假设你已经有一个能跑的Agent服务，它可能是FastAPI应用，也可能是任意Python脚本。我默认读者会基本的HTTP服务开发。

Agent-Reach服务端我建议放在独立的机器或容器里，它本身需要暴露两个端口：管理端口用于Agent注册，网关端口用于处理外部调用。本地演示时可以直接跑在同一台机器上。

安装SDK：

pip install agent-reach-sdk

如果要用完整服务端，额外安装：

pip install agent-reach[server]

依赖很简单，底层只用了FastAPI、pydantic和httpx。没有引入太多重型组件，因为Agent-Reach的定位是轻量接入层，不是大而全的调度平台。

3.2 注册一个订单查询Agent

我用FastAPI写一个订单查询Agent，它本身不关心Agent-Reach的细节，真正需要做的是声明自己的能力供注册中心发现。先在项目目录下创建一个agent.yaml：

name: order_query version: 1.3.0 description: "根据用户ID和订单号查询订单状态、发货时间" capabilities: - id: query_order input: user_id: string order_id: string output: status: string ship_date: string endpoint: url: http://localhost:8001/invoke timeout: 15s auth: type: none

这里的关键是capabilities部分。它不只是给文档看，网关在做能力路由时会读这一段。比如外部请求要求“查询订单状态”，网关会查找哪个Agent声明了query_order能力，并检查payload里有没有user_id和order_id这两个必要字段。

现在写一个最简单的Agent实现：

from fastapi import FastAPI, Request import httpx app = FastAPI() async def query_order(user_id: str, order_id: str): # 实际中这里会去查询你们的订单中心 return {"status": "SHIPPED", "ship_date": "2024-06-01"} @app.post("/invoke") async def invoke(request: Request): req = await request.json() payload = req.get("payload", {}) results = {} for tool in payload.get("tools", []): if tool == "query_order": results["query_order"] = await query_order( user_id=payload["user_id"], order_id=payload["order_id"], ) return {"result": results, "agent": "order_query"} # 启动时把自己注册到Agent-Reach注册中心 if __name__ == "__main__": import uvicorn from agent_reach import RegistryClient RegistryClient("http://localhost:8080/register").register("agent.yaml") uvicorn.run(app, host="0.0.0.0", port=8001)

注意我没有把业务逻辑和Agent-Reach SDK耦合在一起。每个Agent只需要实现统一的invoke端点，然后启动时上报注册信息。这样如果哪天你没用Agent-Reach了，这个Agent还能普普通通地当独立服务跑，不会被框架绑架。

3.3 跨Agent调用：客服Agent把问题转给订单Agent

假设现在有一个客服Agent接到了用户问题：“我的订单2024001到哪儿了？”它自己只负责话术，不负责查单，因此它要通过网关调用订单Agent。

用SDK发起一次调用：

from agent_reach import ReachClient client = ReachClient(gateway_url="http://localhost:8080/gateway") response = client.invoke( agent="order_query", payload={ "tools": ["query_order"], "user_id": "u_123", "order_id": "2024001", }, context={ "session_id": "s_abc", "customer_tier": "vip", }, timeout=15, ) print(response.result) # 输出: {"query_order": {"status": "SHIPPED", "ship_date": "2024-06-01"}}

这里有几件事我要重点提醒。

首先，session_id一定是调用方主动传的，不是网关生成的。原因很简单：客服Agent才清楚“这次会话是哪位用户在提问”，网关只是一个管道，没法也不应该自作主张地判断会话归属。

其次，payload里的tools字段如果是列表，订单Agent会只处理那几种工具。这可以避免客服Agent传了一个大大的消息对象进来，订单Agent无法解析。实际项目里，我见过很多人把GPT输出的整个JSON一股脑塞给另一个Agent，结果对方解析失败。tool级的白名单是控制这类问题的第一道闸门。

最后，超时设置了15秒。很多Agent调用慢不是模型慢，是前面的工具调用链慢。给足时间但不要无限等。

3.4 参数计算与重试策略

接入Agent-Reach时，最容易被忽视的是调用的超时预算和重试设计。

我建议对外部的agent调用，分三层超时：

• 连接超时：2秒，超过基本属于网络或服务不存在。
• 读超时（首包）：5秒，如果5秒还没返回任何数据，说明这个Agent可能卡在模型推理或工具调用里。
• 总超时：按业务复杂度设置，我当时给大多数Agent设成30秒，但要求网关支持流式返回。

重试并不是越频繁越好。Agent服务和普通数据库不一样，很多Agent内部有状态流转，比如已经调了一次订单接口，失败了重发一次，订单Agent可能会重复查询。所以幂等很重要。Agent-Reach在协议里让网关可以透传一个idempotency_key，Agent端拿到这个key就可以判断“同一笔请求我是不是已经处理过了”。

我踩过的坑是重试只设了固定3次，Agent A调用Agent B超时，立刻重试，结果B还卡在之前的部署排队里，3次重试全是超时，最后A自己也超时了。后来我把重试改成指数退避：第一次等待0.5秒，第二次1秒，第三次2秒，加上3秒的抖动。整体下来成功率高了，资源消耗也没上去。这套策略在Agent场景下比固定重试更合适。

另一个参数是调用深度上限。我在网关里默认把max_hops设为4。如果客服Agent调订单Agent，订单Agent调库存Agent，库存Agent又调回客服Agent，Hop数会迅速上涨。超过4的调用链基本都属于设计出了问题，不应该继续执行，否则会被逻辑错误拖垮。

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

4.1 典型故障速查表

这段时间用Agent-Reach，我整理了一份自己排查时反复用到的速查表。放在Agent互调项目里，90%的问题都能对上号。

比如有一次，客服Agent返回的成功率特别低，我一查trace，发现每次调用都在“订单Agent读上下文”这一步多花了3秒。因为客服Agent把整个对话历史全塞进context，让订单Agent从二十轮对话里找用户ID，这当然又慢又容易出错。让客服Agent只提取必要字段再调用，问题立刻消失。

所以这里也提示下：Agent-Reach的context不是给模型无限读的。它应该只放“没有它就没法解决当前请求”的信息。字段越小，链路越好，排查越容易。

4.2 循环调用与死锁：必须有人打断

多Agent协作最容易出现的就是循环调用。客服Agent处理不了问题，转给订单Agent；订单Agent处理不了，转回给客服。如果网关只做“转发”，没有任何护栏，这两个服务会无休止地把请求抛给对方。

我在Agent-Reach里实现了两个机制对抗这种死锁。

第一个是最大调用深度，刚才说过，默认4。网关每转发一次，会在context里给hop_count加1，放进请求头里。任何Agent收到请求时都可以看一眼这个值，如果接近上限，就直接拒绝而不是继续调用。

第二个是时间预算。一次完整的链路会从发起时记录start_time，网关在每次转发时会检查剩余时间，如果剩余的已经小于该Agent预期的处理时间，就提前返回“预算超限”错误。很多人会觉得SetTimeout已经很够了，但在多Agent场景里，光有单次超时不够，因为A调B用了8秒，B调C用了8秒，两个加起来早就超过了用户体验容忍阈值，但每一段自己看都没超。整体预算必须从链路层面控制。

4.3 鉴权容易漏掉“Agent到Agent”的传鳌

单Agent应用通常只需要在入口做一次登录鉴权就够了，多Agent就要考虑下游Agent如何确认“这个请求真的来自一个被允许的客服Agent”。

我在早期版本里犯过错误：只在网关入口校验了用户令牌，结果客服Agent可以直接以用户身份去调用订单Agent，订单Agent也傻乎乎地返回了用户订单数据。这个在权限上是越权的。

后来的方案是，Agent-Reach内部使用独立的service credential作为Agent身份，它在OIDC里绑定agent_id。外部用户在网关入口拿的是user token，网关做完用户鉴权后，再根据调用链生成一个临时scoped token，里面只含当前链路允许访问的Agent和工具列表。下游Agent只相信这个scoped token，不信任普通的user token。

这样做之后，每个Agent都明确知道自己被谁调用、能访问哪些资源。合规审核Agent尤其重要，因为它在审计时需要记录“哪个Agent，因为哪个会话，触发了哪一次用户数据查询”。

顺便说一下日志的记录方式。Agent-Reach的每个网关日志都带trace_id，我建议你把日志直接接入现有的集中式日志系统，而不是只看单机的stdout。排查多Agent问题，最重要的就是能快速把一条跨服务的日志时间线拉出来。我没见过谁能靠翻三台服务器上的文件把Agent链路捋清楚的。

5. 后续还能怎么扩展：把Agent-Reach当成一种模式

我现在已经没把Agent-Reach当成一个独立的工具看了，它更像一个稳定好用的接入模式。社区里陆续有人开始做类似的事情，有的做成控制平面，有的做成协议标准，这是好事。多Agent真正走向生产，必须有一个像“可达性”这样的基础层，不然所有精力都会被消耗在互相找茬和不匹配的接口上。

如果你只是想跑通一个demo，完全不需要引入Agent-Reach。一旦你有两个以上的Agent需要真实协作，我建议你先定义好三样东西：统一的invoke协议、透传的session_id、全链路trace_id。它们基本可以解决80%的协作问题。

我在实际维护中最大的体会是：Agent调度难，常常不是模型不够聪明，而是触达路径太脆弱。你先让每个Agent能够被稳定地找到、稳定地调用、稳定地追踪，再去考虑Agent多聪明。Agent-Reach是我对这个问题的一个回答，你完全可以按自己的场景改造它。如果之后你接入时遇到什么奇怪的坑，欢迎按这个思路自己复现一遍，多半都能跑通。