发送事件

向 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。

​

示例请求

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

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

当事件流发出 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 无效或过期
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"
}

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

​

相关

Session 事件流

通过 SSE 实时获取 Agent 的思考、消息、工具调用与状态。