发送事件-Qoder CN 系列(Lingma)-阿里云帮助中心

向 Session 发送事件（通常是用户消息），触发 Agent 开始处理。

请求头

头部	必选	说明
`Authorization`	是	`Bearer`
`Content-Type`	是	`application/json`

路径参数

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

请求体

字段	类型	必选	说明
`events`	array	是	事件对象数组
`events[].type`	string	是	事件类型
`events[].content`	string \	array	视类型
`events[].content[].type`	string	是	内容块类型，如 `text`
`events[].content[].text`	string	是	文本内容

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 -X POST "https://api.qoder.com.cn/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"
    }
  ]
}

响应字段

字段	类型	说明
`id`	string	事件唯一标识（`evt_` 前缀）
`type`	string	事件类型
`content`	array	内容块数组
`session_id`	string	所属 Session ID
`turn_id`	string	所属 Turn ID（`turn_` 前缀），服务端自动分配
`schema_version`	string	Schema 版本号
`created_at`	string	创建时间（ISO 8601）
`processed_at`	string	处理时间（ISO 8601）

发送消息后，Agent 会异步开始处理。可通过 GET /v1/sessions/{session_id}/events/stream 实时监听 Agent 的响应事件。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 `content` 字段或格式错误
401	`authentication_error`	PAT 无效或过期
404	`not_found_error`	Session 不存在
409	`conflict_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."
  }
}

完整错误信封说明详见错误参考。