线程事件流 (SSE)

通过 Server-Sent Events 实时接收指定 Session Thread 中的事件。

GET /v1/sessions/{session_id}/threads/{thread_id}/stream

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

​

请求头

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

​

路径参数

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

​

查询参数

参数	类型	必选	说明
type	string	否	按事件类型过滤。支持逗号分隔多值
types[]	string	否	type 的数组写法替代方案

​

示例请求

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

​

示例响应

HTTP 200 OK

Content-Type: text/event-stream

每个事件遵循 SSE 标准格式。所有事件都包含 session_thread_id 字段：

子线程创建：

id: evt_019f0000000000000000000000000100
event: session.thread_created
data: {"id": "evt_019f0000000000000000000000000100", "type": "session.thread_created", "schema_version": "1.0", "session_id": "sess_019f00000000000000000000000000aa", "session_thread_id": "sthr_019f00000000000000000000000002bb", "parent_thread_id": "sthr_019f00000000000000000000000001aa", "agent_id": "agent_019f000000000000000000000000002b", "agent_version": 2, "agent_name": "Research Agent", "role": "child", "created_by_tool_use_id": "toolu_bdrk_01T42NPLcKrBvLJfWgGt3QMt", "created_at": "2026-06-15T08:01:00.000Z"}

线程开始执行：

id: evt_019f0000000000000000000000000102
event: session.thread_status_running
data: {"id": "evt_019f0000000000000000000000000102", "type": "session.thread_status_running", "schema_version": "1.0", "session_id": "sess_019f00000000000000000000000000aa", "session_thread_id": "sthr_019f00000000000000000000000002bb", "agent_name": "Research Agent", "status": "running", "created_at": "2026-06-15T08:01:01.000Z"}

线程间消息发送（coordinator → child）：

id: evt_019f0000000000000000000000000101
event: agent.thread_message_sent
data: {"id": "evt_019f0000000000000000000000000101", "type": "agent.thread_message_sent", "schema_version": "1.0", "session_id": "sess_019f00000000000000000000000000aa", "session_thread_id": "sthr_019f00000000000000000000000002bb", "direction": "coordinator_to_child", "content": "请调研竞品动态", "from_session_thread_id": "sthr_019f00000000000000000000000001aa", "to_session_thread_id": "sthr_019f00000000000000000000000002bb", "created_at": "2026-06-15T08:01:00.500Z"}

线程间消息接收（child → coordinator）：

id: evt_019f0000000000000000000000000110
event: agent.thread_message_received
data: {"id": "evt_019f0000000000000000000000000110", "type": "agent.thread_message_received", "schema_version": "1.0", "session_id": "sess_019f00000000000000000000000000aa", "session_thread_id": "sthr_019f00000000000000000000000001aa", "direction": "child_to_parent", "content": "调研完成，主要发现如下...", "is_error": false, "from_session_thread_id": "sthr_019f00000000000000000000000002bb", "to_session_thread_id": "sthr_019f00000000000000000000000001aa", "created_at": "2026-06-15T08:05:00.000Z"}

线程空闲（子线程完成）：

id: evt_019f0000000000000000000000000111
event: session.thread_status_idle
data: {"id": "evt_019f0000000000000000000000000111", "type": "session.thread_status_idle", "schema_version": "1.0", "session_id": "sess_019f00000000000000000000000000aa", "session_thread_id": "sthr_019f00000000000000000000000002bb", "status": "idle", "stop_reason": {"type": "end_turn"}, "created_at": "2026-06-15T08:05:01.000Z"}

​

线程事件类型

除了 Session 级别的通用事件类型外，线程维度新增以下事件类型：

event (SSE field)	说明
session.thread_created	新子线程被创建。包含 parent_thread_id、agent_id、agent_version、agent_name、role、created_by_tool_use_id
session.thread_status_running	线程开始执行。包含 agent_name、status
session.thread_status_idle	线程回到空闲。包含 status、stop_reason
session.thread_status_terminated	线程被归档或终止。包含 status、stop_reason
agent.thread_message_sent	线程间发送消息。包含 direction、content、from_session_thread_id、to_session_thread_id
agent.thread_message_received	线程间接收消息。包含 direction、content、is_error、from_session_thread_id、to_session_thread_id

在 managed agents 场景下，所有事件都会额外包含 session_thread_id 字段。Session 级事件流（/sessions/{id}/events/stream）会包含所有线程的事件；线程级事件流仅包含指定线程的事件。

​

错误码

HTTP	type	触发条件
400	invalid_request_error	Last-Event-ID 不属于该线程
401	authentication_error	PAT 无效或过期
404	not_found_error	Session 或 Thread 不存在

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

​

相关

Managed Agents

了解线程事件在多 Agent 协作中的语义。

列出线程事件

分页拉取线程的历史事件。

列出 Session Threads

查看 Session 中的所有线程。