前言:封闭告一段落,开始系统复盘:一个生产 Agent 到底怎么跑起来。踩坑、经验和落地,尽量用几篇文章讲清,这篇文章是系列第5篇:
Agent 一旦进入生产环境,问题往往不再是「模型能不能回答」,而是任务跑了很久,前端却没有反馈;用户点了确认,后台却不知道从哪一步继续;页面断线后,进度丢了,甚至还可能重复执行一次危险操作。
希望这篇文章能给正在做 Agent 落地的朋友一些参考,也欢迎在评论区分享实践和问题。
用户说:「重启这个异常实例。」查到一半,又补了一句:「继续查它。」
对普通聊天来说,这可能只是两句自然语言;但对生产 Agent 来说,系统还得知道「它」指向哪个实例、当前任务执行到哪一步,以及重启前是否需要用户确认。
这篇只讲两件事:一次请求如何把进度持续推给前端,以及用户确认后,如何从正确的断点继续执行。
单轮聊天接口并不复杂。真正接入业务后,下面三类问题通常很快就会出现:
- 用户说「继续查它」,系统不知道「它」是谁;
- Agent 跑很久,前端长时间没反馈;
- 删除、发布、转账必须让人确认,确认后还要从中断处继续。
这三类问题分别对应三个核心能力:多轮状态管理、SSE 流式通信,以及 HITL(Human in the Loop,人在回路)。继续使用虚构案例 OpsPilot(企业运维助手),技术栈仍是 TypeScript;前端可以用 Vue 3 配合 fetch 读取流。
不同场景的侧重点也不一样:
- 知识问答:重点是文本增量推送、首字响应速度和断线后的结果恢复。
- 长耗时任务:重点是任务状态持久化、进度查询和前后端连接解耦。
- 运维、发布与审批:重点是人工确认、权限复核、并发控制和副作用的可靠执行。
如果只是做一个聊天演示,很多细节可以先不考虑;但如果要把 Agent 接进真实业务系统,这些设计迟早都要面对。
一次运行要有自己的状态
不要只把所有内容存成一串聊天文本。至少要区分三类数据(可以是三张表,也可以是三份独立记录),因为它们的生命周期和用途并不相同:
- 会话(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。用户确认后,应恢复这次运行,而不是重新发起一轮聊天、再让模型猜之前发生了什么。这样既能保留任务上下文,也能减少重复调用工具的风险。
多轮上下文:让模型听懂“它”,但别把整段历史都塞进去
用户经常会说“继续查它”“刚才那个”。如果每次都把完整聊天记录交给模型,不仅成本更高,还可能让旧信息干扰当前任务。
可以把上下文分成三层:
- 已确认的业务事实:结构化
state,例如服务名、环境、实例 ID。只在工具结果经过校验或用户明确确认后更新。 - 较早的对话摘要:压缩成一段摘要,控制长度。
- 最近几轮原文:保留用户和助手最近说过的话,让模型能够理解“它”“刚才那个”等指代。
其中,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 为例,用户说:“重启这个异常实例。”
这类操作不应该让模型一提出工具调用就立即执行,而应该拆成两段:先查询并明确操作对象,再等待用户确认;确认通过后,才真正执行重启。
第一段:发消息、看进度、弹出确认
- 前端把这句话发给会话服务,同时打开一条 SSE,用来收进度(开始了、正在查、查完了……)。
- 后台先跑只读步骤(比如定位是哪个实例),这些进度通过 SSE 推到页面。
- 模型提出要调「重启」工具。这时还不执行重启,而是发一条
interrupt事件:页面弹出确认(风险说明、要重启谁)。 - 这次 Run 记成「等人」;这一轮推流可以结束。页面上是确认,不是红字报错。
第二段:用户点确认,从断点接着跑
- 用户点「确认」。前端调用恢复接口(带上这次中断的 id、同意/拒绝、以及防双击用的同一把请求键),不是再发一条全新聊天。
- 服务端先确认:这个中断还有效、当前用户仍有权限、实例现在还是那个状态;通过后才真正重启。
- 执行过程再次用 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 状态应先可靠保存,再通知前端。否则一旦进程在发送事件后崩溃,页面可能出现确认卡,但后台根本没有可恢复的断点。
SSE、WebSocket 怎么选:不是越复杂越好
SSE(Server-Sent Events)基于 HTTP,由服务端持续向客户端推送事件。
对于“用户发起一次请求,服务端持续返回进度”的场景,SSE 通常比 WebSocket 更简单;如果业务需要高频双向通信或传输二进制数据,再考虑 WebSocket。
| 对比维度 | SSE | WebSocket |
|---|---|---|
| 通信方向 | 服务端向客户端推送为主 | 双向通信 |
| 接入复杂度 | 通常较低,基于 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。但这只是恢复协议的一部分:真正补发事件的仍然是服务端。
HITL:暂停等人,不要当成报错
缺参数、需要审批或执行高风险操作时,这次 Run 应进入 interrupted,而不是直接记成 failed。
前端展示“等待确认”或“请补充参数”,而不是直接显示执行失败。两者的语义完全不同:失败意味着当前执行未能正常完成;中断则意味着任务暂时不能继续,需要外部输入后再恢复。
暂停时,至少要留下两类信息:
- 中断记录:告诉前端要展示什么确认卡,也让恢复接口能够定位到本次中断。
- 断点:保存继续执行真正需要的最小状态,例如待执行步骤和必要的参数引用。
中断记录与断点
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 状态,不要再去执行写操作。
防双击只是第一步:如何避免危险操作重复执行
用户连点“确认”、网络抖动后重试、两个标签页各点一次,都可能让恢复接口收到多次请求。
常见的防线有两道:
-
幂等键
idempotencyKey:同一次确认动作应使用同一个idempotencyKey。服务端记录这个键对应的处理状态和结果;重复请求应返回已有结果,而不是重新启动一次操作。不同的确认动作不能随意复用同一个键,否则可能把两次合法操作误判为同一次请求。 -
改中断状态时加条件:真正去执行写操作之前,用代码执行一条带条件的更新——「只有这条中断现在还是
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 的状态;如果任务已经完成,直接读取结果;如果仍在运行,再按约定重新订阅进度。
和 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。
落地顺序(建议,不是行业标准):
- 先做 POST + SSE、统一业务事件、前端 buffer 解析;消息和工具结果写进数据库。
- 再上 Run、中断、断点、独立恢复接口、防双击、恢复前重新鉴权。
- 事件序号、断开后按号把没收到的进度拉回来、多实例下的进度推送、摘要与会话
state,可以后做。
刷新或断线之后,你还能查到任务停在哪、确认卡还能不能点、恢复前该重新验什么——这才比较接近能上线。
小结: Agent 能跑起来不难,难的是中断后还能安全地跑下去
这篇文章最想说明的,不是某个 SSE API 或某个编排框架,而是生产 Agent 必须处理好的几个边界。
常见误区:
- 把“等人确认”当成报错:中断是正常业务状态,失败则是另一种状态。
- 把等待状态只放在内存里:进程重启或扩容后,任务可能无法恢复。Run、中断记录和断点需要可靠持久化。
- 确认后直接拿旧参数执行:等待期间资源和权限都可能变化,恢复前必须重新读取并检查。
- 把 SSE 当成任务本身:SSE 负责推送进度,任务状态应由持久化的 Run 和执行记录决定。
- 认为一条 SQL 就能保证外部操作只执行一次:数据库可以控制并发认领,但外部副作用还需要幂等、状态核验和失败恢复。
- 把整段聊天记录塞给模型:成本更高,也更容易受到旧信息干扰。应区分可信事实、历史摘要和最近原文。
最后记住三件事:
- 进度用 SSE 推业务事件,不要让前端靠读自然语言猜测任务进行到哪一步。
- 等人确认是正常流程,不是报错;用户点确认后走恢复接口,带着
interruptId接着这次 Run 跑,不要当成新开一轮对话。 - 连接断了不等于任务没了:Run / 中断 / 断点要写进数据库;恢复前重新验权限、重读资源,并防双击执行两遍。
这篇文章根据 Agent 落地中的常见问题展开,希望能给正在做相关系统的朋友有所帮助、有所借鉴,有任何问题和不同看法,欢迎一起在评论区沟通交流。