OpenAI allowed_tools 怎么用:控制工具权限又保留提示词缓存

依据 OpenAI Function calling 和 Prompt caching 文档,固定工具定义、逐请求限制可调用集合,并核验权限与缓存命中。

关键词
LALondAI 内容团队发布日期 2026-11-22
6 分钟阅读模型教程
LA
OpenAI allowed_tools 怎么用:控制工具权限又保留提示词缓存
OpenAI allowed_tools官方来源与可执行检查LondAI 内容团队

Agent 的工具集合可能稳定,但每个用户能调用的工具不同。OpenAI Responses API 的 tool_choice.allowed_tools 可在保留同一份 tools 定义时,限制本次可调用的子集;这样也避免每次删改工具列表导致提示词缓存前缀变化。它只是模型侧选择约束,真正执行前仍须由应用再次鉴权。

四种选择方式的区别

OpenAI 函数调用指南说明 tool_choice: "auto" 可调用零个或多个工具,"required" 要求至少调用一个,强制指定函数会要求调用那个函数,allowed_tools 则限制可调用名单。示例形状为 {"type":"allowed_tools","mode":"auto","tools":[{"type":"function","name":"search_docs"}]}。若本次不允许工具,设置 tool_choice: "none",不必从 tools 中删除定义。parallel_tool_calls: false 可限制单轮最多一个函数调用,但不能替代权限检查。

缓存收益取决于前缀是否稳定

OpenAI 提示词缓存文档说明工具名称、描述、Schema 和顺序是可缓存前缀的一部分。若每个用户都动态删改这些定义,后续请求可能无法复用前缀。编辑建议是保持工具定义和顺序稳定,把按用户变化的授权放进 allowed_tools;再用官方 usage 或缓存诊断核对命中。缓存是否产生以及节省多少取决于模型、前缀和真实流量,不是配置后必然发生。

一个两用户测试

  1. 在获授权的官方测试项目中声明 search_docs 与 create_ticket 两个无副作用的模拟函数,固定名称、Schema 和顺序。
  2. 用户甲的请求仅允许 search_docs;用户乙允许两者。分别构造“检索文档”和“创建工单”指令,检查模型输出的函数名,并记录相同前缀的缓存 usage。
  3. 应用执行任何函数前,按当前用户、资源与操作再次做服务端授权。即使模型返回 create_ticket,用户甲也应被拒绝,不能只相信请求里的 allowed_tools。
  4. 再用 tool_choice: "none" 测试只回答不调用工具;比较删改工具定义与保留定义时的缓存诊断和输入成本,记录真实差异。

模型权限不是业务权限

OpenAI 文档定义的是模型可调用范围,没有为应用维护用户角色、审批或审计。高影响动作仍应由后端核验参数、记录操作者并设置人工确认。避免把个人资料或密钥放进工具描述来换取缓存命中。本文未验证 LondAI 是否透传 allowed_tools,没有修改本站鉴权、网关、计费或数据库。

验收标准

至少验证允许工具可调用、禁止工具无法执行、无工具模式、工具 Schema 顺序变化引起的缓存差异及服务端越权拦截。留存脱敏请求 ID、调用结果和实际 usage;本站接入方式见API 文档,工具授权设计参照Agent 工具白名单。