AgentRT 统一网关深度剖析:HTTP/WS/SSE/MCP/A2A/OpenAI 六大协议如何收敛为一个入口
AgentRT 统一网关深度剖析:HTTP/WS/SSE/MCP/A2A/OpenAI 六大协议如何收敛为一个入口
AgentRT(Airymax AgentRT)是面向 AI Agent 团队的操作系统级运行时平台,其统一网关 gateway_d 把 HTTP、WebSocket、SSE、MCP、A2A、OpenAI 六大协议收敛成唯一的 JSON-RPC 2.0 入口:外部系统只需记住一个端口,就能与整个 Agent 运行时对话。本文带你快速看懂这套协议网关的设计思路与落地细节。
一张图看懂:六大协议如何变成一个入口
先看全局示意——左侧是五花八门的外部世界,中间只有一个网关进程,右侧是 15 个各司其职的守护进程:
外部世界 统一网关 gateway_d AgentRT 运行时
┌───────────────┐ ┌─────────────────────────┐ ┌────────────────┐
│ HTTP JSON-RPC │─────▶│ │ │ agent_d 会话 │
│ OpenAI 兼容 │─────▶│ 协议翻译层(无业务逻辑) │─────▶│ tool_d 工具 │
│ WebSocket │─────▶│ → JSON-RPC 2.0 统一流 │ │ llm_d 模型 │
│ SSE 流式 │─────▶│ 端口 8080 / 可漂移 │ │ mem_d 记忆 │
│ MCP 客户端 │─────▶│ 路径感知路由 + 能力注册表 │ │ a2a_d 协作 │
│ A2A 对等方 │─────▶│ │ │ … 共 15 守护进程│
└───────────────┘ └─────────────────────────┘ └────────────────┘
官方对这一层的定义只有一句话:"只做协议翻译,不含业务逻辑,是进入运行时的唯一进程边界"(见 README.md 的 Architecture 一节)。所有跨进程调用都必须经过网关派发,禁止客户端直连守护进程 socket——这在 cli_gw.h 中被作为架构约束明文"立法"。
核心能力矩阵:一个信封覆盖 17 个命名空间
网关把六大协议翻译成的 JSON-RPC 2.0 流之上,挂着一张完整的"能力表"。官方 E2E 回归脚本 agentrt_e2e_regression.sh 就是经网关 http://127.0.0.1:8080 逐一调用全部命名空间方法做端到端验证的:
| 命名空间 | 承载守护进程 | 你能做什么 |
|---|---|---|
agent.* |
agent_d | 会话编排、任务执行与流式运行 |
tool.* / plugin.* |
tool_d | 工具注册、执行、审批,插件加载 |
llm.* |
llm_d | 模型列表、补全、token 计数、embeddings |
think.* |
think_d | 认知处理与多 Agent 编排 |
mem.* / kb.* |
mem_d | 分层记忆读写、RAG 知识库检索 |
a2a.* |
a2a_d | 跨 Agent 注册、任务协作、消息传递 |
sched.* |
sched_d | 任务图(DAG)调度与取消 |
channel.* / notify.* |
channel_d / notify_d | 通道与 topic 订阅发布 |
market.* |
market_d | Agent 与技能市场 |
monit.* / observe.* / info.* |
monit_d | 指标、告警、系统信息 |
cupolas.* / policy.* |
cupolas_d | 权限裁决、策略两段式下发、审计 |
gateway.ping |
gateway_d | 网关自身探活 |
一张表、一个信封、一个入口——这就是"收敛"的直接体现。
逐协议拆解:六大通道各自扮演什么角色
1. HTTP / JSON-RPC:默认非流式通道
最朴素的一条路:POST / 提交 JSON-RPC 2.0 请求,按 Content-Length 读完整响应。CLI 内置的轻量客户端 cli_gw.c 就用 POSIX/Winsock 原生 socket 实现了这条通路,零外部 HTTP 依赖。一条典型调用长这样:
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"agent.list","params":{},"id":1}' \
http://127.0.0.1:8080
2. SSE:流式 token 与工具循环
POST /api/v1/agent/run/stream 是网关的 SSE 纯翻译端点,配套 v1 流式事件帧协议:run_start / plan / tool_start / tool_end / token_delta / message / run_end / error。引擎侧带 sink 推送,网关只负责把帧原样透传成 SSE——协议常量由 airy_run_stream.h 单一来源(SSoT)生成(详见 CHANGELOG.md v0.1.9)。
此外还有 GET /api/v1/hall/watch:事件流长连接推送,TUI 的事件面板就消费它,RPC 轮询降级为 1 秒兜底。
3. OpenAI 兼容:让现有客户端零改造接入
网关提供 OpenAI 风格的兼容端点:/v1/chat/completions 流式响应显式声明 stream_options.include_usage,真实回传 usage;/v1/embeddings 经路径感知路由直接转发给 llm_d 的 embeddings 方法。任何现成的 OpenAI SDK 换个 base_url 就能把 AgentRT 当成一个"模型"来调。
4. WebSocket:全双工实时会话
基于 libwebsockets 的双向通道,适合长会话、审批确认这类需要服务端主动打断的场景;与 SSE 单向流形成互补。
5. MCP:把 AgentRT 接入 LLM 工具生态
Model Context Protocol 端点让主流 LLM 客户端可以把 AgentRT 的能力当作 MCP 工具来发现与调用,无需为其重写工具层。
6. A2A:Agent 与 Agent 的握手通道
A2A 传输映射到 a2a.* 方法族:discover_agents / register_agent / create_task / send_message(离线目标返回 ack 语义)。对等 Agent 之间经同一入口握手、派任务、收结果,跨组织互操作不再需要私有的点对点端口。
为什么坚持"单一入口":四个实际收益
- 集成成本收敛——对接方只需一个端口、一套鉴权、一个 JSON-RPC 信封,六个协议的差异被网关消化。
- 安全策略单点执行——输入清洗(非法 UTF-8 在请求体解析前与记忆注入时双重清洗)、能力(cap)校验都在网关这一道闸门完成,不存在"绕过网关"的旁路。
- 可观测性集中——
gateway_d /health探活、全链路调用都留下统一审计面,airymaxrt doctor一眼看清状态。 - 升级不破坏契约——守护进程整编(plugin_d→tool_d、observe_d/info_d→monit_d 等)后,网关 cap registry 保留旧命名空间转发契约,外部客户端无感升级(CHANGELOG.md M4)。
gateway_d 实现细节:纯化、命名空间独占与端口漂移
纯化(v0.1.9 M1):会话表、编排、工具目录等业务逻辑全部迁出到 agent_d / tool_d,gateway_d 收敛为纯聚合壳,SSE 只做翻译,CLI 直连被切断。越纯粹,越难腐化。
命名空间独占(M4):网关 cap registry 新增 GW_NS_OWNER 归属表(15 个 daemon 契约表 + 整编映射),gw_cap_ns_validate() 在启动期做 fail-closed 校验——两个守护进程抢同一个命名空间,网关直接拒绝启动。
端口漂移处理:默认端口 8080 被占用时,网关会漂移到 8083+,并把实际端口固化到 $AIRY_HOME/run/gateway.port。CLI/TUI/轻量启动器都从该文件读取,根治"硬编码 8080 导致网关不在线"的老毛病(cli_gw.c 中 cli_gw_read_runtime_port() 即此逻辑)。端点也可用 AIRY_GATEWAY_URL 环境变量显式指定。
可调参数:SSE 工具循环轮数上限由 AIRY_GW_SSE_MAX_TOOL_LOOPS 配置,max_tokens 默认 2048、可经 AIRY_GW_SSE_MAX_TOKENS 提至 4096,减少长任务中途截断。
一个反直觉的设计:CLI 的生命周期/自愈面(探活、拉起、恢复)刻意不走网关,而是直接探测守护进程 socket——"监管者不得依赖被监管者":网关宕机时,CLI 必须仍能独立拉起它(见 cli_gw.h 头部注释)。
快速上手:三步验证你的网关
# 1. 安装并启动(终端 UI 会带起全部守护进程,含 gateway_d)
curl -fsSL https://atomgit.com/openairymax/agentrt/releases/download/latest/install.sh | bash
airymaxrt status # 观察 gateway_d 是否就绪
# 2. 探活:网关的 HTTP 健康检查
curl -s http://127.0.0.1:8080/health
# 3. 走一次 JSON-RPC:列出当前 Agent
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"agent.list","params":{},"id":1}' \
http://127.0.0.1:8080
想跑完整回归?直接执行 tests/e2e/agentrt_e2e_regression.sh,它会经网关把上表所有命名空间方法逐一断言一遍,输出 PASS/FAIL/SKIP 汇总。
小结
AgentRT 的统一网关用"一个进程、一条流、六张协议皮"回答了 Agent 基础设施的一个经典问题:外部世界协议五花八门,运行时内部却应该简单。六大协议在 gateway_d 处收敛为 JSON-RPC 2.0 统一流,业务逻辑全部下沉到 15 个守护进程——外部永远只有一个入口,内部可以自由演化。
想进一步深入?推荐阅读:
- README_zh.md — 平台总览与架构分层(中文版)
- CHANGELOG.md — 网关纯化、命名空间独占等演进全记录
- tools/airy_cli/ — CLI 与网关客户端实现
- tests/e2e/ — 网关全命名空间端到端回归