程序化工具调用让模型可以编写并运行 JavaScript 来协调多个工具的使用。程序可以并行调用工具,使用循环和条件判断,并将中间结果保存在托管运行时中。这适用于需要依次执行多个相关工具调用,或需要先处理大量工具输出再返回结果的任务。
在 Responses API 中,您的应用决定是否启用程序化工具调用,并为每个支持此功能的工具指定调用方式:由模型直接调用、通过程序调用,或两种方式均可。由客户端负责的工具调用仍由您的应用执行。Agents API 默认启用程序化工具调用,并为您管理智能体的执行循环。
启用程序化工具调用前,请查看模型页面。
了解运行时环境
OpenAI 在全新的、相互隔离的 V8 运行时中运行每个生成的程序。该运行时支持在 JavaScript 顶层使用 await,但不提供 Node.js、软件包安装、直接网络访问、通用文件系统、子进程执行或控制台,也不会在多次程序执行之间保留 JavaScript 状态。程序只能通过请求中启用的工具与外部系统交互,并可使用 text(...) 或 image(...) 输出结果。
对于 Responses API 请求,程序化工具调用支持零数据保留(ZDR)工作流,无需持久化的代码执行容器。您必须为组织或项目启用 ZDR。设置 store: false 可以无状态地继续处理请求,但仅此设置无法启用 ZDR。请求是否符合 ZDR 条件以及适用的数据保留规则取决于完整请求,包括所用的模型、工具和第三方服务。请参阅数据控制。
选择何时使用程序化工具调用
如果某个阶段的控制流可预测,且代码能返回更精简的结构化结果,请使用程序化工具调用。如果一次调用就足够、每次得到结果后都需要模型重新判断,或者任务需要审批、保留引用或保留原生制品,请直接调用工具。
| 任务类型 | 推荐方式 |
|---|---|
| 单次查询或操作 | 直接调用工具。 |
| 可以用代码对多个结果进行筛选、关联、排序、去重、聚合或验证 | 如果程序能返回更精简的结构化结果,请使用程序化工具调用。 |
| 调用之间存在依赖关系,且数据流可预测 | 如果代码能推导出后续调用的参数,且已明确调用限制和失败时的处理方式,请使用程序化工具调用。 |
| 自适应搜索或语义评估 | 如果每次调用的结果都应影响模型的下一步决策,请直接调用工具。 |
| 写入操作或对审批有要求的操作 | 默认直接调用工具,以保持清晰的授权边界。 |
| 最终核验引用或原生制品 | 请直接调用工具,除非程序能保留原生输出并验证每个必需项。 |
配置程序化工具调用
使用 Responses API 时,请将 programmatic_tool_calling 托管工具添加到请求中。然后,为程序可以调用且支持此功能的每个工具设置 allowed_callers。
[
{
"type": "function",
"name": "get_inventory",
"description": "Return an object with sku (string) and available_units (number).",
"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"]
},
{
"type": "programmatic_tool_calling"
}
]allowed_callers 控制模型可以如何调用工具:
| 值 | 行为 |
|---|---|
省略或设为 ["direct"] |
模型可以直接调用工具。 |
["programmatic"] |
只有 program 项中的代码可以调用工具。 |
["direct", "programmatic"] |
模型可以直接调用工具,也可以通过程序调用。 |
parameters 描述函数的参数。如果函数返回结构可预测的数据,output_schema 描述其 function_call_output.output 字符串中编码的 JSON 对象。请同时定义两者,以便生成的 JavaScript 能可靠地使用返回的字段。
支持的工具
以下工具类型支持 allowed_callers: ["programmatic"]:
function和custommcpapply_patch- 本地和托管的
shell code_interpreter
对于 MCP 工具,工具的 require_approval 审批策略可以暂停程序,直到您批准调用。
对于 OpenAI 托管的工具,请先查阅该工具的数据保留和安全指南,再允许程序调用它。
与工具搜索配合使用
工具搜索作为 Responses API 的顶层工具运行,无法从生成的 JavaScript 内部调用。设置了 defer_loading: true 的函数工具、自定义工具和 MCP 工具最初都不可供程序使用。模型加载匹配的工具后,后续程序可以通过 tools.* 调用它,前提是该工具的 allowed_callers 包含 "programmatic"。已经运行的程序无法调用工具搜索,因此模型必须先加载程序所需的延迟加载工具,再启动程序。
指定两种模式均可用时的调用方式
如果您的应用允许模型直接调用函数,也允许通过程序调用,请为每种调用方式指定适用的工作流阶段。“高效使用程序化工具调用”之类的笼统指令无法明确两种方式各自适用的范围。例如:
<tool_orchestration>
在 [bounded stage] 阶段使用程序化工具调用,只调用 [eligible tools]。
在安全的前提下,并发执行相互独立的调用。只使用工具文档中列出的输入和输出字段。
处理并精简中间结果,然后严格按照 [program result shape] 输出结果,其中必须包含最终答案所需的依据。
满足 [condition] 时就停止。遇到暂时性故障时,最多重试 [R] 次。
不要重复已完成的调用,也不要执行会产生副作用的操作。如果仍缺少必需的结果,请返回结构化的失败信息,清楚说明失败情况。
对于 [semantic judgment, approval, or final validation],请直接调用工具。
</tool_orchestration>
以下示例展示了如何使用此模板:
<tool_orchestration>
使用程序化工具调用比较 sku_123 的库存量与需求量,只调用 get_inventory 和 get_demand。
并发执行这两个调用。只使用工具文档中列出的输入和输出字段。
处理并精简中间结果,然后只输出一个 JSON 对象,包含 sku、available_units、requested_units 和 shortage_units 字段。
将 shortage_units 的值设为 max(requested_units - available_units, 0)。在输出中保留 available_units 和 requested_units 作为计算依据。
两个工具返回的结果都包含必需字段时就停止。遇到暂时性故障时,最多重试 1 次。
不要重复已完成的调用,也不要执行会产生副作用的操作。如果仍缺少必需的结果,请返回结构化的失败信息,清楚说明失败情况。
执行任何会改变库存的操作前,必须先直接调用工具获得批准。仅在此审批步骤直接调用工具。
</tool_orchestration>
对于需要两种模式的工作流,请指定一个交接点,避免来回切换调用方式或重复执行任务。如果有安全的回退方案,只需定义一次,并限制重试次数。
了解与程序相关的响应项
每次 API 调用仍会返回标准的 Responses API 对象。程序化工具调用没有单独的响应封装格式。模型使用程序化工具调用时,响应的 output 数组可以包含以下项:
program项包含生成的 JavaScript、一个call_id和一个不透明的fingerprint,后者用于恢复或重放程序。function_call项表示程序发起的函数调用。它有自己的call_id,您的应用使用该标识符返回函数结果。它的caller.caller_id与程序的call_id一致。program_output项包含程序的最终结果和状态。它的call_id与程序的call_id一致,status为completed或incomplete。
这些项都是 response.output 中独立的顶层项,caller 字段记录它们之间的调用关系。
例如,程序可以暂停,等待您的应用执行 get_inventory 和 get_demand:
[
{
"type": "program",
"id": "prog_123",
"call_id": "call_prog_123",
"code": "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) }));",
"fingerprint": "opaque_replay_state"
},
{
"type": "function_call",
"id": "fc_123",
"call_id": "call_inventory_123",
"name": "get_inventory",
"arguments": "{\"sku\":\"sku_123\"}",
"caller": {
"type": "program",
"caller_id": "call_prog_123"
}
},
{
"type": "function_call",
"id": "fc_456",
"call_id": "call_demand_123",
"name": "get_demand",
"arguments": "{\"sku\":\"sku_123\"}",
"caller": {
"type": "program",
"caller_id": "call_prog_123"
}
}
]这些示例仅展示 response.output 中的相关项,省略了外层的标准 Responses 对象。您的应用返回嵌套函数调用的结果后,后续响应可以包含完整的 program_output 项:
{
"type": "program_output",
"id": "prog_out_123",
"call_id": "call_prog_123",
"result": "{\"sku\":\"sku_123\",\"available_units\":42,\"requested_units\":31,\"shortage_units\":0}",
"status": "completed"
}program_output.result 中的 JSON 字符串遵循您在指令中指定的程序结果格式。外层 program_output 项遵循上文展示的 API 规范。两者各有独立的格式要求。最终的 message 可能与程序输出一同返回,也可能出现在后续响应中,因此请继续处理,直到收到该消息。
OpenAI 在托管运行时中运行模型生成的 JavaScript。您的应用负责执行返回的客户端函数调用,不执行生成的 JavaScript。
请以 function_call_output 的形式返回函数结果,并原样复制函数调用中的 caller。服务使用该值恢复对应的程序。
在客户端执行函数调用后继续运行
程序每次需要调用由客户端执行的工具时都可能暂停,因此同一程序可能暂停多次。请按以下步骤继续,直到响应中包含助手的最终消息:
- 发送请求,其中包含托管工具和允许程序化调用的函数。
- 执行返回的所有客户端函数调用。
- 返回每个函数结果,并附上原始的
call_id和caller。 - 如果响应不完整,请先处理,再继续。
- 如果响应中既没有待处理的
function_call项,也没有最终的message项,请从该响应继续。如果设置了store: false,请重放该响应的输出项。如果已存储该响应,请使用previous_response_id。 - 当响应中包含最终的
message项时停止。读取response.output_text或消息中的拒绝内容。
以下示例使用 store: false,保留每个响应项,并将每个函数结果返回给程序:
import json
from openai import OpenAI
client = OpenAI()
model = "gpt-6.2-astra"
def get_inventory(sku):
return {"sku": sku, "available_units": 42}
def get_demand(sku):
return {"sku": sku, "requested_units": 31}
implementations = {
"get_inventory": get_inventory,
"get_demand": get_demand,
}
tools = [
{
"type": "function",
"name": "get_inventory",
"description": "Return an object with sku (string) and available_units (number).",
"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"],
},
{
"type": "function",
"name": "get_demand",
"description": "Return an object with sku (string) and requested_units (number).",
"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"],
},
{"type": "programmatic_tool_calling"},
]
input_items = [
{
"role": "user",
"content": "Compare inventory with demand for sku_123.",
}
]
while True:
response = client.responses.create(
model=model,
store=False,
input=input_items,
tools=tools,
)
if response.status != "completed":
raise RuntimeError(f"Response ended with status {response.status}")
# Preserve every output item, including program and reasoning items.
input_items.extend(item.model_dump(exclude_none=True) for item in response.output)
calls = [item for item in response.output if item.type == "function_call"]
if not calls:
message = next(
(item for item in response.output if item.type == "message"), None
)
if message:
refusal = next(
(part.refusal for part in message.content if part.type == "refusal"),
"",
)
print(response.output_text or refusal)
break
continue
for call in calls:
run = implementations.get(call.name)
if run is None:
raise ValueError(f"Unknown tool: {call.name}")
result = run(**json.loads(call.arguments))
input_items.append(
{
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result),
# Preserve caller so the runtime can resume the correct program.
"caller": call.caller.model_dump() if call.caller else None,
}
)如果您存储了响应,可以使用 previous_response_id 继续,无需重新发送之前的所有响应项。将新的 function_call_output 项作为下一次输入发送。如果设置了 store: false,请按顺序重放完整序列,包括所有 program 项、推理项、函数调用项、函数调用输出项和 program_output 项。
对于发给推理模型的无状态请求,请重放返回的每个推理项。每个推理项默认都包含 encrypted_content。有关无状态请求的通用处理方式,请参阅对话状态。
为程序设计工具
- 返回精简的结构化数据,以便 JavaScript 直接读取,无需解析自然语言文本。
- 使用
output_schema定义每个工具预期返回的字段及其类型,并说明出错时的行为。如果无法预先确定返回结果的结构,请将工具设为仅允许直接调用,以便模型检查结果。 - 明确定义程序结果的格式以及必须提供的依据。如果程序无法生成有效结果,请以结构化形式清楚地说明失败情况。
- 尽可能让函数调用具有幂等性。重试或重放时,不应重复产生不安全的副作用。
- 在您的应用中检查每次调用的参数和权限,即使调用来自托管程序也要检查。
- 为工具提供具体的名称和描述,以便模型正确组合使用它们。
- 无论调用方是谁,影响重大的操作都必须先在应用层获得审批。
评估程序化工具调用
程序化工具调用可以减少进入模型上下文的中间工具输出,具体效果取决于任务和工具响应。请先以直接工具调用为基准,再选取有代表性的任务比较两种方式。
衡量效率前,请先确定最终答案的质量标准以及必须提供的依据。评估 Token 用量和工具调用次数时,也要评估答案的正确性、完整性和证据覆盖情况,并明确说明您愿意接受哪些质量上的取舍。
请衡量以下指标:
- 最终答案的正确性、完整性和证据覆盖情况。
- 输入 Token 数、Token 总数、端到端延迟和成本。
- 模型交互轮数、工具调用次数、重试次数以及发生故障后的恢复情况。
- 实际运行的安全性,尤其是操作产生的副作用以及是否满足审批要求。
- 实际使用的调用方式是否符合对应工作流阶段的设计。
Agents API
在 Agents API 中,程序化工具调用在 OpenAI 管理的智能体执行框架中运行,并且默认启用。执行框架为智能体提供 exec 工具,并允许生成的 JavaScript 调用智能体已有的工具。您无需将这些工具封装为命令行程序,也无需在沙盒中安装它们。
要禁用程序化工具调用,请在 agent.tools 中添加以下配置项:
{
"type": "programmatic_tool_calling",
"enabled": false
}
如果省略该配置项或其中的 enabled 字段,程序化工具调用会保持启用。只指定类型的配置项 { "type": "programmatic_tool_calling" } 也会保持启用状态。上文的 allowed_callers 配置和用于继续处理响应的循环适用于 Responses API 集成。
程序化工具调用也适用于将 environment.type 设为 none 的纯对话会话。Bash、执行器 MCP 和其他在沙盒中运行的工具仍需要执行环境。
使用 JavaScript 编排工具调用不会改变工具的运行位置。shell 调用会在沙盒中运行命令,JavaScript 运行时本身不会启动系统进程。执行器 MCP 仍使用沙盒,函数工具仍调用您的应用服务器。智能体先处理这些工具的结果,再决定将哪些内容加入模型上下文。
请参照上文关于调用方式的说明,明确哪些工作流阶段应使用代码。有关 Agents API 的配置和调用处理,请参阅函数和 MCP 连接。