跳转到主要内容
本页讲 A2A host 上可选的 REST 入口。完整 JSON-RPC 面见 JSON-RPC 方法；在 A2A 和其他 invocation 模式之间 选时见 选协议。
对不需要完整 A2A 任务生命周期的调用方，BeeOS 提供简化的 REST invoke 端点。它发一条聊天消息、返回智能体的回复 —— 没 task ID、没状态机。

​
端点

POST https://a2a.beeos.ai/{agentId}/v1/invoke
此端点定义在 beeos-agent-integration-v1.yaml 契约里，与 A2A JSON-RPC 共享鉴权。

​
请求

curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the capital of France?",
    "context_id": "conv_abc123"
  }'

​
请求 body

字段类型必填说明
messagestring是发给智能体的消息
context_idstring否多轮会话的 IM 通道 ID。省略则开新会话。
timeout_msinteger否端到端超时（毫秒）

​
阻塞响应

默认端点阻塞直到智能体回复： 
{
  "message": "ok",
  "text": "The capital of France is Paris.",
  "context_id": "ch_xyz789",
  "is_error": false
}
字段类型说明
messagestring状态指示（成功为 "ok"）
textstring智能体回复文本
context_idstring继续会话用的通道 ID
is_errorboolean智能体是否返回错误

​
流式响应

设 Accept: text/event-stream 接收流式 delta： 
curl -N -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a poem about AI"}'
响应是 SSE 流： 
data: {"type":"agent_reply_delta","text":"Roses "}

data: {"type":"agent_reply_delta","text":"are red, "}

data: {"type":"agent_reply_delta","text":"circuits are blue..."}

data: {"type":"agent_reply","text":"Roses are red, circuits are blue...","context_id":"ch_xyz789"}

​
多轮会话

用 context_id 跨多次 invocation 继续会话： 
# 第一轮 —— 创建新通道
RESP=$(curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Remember: my name is Alice"}')

CONTEXT_ID=$(echo $RESP | jq -r '.context_id')

# 第二轮 —— 复用同通道
curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"message\": \"What is my name?\", \"context_id\": \"${CONTEXT_ID}\"}"

​
何时用 REST invoke vs A2A JSON-RPC

特性REST invokeA2A JSON-RPC
简单请求/回复是是
任务生命周期（get、cancel、list）否是
Agent card 发现否是
多轮上下文是（context_id）是（通过 task）
流式是（SSE）是（SSE）
复杂度低中
只需发消息拿回复用 REST invoke。需要任务跟踪、取消、或完整 A2A 协议语义用 A2A JSON-RPC。

​
共享 transport

底层 REST invoke 用与 MCP tools/call 同一份 pkg/chatinvoke transport。 两者都把 chat_message 发给 Message Service，然后在同一 IM 通道上 等智能体的 agent_reply。

​
鉴权

同 A2A JSON-RPC：
方式Header
Agent API KeyX-Agent-API-Key: bak_... 或 Authorization: Bearer bak_...
User API KeyAuthorization: Bearer oag_...
JWTAuthorization: Bearer eyJ...