Agent 跑三分钟的任务HTTP 等不了异步长任务的三个接口让 Agent 查一次季度报表它要调五个工具翻两次知识库最后写一段总结全程三分钟。同步接口扛不住这个时长网关默认超时一分钟反向代理再来一刀浏览器自己也会放弃。用户看到的是转圈然后报错后端日志里任务其实已经跑完了钱也花了。三段式把一次调用拆成三个接口。提交接口返回任务 ID立刻返回毫秒级。查询接口按任务 ID 给状态排队中、执行中、完成、失败带进度和已完成的分步结果。结果接口取最终产物。想要更省事就再加一个回调任务完成时服务端主动通知前端前端不用轮询。这套结构的老祖宗是批处理系统的作业控制用在 Agent 上正合适因为 Agent 任务天然有中间状态每一步工具调用都可以先落盘。队列用哪个任务要排队就有了队列选型的问题。RabbitMQ 的强项是任务分发有确认机制、重试、延迟队列一条消息被消费者拿到处理失败可以重新入队。Kafka 的强项是日志流顺序写、可回放、高吞吐消费者自己记录消费位置适合做数据管道和事件溯源。Agent 任务队列要的是重试、延迟、优先级、死信处理这些是 RabbitMQ 的主场。如果任务本身是长流程事件流要回放要审计才考虑 Kafka。不少项目上来就用 Kafka 做任务队列最后发现延迟重试要自己实现得不偿失。幂等这件事用户手抖点两次提交或者前端重试同一个任务就排队两遍工具调用两遍钱花两遍。做法是让客户端生成请求 ID 随提交带上服务端拿这个 ID 去重重复提交返回同一个任务 ID。别指望用户不点两次。工具级也要幂等。取消订单这类操作同一个订单重复执行要能识别出来别第二次报错也别真的执行两遍。参数校验三层里的业务层正好能兜住这一类。状态机与超时任务状态得是个明确的状态机别用一堆布尔值拼。排队、执行、成功、失败、取消状态之间的迁移写清楚谁能迁到谁。超时是必然要处理的执行超过上限就标失败并回收资源不能让一个卡死的任务占着 worker 到天荒地老。终止条件也得有。执行循环篇讲过的重试上限在异步任务里变成任务级的总预算包括耗时预算和 token 预算超了就停把已完成的部分交回去。半成品比死循环有价值。回调要签名如果做回调回调地址会暴露在公网上必须签名加时间戳接收方校验后才能信任内容。回调还可能被重放时间戳加 nonce 能挡住。回调失败要有限次重试重试策略用指数退避别一秒一次打爆对方。结合系列ChatServer 篇的接口设计和错误语义在这套结构里同样适用提交接口的错误码和查询接口的状态要能对上。会话隔离篇的身份校验在异步场景要多考虑一层任务属于谁查询时必须校验归属不能只凭任务 ID 就能查别人的结果。审核队列篇讲的是人工介入的排队这里讲机器执行的排队两者可以在同一套状态机里共存。
