事件流 (SSE)

通过 Server-Sent Events 实时接收 Session 中的所有事件。

GET /v1/sessions/{session_id}/events/stream

通过 Server-Sent Events (SSE) 实时接收 Session 中的所有事件。连接建立后，服务端会推送该 Session 的完整事件历史，并在有新事件产生时继续推送。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>
Accept	推荐	text/event-stream
Last-Event-ID	否	从该事件 ID 之后继续推送。该 ID 必须属于当前 Session。

​

路径参数

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

​

查询参数

参数	类型	必选	说明
type	string	否	按事件类型过滤。支持逗号分隔多值，也支持重复传参。
types[]	string	否	type 的数组写法替代方案。传入多个 types[]=... 参数可同时流式接收多种事件。

​

示例请求

curl -N -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"

​

示例响应

HTTP 200 OK

Content-Type: text/event-stream

每个事件遵循 SSE 标准格式：

id: <event_id>
event: <event_type>
data: <json_payload>

​

SSE 格式示例

注意： SSE data 行的 JSON 是完全平铺结构——所有字段（如 name、input、evaluated_permission、content、is_error 等）直接位于顶层对象中，没有额外的嵌套 wrapper。content 字段在 SSE 输出中始终为数组格式 [{"type": "text", "text": "..."}]。

用户消息：

id: evt_019e392c0d787cfaa21bda98e06cd913
event: user.message
data: {"id": "evt_019e392c0d787cfaa21bda98e06cd913", "type": "user.message", "content": "你好", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "created_at": "2026-05-18T03:40:48.888851795Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:40:48.888851795Z", "schema_version": "1.0"}

会话调度：

id: evt_771c1195bcbd4a07834d4ed4dd6450ca
event: session.status_running
data: {"id": "evt_771c1195bcbd4a07834d4ed4dd6450ca", "type": "session.status_running", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "created_at": "2026-05-18T03:40:50.321Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:40:50.321Z", "schema_version": "1.0"}

Agent 回复：

id: evt_f8599c68e7784f2d8c490af1b3056716
event: agent.message
data: {"id": "evt_f8599c68e7784f2d8c490af1b3056716", "type": "agent.message", "content": [{"text": "收到！消息已成功接收。", "type": "text"}], "turn_id": "turn_019e392d6aad7158b377c039c6ba5db3", "created_at": "2026-05-18T03:42:41.194Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:42:41.194Z", "schema_version": "1.0"}

Agent 调用工具：

id: evt_01JZ6Q3FB6SG8F7J1M2N
event: agent.tool_use
data: {"id": "evt_01JZ6Q3FB6SG8F7J1M2N", "type": "agent.tool_use", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "name": "Bash", "input": {"command": "echo hello"}, "evaluated_permission": "allow", "processed_at": "2026-05-18T03:41:05.000Z"}

自定义工具请求：

id: evt_01JZ6R1V9Z8K2M3N4P5Q
event: agent.custom_tool_use
data: {"id": "evt_01JZ6R1V9Z8K2M3N4P5Q", "type": "agent.custom_tool_use", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "name": "lookup_order", "input": {"order_id": "ord_123"}, "processed_at": "2026-05-18T03:41:05.000Z"}

工具执行结果：

id: evt_01JZ6Q5Y0S1H2G3F4E5D
event: agent.tool_result
data: {"id": "evt_01JZ6Q5Y0S1H2G3F4E5D", "type": "agent.tool_result", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "tool_use_id": "toolu_bdrk_01T42NPLcKrBvLJfWgGt3QMt", "name": "Bash", "content": [{"type": "text", "text": "hello\n"}], "is_error": false, "processed_at": "2026-05-18T03:41:06.000Z"}

会话空闲（Turn 完成）：

id: evt_a289470296c94e7ba8d7ea562efe5925
event: session.status_idle
data: {"id": "evt_a289470296c94e7ba8d7ea562efe5925", "type": "session.status_idle", "usage": {"input_tokens": 150, "output_tokens": 42, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}, "status": "idle", "turn_id": "turn_019e392d6aad7158b377c039c6ba5db3", "created_at": "2026-05-18T03:42:41.195Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "stop_reason": {"type": "end_turn"}, "processed_at": "2026-05-18T03:42:41.195Z", "schema_version": "1.0"}

会话空闲（等待操作）：

id: evt_01JZ6R2E7H9M0N1P2Q3R
event: session.status_idle
data: {"id": "evt_01JZ6R2E7H9M0N1P2Q3R", "type": "session.status_idle", "status": "idle", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "stop_reason": {"type": "requires_action", "event_ids": ["evt_01JZ6R1V9Z8K2M3N4P5Q"]}, "schema_version": "1.0"}

​

事件类型

完整事件类型列表：

event (SSE field)	说明
user.message	用户发送的消息
session.status_running	Agent 开始处理
agent.thinking	Agent 思考中（内部推理）
agent.message	Agent 生成的回复消息
agent.tool_use	Agent 调用内置工具
agent.tool_result	工具执行返回结果
agent.custom_tool_use	Agent 请求 client-side 自定义工具
user.tool_confirmation	用户批准或拒绝待确认工具调用
user.custom_tool_result	用户/客户端返回自定义工具结果
agent.mcp_tool_use	Agent 调用 MCP 工具
agent.mcp_tool_result	MCP 工具执行返回结果
agent.artifact_delivered	Agent 通过 DeliverArtifacts 投递文件
session.status_idle	处理完成，Session 回到空闲
session.error	处理过程中发生错误
session.thread_created	新子线程被创建（Managed Agents）
session.thread_status_running	子线程开始执行（Managed Agents）
session.thread_status_idle	子线程回到空闲（Managed Agents）
session.thread_status_terminated	子线程被归档或终止（Managed Agents）
agent.thread_message_sent	线程间发送消息（Managed Agents）
agent.thread_message_received	线程间接收消息（Managed Agents）

事件流会过滤内部事件类型，例如 agent.raw、agent.system、turn_completed、turn_cancelled、turn_failed、terminated、span.model_request_start、span.model_request_end 和 pending_action.*。

​

典型事件流生命周期

一次完整的对话 Turn 通常按以下顺序接收事件：

1. user.message — 用户消息入队
2. session.status_running — Agent 开始执行
3. agent.thinking — Agent 内部推理
4. agent.message — Agent 生成回复
5. session.status_idle — Turn 完成，或以 requires_action 暂停

​

客户端实现建议

• 使用 EventSource API 或支持 SSE 的 HTTP 客户端
• 使用标准 Last-Event-ID 请求头从已知事件 ID 后续传
• 监听 session.status_idle；通过 stop_reason.type 判断 turn 是完成还是暂停等待操作
• 当 session.status_idle.stop_reason.type 为 requires_action 时，使用 user.tool_confirmation 或 user.custom_tool_result 响应其中列出的 event_ids
• 通过 turn_id 字段关联同一轮对话的所有事件
• 连接会保持打开直到客户端断开，服务端持续推送新事件

​

错误码

HTTP	type	触发条件
401	authentication_error	PAT 无效或过期
404	not_found_error	Session 不存在

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

​

相关

Session 事件流

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