Feature Request: Native Token Metering & Bounded Overshoot (x402 Protocol)

快速结论：这是一个关于 LlamaIndex 框架的 Feature Request（功能请求），核心诉求是在路由层原生支持 x402 协议的 Token 计量与 Bounded Overshoot（有界超支）机制，用于防止 agent 循环导致 API 费用失控。该 Issue 已被维护者关闭，目前没有合并到框架主线的计划，但评论中提供了可以在现有代码中自行实现的防超支方案。

适用环境：LlamaIndex 框架；涉及 LLM API 调用、多 worker 并发场景；不涉及特定 Python、CUDA、显卡版本。

最快修复方案：暂无确认的一步修复方案。该 Issue 是功能请求而非 bug 报告，未提供可合并的补丁。评论者建议的可行方案是：采用“post-flight 窗口检查 + 有界超支”策略，而不是“pre-flight 预算预测”，并配合“per-call 上限”与“fail open 机制”来控制成本。

注意事项：pre-flight 预估计会误拒正常调用；post-flight 检查的 worst-case 超支是“单次最大调用费用”；共享预算时应使用 lease（租约）而非中央计数器；计量逻辑崩溃时 LLM 调用必须仍能通过（fail open）。“单逻辑调用对应多个 vendor 调用”的成本归因问题尚未解决。

问题场景

企业开发者在 LlamaIndex 中使用 autonomous agent 时，agent 可能进入死循环并持续调用付费 LLM 资源，导致 API 账单迅速飙升（即 “Margin Leak” 问题）。当前开发者需要自行编写 token 计数包装器，但框架没有提供原生的防超支路由机制。Issue 提出在框架路由层原生支持 x402 协议（含 Bounded Overshoot 与 HTTP 402 错误码）来统一解决此问题。

报错原文

Feature Request: Native Token Metering & Bounded Overshoot (x402 Protocol)

As enterprise adoption of this framework accelerates, developers are increasingly hitting the "Margin Leak" problem: autonomous agents entering loops and aggressively polling paid LLM resources without proactive financial guardrails.

If a loop occurs, the API bill skyrockets before the framework can halt it.

Instead of pre-flight token math (which leads to false refusals), the framework passes requests through a meter. If the budget is exceeded, the request returns a standardized `-4020 Payment Required` error, and the agent safely halts.

[Protected] Call 5 INTERCEPTED! HTTP 402 Payment Required.
✅ SUCCESS: Agent safely halted before catastrophic margin leak.
--> Remaining Budget: $0.00

原因分析

可能原因：框架当前没有内建的预算计量与熔断机制，agent 循环调用 LLM API 时缺乏主动的财务护栏。Issue 提出改用 x402 协议的 Bounded Overshoot 方案（post-flight 检查），而非传统的 pre-flight 预测，以避免预测误差导致正常调用被误拒。评论者补充指出：pre-flight 预估在真实工作负载下不可靠，post-flight 检查才是可验证的边界控制方式。

环境排查

框架：确认 LlamaIndex 版本，检查是否有可用的自定义 callback 或 middleware 钩子来插入计量逻辑。
LLM 调用模式：确认是否涉及多 vendor 路由（如 OpenAI → Anthropic fallback），这会影响成本归因的粒度。
并发形态：确认是否存在多 worker 共享预算场景，若有，推荐使用 lease 机制而非中央计数器。
错误处理：确认框架能否识别并捕获自定义错误码（如 402 或自定义子类）并优雅终止 agent。

解决步骤

设计方案（可优先尝试）：在现有框架中自行实现“post-flight 窗口检查”。每个窗口上限只比较“已花费金额”，不接受“预计费用”作为拒绝依据。
设置 per-call ceiling：对单次调用设置硬性上限（如 $1.50），可使用简单启发式（input tokens × max output tokens × price）进行估算，因为拒绝一次昂贵调用是可接受的，误拒率低。
实施 bounded overshoot：允许当前调用超过窗口剩余预算，但下一次调用必须被拒绝。这样 worst-case 超支被限制在“单次最贵调用”的金额。
引入 lease 机制（多 worker 场景）：每个 worker 租用预算切片（建议 $5、5 分钟 TTL、不超过日上限的 1/10）。租约过期后自动释放，防止 worker 崩溃导致预算永久锁定。
强制 fail open：计量逻辑若崩溃，LLM 调用必须仍能通过。agent 因计量系统故障而停止工作，比超支事故更严重。
使用标准化错误码：返回 402 或自定义子类错误，让 agent 框架能捕获并停止重试。

验证方法

在测试环境中使用模拟的 LLM 调用进行验证：确认调用数达到预算上限后，后续调用被返回 402 错误且 agent 能安全退出；确认正常调用不会被误拒（即使 pre-flight 估算会误拒的场景）；确认计量系统崩溃时 LLM 调用仍能正常完成。若为多 worker 场景，验证租约到期后预算能正确释放且 worst-case 超支符合预期（租约大小 × worker 数）。