AgentRT 统一网关深度剖析:HTTP/WS/SSE/MCP/A2A/OpenAI 六大协议如何收敛为一个入口

原创2026-10-12 18:21:131,930 阅读

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 个守护进程——外部永远只有一个入口,内部可以自由演化。

想进一步深入?推荐阅读:

登录后查看全文
agentrt