🎯 今日核心问题

  1. 多步 Agent 的请求要跑 30-90 秒,HTTP 同步等下去体验极差——怎么推送给前端?
  2. 每一步该记录哪些字段,才能在出问题时定位到「哪一步、哪个工具、什么参数」?
  3. 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 记下来了,今天就是把它们变成事件流。

【二】事件模型:一次任务的事件序列长什么样

最小可用的事件模型有五种类型,字段设计要兼顾「前端渲染」和「事后排障」两个用途:

一定要带 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) 并进入重规划,而不是傻等上游。这比在网关层硬超时体验好得多。

【四】常见误区

💻 代码示例

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 的整合代码和本周回顾表。