🚀🚀【封闭结束5】Agent 长任务怎么跑稳?SSE 流式推送与 HITL 暂停恢复实战

442 阅读17分钟

前言:封闭告一段落,开始系统复盘:一个生产 Agent 到底怎么跑起来。踩坑、经验和落地,尽量用几篇文章讲清,这篇文章是系列第5篇:
Agent 一旦进入生产环境,问题往往不再是「模型能不能回答」,而是任务跑了很久,前端却没有反馈;用户点了确认,后台却不知道从哪一步继续;页面断线后,进度丢了,甚至还可能重复执行一次危险操作。
希望这篇文章能给正在做 Agent 落地的朋友一些参考,也欢迎在评论区分享实践和问题。

用户说:「重启这个异常实例。」查到一半,又补了一句:「继续查它。」

对普通聊天来说,这可能只是两句自然语言;但对生产 Agent 来说,系统还得知道「它」指向哪个实例、当前任务执行到哪一步,以及重启前是否需要用户确认。

这篇只讲两件事:一次请求如何把进度持续推给前端,以及用户确认后,如何从正确的断点继续执行。

单轮聊天接口并不复杂。真正接入业务后,下面三类问题通常很快就会出现:

  1. 用户说「继续查它」,系统不知道「它」是谁;
  2. Agent 跑很久,前端长时间没反馈;
  3. 删除、发布、转账必须让人确认,确认后还要从中断处继续。

这三类问题分别对应三个核心能力:多轮状态管理、SSE 流式通信,以及 HITL(Human in the Loop,人在回路)。继续使用虚构案例 OpsPilot(企业运维助手),技术栈仍是 TypeScript;前端可以用 Vue 3 配合 fetch 读取流。

不同场景的侧重点也不一样:

  • 知识问答:重点是文本增量推送、首字响应速度和断线后的结果恢复。
  • 长耗时任务:重点是任务状态持久化、进度查询和前后端连接解耦。
  • 运维、发布与审批:重点是人工确认、权限复核、并发控制和副作用的可靠执行。

如果只是做一个聊天演示,很多细节可以先不考虑;但如果要把 Agent 接进真实业务系统,这些设计迟早都要面对。

Snipaste_2026-10-27_15-57-14.png

一次运行要有自己的状态

不要只把所有内容存成一串聊天文本。至少要区分三类数据(可以是三张表,也可以是三份独立记录),因为它们的生命周期和用途并不相同:

  • 会话(Conversation):左边那一列聊天列表里的一项,比如「排障 - payment-api」。一个人可以有很多个会话。
  • 消息(Message):会话里的每一句:用户说的、助手回的、工具结果,各算一条。
  • 运行(Run):用户点一次发送,后台为这句话开的一次任务(跑模型、调工具、等人确认)。同一会话里可以有很多次 Run。
type Conversation = { // 一次聊天会话(聊天列表里的一项)
  id: string                 // 会话 id
  userId: string             // 属于哪个用户
  createdAt: string          // 创建时间
}

type Message = { // 会话里的一条消息
  id: string                 // 消息 id
  conversationId: string     // 属于哪个会话
  role: 'user' | 'assistant' | 'tool' // 谁说的
  content: string            // 正文(展示 / 写进数据库)
  createdAt: string          // 创建时间
}

type Run = { // 用户点一次发送对应的一次后台运行
  id: string                 // Run id
  conversationId: string     // 落在哪个会话
  userMessageId: string      // 由哪条用户消息触发
  status:                    // 这次运行进行到哪
    | 'running'              // 执行中
    | 'interrupted'          // 等人确认 / 补参
    | 'completed'            // 正常结束
    | 'failed'               // 失败
    | 'cancelled'            // 取消
  checkpoint?: unknown       // 中断后接着跑所需的最小状态
  createdAt: string          // 创建时间
  updatedAt: string          // 状态最后变更时间
}

一次用户请求对应一个 Run。用户确认后,应恢复这次运行,而不是重新发起一轮聊天、再让模型猜之前发生了什么。这样既能保留任务上下文,也能减少重复调用工具的风险。

多轮上下文:让模型听懂“它”,但别把整段历史都塞进去

用户经常会说“继续查它”“刚才那个”。如果每次都把完整聊天记录交给模型,不仅成本更高,还可能让旧信息干扰当前任务。

可以把上下文分成三层:

  1. 已确认的业务事实:结构化 state,例如服务名、环境、实例 ID。只在工具结果经过校验或用户明确确认后更新。
  2. 较早的对话摘要:压缩成一段摘要,控制长度。
  3. 最近几轮原文:保留用户和助手最近说过的话,让模型能够理解“它”“刚才那个”等指代。

其中,state 应尽量来自可信的业务数据源;摘要则是为了压缩历史而生成的辅助信息,不能因为摘要里写了某件事,就把它当成已经确认的事实。

// 1) 已确认事实(挂在会话上)
const state = { service: 'payment-api', env: 'prod' as const }

// 2) 更早对话的摘要
const earlierSummary = '用户在排查生产环境报错;服务名与环境已确认。'

// 3) 最近几句原文(含当前这句「继续查它…」)
const recentMessages = [
  { role: 'user', content: '看下 payment-api 最近的错误' },
  { role: 'assistant', content: '生产环境过去 15 分钟有 12 次 5xx。' },
  { role: 'user', content: '继续查它最近的错误日志' },
]

// 拼装:1+2 → system;3 → 消息列表
const modelInput = [
  {
    role: 'system',
    content:
      `已知事实:${JSON.stringify(state)}\n` +
      `更早摘要:${earlierSummary}\n` +
      `用最近原文理解「它 / 刚才那个」是谁;不要靠关键词硬猜。`,
  },
  ...recentMessages,
]

这只是上下文拼装示例。真实项目还需要处理消息角色、提示词边界、权限过滤、上下文长度和敏感信息脱敏。

先看一条完整链路(SSE + HITL)

以 OpsPilot 为例,用户说:“重启这个异常实例。”

这类操作不应该让模型一提出工具调用就立即执行,而应该拆成两段:先查询并明确操作对象,再等待用户确认;确认通过后,才真正执行重启。

第一段:发消息、看进度、弹出确认

  1. 前端把这句话发给会话服务,同时打开一条 SSE,用来收进度(开始了、正在查、查完了……)。
  2. 后台先跑只读步骤(比如定位是哪个实例),这些进度通过 SSE 推到页面。
  3. 模型提出要调「重启」工具。这时还不执行重启,而是发一条 interrupt 事件:页面弹出确认(风险说明、要重启谁)。
  4. 这次 Run 记成「等人」;这一轮推流可以结束。页面上是确认,不是红字报错。

第二段:用户点确认,从断点接着跑

  1. 用户点「确认」。前端调用恢复接口(带上这次中断的 id、同意/拒绝、以及防双击用的同一把请求键),不是再发一条全新聊天。
  2. 服务端先确认:这个中断还有效、当前用户仍有权限、实例现在还是那个状态;通过后才真正重启。
  3. 执行过程再次用 SSE 推进度(工具开始/结束、最终回答),直到结束。
sequenceDiagram
    participant U as 用户
    participant V as 前端
    participant S as 会话服务
    participant R as Runtime

    U->>V: 重启这个异常实例
    V->>S: 发消息并订 SSE
    S->>R: 开始本次 Run
    S-->>V: 进度:开始 / 正在查询…
    R-->>S: 需要确认(先别重启)
    S-->>V: 弹出确认
    U->>V: 点确认
    V->>S: 调用恢复接口
    S->>R: 再验权限后执行重启
    S-->>V: 进度:重启中 / 最终回答

这里要记住两点:

  • 等待用户确认用 interrupt 表达,这是正常的业务状态,不是执行失败。
  • 用户确认后走恢复接口,继续原来的 Run,不要把它当成新开一轮对话。

另外,事件推送成功不等于状态已经持久化。中断记录、断点和 Run 状态应先可靠保存,再通知前端。否则一旦进程在发送事件后崩溃,页面可能出现确认卡,但后台根本没有可恢复的断点。

Snipaste_2026-10-27_15-57-23.png

SSE、WebSocket 怎么选:不是越复杂越好

SSE(Server-Sent Events)基于 HTTP,由服务端持续向客户端推送事件。

对于“用户发起一次请求,服务端持续返回进度”的场景,SSE 通常比 WebSocket 更简单;如果业务需要高频双向通信或传输二进制数据,再考虑 WebSocket。

对比维度SSEWebSocket
通信方向服务端向客户端推送为主双向通信
接入复杂度通常较低,基于 HTTP需要管理双向消息协议与连接生命周期
事件格式有标准的事件流格式消息格式由应用自行定义
自动重连原生 EventSource 支持通常需要应用自行实现重连策略
断线补发需要服务端支持事件重放同样需要应用层设计
更适合的场景Agent 文本输出、工具进度、任务状态实时协作、高频双向交互、双向控制

这里最重要的不是“哪个性能更高”,而是通信模式是否符合业务需求。

如果 Agent 主要向页面输出文本、工具状态和确认事件,SSE 往往就够了。如果前端需要频繁向服务端发送控制消息,或者系统本身就是高频双向实时交互,再考虑 WebSocket。

性能也不能只看协议名称。实际表现还受连接数量、事件大小、发送频率、代理缓冲、服务端资源占用和消息处理逻辑影响。不要在没有压测数据的情况下,直接下结论说某个方案一定更快。

事件协议:让前端明确知道发生了什么

有些编排框架推送的不是“刚发生的那一步”,而是“截至目前的完整状态”。例如每次更新都把整个步骤列表重新发一遍。

如果直接把这些状态全部转成前端事件,同一个工具步骤可能重复显示。因此,需要比较前后状态,或者根据稳定的步骤 ID、调用 ID 去重,只把真正新增的步骤转换成 tool_started 等业务事件。

建议先约定一组稳定的业务事件:

  • run_started:任务开始。
  • text_delta:助手文本增量。
  • tool_started:工具开始执行。
  • tool_finished:工具执行结束。
  • interrupt:任务暂停,等待用户确认或补充信息。
  • done:任务正常结束。
  • error:任务执行失败。

协议上有几个注意点:

  • 编码使用 UTF-8,响应类型为 text/event-stream; charset=utf-8。
  • 每条业务事件建议带一个本 Run 内递增的 sequence,用于去重和后续进度恢复。
  • sequence 是业务 JSON 中的字段,不等于 SSE 协议自带的 id: 字段。
  • 事件中的文本、参数摘要和错误信息应经过必要的脱敏,不要直接暴露访问令牌、内部堆栈或完整工具结果。
import type { ServerResponse } from 'node:http'

type StreamEvent =
  | {
      type: 'run_started'
      runId: string
      sequence: number // 本 Run 内 1,2,3…;防重复渲染,以后也可按号把没收到的进度拉回来
    }
  | {
      type: 'text_delta'
      runId: string
      sequence: number
      delta: string // 增量字,不是全量覆盖
    }
  | {
      type: 'tool_started'
      runId: string
      sequence: number
      callId: string // 与 tool_finished 配对
      tool: string // 工具名,步骤条展示
    }
  | {
      type: 'tool_finished'
      runId: string
      sequence: number
      callId: string
      tool: string
      status: 'success' | 'error'
      summary?: string // 给前端的短摘要,不是原始大结果
    }
  | {
      type: 'interrupt'
      runId: string
      sequence: number
      interruptId: string // resume 时原样带回
      payload: unknown // 确认:风险说明、参数摘要等(已脱敏)
    }
  | {
      type: 'done'
      runId: string
      sequence: number
      messageId: string // 已写入数据库的助手消息 id
    }
  | {
      type: 'error'
      runId: string
      sequence: number
      code: string
      message: string // 可展示给用户;不要堆栈
    }

// 片段:在已创建 Run、准备推流的路由里调用(res 是 Node/Express 响应,不是 fetch Response)
function openSse(res: ServerResponse) {
  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8')
  res.setHeader('Cache-Control', 'no-cache, no-transform')
  res.setHeader('X-Accel-Buffering', 'no') // 仅 nginx;不用可省略
  res.flushHeaders()
}

function sendEvent(res: ServerResponse, event: StreamEvent) {
  // 一条 SSE 消息:event 行 + data 行 + 空行结束
  res.write(`event: ${event.type}\n`)
  res.write(`data: ${JSON.stringify(event)}\n\n`)
}

// 需要等人时:先把 interrupt 和 Run=interrupted 写进数据库,再推事件(示意)
function emitInterrupt(
  res: ServerResponse,
  runId: string,
  sequence: number,
  interrupt: { id: string; payload: unknown }
) {
  sendEvent(res, {
    type: 'interrupt',
    runId,
    sequence,
    interruptId: interrupt.id,
    payload: interrupt.payload
  })
  // 随后可以 res.end() 结束本轮流;用户确认走 POST resume,不必占用同一条长连接
}

事件类型应表达明确的业务含义。不要让前端解析模型输出的自然语言,再猜测“现在是不是正在调用工具”。模型文本面向用户,业务事件面向程序,两者职责不同。

还有一点:如果改用浏览器原生 EventSource,带有 event: 字段的命名事件不会进入 onmessage,需要通过 addEventListener('事件名', ...) 监听。本文使用 fetch 自己解析 SSE 时,则可以直接从 JSON 的 type 字段分发事件,两种处理方式不要混淆。

前端怎么读流、怎么接到 interrupt

原生 EventSource 只能发起 GET 请求,不能像普通 fetch 那样带请求体和任意自定义请求头。因此,如果聊天接口需要 POST 请求体,可以使用 fetch 读取响应流。

两种客户端方式各有取舍:

方案优点需要注意的地方
EventSource浏览器负责 SSE 解析;支持自动重连和 Last-Event-ID请求方式和请求头受限;服务端仍需实现事件重放
fetch + ReadableStream支持 POST 请求体、自定义请求头,适合聊天接口需要自己解析事件、处理异常和设计重连
先 POST 创建 Run,再用 EventSource 订阅创建任务与订阅进度职责清晰多一次请求;需要设计 Run ID、订阅鉴权和恢复协议

如果采用“先 POST 创建 Run,再订阅 SSE”的方式,通常更容易把任务生命周期与连接生命周期分开。若第一版追求简单,也可以直接使用 POST + fetch,但要明确它不自带断线恢复能力。

为什么需要 buffer?因为网络一次读取到的数据不一定对应一条完整事件,可能只有半条,也可能包含多条;而且 UTF-8 字符、换行符和事件边界都有可能跨越读取块。

下面给出一个用于演示的解析骨架:

// 可运行骨架:POST 聊天并解析 SSE
async function streamChat(
  body: unknown,
  onEvent: (event: StreamEvent) => void
) {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  })

  if (!response.ok || !response.body) {
    throw new Error(`请求失败:${response.status}`)
  }

  const reader = response.body.getReader()
  const decoder = new TextDecoder() // SSE 规定 UTF-8
  let buffer = ''

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n').replace(/\r/g, '\n')

    let boundary: number
    while ((boundary = buffer.indexOf('\n\n')) >= 0) {
      const block = buffer.slice(0, boundary)
      buffer = buffer.slice(boundary + 2)

      // 「: ...」是注释行,没有 data:,得到空串就跳过
      const data = block
        .split('\n')
        .filter(line => line.startsWith('data:'))
        .map(line => {
          const value = line.slice(5)
          return value.startsWith(' ') ? value.slice(1) : value
        })
        .join('\n')

      if (data) onEvent(JSON.parse(data) as StreamEvent)
    }
  }
}

// 接到事件后怎么处理(示意,不是完整 UI)
function handleStreamEvent(event: StreamEvent) {
  switch (event.type) {
    case 'text_delta':
      appendAssistantText(event.delta) // 追加字,不要整段替换
      break
    case 'tool_started':
      showStep(event.callId, event.tool, 'running')
      break
    case 'tool_finished':
      finishStep(event.callId, event.status, event.summary)
      break
    case 'interrupt':
      // 正常等待人:弹确认;保存 interruptId 供 resume
      openConfirmCard(event.interruptId, event.payload)
      break
    case 'done':
      markRunDone(event.messageId)
      break
    case 'error':
      showError(event.code, event.message)
      break
    default:
      break
  }
}

// 用户点确认:另发 resume,不是再 POST 一条「新聊天」
async function approveInterrupt(runId: string, interruptId: string) {
  await fetch(`/api/runs/${runId}/resume`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      interruptId,
      decision: 'approve',
      idempotencyKey: `resume_${interruptId}_1` // 同一确认动作固定一键,防双击
    })
  })
  // resume 若仍用 SSE 推进度:再发一次请求把 SSE 接上,或按你们约定复用同一条连接
}

SSE 断线怎么办:自动重连不等于进度恢复

推流时如果长时间没有业务事件,nginx 或网关可能因为空闲超时而断开连接。可以定期发送一行以 : 开头的注释作为心跳:

: keep-alive

心跳间隔应根据实际网关、负载均衡器和代理配置来确定,常见做法是先从 15~30 秒测试,再根据环境调整。不要把某个间隔当成适用于所有部署环境的固定值。

但心跳只能解决部分空闲连接问题,它不能保证连接永远不断,也不能代替任务状态持久化。

本文使用的是 POST + fetch 读流,需要明确三件事:

  • 连接断了,浏览器不会像原生 EventSource 那样自动重连。
  • 即使 EventSource 自动重连,也不代表服务端已经补发中间丢失的事件。
  • 如果服务端没有保存历史事件,仅靠一个 sequence,无法凭空找回已经丢失的进度。

可以根据项目阶段选择不同方案:

方案实现成本断线后的能力适用场景
只保存 Run 和最终结果低只能重新查询当前状态或最终结果简单问答、第一版产品
保存 Run、断点和中断记录中能恢复任务状态和待确认操作,但不一定能重放每条进度长耗时任务、人工审批
持久化事件并支持按序号重放高可以补发客户端未收到的事件对进度连续性要求高的任务
持久化事件 + 多实例推送协调更高能支持多实例部署下的事件恢复与分发高并发生产系统

第一版通常不必一上来就做完整事件回放。可以先保证 Run 状态和最终结果可靠,再根据业务对进度连续性的要求,决定是否持久化全部事件。

如果需要补发进度,服务端应根据客户端最后确认的序号,读取持久化事件并按顺序重放。还需要考虑事件去重、保留期限、序号作用域,以及重放与实时推送之间如何避免漏事件和乱序。

如果采用原生 EventSource,SSE 的 id: 字段可以配合 Last-Event-ID 告诉服务端客户端最后收到的事件 ID。但这只是恢复协议的一部分:真正补发事件的仍然是服务端。

Snipaste_2026-10-27_15-59-49.png

HITL:暂停等人,不要当成报错

缺参数、需要审批或执行高风险操作时,这次 Run 应进入 interrupted,而不是直接记成 failed。

前端展示“等待确认”或“请补充参数”,而不是直接显示执行失败。两者的语义完全不同:失败意味着当前执行未能正常完成;中断则意味着任务暂时不能继续,需要外部输入后再恢复。

暂停时,至少要留下两类信息:

  1. 中断记录:告诉前端要展示什么确认卡,也让恢复接口能够定位到本次中断。
  2. 断点:保存继续执行真正需要的最小状态,例如待执行步骤和必要的参数引用。

中断记录与断点

type Interrupt = { // 中断记录(等人确认 / 补参)
  id: string                 // 中断 id,恢复时必须原样带回
  runId: string              // 所属 Run
  type: 'confirm_action' | 'select_option' | 'provide_input' // 确认 / 选择 / 补参
  status: 'pending' | 'resolved' | 'expired' | 'cancelled' // 只有 pending 才能恢复
  payload: unknown           // 确认卡上要展示的内容(已脱敏)
  expiresAt: string          // 过了这个时间不能再点「同意」
}

type Checkpoint = { // 断点:继续跑所需的最小状态
  runId: string
  nextStep: string           // 恢复后从哪一步继续
  safeToolArgs: Record<string, unknown> // 已脱敏、恢复前还要再鉴权的参数
  conversationVersion: number // 防止恢复期间会话被别人改乱
  createdAt: string
}

payload 里不要塞数据库连接串、访问令牌、完整工具参数或内部堆栈。断点也只保留继续执行真正需要的字段。

恢复接口:用户确认后,究竟应该做什么

用户点“确认、拒绝或补参”时,调用恢复接口,而不是再发一条新聊天。

// POST /api/runs/:runId/resume 请求体
{
  interruptId: 'int_456', // 仍为 pending 的中断 id
  decision: 'approve', // approve | reject | 补参等
  idempotencyKey: 'resume_int_456_1' // 同一确认动作固定一把键,防双击
}

服务端不能直接信中断里那份旧参数。下面骨架里的 authorize / reloadResource / continueFrom 换成你们自己的实现即可,顺序不要乱:

type ResumeInput = {
  runId: string
  interruptId: string
  decision: 'approve' | 'reject' | { fill: Record<string, unknown> }
  idempotencyKey: string
}

// 1) 找到仍 pending 的中断  2) 用当前登录态鉴权  3) 防重复提交
// 4) 拒绝则只改状态  5) 重读资源  6) 再验权限  7) 从断点续跑
async function resumeRun(input: ResumeInput, auth: AuthContext) {
  const interrupt = await interruptRepo.findPending(input.interruptId)
  if (!interrupt || interrupt.runId !== input.runId) {
    throw new Error('INTERRUPT_NOT_FOUND')
  }

  await authorize(auth, interrupt) // 身份只信这次请求的登录态
  await assertNotExpired(interrupt) // 看 expiresAt;过期直接拒绝
  await idempotency.acquire(input.idempotencyKey) // 同一把键第二次进来:返回上次结果,别再执行

  if (input.decision === 'reject') {
    await markRejected(interrupt) // 只改状态
    return { status: 'cancelled' as const } // 不要再调会改数据的工具
  }

  const checkpoint = await checkpointRepo.load(input.runId)
  const latestResource = await reloadResource(checkpoint) // 等待期间实例可能已变
  await revalidate(latestResource, auth)

  return continueFrom(checkpoint, input.decision) // 按 nextStep 续跑
}

从弹出确认到用户点确认,资源和权限都可能变。所以,必须重读资源、重新鉴权。用户点拒绝时,只更新中断和 Run 状态,不要再去执行写操作。

防双击只是第一步:如何避免危险操作重复执行

用户连点“确认”、网络抖动后重试、两个标签页各点一次,都可能让恢复接口收到多次请求。

常见的防线有两道:

  1. 幂等键 idempotencyKey:同一次确认动作应使用同一个 idempotencyKey。服务端记录这个键对应的处理状态和结果;重复请求应返回已有结果,而不是重新启动一次操作。不同的确认动作不能随意复用同一个键,否则可能把两次合法操作误判为同一次请求。

  2. 改中断状态时加条件:真正去执行写操作之前,用代码执行一条带条件的更新——「只有这条中断现在还是 pending,才改成 resolved」。两个请求几乎同时进来时,数据库里只会有一个更新成功(改动行数 = 1);另一个改动行数 = 0,说明已经有人抢先处理了,这个请求就不要再调重启工具。

// 写在 resume 接口里,通过数据库客户端执行(示意)
const result = await db.query(
  `UPDATE interrupts
   SET status = 'resolved', resolved_at = NOW()
   WHERE id = $1 AND status = 'pending'`,
  [interruptId]
)

if (result.rowCount === 0) {
  // 已经处理过、过期或取消了 → 直接返回,禁止再执行工具
  return alreadyHandledResponse()
}

// rowCount === 1:这是第一个抢到的请求,才允许继续重读资源、执行重启

记住一点就行:两个请求一起来时,靠上面这条带条件的更新,让数据库选出第一个成功的;只有它才能继续执行危险操作,另一个直接返回。

SSE 断了,后台要不要停?

这是另一个很容易设计错的地方。

推流连接断开,只表示前端暂时收不到进度,不等于用户取消了任务。 看任务性质:

  • 查询类:客户端断开后可以取消,省模型和工具费用。
  • 发布、审批、重启实例等:通常应和 HTTP 连接拆开——后台 Run 继续跑,结果写进数据库;用户刷新后再把状态读回来。
// 默认只停推送;是否取消 Run 看策略
// Node:别听 req 的 close(POST 读完请求体就可能触发);听 res 的 close
// 正常 res.end() 也会触发 close:用 !writableFinished 区分「客户端提前断开」
res.on('close', () => {
  subscriber.detach(runId) // 停推送;不等于用户点了取消

  if (!res.writableFinished && runPolicy.cancelWhenNoSubscriber) {
    // 仅客户端提前断开;写操作 / 审批类通常不因断连取消
    runController.cancel(runId)
  }
})

如果任务与连接解耦,用户刷新页面后,就可以重新查询 Run 的状态;如果任务已经完成,直接读取结果;如果仍在运行,再按约定重新订阅进度。

Snipaste_2026-10-27_15-59-57.png

和 LangGraph 怎么对照:框架能解决什么,不能解决什么

不少团队使用 LangGraph 编排 Agent 循环。它和本文解决的是同一类问题,但负责的层次不同。

  • 本文讨论的是对外运行协议:会话、Run、SSE 业务事件、恢复接口,以及前端如何理解任务状态。
  • LangGraph 这类编排框架负责图执行与状态管理:例如节点如何运行、何时中断、如何通过 Checkpointer 保存和恢复图状态。

可以把两者的关系理解为:

本文中的设计LangGraph 中常见的对应概念
Run 和断点图执行状态与 Checkpointer
稳定的任务标识线程标识,例如 thread_id
HITL 暂停interrupt 及相应的恢复机制
SSE 业务事件应用层对执行流的转换和封装
恢复时的鉴权、资源复核应用服务与 Tool Runtime 的职责
外部副作用的幂等控制工具执行层和外部系统集成的职责

具体 API、参数和恢复语义要以实际使用的 LangGraph 版本为准。

特别需要注意:框架能够保存图状态,并不意味着外部工具调用就天然具备幂等性;框架能够暂停执行,也不代表前端确认接口、权限检查和事件回放都已经实现。

如果已经采用 LangGraph,可以优先复用其状态管理与中断恢复能力;如果是自研 Runtime,也可以自行设计 Run、Checkpoint 和恢复机制。关键不是是否使用某个框架,而是整个链路的状态边界是否清晰。

怎么测、常见误区与落地顺序

上线前,建议至少覆盖以下测试:

  • SSE:一个事件被拆成好几块、一块里塞了多条、中文跨块切开、网关空闲超时、断网、刷新页面、重连后同一步是不是又画了一遍。
  • HITL:双击「确认」、确认过期、恢复前权限被撤、实例在等待期间被别人改过、取消之后又点恢复。
  • 会话上下文(顺带):「它 / 刚才那个」有没有认对;工具失败后有没有误写入 state。

落地顺序(建议,不是行业标准):

  1. 先做 POST + SSE、统一业务事件、前端 buffer 解析;消息和工具结果写进数据库。
  2. 再上 Run、中断、断点、独立恢复接口、防双击、恢复前重新鉴权。
  3. 事件序号、断开后按号把没收到的进度拉回来、多实例下的进度推送、摘要与会话 state,可以后做。

刷新或断线之后,你还能查到任务停在哪、确认卡还能不能点、恢复前该重新验什么——这才比较接近能上线。

Snipaste_2026-10-27_15-57-14.png

小结: Agent 能跑起来不难,难的是中断后还能安全地跑下去

这篇文章最想说明的,不是某个 SSE API 或某个编排框架,而是生产 Agent 必须处理好的几个边界。

常见误区:

  • 把“等人确认”当成报错:中断是正常业务状态,失败则是另一种状态。
  • 把等待状态只放在内存里:进程重启或扩容后,任务可能无法恢复。Run、中断记录和断点需要可靠持久化。
  • 确认后直接拿旧参数执行:等待期间资源和权限都可能变化,恢复前必须重新读取并检查。
  • 把 SSE 当成任务本身:SSE 负责推送进度,任务状态应由持久化的 Run 和执行记录决定。
  • 认为一条 SQL 就能保证外部操作只执行一次:数据库可以控制并发认领,但外部副作用还需要幂等、状态核验和失败恢复。
  • 把整段聊天记录塞给模型:成本更高,也更容易受到旧信息干扰。应区分可信事实、历史摘要和最近原文。

最后记住三件事:

  1. 进度用 SSE 推业务事件,不要让前端靠读自然语言猜测任务进行到哪一步。
  2. 等人确认是正常流程,不是报错;用户点确认后走恢复接口,带着 interruptId 接着这次 Run 跑,不要当成新开一轮对话。
  3. 连接断了不等于任务没了:Run / 中断 / 断点要写进数据库;恢复前重新验权限、重读资源,并防双击执行两遍。

这篇文章根据 Agent 落地中的常见问题展开,希望能给正在做相关系统的朋友有所帮助、有所借鉴,有任何问题和不同看法,欢迎一起在评论区沟通交流。