ブラウザとデスクトップのドライバー

ドライバーは、許可されたツール呼び出しを、自分で管理するブラウザやデスクトップ上の操作に変換します。アプリケーションがページのテキスト、コントロール、タブを報告できる場合は、ブラウザドライバーを使用します。モデルがスクリーンショットと座標を基に操作する必要がある場合は、コンピュータードライバーを使用します。SDK はリクエストの送信と呼び出しの振り分けを行い、アプリケーションはセッション、権限、クリーンアップを管理します。

共通設定

まずは Python または Node のブラウザの例を参照してください。ドライバーの実装全体、確認ポリシー、リクエスト数に上限を設けた Responses の実行例が含まれています。実行が終了するまでセッションを開いたままにしてください。Python では、同期ドライバー向けに同期版の BrowserToolset クラスと ResponsesToolRunner クラスも用意されています。

操作の承認とセッションの管理

ドライバーと承認コールバックは、信頼できるアプリケーションコード内で作成してください。実行可能な設定は信頼できないページデータから分離し、ページデータはドライバーのレポートで宣言されたフィールドを通じて返します。

選択したブラウザメソッドが状態を変更する場合や診断情報を読み取る場合は、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）に列挙します。ドライバーが状態やコンテンツを読み取る前に、同じ confirm コールバックが実行されます。このときコンテキストには phase: "before_read" が設定され、状態は Node では state: null、Python では None です。このケースはページのメタデータを読み取らずに処理してください。拒否した場合、ページのコンテンツも状態も返されません。このオプションを省略すると既存の読み取り動作が維持されます。操作に必須の承認は引き続き適用されます。

コンピューター呼び出しでは、ヘルパーが操作を実行する前に、保留中の安全性チェックをすべて確認して承認してください。Node の approveSafetyChecks と Python の approve_safety_checks は、それぞれ厳密に true と 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 も受け取ります。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 です。実行全体の使用量を計測するには、完了した全リクエストについて、トークンのフィールドごとに合計してください。使用量がないリクエストが 1 件でもあれば、合計は不完全です。

ComputerToolset.run の診断コールバックはリクエストの使用量を報告しません。返されるレスポンスに使用量が含まれていても、それは最後のリクエストの分だけです。リクエストごとの使用量が必要な場合は、ResponsesToolRunner と ComputerToolset を組み合わせて使用します。

診断レコードには、API、処理段階、理由、呼び出し ID、メンバー、計測した処理時間も記録されます。生のエラー、ページのテキスト、引数、画像は含まれません。オブザーバーが失敗しても、操作が承認されたり結果が変わったりすることはありません。アプリケーションが呼び出し ID やメンバー名に非公開データを含める場合、それらを公開ログに出力しないでください。

同期オブザーバーを使用してください。ランナーは診断処理の完了を待ちません。非同期の保存処理はアプリケーション側でスケジュールしてください。

先行実行では、ストリームの受信時間に操作時間が含まれることがあるため、各段階の計測時間が重なる場合があります。実行の総所要時間を求めるために、これらを足し合わせないでください。

処理の終了とキャンセル

ヘルパーは、重複して実行される呼び出しをビジーエラーで拒否します。ランナーも、同じインスタンスですでに実行中の場合は次の実行を拒否します。ブラウザまたはデスクトップの各セッションは、単一の所有者が管理してください。

新しい処理を受け付けなくするには、ヘルパーの close() を呼び出します。実行中の呼び出しがなければ status は closed、先行する呼び出しがまだ副作用を起こす可能性があれば draining です。状態が draining の場合は、元の実行呼び出しの終了を待ってからドライバーを閉じるか、セッションを別の所有者に引き渡してください。ヘルパーはブラウザやデスクトップを閉じません。ドライバーのコールバック内で close() を呼び出しても、そのコールバック自体の終了は待ちません。

キャンセルに協調的に対応する Node のドライバーメソッドや通常の関数は、第 2 引数に signal を含むコンテキストを受け取れます。Python のメソッドはキーワード引数 cancelled を受け取れます。ページ移動やスクリーンショット取得など、時間がかかる処理の途中でキャンセルを確認してください。引数が 1 つの既存のコールバックも使用できますが、SDK がそれらを強制停止したり、副作用を取り消したりすることはできません。

ブラウザドライバーの仕様

state() と、公開する操作だけを実装してください。Node のメソッドは値または Promise を返せます。Python には同期用と非同期用のクラスがあります。各操作は、検証済みの引数を 1 つのオブジェクトまたは辞書として受け取ります。値なしを許容するタブ 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 を受け取れます。呼び出し元が実行を停止したら、このコンテキストを使って未完了の状態読み取りを終了してください。引数のない既存の読み取りメソッドも引き続き使用できます。

タブの状態には、https://example.com:8443 のような HTTP または HTTPS のオリジンが含まれます。認証情報、パス、クエリ、フラグメントは含まれません。観測メタデータを持たない従来の状態形式では、about:blank はそのまま維持し、ほかの URL では data: や file: などのスキームだけを報告します。UTF-8 で 2,048 バイトという上限は報告する値に適用されるため、ページのパスが長くても状態を読み取れます。V1 の観測メタデータを含む状態では、タイトルを文字の境界で UTF-8 の 1,024 バイト以内に切り詰め、必要に応じて title_truncated を設定します。タイトルとページのコンテンツには、引き続きアプリケーションのプライバシールールを適用してください。

メソッドの選択

デフォルトでは、SDK は次の 18 個のメソッドのうち実装済みのものを公開し、list_tabs は state() から導出します。list_tabs は実装しないでください。members リストを使うと、公開するメソッドを絞り込んだり、範囲指定とポインター操作のメソッドや診断、スクリプト、ファイル操作のメソッドを明示的に有効にしたりできます。ドライバーが実装しているメソッドの名前を、定義済みのメンバーから重複なく選んでください。list_tabs だけは state() 以外の実装が不要です。空のリストではメソッドは公開されません。SDK は構築時に選択内容をコピーし、ツールの順序は SDK 側で維持します。無効化したメソッドの呼び出しは、状態を読み取ったり同意を求めたりする前に拒否します。

実装済みのデフォルトメソッドを維持したまま任意のメソッドを追加するには、Node では additionalMembers、Python では additional_members を使用します。members とは併用しないでください。追加を指定するメソッドはドライバーに実装されている必要があります。BROWSER_MEMBERS と DEFAULT_BROWSER_MEMBERS は、ドライバーを調べなくても参照できる定義済みの名前の一覧です。

list_tabs を無効にしても、ほかの操作が成功したときに返される状態は非表示になりません。Python と Node のどちらでも、members はブラウザヘルパーのメソッドを絞り込みます。通常の関数名は browser_ で始めてもかまいませんが、有効なブラウザツールと同じ名前にはできません。

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 を除き、第 2 引数として { signal } を受け取ります。list_tabs は前述の状態読み取りメソッドを使用します。Python は、メソッドが受け取れる場合にキーワード引数として cancelled を渡します。このコンテキストを使って、ページ移動や入力などの未完了の処理を停止してください。引数が 1 つの既存のメソッドも引き続き使用できます。

wait_for では、空白の正規化後に空でなく、UTF-8 で 256 バイト以内のテキストを使用してください。タイムアウトは 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 の 7 種類のロールのいずれかがあります。

フィールドの 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 が少なくとも 1 つ必要です。両方のソースフィールドを含めてもかまいませんが、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] です。座標は非負の安全な整数で、幅と高さは正でなければなりません。切り抜きと範囲のチェックはドライバーが行います。その後の座標もすべて、表示領域全体を基準とします。

範囲指定とポインター操作のメソッドの有効化

次の 6 個のブラウザメソッドは、ドライバーに実装されていてもデフォルトでは無効です。members で選択するか、Node では additionalMembers、Python では additional_members で追加してください。元の 18 個のデフォルトメソッドの名前、引数、結果の型は変わりません。members を使う場合は、screenshot や read_page など、引き続き必要なデフォルトメソッドも含めてください。

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 は、非負の座標を持ち、厳密に {x, y} の形式に従う点を 2～100 個受け取ります。どちらも、ズーム後もページの表示領域全体を基準とし、単位には CSS ピクセルを使用します。ドライバーは座標が現在の表示範囲に収まることを確認する必要があります。両メソッドの keys フィールドには Control、Alt、Meta、Shift から選んだ修飾キーを重複なく列挙します。空のリストも使用できます。

hover_at は、ボタンを押さずに、現在のページの指定された CSS 座標にポインターを移動します。set_checked は、指定されたブール値に従ってチェックボックスの状態を設定します。true を 2 回設定してもチェックされた状態を維持する必要があります。状態が変わらない操作でも、元の対象が現在も有効であることを確認し、承認を得てください。古くなったコントロールや置き換わったコントロールは受け付けてはいけません。

hold_keys は重複のない空でないキー名を 1～8 個受け取ります。各キー名には有効な Unicode スカラー値を使用し、UTF-8 で 64 バイト以内にします。duration_ms は 1～3,000 ミリ秒です。状態を変更するメソッドでは、confirm がブール値の真を返す必要があります。キャンセルに協調的に対応するメソッドは、呼び出しごとのキャンセルコンテキストを受け取ります。Node は第 2 引数として { signal } を渡し、Python はメソッドが受け取れる場合にキーワード引数 cancelled を渡します。引数が 1 つの既存のメソッドも引き続き使用できます。

セクション内の読み取り

read_page_scoped で root に null を指定すると、表示中のセクションを検出します。null 以外を指定する場合は、セレクターではなくドライバーが発行したスコープ参照を使用してください。参照は空でない有効な Unicode 文字列で、UTF-8 で 256 バイト以内でなければなりません。depth は 1～32、filter は all または interactive に設定します。深さは、そのルート内で DOM をたどる階層数を表し、フレームやシャドウ DOM の制限とは別に数えます。

BrowserScopedReadV1 を返してください。この型は、既存の読み取り結果に scopes: [{ref, label}] を追加したものです。参照とラベルは空でない有効な Unicode 文字列で、UTF-8 で 256 バイト以内とします。スコープ参照は一意で、どの要素参照とも一致してはいけません。このメソッドは文字列や null の結果を拒否します。SDK は最終状態を要求する前に既知のフィールドをコピーします。

スコープ参照は、次に読み取るルートの選択にだけ使用してください。要素を変更する操作ではスコープ参照を拒否する必要があります。タブ、ドキュメント、世代、表示状態のいずれかが変わったら、スコープ参照と要素参照をまとめて無効にしてください。既存のフィールドのプライバシー制限、総処理量と読み取りの上限を維持します。

診断、スクリプト、ファイル転送の有効化

次の 4 個のメソッドもデフォルトでは無効です。それぞれを members で選択するか、additionalMembers または additional_members で追加し、診断情報の読み取りも含めて confirm を指定してください。ドライバーに実装しただけではモデルに公開されません。

read_diagnostics では、ソースに console または network を指定し、上限を 1～100 に設定します。空の elements 配列を含む構造化された読み取り結果を返してください。Node では結果の型に BrowserTextReadV1 を使用します。ドライバーは非公開データを除外し、保持する履歴の量を制限する必要があります。生のヘッダー、Cookie、認証情報、フィルタリングしていないコンソールメッセージを返さないでください。

run_script は、有効な Unicode からなる空でないソースと、1～30,000 ミリ秒のタイムアウトを受け取ります。SDK はソース全体をそのまま保持します。有効な Unicode のテキストを返してください。空文字列は有効ですが、null の結果は無効です。SDK は大きな結果もそのまま保持します。スクリプトはページの権限で実行されます。認証情報を持たない新しいセッションを使用し、ネットワークアクセスを制限してください。実行状態が不明になった場合は、そのセッションの使用を終了します。ローカル側で待機を停止しても、ページスクリプトが停止したとは限りません。

ファイル操作のメソッドが受け取るのは、呼び出し元が発行した grant_id だけです。これは空でない有効な Unicode 文字列で、UTF-8 で 256 バイト以内とします。この許可は、タスクの範囲内で承認された 1 つのファイルを識別するもので、パスや URL ではありません。ファイルの所有者はファイルについて別途承認を得る必要があります。有効期限と所有権を再確認し、サイズ制限を適用して、許可を 1 回だけ使用できるようにしてください。ブラウザでの確認は、このファイルの承認に代わるものではありません。

返すフィールドは version、status、effect、cleanup の 4 つだけです。version は 1 に設定します。cleanup は not_started、pending、completed のいずれかです。状態と副作用の有効な組み合わせは次のとおりです。

SDK はこの結果をコピーして検証した後、ブラウザの最終状態を要求します。completed の場合だけ、ツール出力の ok が true になります。ほかの結果では、ok が false のまま構造化された結果が保持されるため、ランナーはそのレスポンス内でこの結果に依存するブラウザ呼び出しをスキップします。結果が不明な転送を再試行する前に、実際のファイルとアプリケーションの状態を確認してください。ファイル操作の結果だけでは、その後のフォーム送信や業務処理が成功したかどうかはわかりません。

run_script、upload_file、download_file は呼び出しごとのキャンセル情報を受け取ります。Node は第 2 引数として { signal } を渡し、Python はキーワード引数 cancelled を渡します。Python は ReadDiagnosticsInput、RunScriptInput、BrowserFileInput をエクスポートします。

コンピュータードライバーの仕様

コンピュータードライバーは、ネイティブのコンピューター操作を受け取り、スクリーンショットを返します。次のメソッドを実装する必要があります。Node では ComputerDriver を openai からインポートします。Python では ComputerDriver または AsyncComputerDriver を openai からインポートします。対応する ComputerToolset または Python の AsyncComputerToolset も openai からインポートしてください。

操作メソッドは、スネークケースのフィールドを持つ既存の生成済みコンピューター操作オブジェクトを受け取り、値を返しません。操作を実行できない場合はエラーを発生させてください。未対応の入力を黙って無視してはいけません。Node は同期的な結果と Promise の両方をサポートします。Python の非同期メソッドは await してください。

Python では、同期メソッドは ComputerToolset と、async def メソッドは AsyncComputerToolset と組み合わせます。ヘルパーは作成時に判別できる不一致を拒否します。メソッドをラップするときは、デコレーターのメタデータまたは戻り値の型アノテーションを維持してください。中身を判別できないラッパーは呼び出し時にチェックされるため、ヘルパーが不一致を検出する前にラッパー自体のコードが実行されることがあります。

Node では、ComputerCallInput を ComputerToolset.execute() に渡す呼び出しの型として使用します。この型は、ネイティブ呼び出しに加え、actions 配列を持ち pending_safety_checks を省略した新しい形式の呼び出しも受け付けます。このように正しく省略された場合、承認コールバックには、空のチェックリストを持つ独立した呼び出しオブジェクトが渡されます。再送する呼び出しには元のフィールドが保持されます。

screenshot() は computer_screenshot を返し、そこには image_url（データ URL も可）または file_id が含まれます。コンピューターヘルパーには少なくとも 1 つの画像ソースが必要で、両方のソースフィールドを指定することもできます。ヘルパーはローカルファイルを読み取りません。各操作は順番に 1 回ずつ実行され、最後にヘルパーがスクリーンショットを取得します。ドライバーの操作を再試行することはありません。

コンピューター操作のみの 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 のコンピューターツールを使って、ローカルブラウザに受け取りの詳細を表示します。

隔離デスクトップの利用

OS のデスクトップを操作するには、Python または Node のデスクトップの実装例を参照してください。どちらも隔離された Linux ゲストを使用します。Apple シリコン搭載 Mac では仮想マシン上で、x86-64 Linux では Docker 上で Linux ゲストを実行します。各サンプルには API キーなしで実行できるローカル演習があります。実際に API を使うタスクでは、ブラウザ内の記録と保存したファイルの両方をチェックします。独自の環境では、Docker の設定例を基に、上記のドライバー仕様に沿って実装を調整してください。

ブラウザ操作とほかのツールの併用

Responses ランナーでは、ブラウザヘルパーやコンピューターヘルパーと、通常の関数、ウェブ検索、ファイル検索、Code Interpreter、画像生成、リモート MCP ツールを組み合わせることができます。次のリクエストでレスポンスを再送するとき、サーバーツールの結果はネイティブのコンテンツとコンテナ ID を保持します。サーバー側の結果が失敗、不完全、または未完了の場合、ローカル操作を行う前にターンが停止します。

実行時にサーバーツールを宣言すると、eager が有効でも、ローカル呼び出しはレスポンス全体が完了するまで待機します。ランナーが安全に操作するには、後続のサーバー側の結果と承認リクエストを確認する必要があるためです。

ターンが完了した時点で、Node の supplyOutputs または Python の supply_outputs を使うと、登録時に上書きが許可された通常の関数について、まだ実行を試みていない呼び出しの結果を差し替えられます。先行実行ポリシーを明示していない場合も使用できます。差し替えた結果でブラウザ呼び出し、コンピューター呼び出し、MCP 承認リクエストに応答することはできません。

このランナーが画像生成後に処理を続行するには、レスポンスの保存が必要です。Node の store: false または Python の store=False は、image_generation を宣言した場合は拒否されます。必要に応じて保存設定を true にするか、ステートレスなリクエストを 1 回だけ行う場合は 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 を送出してください。ブラウザ操作で発生したそれ以外のエラーでは、汎用の失敗メッセージが返されます。こうした操作の失敗時には、ランナーはすべてのブラウザ呼び出しに出力を用意し、そのレスポンスに含まれる残りのブラウザ操作をスキップして、次のターンでモデルに再度選択させます。返された結果や状態が無効な場合、実行は停止します。状態を報告できない場合、通常の関数が失敗した場合、ネイティブのコンピューター操作のチェックが承認されなかった場合も停止します。

API リクエスト数を制限するには maxSteps または max_steps を設定します。デフォルトは 20 です。上限に達する最後のリクエストでは、新たな副作用を伴う処理を開始できません。SDK が HTTP リクエストを再試行しても、ドライバーの操作は再試行されません。操作と操作の間で停止するには、Node では signal、Python では cancelled を使用します。すでに進行中のドライバー呼び出しを常に取り消せるとは限りません。

ResponsesToolRunner はすべてのリクエストで tool_choice を維持します。ローカルツールの使用を常に必須にすると実行を終了できないため、ランナーは処理を始める前にこの設定を拒否します。ループには auto を使用し、ツール使用を強制する単発のリクエストには responses.create を使用してください。ツール使用が必須でも、宣言済みのサーバーツールも選択できる設定であれば有効です。

実行時のトラブルシューティング

クリック位置のずれの修正

新しいスクリーンショットを取得し、意図したウィンドウが写っていることを確認してください。スクリーンショットと操作には同じ座標系を使用します。1600 × 1200 の画面から 800 × 600 のスクリーンショットを送信した場合は、返された両方の座標を 2 倍にしてからクリックしてください。コンピュータードライバーが切り抜いたスクリーンショットを送信する場合は、座標の拡大縮小後に切り抜き位置のオフセットを加算します。ブラウザドライバーのポインター操作メソッドは、ズーム後もページの表示領域全体を基準とした CSS ピクセルを使用します。ディスプレイのピクセルと混同しないでください。

スクリーンショットのサイズは入力トークン数とコストに影響します。画像サイズの設定とモデルの制限については、スクリーンショットの取得を参照してください。

ストリーミングと実行の再開

Responses の実行は、デフォルトではストリーミングを使用しません。stream と onEvent（Node）または on_event（Python）を指定すると、ランナーは独立したストリームイベントを渡し、レスポンスが完了してから操作を実行します。eager を有効にすると、完了済みの出力アイテムを順番に先行実行することがあります。引数の差分を実行することはありません。

先行実行は、ランナーがレスポンス全体を検証する前に完了済みアイテムを安全に実行できる場合だけ有効にしてください。後続のイベントでそのアイテムが変更または削除された場合、ランナーは停止し、実行記録を保持します。操作を取り消すことはできません。すべての操作でレスポンス全体が検証に合格するまで待つ必要がある場合は、先行実行を無効のままにするか、空の先行実行ポリシーを使用してください。

完了済みアイテムが順不同で届いた場合やインデックスに欠番がある場合、ランナーはレスポンス全体が揃うまで待ってから、該当部分を実行します。ストリームが失敗しても、すでに発生した副作用の記録は残ります。

earlyExecution または early_execution を使用すると、先行実行する関数を通信上の名前で限定し、ネイティブのコンピューター操作のディスパッチャーを別のブール値で制御できます。空のオブジェクトを指定すると、すべてのローカルツールが延期されます。省略すると、通常どおり全体に先行実行が適用されます。順序を保つため、最初に延期されたツール以降のツールもすべて延期されます。iterate() を使用する場合は、先に進む前に完了したターンを確認してください。その時点で閉じれば、延期されたツールは実行されません。これらのオプションが変更するのは実行のタイミングだけで、承認の扱いは変わりません。

完了済みの個々の呼び出しについて、beforeEarlyCall または before_early_call はディスパッチ前に defer を返せます。先行実行の許可リストにない呼び出しを先行実行させることはできません。通常の関数に independent: true を指定するのは、ほかの操作に依存せず実行できる場合だけにしてください。台帳がなければ、独立した関数はストリームの受信と並行して実行できます。永続化する実行、ブラウザ操作、コンピューター操作では順序が維持されます。別の呼び出しが失敗しても、開始済みの処理の実行記録は残ります。

デフォルトでは、独立した呼び出しを同時に先行実行できるのは 2 件までです。この上限を変更するには、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 宣言では、認可情報とカスタムヘッダーが省略され、サーバー URL は SHA-256 フィンガープリントに置き換えられます。ネイティブのリクエストは引き続き元の URL を使用します。ローテーションが必要な認証情報は、認可情報またはヘッダーに含めてください。URL のパスや認識されないクエリ値を変更すると別の接続先として識別されるため、新しい実行が必要になります。生の MCP URL を含むチェックポイントからは再開できません。Node で MCP URL を保存するには crypto.subtle.digest が必要です。チェックポイントのその他の入力と出力も、アプリケーションの非公開データとして扱ってください。

再開時は現在有効な認証情報を指定し、意図したサーバーとアカウントに対応していることを確認してください。

保存される Code Interpreter 宣言には認証情報の名前とドメインが残りますが、秘密の値は消去されます。再開時にツール設定で現在の値を指定してください。MCP の承認では、空の always: {} または never: {} フィルターはすべてのツールに適用されます。

初期入力または保存済みの台帳に承認済みの MCP リクエストが含まれる場合は、Node では approveMcp、Python では approve_mcp を指定してください。ランナーは初回の保存や API リクエストの前に、対応する完了済みの MCP 呼び出しがない承認について、1 件ずつ改めて承認を求めます。これは台帳やコンテキスト予算の有無にかかわらず適用されます。完了済みの呼び出しと以前の拒否はそのまま維持されます。新たな承認が必要なときにコールバックがなければ、実行は停止します。

カスタムドライバーのローカル検証

予約デモまたは隔離デスクトップの例を変更する前に、付属のローカル演習を実行してください。ドライバーが扱う実際のページの状態、入力が反映された結果、クリーンアップを確認する処理を追加します。SDK の検証に合格しても、環境内で操作が正しく行われたことまでは保証されません。

動作する SDK ワークフローは初めてのタスクの実行、環境のセットアップは統合の設定例を参照してください。変更を加えた後は、成功を報告する前に、保存されたフォーム、ファイル、その他のアプリケーションの記録を確認してください。