发送事件 - Qoder

POST /api/v1/cloud/sessions/{session_id}/events 向 Session 发送一个或多个可接受事件。user.message 会异步触发 Agent 执行，Agent 输出通过 list 或 stream 接口读取。

路径参数

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

请求头

请求头	必填	说明
`Authorization`	是	`Bearer $QODER_ACCESS_TOKEN`
`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`	self-hosted worker 返回内置工具结果。`content` 可选；传入时必须是 content block 数组。`is_error` 可选
`user.custom_tool_result`	`custom_tool_use_id`	返回客户端自定义工具结果。`content` 可选；传入时必须是 content block 数组。`is_error` 可选
`user.define_outcome`	`description`, `rubric`	`rubric` 是对象，可取 `{"type":"text","content":"..."}` 或 `{"type":"file","file_id":"file_..."}`；不允许多余字段。`max_iterations` 可选，必须是 1–20 之间的整数。`outcome_id`（`outc_` 前缀）由服务端生成，客户端不可传

不支持字符串形式的 events[].content。事件包含 content 字段时，需传 content block 数组。

示例请求

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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

{
  "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 响应：

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

self-hosted Environment 中，worker 执行内置工具后使用 user.tool_result 返回结果。tool_use_id 取对应 agent.tool_use 事件的 id：

{
  "events": [
    {
      "type": "user.tool_result",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "content": [{"type": "text", "text": "Command completed successfully."}],
      "is_error": false
    }
  ]
}

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

{
  "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 或 SAT 无效或过期
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 数组：

{
  "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 不存在

{
  "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：

{
  "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"
}

完整错误信封格式参见错误处理。

​路径参数

​请求头

​请求体

​支持的事件类型

​示例请求

​示例响应

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

​错误码

​示例：400 content 非法

​示例：404 Session 不存在

​示例：409 Session 正在 running