Session 事件流

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

Qoder Cloud Agents 使用 Server-Sent Events (SSE) 协议将 Agent 的实时执行状态推送到客户端。你无需轮询——建立一次连接即可持续接收所有事件。

​

连接 URL

GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream

请求头：

Authorization: Bearer $QODER_PAT
Accept: text/event-stream

​

SSE 格式

每个事件由三行组成，以空行分隔：

id: evt_01abc123
event: agent.message
data: {"content":[{"type":"text","text":"Hello, I'm ready to help."}]}

字段	说明
id	事件唯一标识，用于断线重连
event	事件类型，决定 data 的结构
data	JSON 格式的事件负载

​

完整事件类型

事件类型	含义	触发时机	data 结构
user.message	用户发送消息	客户端 POST 事件后	{"content": [{"type":"text","text":"..."}]}
user.interrupt	用户中断当前执行	客户端发送中断事件	{}
user.define_outcome	用户定义预期结果	客户端设定目标	{"outcome": "..."}
session.status_running	Session 开始执行	收到消息后开始处理	{"status": "running"}
span.model_request_start	模型请求开始	Agent 发起 LLM 调用	{"model": "...", "span_id": "..."}
agent.thinking	Agent 思考中	模型推理过程中	{"thinking": "..."}
agent.message	Agent 回复消息	模型产出文本	{"content": [{"type":"text","text":"..."}]}
agent.tool_use	Agent 发起内置工具调用	模型决定调用内置工具	见下文「工具调用」
agent.tool_result	内置工具执行回执	工具执行完成后	见下文「工具调用」
agent.custom_tool_use	Agent 请求 client-side 自定义工具	模型决定调用自定义工具	见下文「工具调用」
session.status_idle	Session 进入空闲	一轮对话完成	见下文「status_idle 完整 schema」
span.model_request_end	模型请求结束	LLM 调用完成	{"span_id": "...", "usage": {...}}
session.error	Session 出错	运行时异常	{"error": "...", "code": "..."}
terminated	Session 终止	Session 被关闭或超时	{"reason": "..."}

每个事件的 data JSON 除上表列出的特有字段外，还包含以下通用字段：id、type、turn_id（user.define_outcome 不含此字段）、session_id、created_at、processed_at、schema_version。

​

典型事件生命周期

一次完整的对话轮次，事件按以下顺序触发：

user.message                  ← 用户输入
session.status_running    ← 开始执行
span.model_request_start      ← 模型请求
agent.thinking                ← 推理中（可选）
agent.message                 ← 回复内容（可能多次 delta）
session.status_idle           ← 完成，或暂停等待 requires_action
span.model_request_end        ← 模型请求收尾

​

工具调用

内置工具调用使用 agent.tool_use。如果工具调用被允许并由平台执行，随后会在同一个 turn_id 下生成对应的 agent.tool_result。

agent.tool_use 关键字段：

{
  "type": "agent.tool_use",
  "id": "evt_1d4c9b3c873b...",
  "name": "Bash",
  "input": { "command": "...", "description": "..." },
  "evaluated_permission": "allow",
  "turn_id": "turn_...",
  "session_id": "sess_..."
}

此事件的 id 与其他事件一样使用 evt_ 前缀。当 evaluated_permission 为 ask 时，回传 user.tool_confirmation.tool_use_id 要使用这个事件 id。

agent.tool_result 关键字段：

{
  "type": "agent.tool_result",
  "id": "evt_<32hex>",
  "name": "Bash",
  "content": [{ "type": "text", "text": "..." }],
  "tool_use_id": "toolu_bdrk_01Kj...",
  "turn_id": "turn_...",
  "is_error": false
}

Client-side 自定义工具使用 agent.custom_tool_use，由你的应用执行并回传：

{
  "type": "agent.custom_tool_use",
  "id": "evt_1f2e3d4c5b6a...",
  "name": "lookup_order",
  "input": { "order_id": "ord_123" },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}

回传时将自定义工具事件的 id 填入 user.custom_tool_result.custom_tool_use_id。

排序建议：按 created_at → 类型（tool_use 在 tool_result 前）→ id 三级排序。不要单靠 id 排序——平台生成的 tool_result id 可能字典序小于 tool_use id。

​

status_idle 完整 schema

session.status_idle 事件除 status 外还携带 stop_reason、usage、turn_id 与 session_id：

{
  "type": "session.status_idle",
  "id": "evt_840b8dc4b1534e52a2b858bf26b7de00",
  "status": "idle",
  "stop_reason": { "type": "end_turn" },
  "usage": {
    "input_tokens": 23487,
    "output_tokens": 1024,
    "cache_read_input_tokens": 11223,
    "cache_creation_input_tokens": 0
  },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}

当 turn 暂停等待工具确认或自定义工具结果时，stop_reason.type 为 requires_action，event_ids 指向需要客户端响应的事件：

{
  "type": "session.status_idle",
  "id": "evt_0f1e2d3c4b5a...",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_1f2e3d4c5b6a..."]
  },
  "turn_id": "turn_...",
  "session_id": "sess_..."
}

其他 stop_reason.type 值包括 end_turn、cancel、max_turns、error，按实际场景出现。

​

断线重连与 after_id

SSE 连接建立后，默认从头重放所有历史事件。若只需增量事件，传入 after_id 参数：

GET /sessions/{session_id}/events/stream?after_id=evt_01abc123

浏览器原生 EventSource 会在断线重连时自动携带 Last-Event-ID 请求头，服务端据此返回增量事件。

长时间保持连接时建议客户端记录最后收到的 id，断线后用 after_id 恢复。

​

delta_flush_interval_ms

通过查询参数控制 agent.message delta 事件的刷新间隔：

GET /sessions/{session_id}/events/stream?delta_flush_interval_ms=100

默认值为 50ms。增大该值可减少事件频率、降低客户端渲染压力。

​

curl 示例

新建连接

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

使用 after_id 续连

curl -N \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  "https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events/stream?after_id=evt_01abc123"

​

JavaScript EventSource 示例

const url = new URL('https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events/stream');
// 如需增量：url.searchParams.set('after_id', lastEventId);

const es = new EventSource(url, {
  headers: { 'Authorization': `Bearer ${QODER_PAT}` }
});

es.addEventListener('agent.message', (e) => {
  const data = JSON.parse(e.data);
  console.log('Agent:', data.content);
});

es.addEventListener('session.status_idle', (e) => {
  const data = JSON.parse(e.data);
  if (data.stop_reason?.type === 'requires_action') {
    console.log('Turn 暂停，请响应:', data.stop_reason.event_ids);
  } else {
    console.log('轮次完成，等待下一轮输入');
  }
});

es.addEventListener('session.error', (e) => {
  const data = JSON.parse(e.data);
  console.error('错误:', data.error);
  es.close();
});

es.onerror = () => {
  console.warn('连接断开，浏览器将自动重连');
};

​

客户端实现建议

1. 记录 last event id —— 每收到事件就更新，用于重连恢复。
2. 处理 delta 拼接 —— agent.message 可能以流式 delta 到达，客户端需拼接为完整文本。
3. 监听 terminated —— 收到后主动关闭连接，不再重连。
4. 超时重试 —— 若 30 秒无事件，主动断开并重连（避免静默断连）。
5. 过滤事件 —— 仅监听业务关心的事件类型，忽略 span 级别事件可减少处理开销。

​

常见问题

Q：连接后收到大量历史事件怎么办？ A：传入 after_id 参数，指向最后处理过的事件 ID，服务端只返回该 ID 之后的事件。

Q：SSE 连接会自动关闭吗？ A：Session 终止时服务端发送 terminated 事件后关闭连接。空闲超时由 Session 配置决定。

Q：能否用 WebSocket 替代？ A：当前仅支持 SSE。SSE 对单向推送场景更轻量，且天然支持断线重连。

Q：delta_flush_interval_ms 设太大会丢事件吗？ A：不会丢失，只是批量合并后发送。最终内容完整性不受影响。

​

下一步

启动 Session

管理会话生命周期。

权限策略

控制工具调用是允许、询问还是拒绝。

定义 Outcomes

告诉 Agent 什么样的结果算成功。

Agent 工具

为 Agent 配备内置、MCP 和自定义工具。