🎯 今日核心问题
- 多步 Agent 的请求要跑 30-90 秒,HTTP 同步等下去体验极差——怎么推送给前端?
- 每一步该记录哪些字段,才能在出问题时定位到「哪一步、哪个工具、什么参数」?
- Thought 直接暴露给用户有什么风险,该怎么脱敏与裁剪?
📖 精读提纲
【一】为什么同步阻塞的 Agent 接口是错的
你在 Controller 里写 return agentService.run(q),前端 fetch 挂 60 秒。中间可能经历:网关 30s 超时、浏览器连接中断、用户以为卡死而刷新导致重复执行(重复扣费/重复下单)。这三个问题没有一个是靠「优化模型速度」能解决的。
正确形态是异步任务 + 事件流:提交时立刻返回 taskId,执行在后台线程跑,进度通过 SSE(SseEmitter)或轮询 /tasks/{id}/events 推给前端。Spring Boot 里 SseEmitter + TaskExecutor 是最轻量的实现,不需要引入 MQ。如果要多实例部署(任务可能落在另一台机器上),才需要把事件写进 Redis Pub/Sub 或 MQ。
关键在于:Agent 的每一轮循环必须主动 emit 一个事件,而不是执行完再一次性返回。这意味着你的 ReAct / Plan 循环里要埋钩子。D1/D2 代码里我特意把 Step 和 PlanStep.status 记下来了,今天就是把它们变成事件流。
【二】事件模型:一次任务的事件序列长什么样
最小可用的事件模型有五种类型,字段设计要兼顾「前端渲染」和「事后排障」两个用途:
task_started:任务 id、原始目标、计划总步数。前端据此渲染一个 N 步的进度骨架。step_started:步 id、goal、预计要用的工具。让用户知道「正在做什么」。step_finished:状态、耗时 ms、token(in/out)、产出摘要(截断到 200 字)、完整产出只存库不推流。step_failed:错误分类 + hint + 是否重试。这是最能提升用户信任的一类事件——用户看到「查询超时,正在重试」就不会以为系统挂了。task_finished:最终结果、总耗时、总 token、总成本。
一定要带 seq 单调递增序号。SSE 断线重连时用 Last-Event-ID 补发,否则用户刷新后进度会乱序或者停在半截。这是 SSE 的标准能力,但绝大多数人不用。
另外:不要把 Thought 原文直接推给用户。原因有二:一是 Thought 里常含内部工具名、表名、员工 id,属于信息泄露;二是模型的思考经常是错的、反复的,用户读了会更困惑。做法是:Thought 完整落库(排障用),推给前端的是一句由 Thought 归纳的进度文案(比如「正在核对订单历史」)。归纳可以再用一次小模型,也可以直接规则映射。
【三】实战应用:Spring Boot 场景
三张表:agent_task(任务级)、agent_step(步骤级,含 status/耗时/token/输出摘要)、agent_event(事件流,供断线重放)。写入要异步且批量,别让日志影响主流程延迟——用一个 @Async 的 TraceWriter + 有界队列,队列满了就丢弃 DEBUG 级别事件,优先保 step_failed。
接口设计三个:POST /agent/tasks 返回 taskId;GET /agent/tasks/{id}/stream(SSE);GET /agent/tasks/{id} 返回完整快照(用于轮询兜底和刷新恢复)。前端优先连 SSE,连不上降级成 1s 轮询快照。
还有一个容易被忽略的点:超时预算。规划时就给每个步骤分配时间预算(比如总 90s,5 步各 15s),运行中超过预算就提前 emit step_failed(reason=TIMEOUT) 并进入重规划,而不是傻等上游。这比在网关层硬超时体验好得多。
【四】常见误区
- ❌ 用
log.info当日志就算可观测。日志能排障,但推不到前端,用户还是面对空白。 - ❌ 事件里塞完整工具返回。一个订单详情 JSON 20KB,推 10 个就把 SSE 连接堵满了。推摘要,详情存库按需拉。
- ❌ 不记 token 和成本。到第7周做成本核算时你会发现数据没了,只能重跑。
- ❌ SSE 不做心跳。中间某个步骤要跑 40 秒没有事件,网关或代理会主动断开空闲连接。每 15 秒发一个
ping注释帧。 - ❌ Thought 原文直接展示。既泄露内部实现,又暴露模型的错误推理过程。
💻 代码示例
public record AgentEvent(
long seq,
String taskId,
String type, // task_started / step_started / step_finished / step_failed / task_finished / ping
String stepId,
String title, // 给用户看的进度文案
String status,
long costMs,
Integer tokensIn,
Integer tokensOut,
String summary, // 截断后的摘要,≤200字
Instant at) {}
@Component
@RequiredArgsConstructor
public class AgentEventBus {
private final AgentEventRepository repo;
private final Map<String, SseEmitter> emitters = new ConcurrentHashMap<>();
private final Map<String, AtomicLong> seqs = new ConcurrentHashMap<>();
public SseEmitter subscribe(String taskId, Long lastEventId) {
SseEmitter emitter = new SseEmitter(0L); // 不设超时,由业务控制
emitters.put(taskId, emitter);
emitter.onCompletion(() -> emitters.remove(taskId));
emitter.onTimeout(() -> emitters.remove(taskId));
// 断线重连:补发 lastEventId 之后的事件
if (lastEventId != null) {
repo.findByTaskIdAndSeqGreaterThanOrderBySeqAsc(taskId, lastEventId)
.forEach(e -> send(emitter, e));
}
return emitter;
}
public AgentEvent emit(String taskId, String type, String stepId,
String title, String status, long costMs,
Integer tin, Integer tout, String summary) {
long seq = seqs.computeIfAbsent(taskId, k -> new AtomicLong()).incrementAndGet();
AgentEvent e = new AgentEvent(seq, taskId, type, stepId, title, status,
costMs, tin, tout, clip(summary, 200), Instant.now());
repo.save(e);
SseEmitter emitter = emitters.get(taskId);
if (emitter != null) send(emitter, e);
return e;
}
private void send(SseEmitter emitter, AgentEvent e) {
try {
emitter.send(SseEmitter.event().id(String.valueOf(e.seq()))
.name(e.type()).data(e));
} catch (IOException ex) {
emitters.remove(e.taskId());
}
}
}
@RestController
@RequestMapping("/api/agent/tasks")
@RequiredArgsConstructor
public class AgentTaskController {
private final PlanExecuteAgent agent;
private final AgentEventBus bus;
private final TaskRepository taskRepo;
private final TaskExecutor executor;
@PostMapping
public Map<String, String> submit(@RequestBody SubmitReq req) {
String taskId = UUID.randomUUID().toString();
taskRepo.create(taskId, req.objective());
executor.execute(() -> {
long t0 = System.currentTimeMillis();
try {
bus.emit(taskId, "task_started", null, "已接收任务,正在规划", "RUNNING", 0, null, null, req.objective());
PlanResult r = agent.execute(taskId, req.objective()); // 内部每步 emit
bus.emit(taskId, "task_finished", null, "任务完成", "DONE",
System.currentTimeMillis() - t0, r.tokensIn(), r.tokensOut(), r.finalText());
} catch (Exception e) {
bus.emit(taskId, "task_finished", null, "任务失败: " + e.getMessage(), "FAILED",
System.currentTimeMillis() - t0, null, null, null);
}
});
return Map.of("taskId", taskId);
}
@GetMapping(value = "/{taskId}/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter stream(@PathVariable String taskId,
@RequestHeader(value = "Last-Event-ID", required = false) Long lastId) {
return bus.subscribe(taskId, lastId);
}
}
一次真实的前端看到的事件流(5 步任务):
seq=1 task_started 已接收任务,正在规划 0ms
seq=2 step_started s1 · 拉取三家竞品本周更新日志 1.2s
seq=3 step_finished s1 · 完成,得到 17 条更新 at 8.4s tok 2.1k/0.9k
seq=4 step_started s2 · 提取可对比功能维度 8.5s
seq=5 step_failed s2 · 上游接口超时,正在重试(1/2) 19.1s
seq=6 step_finished s2 · 重试成功,得到 4 个维度 at 26.0s tok 3.4k/1.1k
seq=7 ping — at 41.0s
seq=8 step_finished s3 · 完成价值排序 at 44.8s tok 2.8k/0.6k
seq=9 step_finished s4 · 周报正文 512 字 at 61.2s tok 4.2k/1.8k
seq=10 task_finished 任务完成 DONE total 61.2s tok 12.5k/4.4k ≈ ¥0.03
seq=5 那条是最有价值的:它把「系统卡了 19 秒」变成了「正在重试」,用户的焦虑直接消失。这也是可观测性真正的产品价值——它不只是给运维看的。
✏️ 今日动手
把 PlanExecuteAgent 改造成事件驱动:① 注入 AgentEventBus,在执行循环的关键节点 emit 六种事件;② 写 SseEmitter 接口 + 一个最简 HTML 页面(10 行 JS 的 EventSource)验证实时渲染;③ 实现 Last-Event-ID 补发,手动断网 5 秒再重连,确认事件不丢不乱序;④ 加 15 秒心跳,并把每个步骤的 token 累加,任务结束时输出总成本和单步成本排行——这个排行会告诉你哪一步最该优化。
🔖 明日预告
周总结。把 ReAct、Plan、分解、反思、纠错、可观测性串成一个能跑 5 步以上真实任务的完整 Agent,给出 Planner + Executor 的整合代码和本周回顾表。