> ## 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.

# JSON-RPC 方法

> A2A v1.0 JSON-RPC 方法完整参考。

A2A 协议用 [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
作 wire 格式。所有请求都是 `POST` 带 `Content-Type: application/json`。

## 端点

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

带 `A2A-Version: 1.0` header 做协议版本协商。

<Note>
  **方法命名。** A2A v1.0 用命名空间小写名如 `message/send` 和
  `tasks/get`。BeeOS A2A Gateway **同时**接受 v1.0 命名空间名和
  历史 PascalCase 别名（`SendMessage`、`GetTask` 等）以向后兼容 ——
  它们解析到同一个 handler。新接入应优先用命名空间名。映射表在
  [本页底部](#标准别名映射)。
</Note>

| A2A v1.0 标准                        | Legacy 别名（仍受支持）        | 说明                                            |
| ---------------------------------- | ---------------------- | --------------------------------------------- |
| `message/send`                     | `SendMessage`          | 发消息；创建任务或继续会话                                 |
| `message/stream`                   | `SendStreamingMessage` | 同上但返回 SSE 流                                   |
| `tasks/get`                        | `GetTask`              | 取任务状态和结果                                      |
| `tasks/cancel`                     | `CancelTask`           | 取消进行中的任务                                      |
| `tasks/list`                       | `ListTasks`            | 列调用方身份的任务                                     |
| `tasks/complete`                   | `CompleteTask`         | （BeeOS）智能体侧标记任务完成                             |
| `tasks/updateStatus`               | `UpdateStatus`         | （BeeOS）推送进行中状态更新                              |
| `tasks/resubscribe`                | `SubscribeToTask`      | 重订阅任务 SSE 流                                   |
| `tasks/pushNotificationConfig/set` | —                      | 注册 webhook（见 [Webhooks](/zh/guides/webhooks)） |

下面的逐方法文档用 PascalCase 形以匹配已有字段名 —— 调用时替换为
命名空间形即可。

## 请求格式

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": { ... }
}
```

## 方法

### SendMessage

给智能体发消息，创建新任务或继续已有会话。

**Params:**

| 字段                     | 类型        | 必填 | 说明                           |
| ---------------------- | --------- | -- | ---------------------------- |
| `message`              | object    | 是  | 要发的消息                        |
| `message.role`         | string    | 是  | 用户消息用 `"user"`               |
| `message.parts`        | array     | 是  | 消息内容部分                       |
| `message.parts[].kind` | string    | 是  | `"text"`、`"file"` 或 `"data"` |
| `message.parts[].text` | string    | 条件 | 文本内容（`kind` 为 `"text"` 时）    |
| `configuration`        | object    | 否  | 任务配置覆盖                       |
| `configuration.skills` | string\[] | 否  | 限定到特定技能                      |

**示例:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {"kind": "text", "text": "What is the weather in San Francisco?"}
      ]
    }
  }
}
```

**响应:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "status": {
      "state": "completed",
      "timestamp": "2026-04-23T10:30:00Z"
    },
    "artifacts": [
      {
        "parts": [
          {"kind": "text", "text": "The weather in San Francisco is 65°F and sunny."}
        ]
      }
    ]
  }
}
```

### GetTask

取任务的当前状态和结果。

**Params:**

| 字段   | 类型     | 必填 | 说明                        |
| ---- | ------ | -- | ------------------------- |
| `id` | string | 是  | `SendMessage` 返回的 task ID |

**示例:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "GetTask",
  "params": {
    "id": "task_abc123"
  }
}
```

### CancelTask

请求取消进行中的任务。

**Params:**

| 字段   | 类型     | 必填 | 说明           |
| ---- | ------ | -- | ------------ |
| `id` | string | 是  | 要取消的 task ID |

**示例:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "CancelTask",
  "params": {
    "id": "task_abc123"
  }
}
```

### ListTasks

列智能体的任务（调用方范围）。

**Params:**

| 字段       | 类型      | 必填 | 说明          |
| -------- | ------- | -- | ----------- |
| `limit`  | integer | 否  | 最大返回（默认 20） |
| `offset` | integer | 否  | 分页 offset   |

### SendStreamingMessage

同 `SendMessage` 但返回 SSE 流而非阻塞响应。详见 [流式](/zh/a2a/streaming)。

## BeeOS 扩展

BeeOS 在 A2A v1.0 spec 之外加了下列方法：

### CompleteTask

智能体侧标记任务完成。

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "CompleteTask",
  "params": {
    "id": "task_abc123",
    "artifacts": [
      {"parts": [{"kind": "text", "text": "Done!"}]}
    ]
  }
}
```

### UpdateStatus

更新进行中任务的状态。

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "UpdateStatus",
  "params": {
    "id": "task_abc123",
    "status": {
      "state": "working",
      "message": "Processing step 2 of 5..."
    }
  }
}
```

## 标准别名映射

A2A Gateway 同时接受 A2A v1.0 命名空间名和历史 PascalCase 形。挑跟你
客户端库风格匹配的用；wire 行为完全相同。

| A2A v1.0 标准          | PascalCase 别名          | 实现                                                                                                                             |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `message/send`       | `SendMessage`          | [`gateway.go`](https://github.com/beeos-ai/openagent/blob/main/backend/services/gateway/internal/http/gateway.go) —— 同 handler |
| `message/stream`     | `SendStreamingMessage` | 同 handler，SSE 响应                                                                                                               |
| `tasks/get`          | `GetTask`              | 同 handler                                                                                                                      |
| `tasks/cancel`       | `CancelTask`           | 同 handler                                                                                                                      |
| `tasks/list`         | `ListTasks`            | 同 handler                                                                                                                      |
| `tasks/complete`     | `CompleteTask`         | BeeOS 扩展（智能体侧）                                                                                                                 |
| `tasks/updateStatus` | `UpdateStatus`         | BeeOS 扩展                                                                                                                       |
| `tasks/resubscribe`  | `SubscribeToTask`      | 同 handler，重挂 SSE                                                                                                               |

新接入：优先用命名空间形。已有 PascalCase 调用方不必迁移 —— 两者都
会无限期接受。

## 错误码

| Code     | 含义             |
| -------- | -------------- |
| `-32600` | 非法 JSON-RPC 请求 |
| `-32601` | 方法未找到          |
| `-32602` | 非法 params      |
| `-32603` | 内部错误           |
| `-32000` | 任务未找到          |
| `-32001` | 智能体未找到         |
| `-32002` | 智能体离线          |
| `-32003` | 任务超时           |