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

# 发送事件

> 向 Session 发送 user 或 system 事件。

`POST /api/v1/cloud/sessions/{session_id}/events`

向 Session 发送一个或多个可接受事件。`user.message` 会异步触发 Agent 执行，Agent 输出通过 list 或 stream 接口读取。

## 路径参数

| 参数           | 类型     | 说明                        |
| ------------ | ------ | ------------------------- |
| `session_id` | string | 以 `sess_` 为前缀的 Session ID |

## 请求头

| 请求头             | 必填 | 说明                  |
| --------------- | -- | ------------------- |
| `Authorization` | 是  | `Bearer $QODER_PAT` |
| `Content-Type`  | 是  | `application/json`  |

## 请求体

| 字段       | 类型    | 必填 | 说明       |
| -------- | ----- | -- | -------- |
| `events` | array | 是  | 非空事件对象数组 |

## 支持的事件类型

| 类型                        | 必填字段                    | 说明                                                                                                                                                                          |
| ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user.message`            | `content`               | `content` 必须是非空 content block 数组                                                                                                                                            |
| `user.interrupt`          | 无                       | `session_thread_id` 可选                                                                                                                                                      |
| `user.tool_confirmation`  | `tool_use_id`, `result` | `result` 为 `allow` 或 `deny`。`deny_message` 可选，且仅在 `result = "deny"` 时允许传入                                                                                                   |
| `user.tool_result`        | `tool_use_id`           | 返回内置工具结果；`content` 和 `is_error` 可选                                                                                                                                          |
| `user.custom_tool_result` | `custom_tool_use_id`    | 返回客户端自定义工具结果；`content` 和 `is_error` 可选                                                                                                                                      |
| `user.define_outcome`     | `description`, `rubric` | `rubric` 是对象，可取 `{"type":"text","content":"..."}` 或 `{"type":"file","file_id":"file_..."}`；不允许多余字段。`max_iterations` 可选，必须是 1–20 之间的整数。`outcome_id`（`outc_` 前缀）由服务端生成，客户端不可传 |
| `system.message`          | `content`               | `content` 必须是非空文本 content block 数组。每次请求最多一个 `system.message`，且必须是 batch 的最后一个事件，紧跟在 `user.message`、`user.tool_result` 或 `user.custom_tool_result` 之后                        |

`user.message` 和 `system.message` 不支持字符串形式的 `content`。

## 示例请求

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {"type": "text", "text": "Help me analyze the performance of this code."}
        ]
      }
    ]
  }'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "evt_019e3bb2c153764da54e4d3acbef52b6",
      "type": "user.message",
      "content": [
        {"type": "text", "text": "Help me analyze the performance of this code."}
      ],
      "processed_at": "2026-05-18T15:27:11.187413896Z"
    }
  ]
}
```

## 人在环（Human-in-the-loop）响应

当事件流发出需要确认的 `agent.tool_use` 时，使用 `user.tool_confirmation` 响应：

```json theme={null}
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "deny",
      "deny_message": "Do not delete files in this directory."
    }
  ]
}
```

当事件流发出 `agent.custom_tool_use` 时，由客户端执行该工具并使用 `user.custom_tool_result` 响应：

```json theme={null}
{
  "events": [
    {
      "type": "user.custom_tool_result",
      "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
      "content": [{"type": "text", "text": "Order status: shipped"}]
    }
  ]
}
```

## 错误码

| HTTP | 类型                      | 触发条件                                                                                          |
| ---- | ----------------------- | --------------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | `events` 为空、事件类型不支持、缺少必填字段、content block 非法或使用旧字段                                             |
| 401  | `authentication_error`  | PAT 无效或过期                                                                                     |
| 404  | `not_found_error`       | Session 或 pending action 不存在                                                                  |
| 409  | `invalid_request_error` | Session 正在处理某个 turn，或其他 Session 状态冲突（注意：`type` 是 `invalid_request_error`，不是 `conflict_error`） |

### 示例：400 `content` 非法

向 `user.message` 传入字符串而非 content block 数组：

```json theme={null}
{
  "error": {
    "message": "Field 'content' must be a non-empty array of content blocks.",
    "type": "invalid_request_error"
  },
  "request_id": "2c9d3d8a-dd0f-4c27-b2ad-24c8719c97e1",
  "type": "error"
}
```

### 示例：404 Session 不存在

```json theme={null}
{
  "error": {
    "message": "Session 'sess_doesnotexist_xxxxxxxxxxxxxxxxxxxxxxxx' was not found.",
    "type": "not_found_error"
  },
  "request_id": "590c2a0c-1656-42d3-ba0c-32c755d22e77",
  "type": "error"
}
```

### 示例：409 Session 正在 running

在 Session 已经处于 running 状态时再发送 `user.message`：

```json theme={null}
{
  "error": {
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion.",
    "type": "invalid_request_error"
  },
  "request_id": "ba018d2f-d6b0-4bbe-a53c-2241baca34fe",
  "type": "error"
}
```

完整错误信封格式参见 [错误处理](/zh/cloud-agents/api/conventions/errors)。

## 相关

<CardGroup cols={2}>
  <Card title="Session 事件流" icon="wave-pulse" href="/zh/cloud-agents/events-stream">
    通过 SSE 实时获取 Agent 的思考、消息、工具调用与状态。
  </Card>
</CardGroup>