social-app/docs/protocols/agent/sse-events.md

Agent SSE Events

本文档描述 GET /api/v1/agent/runs/{thread_id}/events 的事件协议。

---

1) 事件管道

后端事件流转如下：

1. Runtime 直接产出 AG-UI 事件（如 RUN_STARTED、TOOL_CALL_RESULT）
2. agui_codec 仅做协议对齐与字段净化（例如移除仅后端内部统计字段）
3. 事件同时：
   • 持久化到数据库（用于 history）
   • 发布到 Redis Stream（用于 SSE）
4. /runs/{thread_id}/events 从 Redis Stream 读取并输出 SSE

---

2) SSE 帧格式

每条事件遵循标准 SSE：

id: <redis-stream-id>
event: <AG-UI-EVENT-TYPE>
data: <json>

• id 可用于断点续流（Last-Event-ID）
• event 与 JSON 内 type 一致（例如 RUN_STARTED）
• 空闲时可能出现 keep-alive 注释帧：

: keep-alive

---

3) 事件类型（当前实现）

3.1 Run 生命周期

RUN_STARTED

{
  "type": "RUN_STARTED",
  "threadId": "...",
  "runId": "..."
}

RUN_FINISHED

{
  "type": "RUN_FINISHED",
  "threadId": "...",
  "runId": "..."
}

RUN_ERROR

{
  "type": "RUN_ERROR",
  "threadId": "...",
  "runId": "...",
  "message": "runtime execution failed",
  "code": null
}

3.2 阶段事件

STEP_STARTED

{
  "type": "STEP_STARTED",
  "threadId": "...",
  "runId": "...",
  "stepName": "router" | "worker"
}

STEP_FINISHED

{
  "type": "STEP_FINISHED",
  "threadId": "...",
  "runId": "...",
  "stepName": "router" | "worker"
}

3.3 Tool 事件

TOOL_CALL_START

{
  "type": "TOOL_CALL_START",
  "threadId": "...",
  "runId": "...",
  "messageId": "...",
  "toolCallId": "...",
  "toolCallName": "...",
  "stage": "worker"
}

TOOL_CALL_ARGS

{
  "type": "TOOL_CALL_ARGS",
  "threadId": "...",
  "runId": "...",
  "messageId": "...",
  "toolCallId": "...",
  "toolCallName": "...",
  "args": {},
  "stage": "worker"
}

TOOL_CALL_END

{
  "type": "TOOL_CALL_END",
  "threadId": "...",
  "runId": "...",
  "messageId": "...",
  "toolCallId": "...",
  "toolCallName": "...",
  "stage": "worker"
}

TOOL_CALL_RESULT

{
  "type": "TOOL_CALL_RESULT",
  "threadId": "...",
  "runId": "...",
  "messageId": "...",
  "role": "tool",
  "stage": "worker",
  "tool_name": "...",
  "tool_call_id": "...",
  "tool_call_args": {},
  "status": "success" | "failure" | "partial",
  "result": "...",
  "error": null
}

说明：TOOL_CALL_RESULT 不再携带 ui_schema。tool 结果通过 result 字段提供紧凑、结构化、可执行的信息（优先包含 id/status/count 等关键事实），用于 agent 后续推理与工具编排。

补充约束：

• tool_call_id 必须与同次调用的 TOOL_CALL_START/ARGS/END.toolCallId 一致，并在每次工具调用中保持唯一。
• tool_call_args 仅表示输入参数快照。
• result 仅表示执行输出事实，不重复 tool_call_args 已包含的输入参数。

3.4 文本完成事件

TEXT_MESSAGE_END

当前实现仅在 worker 输出完成后发送完整结果，不发送 token delta 事件。

{
  "type": "TEXT_MESSAGE_END",
  "threadId": "...",
  "runId": "...",
  "messageId": "...",
  "role": "assistant",
  "stage": "worker",
  "status": "success" | "partial_success" | "failed",
  "answer": "...",
  "key_points": [],
  "result_type": "execution_report" | "clarification" | "error_report" | "unknown",
  "suggested_actions": [],
  "error": null,
  "ui_schema": {}
}

inputTokens、outputTokens、cost、latencyMs、model 属于后端内部统计字段，不在 SSE 对外协议中暴露。

3.5 快照事件

编码器支持以下 AG-UI 类型映射：

• STATE_SNAPSHOT
• MESSAGES_SNAPSHOT

当前 /runs/{thread_id}/events 主流程通常不主动产出这两类事件；历史查询请使用 /history。

---

4) 字段命名约定

• 事件顶层通用字段使用 AG-UI 风格：type、threadId、runId
• 部分业务字段沿运行时模型历史命名保留下划线：
  • tool_name
  • tool_call_id
  • tool_call_args
  • ui_schema

这部分命名属于当前后端实现约束，文档与实现保持一致。