受众：集成工程师、平台架构师、运维团队 —— 任何需要一份单一真相源
来回答 “BeeOS 哪些服务对外可达、各自收什么凭证、调用方/网关/智能体 pod
之间是怎么接的” 的人。
backend/.cursor/rules/communication-principles.mdc
和 backend/docs/adr/
下的 ADR 集合里）；这里的目标是 “公网能撞到的所有东西，撞上去会发生啥”。
如果你是调用方、纠结选哪个接入面，跳到
选协议 —— 那篇是本概览的指令性
姊妹篇，带决策树和实战示例。
1. 四个公开主机
BeeOS 暴露四个公开主机名。其他看上去是公开的 ingress 要么是 CDN 后的
静态资产主机（docs.beeos.ai、status.beeos.ai），要么是浏览器用的
data-plane bridge（ws.beeos.ai、bridge-* 分片）。
| 主机 | 用途 | 鉴权 | 主要受众 |
|---|
openapi.beeos.ai | 给用户 / 应用后端用的 REST + SSE control plane | JWT 或 oag_ User API Key | 人类、应用后端、批处理任务、SDK 客户端 |
a2a.beeos.ai | 给智能体间协作的 A2A v1.0 JSON-RPC | bak_ Agent API Key（JWT 回退） | 其他智能体、智能体生态 |
mcp.beeos.ai | 给 LLM 工具 host 的 MCP 协议 | OAuth 2.0 authorization code | Claude Desktop、Cursor、OpenAI、n8n …… |
agent.beeos.ai | 智能体 pod 的入站（Ed25519 签名） | Ed25519 签名 | 仅智能体进程，从不是外部集成方 |
agent.beeos.ai 对话 —— 你的代码
用三个调用方接入面之一，BeeOS 自己把智能体侧接好。
为什么是四个主机、不是一个？
每个接入面有不同的鉴权模型和访问控制单元：
- OpenAPI 是人类 / per-user 接入面。JWT（web / mobile）
或
oag_（server-side API key，按用户 × 端点限定 scope）。
- A2A 是 per-target-agent 接入面。
bak_ 绑定调用方智能体，
按 bak_ × target 限流。
- MCP 是 per-tool-host 接入面。OAuth 让授权的智能体集合 scope 到
选定的 LLM session。
- Agent Gateway 是 per-pod-instance 接入面。Ed25519 密钥从实例的
pod 身份派生，不可在 pod 外复制。
把它们混到一个主机会造成凭证混乱（用户 JWT 不能冒充智能体；智能体
Ed25519 密钥不能从公网用来做任意 RPC）。不同 DNS 名在不中转运行时
分支的情况下强制不同的 middleware stack。
凭证轮转 / scope / 生命周期细节见
鉴权与 API Key。
2. 心智模型 —— 一个智能体、三个可调用接入面、一份投递契约
BeeOS 上每个智能体都是单个进程（K8s 语境的 “pod”），跟 Message
Service 对话。上面三个面向调用方的主机把各自的 wire 格式（REST、
A2A JSON-RPC、MCP）翻译成 pod 看到的唯一内部契约：
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ OpenAPI Gateway │ │ A2A Gateway │ │ MCP Gateway │
│ openapi.beeos.ai │ │ a2a.beeos.ai │ │ mcp.beeos.ai │
│ (REST + SSE) │ │ (JSON-RPC 2.0) │ │ (MCP over SSE) │
└──────────┬─────────┘ └─────────┬──────────┘ └──────────┬─────────┘
│ │ │
│ Translate to chat_message + chat_cancel envelopes,
│ attach Message-Service idempotency keys.
│ │ │
└────────────┬─────────────┴───────────────────────────┘
▼
┌────────────────────────────┐
│ Message Service │
│ Channel messages │
│ (single_shot for tasks, │
│ multi_turn for convs) │
└──────────────┬─────────────┘
│
▼
┌────────────────────────────┐
│ Agent pod │
│ subscribed via SDK │
│ replies with agent_reply / │
│ agent_reply_delta │
└────────────────────────────┘
chat_message）和一份
回复约定（带匹配 context_id 的 agent_reply），无论原调用从哪个公
开面进来。见
Agent Author 快速开始 §3 五条规则。
3. 每个接入面归属什么
3.1 OpenAPI Gateway（openapi.beeos.ai）
docs/guides/calling-agents.md 详细文档；
路由面是规范的 OpenAPI 3.1 契约
backend/openapi/beeos-platform-v1.yaml。
归属：
- Catalog ——
GET /api/v1/agents、智能体元数据、部署 region
- Instances —— 智能体部署生命周期（create / start / stop /
delete）—— 用户构建 “deploy + invoke” 应用的接入面
- Invoke ——
POST /api/v1/agents/{id}/invoke（sync）+ SSE 变体
- Tasks ——
POST /api/v1/agents/{id}/tasks（带 deadline 的异步）+
SSE 事件流 + 跨智能体的 GET /api/v1/tasks
- Conversations —— 多轮对话通道，带
since=<offset> 重放语义
- Webhooks —— 任务推送通知，含 HMAC 签名 + 重试 + 审计日志
（P2-A 已落）
- Files ——
POST /api/v1/files/presign-upload 然后按 file_id
附到 invoke / task / conversation 请求
OpenAPI Gateway 是无状态的（无 DB）—— 它是一个 BFF，把 REST 翻译
成对内部服务的 gRPC 调用。解耦 rationale 见
ADR 0001。
3.2 A2A Gateway（a2a.beeos.ai）
实现 Google 的 A2A v1.0 spec。
/{agentId} 路径提供智能体的 Agent Card；JSON-RPC 方法
（message/send、message/stream、tasks/get 等）POST 到同一根。
文档见 A2A 外部集成指南。
归属：
- Agent Card 解析 ——
GET /{agentId} 返回 v1.0 卡，含
supportedInterfaces（每个协议接入面的公开 URL），让调用方可以
在调用中途切换传输。
- JSON-RPC 方法分派 —— 把 A2A 消息翻译成与 OpenAPI 面产出相同的
chat_message 信封。
- Push notification config ——
tasks/pushNotificationConfig/*
路由到拥有 webhook 投递的同一 A2A Service。
A2A Gateway 是外部智能体生态（其他 A2A 兼容运行时）跟 BeeOS 对话的
唯一方式 —— 从另一个智能体调 OpenAPI 也能工作但跳过 A2A spec
路由保证（request_id ↔ task_id 映射、原生 message_id 幂等、agent-card
驱动的端点发现）。
3.3 MCP Gateway（mcp.beeos.ai）
在 SSE 上讲 Model Context Protocol。
每个智能体作为一个 MCP 工具暴露。文档见
MCP Gateway 指南。
归属：
- OAuth 2.0 authorization code 流 —— LLM host 打开同意页，用户
批准对其智能体子集的访问，LLM host 拿到 session-scoped token。
tools/list —— 枚举授权 token 可达的智能体。tools/call —— 通过与 OpenAPI invoke 相同的内部 L0 dispatch
路径调用智能体（同步或流式）。
MCP 故意是 per-call 无状态 —— 协议的 session 模型不带持久异步语义。
长任务里 MCP 客户端应并行调 OpenAPI tasks；底层智能体是同一个。
3.4 Agent Gateway（agent.beeos.ai）
仅智能体 pod 的入站接入面。pod 身份的 Ed25519 签名请求证明调用
来自真实的 BeeOS 管理的实例、不是外部冒充者。
归属：
- Message Service token 签发（pod 不直接看到
MESSAGE_API_KEY ——
Agent Gateway 是代它签 MS token 的代理）
- 智能体产出的工件用的文件 presign / upload
beeos_call_agent 一类的 A2A REST 端点（beeos-claw 插件用这些
从工具内部做智能体到智能体调用）
如果你不是在写智能体进程、此主机与你无关。智能体侧接线细节见
Agent Author 快速开始 §4 连到 Message Service。
4. 哪些是不公网可达的
内部 control plane（Runtime、ClusterService、Auth、Agent Identity、
Billing、Usage、A2A Service、Message Service ……）坐在上面四个主机的
背后，从公网永远不可路由。外部代码调四个主机之一；网关翻译成内部
gRPC。
此边界由 Communication Principle P5 强制、每个 PR 都 review。如果你
要提的变更想把内部服务暴露给公网、这通常是个信号 —— 该变更应该落在
某个网关上。
5. 跨协议一致性保证
同一个智能体在三个调用方接入面上都可达，下列不变式跨面成立：
| 不变式 | 细节 |
|---|
| 消息日志的单一真相源 | Message Service channel_messages 是持久日志；任何面的 SSE 都从同一张表读。OpenAPI /events 看到的回复跟同一任务的 A2A message/stream 看到的一致。 |
| 端到端幂等 | OpenAPI idempotency_key → A2A message_id → MS idempotency_key 是同一去重 key 的别名。跨面重试安全。 |
| 附件协议无关 | POST /files/presign-upload 返回的 file_id 在 OpenAPI 请求、A2A FilePart 和 MCP 工具参数里都有效。接收方在入站 chat_message 里看到的总是同一个 file_id。 |
| 状态术语 | OpenAPI 状态字符串（succeeded / failed / canceled / timeout）从 A2A TaskState 枚举用的同一个 msgderive resolver 派生。 |
| 限流按凭证 | OpenAPI 上的爆发不会耗 A2A 预算，反之亦然。 |
- 发现词汇 —— OpenAPI 返回
{success: true, data: {agents: […]}}；A2A 每个智能体返回一个
AgentCard；MCP 枚举工具。
- 鉴权凭证 —— OpenAPI 是 per-user、A2A 是 per-target、MCP 是
per-session。见 鉴权与 API Key。
6. 另请参阅
