AgentRT 统一网关深度解析:6种协议传输如何汇聚为一条 JSON-RPC 2.0 流
AgentRT 统一网关深度解析:6种协议传输如何汇聚为一条 JSON-RPC 2.0 流
AgentRT 统一网关(gateway_d)是 Airymax 运行时平台对外唯一的入口进程。本文将拆解它如何将 HTTP、WebSocket、SSE、MCP、A2A、OpenAI 这 6 种协议传输统一翻译为一条 JSON-RPC 2.0 流,让外部系统只需对接一个端点,就能驱动整个智能体运行时。
为什么智能体运行时需要一个统一网关 🚪
在多智能体系统里,外部世界与运行时之间的边界往往是最乱的:
- 前端要用 SSE 看流式 token;
- 其他 AI Agent 要用 A2A(Agent-to-Agent)协议互调;
- MCP 客户端要用 MCP 发现并调用工具;
- 现有应用习惯 OpenAI 兼容接口(
/v1/chat/completions); - 运维脚本只需要最朴素的 HTTP POST。
如果没有统一网关,每种传输都要单独实现鉴权、路由、错误码与日志,边界代码会爆炸式增长。AgentRT 的解法很干脆:网关只做协议翻译,不含业务逻辑,把所有传输收敛为内部唯一的 JSON-RPC 2.0 调用流。这与 Kubernetes 之于微服务的定位一致——把"怎么连进来"标准化,让上层专注"做什么"。
一句话:外部系统只有唯一一个入口,内部服务只认一种消息。
6 种协议传输的角色分工 📡
| 传输 | 典型场景 | 网关侧行为 |
|---|---|---|
| HTTP | 脚本、CLI、通用集成 | POST / 直发 JSON-RPC;/health 可达性探测 |
| WebSocket | 长连接、双向推送 | 经 libwebsockets 建立连接,消息转 JSON-RPC |
| SSE | 流式输出、事件流 | 如 POST /api/v1/agent/run/stream、GET /api/v1/hall/watch,纯翻译为流式帧 |
| MCP | MCP 客户端发现与调用工具 | 请求翻译为 tool 命名空间的 RPC 方法 |
| A2A | 智能体之间互通 | 翻译为 a2a.* 命名空间方法,由 a2a_d 执行 |
| OpenAI | 既有 LLM 应用零改造接入 | /v1/chat/completions、/v1/embeddings 等路径感知路由 |
值得注意的细节:
- SSE 是"纯翻译":
agent.run_stream事件帧协议定义了run_start / plan / tool_start / tool_end / token_delta / message / run_end / error八种帧,引擎侧推送、网关侧只做帧格式转换,不掺业务判断; - OpenAI 兼容端点显式支持
stream_options.include_usage,流式响应也能真实回传 token 用量; - 路径感知路由:HTTP 传输层构造带 method/path 的请求结构,
gateway_protocol_entry以 path 参与gw_proto_detect协议判定与路由,保证/v1/embeddings这类路径能正确分发。
一条 JSON-RPC 2.0 流内部怎么走 🔁
翻译之后,所有请求走同一条内部路径:
- 协议判定:
gw_proto_detect根据传输特征 + 路径判定请求属于哪条协议语义; - 命名空间路由:请求映射为
命名空间.方法(如mem.write、a2a.create_task、sched.*)的 RPC 调用; - 能力登记校验:网关维护 cap registry 与
GW_NS_OWNER归属表,启动期由gw_cap_ns_validate()做 fail-closed 校验——命名空间归属冲突直接拒启; - 分发到守护进程:15 个运行时服务(
agent_d、llm_d、tool_d、mem_d、a2a_d等)按命名空间接管执行。
错误处理遵循分层契约:JSON-RPC 的 error 信封只承载协议/传输层失败;工具执行中的业务错误以正常 result 返回,让调用方可以区分"网关说错了"和"智能体说错了"。这一契约在端到端回归测试中被逐条断言。
网关的自我纪律:纯化与链接白名单 🧹
0.1.9 版本的架构改进中,gateway 经历了一次"纯化":会话表、编排逻辑、工具目录等业务全部迁往 agent_d / tool_d,gateway_d 收敛为纯粹的聚合壳。
纪律不止于运行时,还落到构建期:
- link-whitelist.txt 登记了链接边界,例如
gateway只允许链svc_common / airy_syscall / airy_protocols / airy_common,gateway_d额外挂载airy_security_dome; - 越界链接(比如网关偷偷依赖认知引擎)会在构建门禁阶段被 fail-closed 阻断;
- 这套门禁由 scripts/verify_release_gates.sh 等发布脚本在每次发布前自动执行。
结果就是:升级任何守护进程,不会意外牵动网关的依赖面。
如何连上 AgentRT 网关:一分钟接入 ✅
安装后(Linux/macOS 一行命令安装,见 README_zh.md),运行时默认监听 http://127.0.0.1:8080,一条 curl 即可调用:
curl -fsS -X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"mem.write","params":{"data":"hello","metadata":{"src":"demo"}},"id":1}' \
http://127.0.0.1:8080
几个实用细节:
- 端口漂移自动感知:若 8080 被占用,网关会漂移到 8083+ 并写入
run/gateway.port;CLI 与 TUI 会读取该文件自适应,无需手改配置; - 自定义入口:设置
AIRY_GATEWAY_URL环境变量可指向任意网关实例(e2e 回归脚本正是这么做的); - 健康探测:
GET /health用于可达性检查,airymaxrt status/airymaxrt doctor会把它纳入整体体检。
官方的端到端回归脚本 tests/e2e/agentrt_e2e_regression.sh 展示了标准用法:经网关逐一调用全部命名空间方法,断言成功响应或预期错误码,输出 PASS/FAIL/SKIP 汇总——它既是测试,也是一份活的路由文档。
相关文件速查 📁
| 文件/目录 | 说明 |
|---|---|
| gateway/ | 协议网关子模块源码(传输层 → JSON-RPC 2.0 翻译) |
| tools/airy_cli/src/cmd/cli_gw.c | 轻量 HTTP/1.1 JSON-RPC 客户端,演示网关标准用法 |
| tests/e2e/agentrt_e2e_regression.sh | 全命名空间 RPC 端到端回归测试 |
| link-whitelist.txt | 网关链接白名单,构建期门禁依据 |
| README_zh.md | 平台总览与安装指南 |
小结
AgentRT 统一网关的设计哲学可以浓缩为三句话:
- 一个入口——6 种传输协议全部收敛,外部只需记住一个 URL;
- 一种消息——内部只有 JSON-RPC 2.0,错误分层清晰可判读;
- 一层纪律——网关零业务逻辑 + 构建期链接门禁,升级永远低风险。
当你需要接入 LLM 应用、其他智能体或流式前端时,先问一句"走哪条协议",然后在网关上找到对应翻译即可——剩下的调度、记忆、安全,都由这条 JSON-RPC 2.0 流背后的 15 个运行时服务接管。