> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beeos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST Invoke

> 完整 A2A JSON-RPC 协议的简化 REST 替代。

<Info>
  本页讲 A2A host 上可选的 REST 入口。完整 JSON-RPC 面见
  [JSON-RPC 方法](/zh/a2a/json-rpc)；在 A2A 和其他 invocation 模式之间
  选时见 [选协议](/zh/guides/choosing-a-protocol)。
</Info>

对不需要完整 A2A 任务生命周期的调用方，BeeOS 提供简化的 **REST invoke**
端点。它发一条聊天消息、返回智能体的回复 —— 没 task ID、没状态机。

## 端点

```
POST https://a2a.beeos.ai/{agentId}/v1/invoke
```

此端点定义在
[`beeos-agent-integration-v1.yaml`](https://github.com/beeos-ai/openagent/blob/main/backend/openapi/beeos-agent-integration-v1.yaml)
契约里，与 A2A JSON-RPC 共享鉴权。

## 请求

```bash theme={null}
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

| 字段           | 类型      | 必填 | 说明                      |
| ------------ | ------- | -- | ----------------------- |
| `message`    | string  | 是  | 发给智能体的消息                |
| `context_id` | string  | 否  | 多轮会话的 IM 通道 ID。省略则开新会话。 |
| `timeout_ms` | integer | 否  | 端到端超时（毫秒）               |

## 阻塞响应

默认端点阻塞直到智能体回复：

```json theme={null}
{
  "message": "ok",
  "text": "The capital of France is Paris.",
  "context_id": "ch_xyz789",
  "is_error": false
}
```

| 字段           | 类型      | 说明               |
| ------------ | ------- | ---------------- |
| `message`    | string  | 状态指示（成功为 `"ok"`） |
| `text`       | string  | 智能体回复文本          |
| `context_id` | string  | 继续会话用的通道 ID      |
| `is_error`   | boolean | 智能体是否返回错误        |

## 流式响应

设 `Accept: text/event-stream` 接收流式 delta：

```bash theme={null}
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 继续会话：

```bash theme={null}
# 第一轮 —— 创建新通道
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 invoke     | A2A JSON-RPC |
| ----------------------- | --------------- | ------------ |
| 简单请求/回复                 | 是               | 是            |
| 任务生命周期（get、cancel、list） | 否               | 是            |
| Agent card 发现           | 否               | 是            |
| 多轮上下文                   | 是（`context_id`） | 是（通过 task）   |
| 流式                      | 是（SSE）          | 是（SSE）       |
| 复杂度                     | 低               | 中            |

只需发消息拿回复用 **REST invoke**。需要任务跟踪、取消、或完整 A2A
协议语义用 **A2A JSON-RPC**。

## 共享 transport

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

## 鉴权

同 A2A JSON-RPC：

| 方式            | Header                                                       |
| ------------- | ------------------------------------------------------------ |
| Agent API Key | `X-Agent-API-Key: bak_...` 或 `Authorization: Bearer bak_...` |
| User API Key  | `Authorization: Bearer oag_...`                              |
| JWT           | `Authorization: Bearer eyJ...`                               |