Agent 前端交互：工具调用的可视化与中断恢复机制

一、黑箱里的多步推理：Agent 执行过程的前端可观测性缺口

大模型 Agent 的典型执行是"思考—调用工具—观察结果—再思考"的多步循环。一次任务可能连续调用五到十次工具：查数据库、检索文档、执行代码、请求第三方 API。后端在循环里忙碌，前端却往往只显示一个"思考中..."的转圈动画，用户对中间步骤一无所知。

这种黑箱带来三个生产级问题。第一是信任缺口，用户看不到 Agent 调用了哪些工具、传了什么参数、拿到了什么结果，自然无法判断答案是否可靠。第二是失败成本高，Agent 在第七步工具调用失败时，整个任务从头重跑，前六步的成果全部作废，token 与时间成本翻倍。第三是无法干预，用户发现 Agent 走错方向时只能干等它跑完，无法在中途打断或修正。

前端在 Agent 链路里的职责正是填补这个可观测性缺口。把每一步工具调用可视化成可审查的卡片，把执行状态做成可中断的状态机，把中间结果持久化成可恢复的检查点，才能让 Agent 从"一次性黑箱"变成"可观测、可干预、可恢复"的工程系统。这不是锦上添花的 UI 美化，而是 Agent 能否进入生产的核心基础设施。

二、事件流与检查点：Agent 执行状态的可视化建模

Agent 执行的本质是一个事件流。后端每完成一步就推送一个事件，前端消费事件并驱动 UI 状态机演进。下面这张图描述了从后端事件到前端状态再到检查点持久化的完整链路。

[Agent 后端执行循环]
        |
        v  (SSE 事件流)
[事件分发器] --> thought: 思考文本
        |      --> tool_call: 工具名 + 参数
        |      --> tool_result: 返回值 + 耗时
        |      --> error / done
        v
[前端状态机] --> steps[]: 有序步骤列表
        |      --> status: running | paused | done | error
        v
[检查点持久化] --> IndexedDB: 按 runId 存全量 steps
        |       --> 支持中断后按 runId + stepIndex 续跑
        v
[恢复控制器] --> 读取检查点 --> 向后端发送 resume(runId, fromStep)

事件流的核心设计是"事件即状态"。前端不维护独立的业务状态，所有状态由事件驱动产生。每条事件携带 runId（运行实例）、stepIndex（步骤序号）、type（事件类型）与 payload。前端按 stepIndex 有序写入步骤列表，任何乱序事件都通过序号重排而非直接追加。

下表列出事件类型与前端状态映射。

检查点持久化是中断恢复的基础。每收到一个事件，前端就把当前 steps 全量写入 IndexedDB，键为 runId。中断后用户重新打开页面，前端读取检查点恢复 UI，并向后端发送 resume(runId, fromStep) 请求从指定步骤续跑，而非从头开始。这个机制把"失败重跑"变成"断点续传"，是 Agent 进入生产的关键能力。

三、事件驱动渲染与断点恢复：生产级 Agent UI 实现

下面是一段 TypeScript 实现，封装了 Agent 事件流消费、状态机演进、检查点持久化与中断恢复。它处理了事件乱序、断连重试、幂等写入与超时。

import { useEffect, useReducer, useRef } from "react";

// 事件结构: 后端推送, 前端只消费不修改
interface AgentEvent {
  runId: string;
  stepIndex: number;
  type: "thought" | "tool_call" | "tool_result" | "error" | "done";
  payload: Record<string, unknown>;
  ts: number;
}

interface Step {
  index: number;
  type: AgentEvent["type"];
  status: "running" | "done" | "error";
  data: Record<string, unknown>;
}

interface AgentState {
  runId: string | null;
  status: "idle" | "running" | "paused" | "done" | "error";
  steps: Step[];
}

// 状态机: 事件驱动, 纯函数 reducer 保证可重放
// 之所以用 reducer 而非 setState 散写, 是为了让状态变更可追溯可重放
function reducer(state: AgentState, event: AgentEvent): AgentState {
  if (state.runId !== event.runId) {
    // 新 runId 到来时重置状态, 避免跨任务串扰
    state = { runId: event.runId, status: "running", steps: [] };
  }
  // 幂等: 同 stepIndex 重复事件直接丢弃, 防止断连重连后重复渲染
  if (state.steps.some((s) => s.index === event.stepIndex && s.type === event.type)) {
    return state;
  }
  const step: Step = {
    index: event.stepIndex,
    type: event.type,
    status: event.type === "error" ? "error" : event.type === "done" ? "done" : "running",
    data: event.payload,
  };
  // 按 stepIndex 有序插入, 处理乱序到达
  const steps = [...state.steps, step].sort((a, b) => a.index - b.index);
  let status = state.status;
  if (event.type === "error") status = "error";
  else if (event.type === "done") status = "done";
  return { ...state, steps, status };
}

// IndexedDB 检查点: 每个 runId 一份全量快照, 支持中断恢复
// 用 IndexedDB 而非 localStorage, 因为 steps 可能含大体量 tool_result
async function saveCheckpoint(state: AgentState): Promise<void> {
  if (!state.runId) return;
  const db = await openDB("agent-ui", 1);
  await db.put("checkpoints", state, state.runId);
}

function openDB(name: string, version: number): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open(name, version);
    req.onupgradeneeded = () => {
      req.result.createObjectStore("checkpoints", { keyPath: "runId" });
    };
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

// SSE 消费: 自动重连, 重连后从最后 stepIndex 续传
export function useAgentRun(runId: string | null) {
  const [state, dispatch] = useReducer(reducer, {
    runId: null, status: "idle", steps: [],
  });
  const lastStepRef = useRef(0);

  useEffect(() => {
    if (!runId) return;
    const ctrl = new AbortController();

    const connect = (fromStep: number) => {
      // 服务端约定: ?fromStep=N 表示从第 N 步续传
      const url = `/api/agent/run/${runId}/events?fromStep=${fromStep}`;
      const es = new EventSource(url);
      es.onmessage = (e) => {
        try {
          const event: AgentEvent = JSON.parse(e.data);
          dispatch(event);
          lastStepRef.current = Math.max(lastStepRef.current, event.stepIndex);
          saveCheckpoint({ runId: event.runId, status: "running", steps: [] }).catch(console.error);
        } catch (err) {
          console.error("[agent] event parse failed:", err);
        }
      };
      es.onerror = () => {
        es.close();
        // 指数退避重连, 上限 10 秒, 避免风暴
        const delay = Math.min(1000 * 2 ** retryCount.current, 10_000);
        retryCount.current += 1;
        retryTimer = window.setTimeout(() => connect(lastStepRef.current), delay);
      };
    };

    let retryTimer: number;
    const retryCount = { current: 0 };
    connect(0);
    return () => {
      ctrl.abort();
      clearTimeout(retryTimer);
    };
  }, [runId]);

  return state;
}

这段代码的关键契约：状态机用纯函数 reducer 实现，保证事件可重放、状态可追溯；事件按 stepIndex 有序插入并做幂等去重，断连重连后重复事件被丢弃而非重复渲染；检查点写 IndexedDB 而非 localStorage，因为 tool_result 可能含大体量数据；SSE 断连用指数退避重连，从最后 stepIndex 续传而非从头。

生产环境还需处理三件事：一是恢复时先读 IndexedDB 检查点立即渲染历史步骤，再建立 SSE 连接，避免空白闪烁；二是用户主动中断时调用 abort() 并把状态置为 paused，后端收到断开信号后停止后续工具调用；三是工具参数与结果可能含敏感信息，前端展示前需做脱敏。下表列出常见故障与应对。

四、状态膨胀、恢复一致性与 UI 抖动的代价

检查点持久化的首要代价是存储膨胀。每个事件都全量写 IndexedDB，一个长任务可能产生数百个事件，累积体积可达数 MB。多个 runId 堆积后，IndexedDB 配额会被撑爆。必须为检查点设 TTL（如 7 天）与单任务上限（如 50 步后只存摘要），并定期清理过期 run。把检查点当成"永久日志"会很快拖垮前端存储。

恢复一致性是更深的代价。断点续传要求后端工具调用具备幂等性：同一个 tool_call 重放一次与重放两次结果必须一致。但现实中很多工具不幂等——发邮件、扣款、写入数据库。前端恢复时无法判断某个 tool_call 是否已实际执行，只能把"是否重放"的决策交给后端，前端只负责把检查点里的步骤重放给用户看。这意味着中断恢复对非幂等工具存在语义风险，不能无脑启用。

UI 抖动是用户体验侧的代价。事件流式到达时，步骤卡片频繁追加会导致页面持续滚动，用户正在阅读的中间步骤会被新步骤顶下去。需要做两件事：一是自动滚动只发生在用户未手动滚动时（通过 scroll 事件判断）；二是步骤卡片高度固定，避免内容异步加载导致高度跳变。流式 UI 的"稳定感"是工程出来的，不是天然的。

禁用场景需要明确。对工具调用强非幂等且不可补偿的 Agent（如金融交易、 irreversible 写操作），中断恢复的语义风险过高，应禁用续传改为"失败即重跑"。对超长任务（数千步），检查点全量写入成本不可接受，应改为采样持久化。对实时性要求极高的对话型 Agent，逐事件渲染的开销不划算，应聚合后批量更新。中断恢复适合"工具幂等或可补偿、任务步数中等、用户有断点续跑需求"的场景。

五、总结

Agent 前端工具调用可视化的核心，是把后端多步执行建模成"事件流驱动状态机、检查点支撑中断恢复"的双层结构。事件按 stepIndex 有序写入并做幂等去重，检查点全量持久化到 IndexedDB 支持断点续传，SSE 断连用指数退避重连并从最后 stepIndex 续传。工程落地的关键步骤包括：用纯函数 reducer 保证状态可重放，恢复时先读检查点再建 SSE 避免空白闪烁，用户主动中断时 abort 并置 paused 态，敏感信息展示前脱敏。该机制的代价是检查点存储膨胀需设 TTL 与上限、非幂等工具的恢复存在语义风险、流式 UI 需工程化处理抖动；适合工具幂等、任务步数中等、用户有续跑需求的中长任务场景，不适合强非幂等工具或超长任务。