透過程式化工具呼叫,模型可以撰寫並執行 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和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-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 連線。