[!info] related notes

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

Event Envelope

一句话定义

Event Envelope 是 SSE 事件的统一包装格式。每个事件都有相同的顶层结构：event（类型）、data（数据）、meta（元数据），让前端可以用统一的方式解析所有事件。

核心原理

Envelope 结构

{
  "event": "text_delta",
  "data": {
    "delta": "你好"
  },
  "meta": {
    "run_id": "run_001",
    "sequence": 1,
    "timestamp": 1719700000
  }
}

TypeScript 类型定义

interface EventEnvelope<T = any> {
  event: string;
  data: T;
  meta: {
    run_id: string;
    sequence: number;
    timestamp: number;
  };
}

// 具体事件类型
type TextDeltaEvent = EventEnvelope<{ delta: string }>;
type ToolCallStartEvent = EventEnvelope<{ tool_call_id: string; tool_name: string }>;
type DoneEvent = EventEnvelope<{ total_tokens: number }>;

SSE 格式

event: text_delta
data: {"delta": "你好", "meta": {"run_id": "run_001", "sequence": 1}}

event: tool_call_start
data: {"tool_call_id": "tc_001", "tool_name": "search", "meta": {"run_id": "run_001", "sequence": 2}}

常见坑

1. 事件格式不统一: 有的事件有 meta，有的没有
2. data 类型不固定: 同一个事件的 data 结构不一致
3. 不做类型检查: 前端解析时不做类型校验

参考资料

• Event Contract
• Event Type