Skip to main content
Sessions

发送 Session Event

向 Forward Session 写入用户或系统输入事件。

请求头

Header是否必填说明
Authorization是Bearer <PAT>
Content-Type是application/json
Idempotency-Key否有副作用请求可选的幂等键。

路径参数

参数类型是否必填说明
session_idstring是Session ID。

请求体

字段类型必选说明
eventsarray是事件对象数组
events[].typestring是事件类型
events[].contentstring \array视类型
events[].content[].typestring是内容块类型，如 text
events[].content[].textstring是文本内容
content 支持两种格式：
  • 简写：纯字符串 "content": "文本内容"
  • 完整：内容块数组 "content": [{"type": "text", "text": "文本内容"}]
纯文本消息建议使用简写格式；需要发送多媒体内容（如图片）时使用完整格式。

支持的事件类型

type说明必填字段
user.message用户发送消息content
user.interrupt用户中断 Agent 执行-
user.tool_confirmation对 Agent 的工具调用进行授权tool_use_id、decision（approve 或 deny）
user.custom_tool_result返回自定义工具的执行结果tool_use_id、content
user.define_outcome用户定义预期结果content

示例请求

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "file_attachments": []
    }
  ]
}'

示例响应

HTTP 200 OK 
{
  "data": [
    {
      "id": "evt_xxx",
      "type": "user.message",
      "session_id": "sess_xxx",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "processed_at": "2026-06-22T11:00:00Z"
    }
  ]
}

响应字段

字段类型说明
dataarray创建后的 Event 对象数组，已按 Forward 规则过滤。

错误

HTTPTypeCode触发条件
400invalid_request_errorinvalid_eventEvent 类型或字段不合法。
404not_found_errorsession_not_foundSession 不存在。
409conflict_errorsession_archivedSession 已归档。
409conflict_errorturn_already_running当前 Turn 状态不允许新建 Turn。
404not_found_errorpending_action_not_found工具确认或结果找不到对应 Pending Action。
409conflict_errorpending_action_already_resolvedPending Action 已处理。
401-TOKEN_INVALIDPAT 无效或已过期，或缺少 Authorization header。

备注

  • 允许写入的类型包括 user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome 和 system.message。
  • system.message 每次请求最多一条，必须是最后一个事件。
  • 响应不会返回运行时原始 event JSON。
  • session&event数据结构
  • 查询 Event 历史
  • 订阅 Session Event Stream
操作指南
实践教程
API参考