Agentpause：LLM 智能体速率限制预测调度工具

Agentpause 是一款面向自主 LLM 智能体的开源调度库，核心思路是在智能体即将撞上云端或本地模型的速率限制（rate limit）之前，将其「预测性地」优雅挂起，并在恢复后继续未完成的工作而不必重做已完成的步骤。项目当前版本为 0.4.0，已开源在 GitHub，可通过 pip install agentpause 直接安装。

核心思路：预测式暂停 + 无缝恢复

传统的反应式（reactive）做法是在收到 429 限流错误后才报错退出，浪费已完成的工作并产生大量重发 token。Agentpause 反其道而行：在每一次 LLM 调用之前先调用 should_suspend()，依据剩余配额判断是否需要挂起；若需要，则保存检查点（checkpoint）并安全退出，下次启动时从断点继续。

该方案不绑定特定供应商，云端（OpenAI、Anthropic、Groq 等）与本地推理均可使用，因为挂起和恢复只序列化应用层状态。对于自托管运行时（llama.cpp、vLLM），还可选配「真正的 KV-cache 热启动」插件，进一步避免上下文重建开销。需要注意的是，本地模式本身并不暴露速率限制信号，开发者需要自行接入配额来源。

实测对比：错误率与 token 浪费双降

项目附带了一份可复现的研究报告，关键数据如下：

模拟环境（300 次/配置）：反应式基线在某些配置下崩溃率高达 100%，预测式方案在 k=4 时降至 0%，token 浪费减少 80%。
Groq 免费层（6K TPM）真实任务：多窗口任务以「零 429 错误」完成。
对比 LangGraph MemorySaver（200 次）：LangGraph 平均每次运行触发 7.8 次 429、浪费 9239 个 token；Agentpause 均为 0。
思考类模型端到端 A/B（4B/8B）：恢复速度快 54–93 倍，总任务时长缩短 19%。

一组 2026-07-08 的现场运行（Groq 免费层、12 步、约 1k token 上下文、补给感知的分块等待、均衡窗口）显示：反应式基线产生 7 次 429、12,840 个重发 token，而 Agentpause 为 0 和 0；代价仅是 259 次遥测 ping（ping 本身也消耗 token，但仅约崩溃浪费的 2%）。

上下文瘦身 vs 回答质量

项目还对比了两种历史压缩策略：

A — 完整历史（8984 字符）：6/6 事实召回。
B — compact() 盲截断（4370 字符）：0/6 召回，且模型会凭空编造替代内容。
C — summarize_with() 单次摘要（3608 字符）：6/6 召回。

在更大体量（19,145 字符，已接近免费层单次 TPM 上限）的复测中模式依旧：A 与 C 均为 6/6，B 仍为 0/6，但 prompt 仅为原来的三分之一。值得注意的是，B 的失败是「不可预测」的——同一脚本某次会自信地给出虚构的代号、预算、城市；某次则会坦诚拒绝。开发者无法事先预知会得到哪一种，而「自信编造」恰恰是最危险的那一种。

「语气与人设」也会被一起压扁

另一项 2026-07-20 的实验在六条事实之外又埋入了两条简短的口头禅（voice tic）。结果显示：

A 完整历史：6/6 事实，1/2 口头禅。
B 盲截断：0/6 事实，1/2 口头禅（短句被原样保留，但散落在前面的事实丢失）。
C summarize_with()：6/6 事实，0/2 口头禅（事实被摘要恢复，但语气被改写成模型自己的口吻）。

结论是：截断和摘要在「失败方式」上互补——盲截断保留短的原话但丢事实，摘要恢复事实但抹掉人设语气。如果智能体的语气一致性是产品要求，compact() 与 summarize_with() 不可互换，需按「不能失去的是事实还是风格」来取舍。

已具备能力与上手方式

0.4.0 版本包含：核心调度器、direct / LiteLLM / Anthropic 适配器、LangGraph 集成、多供应商路由、多智能体共享配额、基于特征的 cost/latency 估算、任务完成预测、检查点分叉与跨机迁移、可选的 llama.cpp 真热启动 KV-cache 插件、人类注意力作为预算维度、可运行示例与完整测试套件。

最小上手示例只需两步：定义 backend（任意可调用对象，签名 messages -> (reply, tokens_used)）和 telemetry（任意可调用对象，签名 () -> remaining_tokens），然后在循环中调用 should_suspend()、checkpoint()、call()、complete() 即可。也可直接运行无需 API Key 的示例：python examples/quickstart.py，首次运行会中途挂起，再次运行即可从断点恢复。

对于已经在使用 LiteLLM 或 LangGraph 的项目，可安装对应可选依赖：pip install "agentpause[litellm]" 或 pip install "agentpause[langgraph]"；参与开发则克隆仓库后执行 pip install -e ".[dev]" 并运行 pytest。所有 benchmark 脚本（如 scripts/benchmark_groq.py、scripts/quality_ab.py）均随仓库提供，读者可自行复现文中数据。