LLM/Agent SSE流式全量事件（含 start / step_node / tool_start / tool_end / delta）

这套是SSE流式推送、Agent工作流、模型推理通用事件标识，分为5大类：全局生命周期、步骤节点、工具调用、流式增量delta、结束/异常事件，每个事件详细作用、场景、前后顺序全部整理。

一、全局生命周期事件（整轮对话/任务总流程）

1. start（agent_start / run_start）

含义：一轮完整问答/Agent任务全局启动事件
触发时机：用户发送提问、服务端初始化会话后第一条SSE事件
携带数据：runId、会话ID、用户原始输入、全局上下文、计时起点
核心作用

1. 前端初始化对话画布、清空旧缓存；
2. 日志埋点：记录本次任务开始时间、请求入参；
3. 全局权限校验、限流、初始化记忆/向量库；
4. 标记整条SSE流正式开启。
   示例链路起点：start → step_node

2. end / finish / agent_done / run_finish

含义：整轮任务正常结束
触发时机：模型输出完整答案、无更多工具调用循环
携带数据：完整回答文本、token消耗、全链路耗时、工具调用记录
作用

1. 前端停止打字机流式渲染；
2. 后端落库完整对话记录、统计指标；
3. 关闭SSE连接或等待下一轮用户输入。

3. error / agent_error / run_error

含义：任务异常终止（致命错误，不再继续执行）
触发场景：模型超时、工具调用报错、权限不足、上下文超限、服务崩溃
携带：错误码、报错信息、失败步骤位置
作用：前端展示错误提示、日志告警、中断流程。

二、步骤节点类事件（step_node 系列，中间推理子流程）

1. step_node / step_start / StepStarted

含义：单步推理/子任务节点开始（思维链、判断、分支、反思都属于step_node）
触发时机

• 模型开始思考要不要调用工具；
• 工具返回结果后，模型二次整合答案；
• 多分支工作流进入某一个判断分支；
• 循环Agent每一轮思考规划。
  携带：step序号、步骤类型（thinking/planning/reflect）、当前上下文快照
  作用

1. 前端可视化流程步骤（时间线/流程图展示“正在思考”）；
2. 分段统计每一步耗时，定位卡顿节点；
3. 调试：区分“模型纯推理”和“工具执行”两个阶段。

2. step_end / step_finish / StepFinished

含义：当前单步推理执行完毕
携带：该步骤完整输出、分支选择结果、是否要继续调用工具标记
作用：标记当前步骤结束，流转到下一个step_node或tool流程。

三、工具调用完整事件（tool_start ↔ tool_end 成对出现）

1. tool_start / tool_call_start

含义：即将发起外部工具调用
触发时机：模型输出tool_call指令，准备调用搜索/计算器/数据库/接口
携带：工具名称、toolCallId、流式生成的参数片段、调用来源stepId
作用

1. 前端展示“正在调用XX工具”加载状态；
2. 安全校验：拦截高危工具、脱敏入参；
3. 记录工具调用起始时间，统计耗时。

2. tool_delta / tool_input_delta

补充delta类：模型流式生成工具入参JSON片段（边输出边推送）
比如模型一边输出{"query":"今天北京天气"，分段推送delta增量，前端拼接完整参数。

3. tool_end / tool_call_end / tool_result

含义：工具执行完成，返回结果/报错
携带：工具完整返回数据、接口响应码、耗时、异常信息（超时/403/无数据）
作用

1. 前端展示工具返回卡片（搜索结果、计算结果）；
2. 清洗工具输出，格式化后喂给大模型继续推理；
3. 失败重试判断：如果tool_end报错，回到step_node重新思考换工具。

四、delta 增量流式事件

核心定义：delta = 增量片段，SSE流式输出的最小数据块

模型不会一次性返回完整文本，而是逐token分段推送，每一段就是一条delta事件。
细分3种常用delta：

1. delta / text_delta / model_text_delta

含义：模型主回答文本增量（最终答案打字机效果）
触发：模型生成回复文字时持续推送，一条delta=几个字/一个token
数据示例：{"delta":"今天北京气温25℃，晴"}
前端作用：不断append追加到对话气泡，实现打字机实时输出。

2. thinking_delta / reasoning_delta

含义：模型思维链/内部思考过程增量（深度思考、CoT推理文本）
很多Agent会先输出思考内容，再输出正式答案，思考内容单独走thinking_delta。

3. tool_input_delta / content_block_delta

含义：工具调用参数JSON增量
模型生成tool_call的入参是流式的，分段推送JSON片段，前端拼接完整参数传给工具。

delta通用特点

1. 多条连续出现，无固定数量；
2. 必须持续累加拼接，不能单条独立展示；
3. 仅在step_node内部、模型生成阶段触发；
4. 所有delta结束后会触发step_end标记本段生成完成。

五、完整标准执行链路（串联所有事件）

场景1：纯文本回答（不调用工具）

start
→ step_node（step_start，模型开始思考）
→ 多条 text_delta（持续输出文字）
→ step_end（本段推理结束）
→ end（整轮任务完成）

场景2：需要调用工具的Agent完整流程

start
→ step_node（step_start：模型判断需要查天气）
→ tool_start（准备调用天气工具）
→ 多条 tool_input_delta（流式生成城市参数）
→ tool_end（工具返回温度结果）
→ step_node（step_start：模型整合工具结果写答案）
→ 多条 text_delta（输出最终回答）
→ step_end
→ end

异常链路示例

start
→ step_node
→ tool_start
→ tool_end（携带timeout报错）
→ error（任务终止）

六、所有事件汇总对照表

事件标识	大类	核心含义	核心用途
start / agent_start	全局生命周期	整轮任务启动	初始化会话、计时、前端重置界面
end / agent_done	全局生命周期	任务正常结束	落库、停止流式渲染、统计指标
error / run_error	全局生命周期	任务致命异常	弹窗报错、日志告警、中断流程
step_node / step_start	步骤节点	单步推理/子任务开始	流程可视化、分段耗时统计
step_end / step_finish	步骤节点	单步推理完成	切换下一流程分支
tool_start / tool_call_start	工具调用	准备调用外部工具	展示工具加载、校验入参
tool_input_delta	Delta增量	工具参数流式片段	拼接完整工具入参JSON
tool_end / tool_result	工具调用	工具执行结束返回数据	展示工具结果、回填模型上下文
delta / text_delta	Delta增量	回答文本增量token	前端打字机实时输出答案
thinking_delta	Delta增量	模型思维链增量	展示思考过程、深度推理日志

七、关键区分易混点

1. delta不是独立“流程节点”，是流式数据片段
   start/step_node/tool_start是流程阶段标记（只发一次）；delta是持续多条的增量内容，依附在step_node内部产生。
2. step_node 是通用容器
   思考、规划、工具后复盘都属于step_node，工具调用是step_node内部的子流程。
3. tool_start 和 tool_end 严格成对
   一个tool_start必然对应一条tool_end，中间穿插tool_input_delta；
4. 所有delta只会出现在两个节点之间：step_start → step_end 区间内。