切换主题
事件协议与流式消费
所有事件使用版本 1.0 信封。HTTP 接口与事件协议分别版本化，客户端需要检查 protocolVersion 和事件序号。
信封
json
{
"protocolVersion":"1.0","event":"text.delta","runId":"run_example",
"traceId":"trace_example","conversationId":"conversation_example",
"messageId":"message_example","sequence":2,"data":{"text":"你好"}
}sequence 从 1 递增，唯一性在单个 Run 内。SSE 使用 id: runId:sequence、event: 事件名 和 data: 完整JSON信封，空行结束一帧，: heartbeat 是心跳注释。
事件与字段
| event | data | 消费方式 |
|---|---|---|
| message.started | status | 建立当前回复 |
| status.changed | status | 替换当前状态 |
| text.delta | text | 按序追加文本 |
| agent.started | agentCallId、parentAgentCallId、depth、agentId、agentVersion | 显示执行步骤 |
| agent.completed | 上述调用标识、status、result（成功）、usage/errorCode（失败） | 保存类型化调用结果，子完成不等于任务终态 |
| model.started | invocationId、stepId、attempt、binding、model、selectionReason、Agent 调用关系 | 显示当前模型尝试 |
| model.completed | 上述标识、status、errorCode、outputStarted、usage、cost | 更新该尝试；FAILED/SKIPPED 不等于聊天终态 |
| tool.started | callId、toolId、version、effect | 显示工具进度 |
| tool.completed | callId、toolId、status | 更新工具结果状态 |
| knowledge.retrieved | knowledgeId、count | 记录检索信息 |
| citation.created | id、documentId、title、source、knowledgeId | 显示引用 |
| ui.created | component、version、props | 调用可信前端 Renderer |
| confirmation.required | confirmationId、toolId、version、arguments、argumentsHash、expiresAt | 请求用户批准或拒绝 |
| usage.updated | budgetUnits、steps、toolCalls、agentCalls、scopeUsage、providerUsage、cost | 覆盖累计快照 |
| error | code、message、retryable | 显示错误，等待终态 |
| message.completed | status | 终结当前回复，逻辑仅一条 |
providerUsage 含 prompt_tokens、completion_tokens、total_tokens，不完整项为 null。cost 为 null 或 {source:"configured-pricing",amounts:{USD:"0.001"}}，金额为十进制字符串。
订阅与恢复
bash
curl -N "$SPARKTIDE_BASE_URL/v1/apps/customer-service/runs/$RUN_ID/events" \
-H "Authorization: Bearer $SPARKTIDE_USER_TOKEN" \
-H 'Accept: text/event-stream' \
-H "Last-Event-ID: $RUN_ID:0"保存最后成功处理的 sequence，断线后从该序号恢复，丢弃重复事件。序号跳跃应报错或重新同步，不静默拼接残缺回答。
事件超出访问窗口或游标无效返回 410。断开网络不取消任务；终态后可以读取尚在窗口内的历史事件。对于已读到终态的游标，订阅可能没有新事件而正常结束。
前端显示原则
text.delta 在 Provider.stream=true 且供应商支持时逐帧到达，否则模型整轮完成后分块到达。不要以“能接收 SSE”推断供应商原生流式已经开启。错误事件与 HTTP 请求错误分别处理；收到 error 后仍处理 message.completed。
模型事件属于协议 1.0 增量能力，旧客户端可保留或忽略。RESPONDED 只表示收到响应，最终校验仍可失败；SKIPPED 表示没有发出请求，不伴随 started。使用 message.completed 判断聊天终态，不因单次候选失败重新发送聊天。详见模型接入。
成功结果包含经过输出 Schema 校验的 TEXT/JSON、精确 Agent 版本、调用关系和去重引用；子结果只进入结果记录，主文字仍只追加 text.delta。详见父子结果与 SDK。