SSE 與事件

即時串流事件與 DOM 互動協議。

在 Agent 執行期間，伺服器透過 Server-Sent Events (SSE) 串流事件給客戶端。本頁涵蓋所有事件類型、DOM 互動的 Action Request 協議，以及用於視覺理解的 Page State。

SSE 事件參考

SSEEvent 聯合型別

SSEEvent

type SSEEvent =
  | SSETextEvent
  | SSEToolCallEvent
  | SSEToolResultEvent
  | SSEActionRequestEvent
  | SSEErrorEvent
  | SSEDoneEvent;

事件類型

text — 串流文字 token。欄位：content: string
tool_call — Agent 正在呼叫工具。欄位：name: string、parameters: Record<string, any>
tool_result — 工具執行完成。欄位：name: string、result: ToolResult
action_request — 伺服器請求客戶端執行 DOM 動作。欄位：correlationId、action、parameters
error — 發生錯誤。欄位：error: string、fatal: boolean
done — Agent 執行完成。無欄位。

事件介面

介面

interface SSETextEvent {
  type: 'text';
  content: string;
}

interface SSEToolCallEvent {
  type: 'tool_call';
  name: string;                    // 工具名稱
  parameters: Record<string, any>; // 工具參數
}

interface SSEToolResultEvent {
  type: 'tool_result';
  name: string;                    // 工具名稱
  result: ToolResult;              // { success, result?, error? }
}

interface SSEActionRequestEvent {
  type: 'action_request';
  correlationId: string;           // 用於配對請求/結果的唯一 ID
  action: string;                  // 'click', 'scroll', 'navigate' 等
  parameters: Record<string, any>;
}

interface SSEErrorEvent {
  type: 'error';
  error: string;
  fatal: boolean;                  // 若為 true，Agent 停止執行
}

interface SSEDoneEvent {
  type: 'done';
}

在 onEvent 中處理事件

事件處理

useLensAgent({
  endpoint: '/api/lens/agent/chat',
  onEvent: (event) => {
    switch (event.type) {
      case 'text':
        // 串流文字 — messages 狀態會自動更新
        break;

      case 'tool_call':
        console.log(`呼叫工具: ${event.name}`, event.parameters);
        // 顯示此工具的「載入中」UI
        break;

      case 'tool_result':
        console.log(`工具結果: ${event.name}`, event.result);
        // 更新工具卡片為「已完成」
        break;

      case 'action_request':
        // 由 hook 自動處理（DOM 動作）
        break;

      case 'error':
        console.error(event.error);
        if (event.fatal) {
          // Agent 已停止 — 向用戶顯示錯誤
        }
        break;

      case 'done':
        // Agent 完成 — 如需要可進行清理
        break;
    }
  },AI 代理
});