驅動程式會將允許的工具呼叫轉換成動作,在你控制的瀏覽器或桌面中執行。如果應用程式可以回報網頁文字、控制項與分頁,請使用瀏覽器驅動程式。如果模型必須依據螢幕截圖與座標操作,請使用電腦驅動程式。SDK 負責傳送請求與分派呼叫,應用程式則負責管理工作階段、權限與資源清理。
設定常用控制選項
先參閱 Python 或 Node 的瀏覽器範例。範例包含完整的驅動程式、確認政策,以及設有請求次數上限的 Responses 執行流程。請保持工作階段開啟,直到執行結束。Python 也提供同步的 BrowserToolset 和 ResponsesToolRunner 類別,供同步驅動程式使用。
| 目標 | 設定位置 | 預期行為 |
|---|---|---|
| 限制瀏覽器方法 | 請設定 members,在建立 BrowserToolset 或 AsyncBrowserToolset 時傳入。 |
只會開放已選取且已實作的方法。若要以唯讀方式使用範例驅動程式,只選取 read_page。請參閱選取方法。 |
| 核准瀏覽器變更 | 將 confirm 傳給 BrowserToolset 或 AsyncBrowserToolset 建構函式。 |
只有回傳值恰為 true 或 True 才會允許提議的動作。請檢查動作的成員、目標與引數。請參閱核准動作。 |
| 限制瀏覽器導覽 | 將 Node 的 urlPolicy 或 Python 的 url_policy 傳給 BrowserToolset 或 AsyncBrowserToolset 建構函式。 |
啟用 navigate 或 new_tab 時必須設定。SDK 會先檢查請求的 URL,再要求確認。請參閱限制 URL。 |
| 核准原生電腦動作 | 使用 ResponsesToolRunner 時,在 Node 的執行選項中設定 computerOptions。在 Python 中,將 approve_safety_checks 和 before_action 傳給 run。 |
待處理的安全檢查需要明確核准。選用的動作前回呼可以拒絕任何單一動作。請參閱核准電腦動作。 |
| 限制每次執行的請求數 | 在 Responses 執行器的執行選項中設定 Node 的 maxSteps 或 Python 的 max_steps。 |
預設上限為 20 個請求。最後一個允許的請求無法啟動會產生新作用的操作。 |
| 衡量用量 | 將 Node 的同步回呼 onDiagnostic 或 Python 的同步回呼 on_diagnostic 傳給 ResponsesToolRunner.run。 |
加總已完成請求記錄中的 Token 用量。如果任何已完成的請求缺少用量,請註明總計不完整。請參閱查看用量與耗時。 |
核准動作並管理工作階段
請在受信任的應用程式程式碼中建立驅動程式與核准回呼。將可執行的設定與不受信任的網頁資料分開,並透過驅動程式宣告的回報欄位傳回網頁資料。
如果選取的瀏覽器方法會改變狀態或讀取診斷資料,就必須提供 confirm。只有在 Node 中回傳值恰為 true,或在 Python 中恰為 True,才會核准動作。navigate 和 new_tab 還需要 urlPolicy(Node)或 url_policy(Python)。兩個回呼都會收到一個獨立物件,其中包含 member、已驗證的 arguments、先前的 state 和 call_id。URL 政策回呼還會收到請求的 URL。修改這個物件無法改變已驗證的動作。
confirm 核准的是引數已固定的動作。其 state 是先前觀察到的狀態,不會鎖定文件或目前取得焦點的控制項。使用者考慮是否核准時,網頁仍可能導覽至其他位置或改變焦點。如果同意僅適用於特定網頁或控制項,驅動程式就必須在執行時檢查原始目標。在這類流程中,請停用 key,並拒絕目標為 null 的 type 動作,因為兩者都會使用當下的焦點。其他依賴瀏覽器目前狀態的動作,也應以同等方式綁定目標。
若要在讀取私人網頁前詢問使用者,請在 confirmReads(Node)或 confirm_reads(Python)中列出需要確認的讀取方法。對這些方法,SDK 會先執行同一個 confirm 回呼,再透過驅動程式讀取任何狀態或內容。此時上下文包含 phase: "before_read",且在 Node 中為 state: null,在 Python 中狀態值為 None。處理這種情況時,請勿讀取網頁中繼資料。若拒絕讀取,就不會傳回網頁內容或狀態。未設定此選項時,既有讀取操作的行為不變,強制性的動作核准要求仍然適用。
對於電腦呼叫,必須先逐項核准所有待處理的安全檢查,輔助程式才能執行任何動作。Node 的 approveSafetyChecks 和 Python 的 approve_safety_checks 必須回傳布林值 true。缺少回呼或回呼拒絕核准時,執行就會停止。選用的 beforeAction 或 before_action 會在每個動作執行前立即檢查,包括最後擷取螢幕截圖的動作。如果提供此回呼,也必須明確核准。模型選擇的動作或完成訊息都不能代為核准。請參閱電腦操作安全指引。
Node 會將 { signal } 作為最後一個引數傳給兩個電腦核准回呼。Python 會在回呼接受 cancelled 關鍵字引數時提供此選用引數。既有的回呼即使接受較少引數,仍可使用。執行停止時,可利用此上下文關閉仍在等待回應的核准提示。輔助程式會等回呼結束後才釋放工作階段。
電腦動作的核准僅涵蓋已固定的動作引數。使用者考慮是否核准時,畫面與焦點仍可能改變。如果同意僅適用於特定目標,驅動程式就必須將動作綁定至該目標,或在狀態改變後拒絕執行。請在網路存取受限的隔離環境中執行電腦動作。
限制 URL
只有任務需要時,才啟用 navigate 或 new_tab。在 Node 中同時提供 confirm 和 urlPolicy,或在 Python 中同時提供 confirm 和 url_policy。URL 回呼會收到 (context, url),在 Node 中還可接收執行上下文,在 Python 中則可接收 cancelled 關鍵字引數。回呼必須回傳布林值 true,SDK 才會繼續呼叫 confirm。新增 URL 為 null 的空白分頁仍需要確認,但沒有 URL 可供檢查。
請解析請求的 URL,並將其通訊協定、主機名稱和連接埠與任務允許的目的地比對。不要只比對字串前綴,例如不得將 https://example.com.evil.test 視為 https://example.com。不提供導覽功能的瀏覽器驅動程式無須提供 URL 回呼。瀏覽器範例並未啟用這些方法。
也請在瀏覽器或環境中強制執行網路政策。回呼會檢查導覽請求,但無法限制重新導向、彈出式視窗、網頁指令碼或內嵌資源。各次請求之間請沿用同一個隔離的工作階段。應用程式自行建立的資源用完後應關閉,借用的資源則交由擁有者管理。
查看用量與耗時
使用 ResponsesToolRunner 時,請將 Node 的 onDiagnostic 或 Python 的 on_diagnostic 傳給 run。每個 Responses 請求完成後,回呼都會收到一筆記錄,其中包含 api: "responses"、stage: "request"、reason: "completed" 和 usage。如果 API 提供用量,這份用量資料就會包含 input_tokens、output_tokens 和 total_tokens。否則,用量值在 Node 中為 null,在 Python 中為 None。將各個已完成請求的 Token 欄位分別加總,即可衡量整次執行的用量。如果任何請求缺少用量,總計就不完整。
ComputerToolset.run 不會透過診斷回呼回報請求用量。傳回的回應最多只包含最後一個請求的用量。如果需要每個請求的用量,請搭配使用 ResponsesToolRunner 與 ComputerToolset。
診斷記錄也會列出 API、階段、原因、呼叫 ID、成員與實測耗時。其中不包含原始錯誤、網頁文字、引數或圖像。即使觀察器失敗,也不會因此核准動作或改變動作結果。如果應用程式會在呼叫 ID 或成員名稱中放入私人資料,請勿將這些資訊寫入公開日誌。
請使用同步觀察器。執行器不會等待診斷工作完成,如需非同步儲存,請由應用程式自行安排。
啟用提前執行時,接收串流的時間可能包含動作執行時間,因此各階段的計時區間可能重疊。請勿將各階段耗時相加來計算總執行時間。
關閉與取消工作
如果兩個呼叫的執行時間重疊,輔助程式會以忙碌錯誤拒絕後來的呼叫。同一個執行器執行個體也會拒絕同時啟動第二次執行。每個瀏覽器或桌面工作階段都應由單一擁有者管理。
呼叫輔助程式的 close() 即可拒絕新工作。所有呼叫都已結束時,status 為 closed。如果先前的呼叫仍可能產生作用,狀態則為 draining。如果狀態是 draining,請等待原本的執行呼叫結束,再關閉驅動程式或將工作階段交給其他擁有者。輔助程式不會關閉你的瀏覽器或桌面。在驅動程式回呼內呼叫 close() 時,它不會等待該回呼本身結束。
支援協作式取消的 Node 驅動程式方法與一般函式可以接受第二個引數,也就是含有 signal 的上下文。Python 方法可以接受 cancelled 關鍵字引數。執行耗時工作時,包括導覽與擷取螢幕截圖,都應檢查取消狀態。既有的單一引數回呼仍然有效,但 SDK 無法強制停止這些回呼或撤銷其作用。
瀏覽器驅動程式介面規範
請實作 state(),並只實作打算開放的操作。Node 方法可回傳值或 Promise,Python 則分別提供同步與非同步類別。每項操作都會收到一個經過驗證的引數物件或字典。如果分頁 ID 或目標允許沒有值,請在 Node 中明確使用 null,在 Python 中使用 None。
建立輔助程式時,如果 Python 能辨識出方法的同步或非同步類型不符,就會拒絕建立。請搭配使用 async def 方法與 AsyncBrowserToolset。包裝方法時,請保留裝飾器中繼資料或回傳型別註釋。無法預先辨識的包裝函式會在呼叫時接受檢查。你可以使用 BrowserReadDriver 和 AsyncBrowserReadDriver 等選用協定,為僅實作部分操作的驅動程式標註型別,無須實作所有操作。Node 會匯出 BrowserArguments<Member> 和 BrowserResult<Member>,分別對應輸入與輸出。
state() 會回報 tabs,這是一個物件陣列,每個物件包含 id、title、url 和 active。請使用穩定的 ID,並標示實際作用中的分頁。標題和 URL 不應包含憑證或私人資訊。一般操作結束後,即使操作失敗,SDK 也會傳回目前狀態。若受保護的讀取操作遭拒,則只會傳回固定的拒絕回應,不會讀取或揭露狀態。如果必要的狀態讀取失敗,執行就會停止。Node 的狀態讀取函式會收到 { signal },Python 的狀態讀取函式則可接受 cancelled 關鍵字引數。當呼叫端停止執行時,請使用此上下文結束尚未完成的狀態讀取。既有的不帶引數讀取函式仍受支援。
分頁狀態會回報 HTTP 和 HTTPS 的來源,例如 https://example.com:8443,其中不含憑證、路徑、查詢字串或片段。舊版狀態不含觀察中繼資料,會保留 about:blank,對其他 URL 則只回報其配置名稱,例如 data: 或 file:。2,048 個 UTF-8 位元組的上限適用於回報的值,因此網頁路徑過長不會妨礙狀態讀取。含有 V1 觀察中繼資料的狀態會在字元邊界截斷標題,使其不超過 1,024 個 UTF-8 位元組,並視需要設定 title_truncated。標題和網頁內容仍須套用應用程式的隱私規則。
選取方法
預設情況下,SDK 會開放下列 18 個方法中已實作的方法,其中 list_tabs 的結果由 SDK 根據 state() 推導。請勿實作 list_tabs。使用 members 清單可減少開放的方法,也可以明確啟用限定範圍的讀取與指標方法,或診斷、指令碼與檔案方法。名稱必須是驅動程式已實作的固定成員名稱,且不得重複。只有 list_tabs 不需要實作 state() 以外的方法。空清單不會開放任何方法。SDK 會在建構時複製選取清單,沿用自身的工具順序,並在讀取狀態或徵求同意前拒絕已停用的呼叫。
若要保留已實作的預設方法並新增選用方法,請使用 Node 的 additionalMembers 或 Python 的 additional_members。請勿與 members 同時使用。驅動程式必須已實作要新增的方法。BROWSER_MEMBERS 和 DEFAULT_BROWSER_MEMBERS 會列出固定名稱,無須檢查驅動程式。
停用 list_tabs 不會隱藏其他成功操作傳回的狀態。在 Python 和 Node 中,members 都只篩選瀏覽器輔助程式的方法。一般函式名稱可以 browser_ 開頭,但不得與已啟用的瀏覽器工具同名。
| 方法 | 引數 | 結果 | 是否需要確認 |
|---|---|---|---|
navigate |
url、tab_id |
文字或無結果 | 是,另須通過 URL 政策檢查 |
read_page |
filter(“all” 或 “interactive”)、tab_id |
文字或結構化讀取結果 | 否 |
get_page_text |
tab_id |
文字或不含元素的結構化讀取結果 | 否 |
find |
query、tab_id |
文字或結構化讀取結果 | 否 |
click |
target、tab_id |
文字或無結果 | 是 |
type |
text、target(可為 null)、tab_id |
文字或無結果 | 是 |
key |
keys(字串)、tab_id |
文字或無結果 | 是 |
scroll |
direction、非負的 amount、tab_id |
文字或無結果 | 是 |
scroll_to |
target、tab_id |
文字或無結果 | 是 |
wait_for |
text、timeout_ms、tab_id |
文字或無結果 | 否 |
select_option |
target、values(字串)、tab_id |
文字或無結果 | 是 |
hover |
target、tab_id |
文字或無結果 | 是 |
screenshot |
tab_id |
原生輸入圖像 | 否 |
zoom |
region、tab_id |
原生輸入圖像 | 否 |
new_tab |
url(可為 null) |
文字或無結果 | 是,另須通過 URL 政策檢查 |
list_tabs |
無 | 推導出的目前狀態 | 否 |
switch_tab |
必填的 tab_id |
文字或無結果 | 是 |
close_tab |
必填的 tab_id |
文字或無結果 | 是 |
除了 switch_tab 和 close_tab,表中各方法列出的 tab_id 都可以是 null。方向可為 up、down、left 或 right。Node 的 BrowserArguments<Member> 描述各方法的引數物件。Python 則提供具名輸入型別,例如 TabInput、ReadPageInput 和 ClickInput。
對於 read_page、find 和 get_page_text,如果只要提供更新後的瀏覽器狀態,請在 Node 中回傳 null 或不回傳值,在 Python 中則回傳 None。如果已完成讀取但沒有文字,請回傳空字串。
在 Node 中,表內除了 list_tabs 以外的操作都會收到第二個引數 { signal }。list_tabs 使用前述狀態讀取函式。在 Python 中,如果方法接受 cancelled,就會以關鍵字引數傳入。請利用此上下文停止尚未完成的工作,包括導覽與輸入。既有的單一引數方法仍受支援。
使用 wait_for 時,文字在空白字元正規化後不得為空,且不得超過 256 個 UTF-8 位元組。逾時時間必須介於 1 至 30,000 毫秒之間。執行 scroll_to 後,請先重新讀取目前的網頁,再操作控制項。
回報結構化讀取結果
read_page、find 和 get_page_text 可以傳回 BrowserReadV1,其中包含 version: 1、可見的 text、elements 陣列與 omitted 陣列。每個元素都有唯一的 ref、非空的 label,以及以下七種角色之一:button、textbox、combobox、checkbox、radio、slider 或 listbox。
只有在應用程式允許模型查看時,才回報欄位的 value 或其 options(由 label 和 value 配對組成)。核取方塊或單選按鈕可以回報布林值 checked,listbox 的選項可以回報布林值 selected。SDK 會在其他角色上省略這些欄位。在 Node 中,設為 undefined 的選用欄位會被省略,這些欄位若設為 null 則會遭拒。get_page_text 必須回傳空的 elements 陣列。SDK 不會將一般字串解析為結構化讀取結果。
SDK 不限制元素或選項的數量、網頁文字大小或完整報告大小。參照和標籤的上限為 256 位元組,值的上限為 512 位元組。請使用有效的 Unicode 純量值。如果讀取結果只涵蓋部分內容,驅動程式可透過不重複的 omitted 代碼回報原因:report_limit、text_limit、target_limit、work_limit、frame_limit、unsupported_root、unsupported_control、remote_action、private、value 或 name_limit。
驅動程式負責判斷元素是否可見、保護欄位隱私,並確保參照有效。取得核准後、執行動作前,請再次比對目前網頁,確認參照仍有效。控制項的標籤不代表有權讀取其值。光靠大小限制無法確保網頁內容安全。
傳回瀏覽器圖像
screenshot 和 zoom 會傳回原生 input_image,其中 image_url 或 file_id 至少有一個不為空。兩個來源欄位可以同時存在,每個非 null 的來源都必須是非空字串。支援的欄位為 type、image_url、file_id、detail 和 prompt_cache_breakpoint。快取中斷點必須為 { mode: "explicit" },原生內容型別允許時也可使用 null。SDK 會先驗證並複製這些欄位,再傳回圖像。在 Node 中,這兩個方法都會傳回 ResponseInputImageContent,其中 detail 可以省略或設為 null。如果要指定值,請使用 auto、low、high 或 original。
對於 zoom,region 的格式為 [left, top, right, bottom]。座標必須是非負的安全整數,區域的寬度與高度都必須大於零。驅動程式負責裁切圖像與檢查邊界。後續所有座標仍以完整可見區域為準。
啟用限定範圍的讀取與指標方法
以下六個瀏覽器方法預設停用,即使驅動程式已實作也一樣。請使用 members 選取這些方法,或使用 Node 的 additionalMembers 或 Python 的 additional_members 新增。原有 18 個預設方法的名稱、引數與結果型別均維持不變。使用 members 時,請一併列出仍需要的預設方法,例如 screenshot 或 read_page。
| 方法 | 必填欄位 | 結果 | 是否需要確認 |
|---|---|---|---|
read_page_scoped |
tab_id、root、depth、filter |
BrowserScopedReadV1 |
否 |
click_at |
tab_id、x、y、button、click_count、keys |
文字或無結果 | 是 |
drag_path |
tab_id、path、keys |
文字或無結果 | 是 |
hold_keys |
tab_id、keys、duration_ms |
文字或無結果 | 是 |
hover_at |
tab_id、x、y |
文字或無結果 | 是 |
set_checked |
tab_id、target、checked |
文字或無結果 | 是 |
Node 使用 BrowserArguments<Member>。Python 會匯出 ReadPageScopedInput、ClickAtInput、DragPathInput、HoldKeysInput、HoverAtInput 和 SetCheckedInput。所有欄位皆為必填,但 tab_id 可設為 null 或 None 以指定作用中的分頁。未知欄位會遭拒,包括路徑點中額外的欄位。數值必須是有限的安全整數。需要數值時,Python 不接受 True 和 False。
click_at 接受非負的 x 和 y,button 可設為 left、right 或 middle,click_count 則可設為 1、2 或 3。drag_path 接受 2 至 100 個座標點,每個點都必須完全符合 {x, y} 格式,且座標不得為負。即使放大後,這兩個方法仍以網頁完整可見區域的 CSS 像素為座標單位。驅動程式必須檢查目前的邊界。兩個方法的 keys 欄位都是修飾鍵清單,可包含 Control、Alt、Meta 或 Shift,各鍵不得重複。清單可以為空。
hover_at 會將指標移至指定的 CSS 座標,過程中不按住任何滑鼠按鈕。set_checked 會將核取方塊設為指定的布林狀態。連續兩次設為 true 後,核取方塊必須維持勾選。即使不需要改變狀態,也必須使用仍然有效的原始目標並通過確認,不得接受已失效或被替換的控制項。
hold_keys 接受 1 至 8 個不重複且非空的按鍵名稱,每個名稱最多 64 個 UTF-8 位元組,且必須由有效的 Unicode 純量值組成。duration_ms 必須介於 1 至 3000 之間。會改變狀態的方法要求 confirm 回傳布林值 true。支援協作式取消的方法會收到該次呼叫的取消上下文:Node 會將 { signal } 作為第二個引數傳入,Python 則會在方法接受 cancelled 關鍵字引數時傳入該引數。既有的單一引數方法仍然有效。
在指定區段內讀取
使用 read_page_scoped 時,將 root 設為 null 即可找出可見區段。非 null 的根必須是驅動程式核發的範圍參照,不得使用選取器。參照必須是非空且有效的 Unicode 字串,最多 256 個 UTF-8 位元組。將 depth 設為 1 至 32,並將 filter 設為 all 或 interactive。深度計算的是該根內的 DOM 走訪層數,與框架或影子 DOM 的限制分開計算。
請傳回 BrowserScopedReadV1。此型別在既有讀取結果中新增 scopes: [{ref, label}]。參照與標籤必須是非空且有效的 Unicode 字串,最多 256 個 UTF-8 位元組。範圍參照必須唯一,且不得與任何元素參照相同。這個方法不接受字串或 null 結果。SDK 會先複製已知欄位,再要求最終狀態。
範圍參照只能用來選取下一次讀取的根。修改元素的操作必須拒絕這類參照。如果參照所屬的分頁、文件、世代或可見性有所變更,請讓範圍參照與元素參照一併失效。請沿用既有的欄位隱私規則、總工作量限制與讀取限制。
啟用診斷、指令碼與檔案傳輸方法
以下四個方法同樣預設停用。請在 members 中逐一選取,或使用 additionalMembers 或 additional_members 新增,並提供 confirm。診斷讀取也需要確認。僅在驅動程式中實作方法,並不會將其開放給模型。
| 方法 | 必填引數 | 結果 |
|---|---|---|
read_diagnostics |
tab_id、source、limit |
純文字的結構化讀取結果 |
run_script |
tab_id、source、timeout_ms |
文字 |
upload_file |
grant_id |
BrowserFileOutcome |
download_file |
grant_id |
BrowserFileOutcome |
使用 read_diagnostics 時,請選擇 console 或 network 作為來源,並將筆數上限設為 1 至 100。請傳回結構化讀取結果,其中 elements 必須是空陣列。在 Node 中,請使用 BrowserTextReadV1 結果型別。驅動程式必須過濾私人資料,並限制保留的歷程記錄。請勿傳回原始標頭、Cookie、憑證或未經篩選的主控台訊息。
run_script 接受非空且由有效 Unicode 組成的原始碼,逾時時間為 1 至 30000 毫秒。SDK 會完整保留原始碼。請傳回由有效 Unicode 組成的文字。空字串有效,null 結果無效。即使結果很大,SDK 也會完整保留。指令碼會以網頁的權限執行。請使用不含憑證的全新工作階段,限制其網路存取,並在無法確定執行狀態時停用該工作階段。停止本機端的等待程序,並不能證明網頁指令碼已停止。
檔案方法只接受呼叫端核發的 grant_id,其值必須是非空且有效的 Unicode 字串,最多 256 個 UTF-8 位元組。這項授權用來識別一個已核准且限於本次任務使用的檔案,不是路徑或 URL。檔案擁有者必須另外取得該檔案的核准,重新檢查授權是否過期與檔案的擁有權,強制執行大小限制,並只允許使用該授權一次。瀏覽器確認無法取代這項檔案核准。
回傳結果必須恰好包含 version、status、effect 和 cleanup。將 version 設為 1。cleanup 可為 not_started、pending 或 completed。有效的狀態與作用組合如下:
status |
effect |
|---|---|
completed |
completed |
refused |
none |
unknown |
unknown |
interrupted |
none 或 unknown |
SDK 會先複製並驗證此結果,再要求最終瀏覽器狀態。只有 completed 會將工具輸出的 ok 設為 true。其他情況會保留結構化結果,且 ok 為 false,因此執行器會略過該回應中依賴此結果的瀏覽器呼叫。如果傳輸結果不明,請先檢查實際檔案與應用程式狀態,再重試。檔案操作的結果不能證明後續的表單提交或業務操作已成功。
run_script、upload_file 和 download_file 都會收到各次呼叫的取消資訊。Node 會將 { signal } 作為第二個引數傳入,Python 則會傳入 cancelled 關鍵字引數。Python 會匯出 ReadDiagnosticsInput、RunScriptInput 和 BrowserFileInput。
電腦驅動程式介面規範
電腦驅動程式會接收原生電腦動作並傳回螢幕截圖。它必須實作以下方法。在 Node 中,請匯入 ComputerDriver,來源為 openai。在 Python 中,請匯入 ComputerDriver 或 AsyncComputerDriver,來源同樣為 openai。也請匯入對應的 ComputerToolset 或 Python 的 AsyncComputerToolset,兩者都來自 openai。
| 方法 | 驅動程式收到的動作 |
|---|---|
click |
座標、按鈕及任何按住的鍵 |
double_click |
座標及任何按住的鍵 |
drag |
路徑及任何按住的鍵 |
keypress |
按鍵組合 |
move |
指標座標 |
scroll |
座標、scroll_x 和 scroll_y |
type |
要輸入至目前取得焦點之控制項的文字 |
wait |
等待環境進入穩定狀態的請求 |
screenshot |
不帶引數,傳回目前的顯示畫面 |
動作方法會收到既有的自動產生電腦動作物件,其中的欄位以小寫字母和底線命名,方法本身不回傳值。如果無法執行動作,必須拋出錯誤,不得默默忽略不支援的輸入。Node 支援同步結果或 Promise。在 Python 中,請等待非同步方法執行完畢。
在 Python 中,請搭配使用同步方法與 ComputerToolset,或搭配使用 async def 方法與 AsyncComputerToolset。建立輔助程式時,它會拒絕可辨識的類型不相符情況。包裝方法時,請保留裝飾器中繼資料或回傳型別註釋。無法預先辨識的包裝函式會在呼叫時接受檢查,因此輔助程式發現類型不符前,包裝函式本身的程式碼可能已經執行。
在 Node 中,請使用 ComputerCallInput 型別來表示要傳給 ComputerToolset.execute() 的呼叫。它接受原生呼叫,也接受包含 actions 陣列但省略 pending_safety_checks 的新版呼叫。合法省略該欄位時,核准回呼會收到獨立的呼叫副本,其中的檢查清單為空。重播呼叫時會保留原始欄位。
screenshot() 會傳回 computer_screenshot,其中包含 image_url(可使用資料 URL)或 file_id。電腦輔助程式要求至少提供一個圖像來源,也接受同時提供兩個來源欄位。輔助程式不會讀取本機檔案。每個動作都會依序執行一次,全部執行完畢後,輔助程式才會擷取最後的螢幕截圖。它不會重試驅動程式動作。
如果 Responses 迴圈只使用電腦工具,請使用 ComputerToolset.run 或 Python 的 AsyncComputerToolset.run。請選擇專案可使用且支援電腦工具的模型。混用多種工具時,請將電腦輔助程式傳入 Responses 執行器的 computer 選項。在 Node 中,透過執行選項 computerOptions 傳入電腦回呼。在 Python 中,直接將 approve_safety_checks 和 before_action 作為執行時的關鍵字引數傳入。瀏覽器範例只會控制瀏覽器,並未實作或驗證原生桌面。
電腦輔助程式和 ResponsesToolRunner 都支援 Responses 的 context_management 壓縮功能。兩者都會檢查項目的必要欄位,並原樣重播加密內容。使用 ResponsesToolRunner 時,請在此原生選項與本機的 contextBudget 或 context_budget 選項之間擇一使用,不得併用。
執行以螢幕截圖為依據的任務
執行第一個任務提供完整範例,可選用 Python 或 Node 版本。範例使用 Responses 電腦工具,在本機瀏覽器中顯示取件詳細資料。
使用隔離的桌面
若要控制作業系統桌面,請參閱 Python 或 Node 的完整桌面範例。兩者都使用隔離的 Linux 客體環境。在配備 Apple 晶片的 Mac 上,Linux 客體環境在虛擬機器中執行,在 x86-64 Linux 上則在 Docker 中執行。每個範例都包含不需要 API 金鑰的本機練習。實際執行任務時,會同時檢查瀏覽器記錄與已儲存的檔案。若要使用自己的環境,請先參閱 Docker 設定範例,再依上述介面規範調整驅動程式。
搭配其他工具使用瀏覽器動作
Responses 執行器可以搭配使用瀏覽器與電腦輔助程式、一般函式、網頁搜尋、檔案搜尋、程式碼解譯器、圖像生成及遠端 MCP 工具。下一個請求重播回應時,伺服器工具的結果會保留原生內容與容器 ID。如果伺服器端的結果顯示失敗、不完整或尚未完成,該回合會在執行本機動作前停止。
如果執行流程宣告了伺服器工具,即使啟用 eager,本機呼叫也會等待完整回應。執行器必須先檢查後續的伺服器結果與核准請求,才能安全執行動作。
回合完成時,如果一般函式在註冊時允許覆寫,Node 的 supplyOutputs 或 Python 的 supply_outputs 可以替換尚未嘗試執行的該函式呼叫結果。即使未明確設定提前執行政策,此功能仍然適用。替換結果無法用來回覆瀏覽器呼叫、電腦呼叫或 MCP 核准請求。
此執行器必須使用已儲存的回應,才能在圖像生成後繼續執行。在 Node 中使用 store: false 或在 Python 中使用 store=False 時,如果同時宣告 image_generation,執行器就會拒絕執行。請視情況將儲存選項設為 true,或使用 client.responses.create 發出單一無狀態請求。執行器不會代你啟用儲存功能。
請重用具型別的函式工具,避免重複實作驗證。在 Node 中,請將 zodResponsesFunction 或 standardResponsesFunction 包裝在 runnerFunction 中,後者可從 openai/helpers/responses-tool-runner 匯入。工具必須包含自己的回呼。在 Python 中,請使用 RegisteredFunction.from_tool 或 AsyncRegisteredFunction.from_tool,搭配既有的 pydantic_responses_function_tool 和明確指定型別的執行函式。引數無效時,流程會在執行函式啟動前停止。回呼輸出無效時,執行也會停止,且不會重複執行已產生作用的操作。直接註冊 RunnerFunction 和 RegisteredFunction 時,會保留既有的引數處理方式。
對於 MCP,請提供 Node 的 approveMcp 或 Python 的 approve_mcp。回呼會收到實際核准請求的獨立副本,並回傳 true 或 false。執行器會將回覆綁定至該請求的 ID 和宣告的伺服器。它不能自行核准,也不能將最終訊息視為同意。
只要請求宣告了 MCP 工具,SDK 就會停用自動重試,無論是否使用執行紀錄簿。如果請求失敗,請先確認 MCP 伺服器已執行哪些操作,再開始另一次執行。
處理失敗
遇到參照失效等可復原的問題時,才拋出 BrowserError,且錯誤文字必須適合安全地提供給模型。瀏覽器操作拋出的其他錯誤會產生通用的失敗訊息。遇到這些操作失敗情況時,執行器會為每個瀏覽器呼叫提供輸出,略過該回應中剩餘的瀏覽器操作,並讓模型在下一回合重新選擇。傳回的結果或狀態無效時,執行會停止。無法回報狀態、一般函式執行失敗,或原生電腦安全檢查未獲核准時,執行也會停止。
請設定 maxSteps 或 max_steps 來限制 API 請求次數,預設上限為 20。最後一個允許的請求無法啟動會產生新作用的操作。SDK 重試 HTTP 請求時,不會重試驅動程式動作。請使用 Node 的 signal 或 Python 的 cancelled 在操作之間停止執行。已在進行中的驅動程式呼叫不一定能撤銷。
ResponsesToolRunner 會在每個請求中保留 tool_choice。如果設定為每次都必須使用本機工具,執行流程就無法結束,因此執行器會在開始任何工作前拒絕這項設定。迴圈請使用 auto,若要發出單一強制使用工具的請求,則使用 responses.create。如果設定要求使用工具,但也允許使用已宣告的伺服器工具,則仍然有效。
排解執行問題
| 症狀 | 檢查與修正方式 |
|---|---|
無法匯入 ComputerToolset 或瀏覽器輔助程式 |
檢查執行指令碼的環境中安裝的套件。請使用 Python 的 openai==3.31.0、Node 的 openai@7.33.0,或包含這些輔助程式的更新版本。 |
| Chromium 無法啟動 | 在執行指令碼的同一環境中執行 Playwright 安裝指令。在 Linux 容器中,請安裝所需的系統程式庫,並以非 root 使用者身分執行。請勿停用沙盒來掩蓋錯誤。 |
| API 拒絕模型或工具 | 檢查專案的模型存取權,再查看該模型的工具區段。此區段位於模型目錄。原生 computer 工具與瀏覽器函式工具對模型的要求不同。 |
| 動作或待處理的安全檢查遭拒 | 檢查應用程式的核准政策。根據目前狀態檢查已固定的動作引數。需要時請要求核准,不要為了讓執行通過而核准所有請求。 |
| 模型達到步驟上限 | 先檢查實際網頁或檔案,再確認任務是否需要驅動程式拒絕提供的功能。提高 maxSteps 或 max_steps 前,請先簡化任務。 |
| 瀏覽器模型未讀取網頁就回答 | 啟用驅動程式已實作的讀取方法,例如範例中的 read_page。要求模型讀取目前網頁,並重新執行任務。接受答案前,請驗證網頁或檔案中的結果。 |
| 點擊未落在可見目標上 | 檢查螢幕截圖與座標。 |
修正點擊位置偏差
重新擷取螢幕截圖,確認畫面顯示的是預期視窗。截圖與動作必須使用相同的座標系統。如果傳送的是 800 × 600 的截圖,而顯示器解析度為 1600 × 1200,請在點擊前將傳回的兩個座標值都乘以二。如果電腦驅動程式傳送的是裁切後的截圖,請在換算比例後加上裁切區域的偏移量。瀏覽器驅動程式的指標方法以網頁完整可見區域中的 CSS 像素為單位,即使放大後也一樣。請勿將 CSS 像素與顯示器像素混用。
螢幕截圖的大小會影響輸入 Token 數與費用。圖像尺寸與模型限制請參閱擷取螢幕截圖。
串流與續跑
Responses 預設不使用串流。使用 stream 搭配 onEvent(Node)或 on_event(Python)時,執行器會提供串流事件的獨立副本,並等到回應完成才開始執行動作。使用 eager 時,執行器可以依序提前執行已完成的輸出項目。它絕不會根據串流中尚不完整的引數增量執行動作。
只有在執行器驗證完整回應之前,已完成的項目就能安全執行時,才啟用提前執行。如果後續事件變更或移除該項目,執行器會停止並保留其執行記錄,但無法撤銷動作。如果所有動作都必須等到完整回應通過驗證,請停用提前執行,或使用空的提前執行政策。
如果已完成的項目未依序抵達,或其索引不連續,執行器會等到收到完整回應,才執行序列中的該部分。即使串流失敗,已完成操作所產生的作用仍會留在記錄中。
earlyExecution 或 early_execution 可依通訊協定中使用的函式名稱,限制哪些函式能提前執行,並以獨立的布林值控制原生電腦動作的分派。傳入空物件會延後所有本機工具的執行。省略此選項則會保留一般行為,對所有工具套用提前執行。為維持順序,從第一個延後的工具開始,後續工具也都會延後。使用 iterate() 時,請先檢查已完成的回合,再繼續下一步。如果在回合結束時關閉迭代,就不會執行任何延後的工具。這些選項只會改變執行時機,不會改變核准要求。
對於個別已完成的呼叫,beforeEarlyCall 或 before_early_call 可以在分派前傳回 defer。它無法讓提前執行許可清單以外的呼叫提前執行。只有一般函式能在不依賴其他動作的情況下執行時,才將其標示為 independent: true。未使用執行紀錄簿時,獨立函式可在串流繼續接收資料的同時執行。可持久保存進度的執行流程、瀏覽器動作與電腦動作仍會依序執行。即使另一個呼叫失敗,已啟動的工作仍會保留其執行記錄。
預設最多可同時執行兩個獨立的提前呼叫。若要變更上限,請將 Node 的 maxConcurrentCalls 或 Python 的 max_concurrent_calls 設為正整數。執行器會等目前這一組呼叫完成,再讀取串流中的後續呼叫。此選項只適用於未使用執行紀錄簿的獨立提前執行。每個函式仍必須自行限制它所啟動的工作量。
如果提前執行中斷,請在 Node 中檢查 ResponsesToolRunnerError.attemptedCallIds 與 completedCallIds,或在 Python 中檢查 attempted_call_ids 與 completed_call_ids。這些欄位只包含呼叫 ID,不含結果、引數或驅動程式訊息。動作可能已經產生作用。在重試已嘗試執行或結果不明的動作前,請先從應用程式的權威資料來源讀取實際狀態。
無論是否使用持久儲存,都可以透過 contextBudget 或 context_budget 限制下一個請求的輸入位元組數與圖像數量。為下一個請求整理出的輸入會保留目前的觀察結果與必要的工具關聯。只設定記憶體內的限制,無法讓執行流程在程序結束後復原。
回合完成時,可透過 appendUserText 或 append_user_text 將使用者指示加入佇列。執行器會先記錄待處理的輸出,再附加這些指示。此方法只接受文字,不接受任意工具輸出或核准物件,也不會重設請求額度。
此方法可用來釐清目前的任務,例如要求智慧體檢查另一個日期。如果使用者改換任務,請先停止目前的執行並等待其結束,再開始新的執行。請重新讀取應用程式狀態,並為新的動作重新取得核准。保留舊的執行記錄,因為變更指示不會撤銷先前動作的作用。
若要在程序結束後仍能復原,請提供 ledger,並確保每個檢查點都由獨佔該次執行的擁有者儲存。只能從已完成的回合邊界續跑。如果動作仍待處理或結果不明,必須先核對實際狀態。續跑時會保留剩餘的請求額度與已完成的歷程記錄。本機依上下文額度進行壓縮時,會在執行紀錄簿中保留完整依據,並固定保留目前的觀察結果、安全檢查、訊息與推理內容。壓縮本身不會授予核准。
每次儲存時都會收到獨立且完整的檢查點,包括在本機操作產生作用前後所做的儲存。檢查點包含整個批次與累積的歷程記錄。如果批次很大,複製與儲存這些記錄的總工作量可能隨批次大小呈平方成長。請選擇能處理相應資料量的儲存方式。contextBudget 和 context_budget 限制的是請求輸入大小,不會限制執行紀錄簿的儲存量。
如果執行在檢查點仍待處理時中斷,該檢查點只包含截至上次儲存時的內容。它可能未包含後續文字與尚未嘗試的提議,也絕不構成重播授權。在操作產生作用前後儲存的檢查點,都會包含截至當時觀察到的完整內容與執行記錄。
含有 MCP 工具的執行流程會在每次發出請求前儲存待處理的檢查點。如果連線失敗,請先確認 MCP 伺服器執行了哪些操作,再開始另一次執行。無法從待處理的檢查點自動續跑。
儲存 MCP 宣告時,會省略授權資訊與自訂標頭,並以 SHA-256 指紋取代伺服器 URL。原生請求仍會使用原始 URL。需要定期更換的憑證應放在授權資訊或標頭中。變更 URL 路徑或無法辨識的查詢參數值,會改變伺服器的識別資訊,必須重新開始執行。含有原始 MCP URL 的檢查點無法續跑。Node 需要 crypto.subtle.digest 才能儲存 MCP URL 的指紋。檢查點中的其他輸入與輸出仍屬於應用程式的私人資料。
續跑時,請提供目前有效的憑證,並確認憑證對應至預期的伺服器與帳戶。
儲存程式碼解譯器宣告時,會保留憑證名稱與網域,但會清除機密值。續跑時,請在工具設定中提供目前有效的值。對於 MCP 核准,空的 always: {} 或 never: {} 篩選條件會套用至所有工具。
如果初始輸入或已儲存的執行紀錄簿包含已核准的 MCP 請求,請提供 Node 的 approveMcp 或 Python 的 approve_mcp。第一次儲存或發出 API 請求前,執行器會逐一檢查每項核准。若沒有對應且已完成的 MCP 呼叫,就會再次要求核准。無論是否使用執行紀錄簿或設定上下文額度,此規則都適用。已完成的呼叫與先前的拒絕決定會維持不變。如果需要重新核准,但缺少回呼,執行就會停止。
在本機檢查自訂驅動程式
調整範例前,請先執行預訂示範或隔離桌面範例中的本機練習。請加入檢查,確認驅動程式操作後的實際網頁狀態、輸入造成的變化,以及資源清理情況。通過 SDK 驗證並不能證明環境已正確執行動作。
如需可實際執行的 SDK 工作流程,請參閱執行第一個任務。如需設定環境,請參閱整合範例。每次變更後,請先驗證已儲存的表單、檔案或其他應用程式記錄,再回報成功。