[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Event Envelope, 事件契约

Event Type

一句话定义

Event Type 是 SSE 事件的类型标识。前端根据 event type 决定如何处理数据——text_delta 追加文本，tool_call_start 显示工具卡片，done 结束流。

核心原理

事件类型体系

类型	触发时机	data 结构
text_delta	LLM 产生 token	{delta: string}
tool_call_start	开始调用工具	{tool_call_id, tool_name, arguments}
tool_call_delta	工具参数增量	{tool_call_id, delta}
tool_call_result	工具执行完成	{tool_call_id, result, duration_ms}
progress	进度更新	{message, step, total}
interrupt	需要审批	{interrupt_id, type, message}
error	发生错误	{code, message, recoverable}
done	完成	{total_tokens, duration_ms}
heartbeat	心跳	{}

前端处理

const handlers: Record<string, (data: any) => void> = {
  text_delta: (data) => appendText(data.delta),
  tool_call_start: (data) => addToolCallCard(data),
  tool_call_result: (data) => updateToolCallCard(data),
  interrupt: (data) => showApprovalDialog(data),
  error: (data) => showError(data),
  done: (data) => finishStream(data),
  heartbeat: () => {}, // 忽略
};

function handleEvent(event: EventEnvelope) {
  const handler = handlers[event.event];
  if (handler) {
    handler(event.data);
  }
}

常见坑

1. 事件类型不够用: 新增功能时没有对应的类型
2. 类型名不规范: 有的用 snake_case，有的用 camelCase
3. 不处理未知事件: 前端遇到未知 event type 应该忽略而不是报错

参考资料

• Event Envelope
• Event Contract