跳转到主要内容
POST /v1/sessions/{session_id}/events 向 Session 发送事件（通常是用户消息），触发 Agent 开始处理。这是一个异步操作：消息被接受后，Agent 会在后台开始生成回复，可通过 SSE 流或列表事件 API 获取结果。

​
请求头

头部必选说明
Authorization是Bearer <PAT>
Content-Type是application/json

​
路径参数

参数类型必选说明
session_idstring是Session ID（sess_ 前缀）

​
请求体

字段类型必选说明
eventsarray是事件对象数组
events[].typestring是事件类型
events[].contentstring | array视类型消息内容（user.message 类型时必填）
events[].content[].typestring是内容块类型，如 text
events[].content[].textstring是文本内容
events[].file_attachmentsarray否user.message 的可选文件附件元数据。服务端会保留在事件中，并转发到 turn 输入。
content 支持两种格式：
  • 简写：纯字符串 "content": "文本内容"
  • 完整：内容块数组 "content": [{"type": "text", "text": "文本内容"}]
纯文本消息建议使用简写格式；需要发送多媒体内容（如图片）时使用完整格式。

​
支持的事件类型

type说明必填字段
user.message用户发送消息content
user.interrupt用户中断 Agent 执行-
user.tool_confirmation对需要确认的 Agent 工具调用授权或拒绝tool_use_id、result（allow 或 deny）
user.custom_tool_result返回 client-side 自定义工具的执行结果custom_tool_use_id；content 可选，默认保存为空 text block
user.define_outcome用户定义预期结果服务端不强制额外必填字段
session.status_idleWorker/session 状态事件服务端不强制额外必填字段
turn_completedWorker 终态事件服务端不强制额外必填字段

​
Human-in-the-loop 响应事件

当某一轮需要人工输入时，事件流会发送 session.status_idle，其中 stop_reason.type 为 "requires_action"，并带有 event_ids 数组。每个 ID 都指向需要响应的事件：
  • 对 agent.tool_use，发送 user.tool_confirmation，并将 tool_use_id 设为该 agent.tool_use 事件的 id
  • 对 agent.custom_tool_use，客户端先执行自定义工具，再发送 user.custom_tool_result，并将 custom_tool_use_id 设为该 agent.custom_tool_use 事件的 id
批准工具调用： 
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "allow"
    }
  ]
}
拒绝工具调用： 
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "deny",
      "deny_message": "不要删除该目录下的文件。"
    }
  ]
}
返回自定义工具结果： 
{
  "events": [
    {
      "type": "user.custom_tool_result",
      "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
      "content": [{"type": "text", "text": "订单状态：已发货"}]
    }
  ]
}
user.custom_tool_result 的 content 可以是字符串、单个 text content block 或 text content block 数组。返回事件中会统一保存为 content block 数组。 user.tool_confirmation 的最新字段是 result，取值 "allow" 或 "deny"。服务端仍兼容旧字段 decision（"approve" 或 "deny"），但只有在未提供 result 时才读取，返回事件会统一保存为 result。

​
示例请求

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": "请帮我分析这段代码的性能问题"}
        ]
      }
    ]
  }'

​
示例响应

HTTP 202 Accepted 返回已创建的事件列表。HTTP 202 表示消息已被接受并进入处理队列。 
{
  "data": [
    {
      "id": "evt_019e3bb2c153764da54e4d3acbef52b6",
      "type": "user.message",
      "content": [
        {"type": "text", "text": "请帮我分析这段代码的性能问题"}
      ],
      "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
      "turn_id": "turn_019e3bb2c15376429b88e1f7976c1907",
      "schema_version": "1.0",
      "created_at": "2026-05-18T15:27:11.187413896Z",
      "processed_at": "2026-05-18T15:27:11.187413896Z"
    }
  ]
}

​
响应字段

顶层响应：
字段类型说明
dataarray已创建事件对象数组，顺序与请求中的 events 一致
单个事件通用字段：
字段类型说明
idstring事件唯一标识（evt_ 前缀）
typestring事件类型
contentstring 或 array事件特定内容。user.message 保留请求中的形态；user.custom_tool_result 保存为 text content block 数组。
session_idstring所属 Session ID
turn_idstring事件属于某个 turn 时存在。user.message 会创建新的 turn_id。
schema_versionstringSchema 版本号
created_atstring创建时间（ISO 8601）
processed_atstring处理时间（ISO 8601）
tool_use_idstringuser.tool_confirmation 存在此字段
custom_tool_use_idstringuser.custom_tool_result 存在此字段
resultstringuser.tool_confirmation 存在此字段，取值 "allow" 或 "deny"
deny_messagestringuser.tool_confirmation 拒绝时的可选原因
发送消息后，Agent 会异步开始处理。可通过 GET /v1/sessions/{session_id}/events/stream 实时监听 Agent 的响应事件。

​
错误码

HTTPtype触发条件
400invalid_request_errorevents 为空、事件类型不支持、user.message 缺少 content、缺少 tool_use_id、缺少 custom_tool_use_id、result 非法，或请求格式错误
401authentication_errorPAT 无效或过期
404not_found_errorSession 不存在
409conflict_error向 processing 状态的 Session 发消息（需先 cancel 当前轮或等待 idle）
400 错误响应示例： 
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'content' is required."
  }
}
409 错误响应示例： 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
  }
}
完整错误信封说明详见 错误参考。

​
相关

Session 事件流

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