OpenAI Programmatic Tool Calling 怎么用？JavaScript 工具编排教程

Programmatic Tool Calling 解决什么问题？

普通工具循环常把每次工具结果交给模型再决定下一步。结果多、字段大或控制流固定时，中间内容会反复进入上下文。Programmatic Tool Calling（PTC）让模型生成 JavaScript，把中间结果保留在运行时变量中，并在代码内完成并行调用、循环、条件分支与结构化压缩。

运行时边界：它不是 Node.js 容器

OpenAI 会为每段生成程序启动新的隔离 V8 运行时。它支持 JavaScript 和顶层 await，但官方明确说明没有 Node.js、包安装、直接网络访问、通用文件系统、子进程、console 或跨程序持久 JavaScript 状态。

• 外部系统只能通过请求中已启用的 tools.* 访问。
• 程序用 text(...) 或 image(...) 发出最终结果。
• 客户端函数仍在你的应用服务器执行，V8 只负责编排。
• 每次程序都要把必要状态从工具结果或当前响应项目中重新获得。

Responses API 最小配置

下面把库存和需求查询仅开放给 program。parameters 约束输入，output_schema 描述函数结果 JSON 的稳定字段；使用前仍需在官方模型页确认所选模型支持 PTC。

import OpenAI from "openai";

const client = new OpenAI();

const tools = [
  {
    type: "function",
    name: "get_inventory",
    description: "Return stock for one SKU.",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        available_units: { type: "number" }
      },
      required: ["sku", "available_units"],
      additionalProperties: false
    },
    allowed_callers: ["programmatic"],
    strict: true
  },
  {
    type: "function",
    name: "get_demand",
    description: "Return requested units for one SKU.",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        requested_units: { type: "number" }
      },
      required: ["sku", "requested_units"],
      additionalProperties: false
    },
    allowed_callers: ["programmatic"],
    strict: true
  },
  { type: "programmatic_tool_calling" }
];

const response = await client.responses.create({
  model: "gpt-6-astra",
  store: false,
  tools,
  input: "比较 sku_123 的库存与需求，只返回缺口摘要。"
});

allowed_callers 三种设置

不要只写“高效使用 PTC”。官方建议把路由写具体：哪个有界阶段使用程序、可用哪些工具、何时并行、程序最终必须输出什么结构、停止条件、重试次数，以及哪些判断或审批必须回到直接调用。

output_schema 为什么重要？

程序会直接读取工具返回字段；如果结果只是自然语言，模型生成的 JavaScript 可能猜错字段或解析失败。为可预测结果定义 output_schema，并把实际对象编码为 function_call_output.output 字符串。若返回形态不可预期，就不要强行程序化，改用直接调用让模型查看结果。

• 返回紧凑结构，不要把大段无关日志塞给程序。
• 记录明确的错误字段、可重试类型和终止条件。
• 需要证据时，把证据字段写入程序最终结果 Schema。
• 函数尽量幂等，避免重放或重试重复产生副作用。

识别 program、function_call 与 program_output

PTC 不会创建新的响应信封，仍返回标准 Responses 对象。response.output 可能包含以下顶层项目：

客户端函数回传循环

你的应用仍要运行每个客户端函数，并把结果送回正确的 program。回传时保留函数的 call_id，还要原样复制 caller；否则服务无法恢复对应程序。

const calls = response.output.filter(
  (item) => item.type === "function_call"
);

const outputs = await Promise.all(calls.map(async (call) => ({
  type: "function_call_output",
  call_id: call.call_id,
  caller: call.caller,
  output: JSON.stringify(
    await implementations[call.name](JSON.parse(call.arguments))
  )
})));

// store:false：继续请求时按原顺序重放完整 response.output，
// 再追加 outputs；不能只保留 function_call。

循环要处理暂停多次、incomplete 状态和无待处理函数但尚未出现最终 message 的情况。存储响应可使用 previous_response_id；store:false 时要完整重放 program、reasoning、function_call、function_call_output 与 program_output。最终只在收到 message 后读取 response.output_text 或 refusal。

程序适合怎样编排工具？

const [stock, demand] = await Promise.all([
  tools.get_inventory({ sku: "sku_123" }),
  tools.get_demand({ sku: "sku_123" })
]);

text(JSON.stringify({
  sku: stock.sku,
  available_units: stock.available_units,
  requested_units: demand.requested_units,
  shortage_units: Math.max(
    demand.requested_units - stock.available_units,
    0
  )
}));

这类流程适合 PTC，因为两个只读调用可安全并行，字段稳定，最后只需返回四个数字。若下一步要根据语义质量决定搜索方向，或要修改库存，则应退出程序阶段，由模型直接判断并由应用审批写操作。

与 Tool Search 怎样配合？

Tool Search 先解决“大目录里要加载哪些工具”，PTC 再解决“已加载工具如何用代码编排”。Tool Search 是顶层工具，正在运行的 JavaScript 不能直接搜索工具。

1. 函数、custom 或 MCP 先设置 defer_loading:true。
2. 模型在顶层执行 Tool Search 并加载需要的定义。
3. 工具还需允许 allowed_callers 包含 programmatic。
4. 后续 program 才能通过 tools.* 调用它们。

支持的工具与审批边界

官方当前列出的可编程调用类型包括 function、custom、MCP、Apply Patch、本地和托管 Shell、Code Interpreter。MCP 的 require_approval 可以暂停程序等待审批。工具进入 program 不会改变它真正运行的位置：Shell 仍在沙箱，MCP 仍连接相应服务器，函数仍由你的应用执行。

ZDR 与数据保留要单独核对

Responses API 的 PTC 可以支持 Zero Data Retention 工作流，而且不要求持久代码执行容器，但 ZDR 必须先为组织或项目启用。store:false 只代表无状态续接，并不会自动启用 ZDR；最终资格取决于完整请求中的模型、工具和第三方服务。

如何评测成本与质量

PTC 可能减少进入模型上下文的中间工具输出，但不能只看 Token。先以直接调用建立基线，再用相同真实任务比较：

• 最终答案正确性、完整性和证据覆盖。
• 输入 Token、总 Token、端到端延迟和总成本。
• 模型轮次、工具调用数、重试与恢复次数。
• 副作用、审批、越权和错误降级结果。
• 实际走的调用路径是否符合设计阶段。

常见错误与排查顺序

1. 没有 program：确认模型支持，并在 tools 中加入 programmatic_tool_calling。
2. 工具不可用：检查 allowed_callers 是否包含 programmatic；延迟工具是否已经先由 Tool Search 加载。
3. 字段为 undefined：检查 output_schema 和实际 output JSON 是否一致。
4. 程序无法恢复：回传时是否保留原 call_id 与 caller。
5. 无限续接：明确停止条件、最大轮次、重试和 incomplete 处理。
6. 结果缺证据：把必需证据字段写进程序最终结果，不要只返回结论。
7. 出现越权写入：缩小 allowed_callers，把高风险动作改为直接调用和审批。

上线前检查清单

• 在官方模型页确认生产模型支持 Programmatic Tool Calling。
• 逐个标注工具是 direct、programmatic 还是两者，默认最小授权。
• 为稳定工具结果定义 output_schema、错误形态和幂等行为。
• 循环完整处理 program、caller、function_call、program_output、message 和 incomplete。
• 限制程序可用工具、最大轮次、重试、超时和结果大小。
• 用直接调用基线比较质量、证据、Token、延迟、成本与安全。
• 对写操作、审批、引用与原生文件保留直接验证路径。

常见问题

官方资料

• OpenAI：Programmatic Tool Calling
• OpenAI：Using tools
• OpenAI：API deployment checklist
• OpenAI：Tool Search

本文核对日期为 2026-11-01。模型支持、工具类型、响应项目、ZDR 资格和 SDK 辅助函数可能调整；生产上线前请重新读取 Programmatic Tool Calling、Tools、Deployment checklist 与模型页。