如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

程序化工具调用

让模型编写并运行 JavaScript 来编排工具调用。

程序化工具调用让模型可以编写并运行 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 和 custom
  • mcp
  • apply_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。服务使用该值恢复对应的程序。

在客户端执行函数调用后继续运行

程序每次需要调用由客户端执行的工具时都可能暂停,因此同一程序可能暂停多次。请按以下步骤继续,直到响应中包含助手的最终消息:

  1. 发送请求,其中包含托管工具和允许程序化调用的函数。
  2. 执行返回的所有客户端函数调用。
  3. 返回每个函数结果,并附上原始的 call_id 和 caller。
  4. 如果响应不完整,请先处理,再继续。
  5. 如果响应中既没有待处理的 function_call 项,也没有最终的 message 项,请从该响应继续。如果设置了 store: false,请重放该响应的输出项。如果已存储该响应,请使用 previous_response_id。
  6. 当响应中包含最终的 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 连接。

相关指南

  • 使用函数调用定义由客户端执行的函数。
  • 使用工具搜索延迟加载体积较大的工具定义,直到模型需要时再加载。
  • 使用对话状态继续处理 Responses API 请求,无论是使用已存储的响应还是采用无状态模式。
  • 选择存储模式前,请查阅数据控制。