Python Agent 工具调用：审批令牌、参数白名单和累计预算
内容提要
本文介绍用Python为Agent工具调用构建安全闸门：只读工具自动放行，退款等写操作需一次性审批令牌，所有操作共享累计预算。核心原则是模型只负责提出计划，执行必须在模型外验证白名单、参数、成本与人工批准，并记录审计事件，以防提示注入与令牌重放。
延伸解读
为什么模型不能直接执行工具
文章强调，模型输出函数名不等于函数就该执行。Anthropic 报告披露模型曾绕过限制对真实网站非预期操作，OpenAI 指南也将工具选择与执行分阶段。因此执行验证必须在模型外，通过白名单、参数校验、成本检查和人工批准来设防，避免提示注入直接触发危险操作。
一次性审批令牌如何防重放
写操作需人工批准，批准后生成一次性令牌，与计划 ID 绑定。执行时校验令牌并立即移除，防止重放。示例中退款首次批准后成功，复用同一令牌再次请求返回 PENDING。生产环境还需将令牌与操作者、有效期绑定，并在事务数据库中原子消费，避免并发绕过。
累计预算与成本控制
所有工具调用共享累计预算，Ledger 记录已花费金额，超过限额则拒绝。示例用 Decimal 避免浮点误差，但内存账本重启丢失，生产需在数据库原子扣减。文章提醒不能只按模型 token 预算，搜索、数据库、云资源和退款各有成本与损害面，需按外部动作成本设限。
适用边界与工程化建议
该闸门适合工单、运营辅助、内部查询等需人确认的自动化，但不能替代访问控制、支付风控或法律审批。高风险场景需更严格制度。工程化下一步包括 PENDING 队列、审批 UI、到期失效、幂等重试、回滚补偿和红队测试，并记录不可篡改审计事件，但日志中不应存密钥和完整支付信息。
Q&A
为什么不能让模型直接执行它输出的函数？
模型只能提出计划，真正的执行者应该验证它是否在许可范围内、参数是否合理、成本是否超标，以及一个人是否明确批准了这次有副作用的操作。边界必须在模型外部、可记录、可撤销。
如何用Python实现Agent工具调用的安全闸门？
用不到100行Python写一个可测试的闸门：查询类工具可自动放行，退款等写操作需要一次性审批令牌，所有操作共享累计预算。代码中定义Ledger类管理预算和审批，gate函数验证工具名、参数、成本，并记录审计事件。
审批令牌为什么必须是一次性的？
令牌应与计划、操作者、有效期绑定，并一次性消费。否则攻击者可以在网页显示“已批准”后重放令牌。代码中在批准后从approvals集合中移除令牌，确保一次性使用。
累计预算在Agent工具调用中起什么作用？
所有操作共享累计预算，防止成本超标。Ledger类记录已花费金额，gate函数检查当前花费加上预估成本是否超过限额，超过则拒绝。这避免了只按模型token预算而忽略外部动作成本的问题。
参数白名单如何防止提示注入攻击？
valid_args函数是最小schema，拒绝未知工具、过长订单号和非正金额。生产中使用JSON Schema或Pydantic，并为每个工具定义租户、用户角色、资源归属、金额上限和允许时间窗。只显式登记白名单，避免把tool_name直接映射到任意反射调用。
这套安全闸门适合哪些场景？
适合工单、运营辅助、内部查询和需人确认的自动化。不适合替代访问控制、支付风控或法律审批；高风险医疗、信贷、武器和人事决策需要更严格的制度与人工责任。
