成本治理器与预算终止开关

每个自主 Agent 都需要三个预算：max_turns（迭代次数）、max_budget_usd（美元上限）和 max_wallclock_s（挂钟秒数）。Claude Code 在每次运行时强制执行所有三个。LangGraph 的运行时在每个超步检查预算。没有这些，长时间范围 Agent 会静默消耗无限资源——无论是 token、计算还是挂钟时间。成本治理器是安全层 0。

类型： 学习 语言： Python (stdlib, 带三个预算的运行时门控) 前置条件： Phase 15 · 01 (长时间范围Agent), Phase 15 · 12 (持久执行) 时间： ~30 分钟

问题

没有预算的 Agent 是一个资源泄漏。LLM 调用花费金钱。工具调用花费时间。长时间范围运行花费挂钟时间。三者中任何一个无限制的 Agent 最终会消耗超出你愿意支付的。

预算终止开关是自主性的最低安全层。Claude Code 在每次运行时强制执行 max_turns、max_budget_usd 和 max_wallclock_s。LangGraph 的运行时在每个超步检查预算。任何没有等价物的生产 Agent 系统都是在裸奔。

概念

三个预算

所有三个独立强制执行。任何一个超限终止运行。

为什么三个都需要

• 仅 max_turns：Agent 可以在单次迭代中发出昂贵的 LLM 调用。200 次迭代 × $0.50/调用=$100。
• 仅 max_budget_usd：Agent 可以在免费操作上永远循环（文件读取、本地计算）。零美元但无限挂钟时间。
• 仅 max_wallclock_s：Agent 可以在时间预算内快速消耗 token。

三个预算覆盖三个独立资源维度。任何两个都不充分。

预算耗尽时会发生什么

运行终止。Agent 的状态持久化到检查点 (Lesson 12)。终止原因记录：哪个预算超限、当前进度和部分结果。

两个设计选择很重要：

1. 优雅 vs 硬终止。 优雅终止给 Agent 一次迭代总结进度。硬终止立即杀死进程。优雅更好但需要 Agent 在预算中留出空间进行总结迭代。
2. 部分结果交付。 Agent 是否将其部分工作交付给用户？通常是的——部分代码比没有好。但部分结果必须标记为不完整，以免用户误以为任务已完成。

每工具预算

除了全局预算外，一些系统强制执行每工具预算。示例：不超过 N 次 WebFetch 调用，不超过 M 次 Shell 执行。这防止 Agent 在单个工具上消耗其全局预算。

成本估算

在运行前，根据任务复杂性估算成本：

• 简单任务（1-5 次工具调用）：约 $0.01-0.10
• 中等任务（10-30 次工具调用）：约 $0.10-1.00
• 复杂任务（50+ 次工具调用）：约 $1.00-10.00
• 长时间范围研究（100+ 次工具调用）：约 $10.00-100.00

设置预算为估算的 2-3 倍以考虑意外复杂性。

构建它

code/main.py 实现带三个预算的运行时门控。模拟 Agent 运行；当任何预算超限时运行终止并记录原因。

运行：

python3 code/main.py

练习

1. 运行 code/main.py。观察哪个预算首先触发。更改参数使不同预算首先触发。
2. 实现优雅终止：当预算达到 90% 时，给 Agent 一次总结迭代的额外机会。
3. 添加每工具预算：不超过 5 次 WebFetch 调用。当工具预算超限时会发生什么？
4. 设计一个成本估算器，根据任务描述和模型选择输出建议的 max_budget_usd。

关键术语