Python Agent工具调用的白名单、参数校验与审批门禁
内容提要
文章以Python示例说明Agent工具调用安全：模型仅建议调用，应用须设白名单、参数校验、预算与人工审批。代码只允许search_kb和draft_email，邮件参数须精确匹配，搜索限3次，允许后仍返回待审批。强调不信任模型输出，适合低风险场景，付款、删数据等须人工确认。
延伸解读
为什么函数调用不等于授权
文章指出，Gemini API 的函数调用流程是模型提出调用建议，应用负责执行。这意味着模型输出只是建议，不能作为授权依据。如果应用直接执行模型返回的函数名和参数，就可能被诱导调用删除工具等危险操作。因此，必须在应用层独立设置白名单、参数校验和审批门禁，而不是依赖提示词或模型自身的安全判断。
参数精确匹配如何降低风险
示例中邮件工具要求参数集合必须精确等于 {customer_id, template}，模板也只能是 follow_up 或 receipt_request。这种严格校验能防止模型在参数中夹带额外字段，比如多塞一个收件人或“立即发送”开关。文章强调，只校验函数名不校验参数是常见错误，因为攻击者可能通过合法函数名传入恶意参数。
预算与审批门禁的工程意义
搜索工具累计上限为 3 次，超过则 blocked；即使允许，execute 也只返回 needs_approval，不直接发送邮件。这体现了预算控制和人工确认的双重防线。文章提醒，重试时不要重置预算，否则限制形同虚设。实际接入 API 时，还应关联用户身份、租户、请求 ID 和幂等键，以便审计和限流。
适用边界与不适用场景
文章明确，这套门禁适合知识检索、草稿生成和低风险查询，但不适合无审批地付款、删除数据、修改权限或向外部发送不可撤回消息。对于这些高风险操作，必须保留人工确认。工程化可进一步加入 JSON Schema、审计事件、租户级速率限制、审批时效和回放测试，以提升安全性和可维护性。
Q&A
Agent工具调用安全的核心原则是什么？
模型决定“建议调用什么函数”，应用决定“是否真的调用”。应用必须对工具调用进行独立的白名单、参数校验、预算和人工审批，不能信任模型输出。
如何用Python实现Agent工具调用的白名单和参数校验？
定义ALLOWED集合限制可调用工具（如search_kb和draft_email），在authorize函数中检查工具名是否在白名单，并对参数进行校验：search_kb要求query为非空字符串且长度≤120，draft_email要求参数集合精确匹配{customer_id, template}且template在批准列表中。
为什么即使工具调用被允许，仍然需要人工审批？
因为模型可能被诱导或出错，允许调用不代表可以自动执行。例如发送邮件等操作不可撤回，必须人工确认。代码中execute函数即使允许也只返回needs_approval状态，不直接执行。
Agent工具调用中如何设置预算限制？
可以为特定工具设置累计调用上限，例如搜索工具MAX_SEARCHES=3，每次调用时检查已用次数，超过则拒绝。重试时不应重置预算。
哪些场景适合使用这种工具调用门禁？哪些不适合？
适合知识检索、草稿生成和低风险查询；不适合无审批地付款、删除数据、修改权限或向外部发送不可撤回消息。
接入真实API时，除了白名单和参数校验，还需要考虑哪些安全措施？
应为每个tool call关联用户身份、租户、请求ID和幂等键；可进一步加入JSON Schema、审计事件、租户级速率限制、审批时效和回放测试。
