如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

程式化工具呼叫

讓模型撰寫並執行 JavaScript,協調多個工具呼叫。

透過程式化工具呼叫,模型可以撰寫並執行 JavaScript,協調各項工具的使用。程式可以平行呼叫工具、使用迴圈與條件判斷,並將中間結果保留在代管執行環境中。當任務需要依序執行一系列相關的工具呼叫,或需要先處理大量工具輸出再傳回結果時,就適合使用這項功能。

在 Responses API 中,你的應用程式決定是否啟用程式化工具呼叫,以及模型可以直接呼叫哪些工具、透過程式呼叫哪些工具,或對哪些工具採用任一種方式。這些工具必須支援對應的呼叫方式。所有由用戶端負責的工具呼叫仍由你的應用程式執行。Agents API 預設啟用程式化工具呼叫,並代你管理智慧體的執行迴圈。

啟用程式化工具呼叫前,請先查看模型頁面。

瞭解執行環境

OpenAI 會在全新且隔離的 V8 執行環境中執行每個產生的程式。此環境支援使用頂層 await 的 JavaScript,但不提供 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-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 回應的迴圈適用於 Responses API 整合。

程式化工具呼叫也適用於純對話工作階段,即 environment.type 設為 none 的情況。Bash、執行器 MCP 和其他在沙盒中執行的工具仍需要執行環境。

透過 JavaScript 協調工具呼叫,不會改變工具的執行位置。Shell 呼叫會在沙盒中執行指令,JavaScript 執行環境本身不會啟動系統程序。執行器 MCP 仍使用沙盒,函式工具仍會呼叫你的應用程式伺服器。智慧體會先處理這些工具的結果,再決定將哪些內容加入模型上下文。

請依照上述指引,指定工作流程中哪些階段應使用程式碼。關於 Agents API 的設定與呼叫處理方式,請參閱函式和 MCP 連線。

相關指南

  • 使用函式呼叫定義由用戶端負責的函式。
  • 使用工具搜尋,等到模型需要時才載入大型工具定義。
  • 使用對話狀態接續已儲存回應或採用無狀態模式的 Responses API 請求。
  • 選擇儲存模式前,請先查看資料控制。