agent-request-queue

Agent 请求队列

一次 Agent 运行可能包含多次模型调用、知识库检索、工具执行和文件操作。为了避免同一对话同时修改同一份上下文，Yuxi 把“收到请求”和“开始运行”分成两个阶段，并为每个线程维护 FIFO 队列。

本页说明调度行为和可观察状态；接口字段以 /docs 的 OpenAPI 为准。

调度范围

队列按用户、智能体和对话线程确定范围。同一范围最多运行一个普通 AgentRun；同一用户在不同线程中提交的任务可以并行。

线程 A：请求 1（运行中） → 请求 2（排队） → 请求 3（排队）
线程 B：请求 4（运行中） → 请求 5（排队）

顺序由服务端保存的创建顺序决定，不使用浏览器时间。只有当前线程的队头请求可以被派发。

Request 和 Run

• Request 表示输入已被系统接收。它先保存到 PostgreSQL，可以处于排队、已派发、已取消、已拒绝或派发前失败。
• AgentRun 表示请求已经进入执行链路。只有请求获得派发机会后，系统才创建对应 Run。

这种拆分让排队请求可以单独查询和取消，也让刷新页面或重启服务后仍能恢复队列。排队中的用户消息不会提前加入当前 Run 的上下文；请求派发后才成为下一轮运行的输入。审批或用户回答产生的 resume 是例外：它从 LangGraph checkpoint 直接创建新的 Run，不经过普通消息 Request 队列。

普通调度流程

1. API 在 PostgreSQL 中保存输入消息和 Request。
2. 线程空闲且请求是队头时，创建 AgentRun。
3. 数据库事务提交后，API 才把 Run 投递给 Redis/ARQ。
4. Worker 执行 Run。成功结束后，检查同一线程的队头。
5. 队头存在时，自动创建并投递下一条 Run。

同一个 request_id 重试会返回已有 Request/Run，不会重复排队。不同用户、智能体、线程或来源复用该 ID 时返回冲突。

队列策略

策略	线程空闲	线程忙碌	使用场景
enqueue	立即派发	保存并按 FIFO 等待	网页聊天、异步 Agent Call
reject	立即派发	记录拒绝，不进入队列	需要立即得到结果的同步调用
steer	立即派发	保存为待接替请求	主会话 Chat/Channel 修正后续方向

enqueue

这是普通聊天的默认策略。调用方可以查询排队位置，并在派发前取消。前端把排队输入和正在生成的回复分开显示，避免用户误以为排队消息已经执行。

reject

只要请求不能立即成为并派发的 FIFO 队头，reject 就会返回拒绝结果。线程忙碌、已有积压、队列暂停或运行正在等待人工回答时都可能触发拒绝。拒绝是正常调度结果，不是服务器内部错误。

同步 Agent Call 固定使用 reject，这样调用方可以自己选择重试或切换线程，而不会把排队时间隐藏在同步请求里。

steer

steer 只适用于主会话 Chat/Channel。它把请求保存为队列中的一项；当前 Run 完成已经开始的模型调用和完整工具批次后，SteerMiddleware 在下一次模型调用前发现该请求并结束当前 Graph，worker 再按 completed 接力流程派发它。

因此，Steer 不强制取消正在执行的工具。一个线程同时只能有一个待处理 Steer。普通 Chat 排队项可以提升为 Steer，但等待当前 Run 到达安全点时不能取消。

系统在模型调用前和无工具调用的模型轮次结束后检查 Steer；如果进程在接力前退出，worker 启动恢复会重新扫描 queued Request。这个兜底保证持久化的 Steer 意图最终进入下一次 Run，但不改变已开始批次不可强制终止的边界。

状态

Request 状态

状态	含义
queued	已保存，等待派发
dispatched	已关联 AgentRun
cancelled	派发前被取消
rejected	reject 策略无法立即派发
failed	派发前处理失败

Run 状态

状态	含义
pending	数据库已记录投递意图，worker 尚未取得执行 lease
running	当前 attempt 持有 lease 并持续 heartbeat
cancel_requested	已记录取消意图，当前 owner 会在安全边界停止
completed	执行成功结束
failed	执行失败或 lease 过期后被收敛
cancelled	worker 确认取消
interrupted	等待用户回答或工具审批，可由 resume 请求恢复