For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション

パッチの適用

モデルが構造化された差分を提案し、連携先のアプリケーションで適用できるようにします。

apply_patch ツールを使うと、GPT-5.1 が構造化された差分を用いて、コードベース内のファイルを作成、更新、削除できます。モデルは編集内容を提案するだけでなく、パッチ操作を出力します。アプリケーションがその操作を適用し、結果をモデルに返すことで、複数のステップにわたってコードの編集を繰り返すワークフローを実現できます。

利用場面

apply_patch の代表的な利用場面は次のとおりです。

  • 複数ファイルのリファクタリング :多数のファイルにまたがるシンボルの名前変更、ヘルパーの抽出、モジュールの再編成を一度に行います。
  • バグ修正 :問題の診断と正確なパッチの出力の両方をモデルに任せます。
  • テストとドキュメントの生成 :コードの変更に合わせて、新しいテストファイル、フィクスチャ、ドキュメントを作成します。
  • 移行と機械的な編集 :API の移行、型注釈、書式の修正など、定型的な更新を繰り返し適用します。

リポジトリと希望する変更内容をテキストで説明できれば、通常は apply_patch で対応する差分を生成できます。

Responses API でのパッチ適用ツールの使用

Responses API で apply_patch を使用する際の大まかな流れは次のとおりです。

  1. apply_patch ツールを指定して Responses API を呼び出し
    • input に利用可能なファイルのコンテキスト(またはその要約)を含めてモデルに提供するか、ファイルシステムを探索するためのツールをモデルに提供します。
    • tools=[{"type": "apply_patch"}] でツールを有効にします。
  2. モデルから 1 つ以上のパッチ操作を受け取り
    • レスポンスの出力には、1 つ以上の apply_patch_call オブジェクトが含まれます。
    • 各呼び出しは、作成、更新、削除のいずれか 1 つのファイル操作を表します。
  3. 環境内でのパッチの適用
    • 次の処理を行うパッチハーネスまたはスクリプトを実行します。
      • apply_patch_calloperation の差分を解釈
      • 作業ディレクトリまたはリポジトリにパッチを適用
      • 各パッチの成否と、ログやエラーメッセージを記録
  4. パッチの適用結果をモデルに報告
    • previous_response_id を指定するか、会話の項目を input に再度渡して、Responses API をもう一度呼び出します。
    • call_id に対応する apply_patch_call_output イベントを含めます。このイベントには status と、任意の output 文字列を含めます。
    • 必要に応じてモデルが編集を続けられるよう、tools=[{"type": "apply_patch"}] を維持します。
  5. モデルによる編集の継続または変更内容の説明
    • モデルは追加の apply_patch_call 操作を出力するか、
    • 変更内容とその理由をユーザー向けに説明します。

例:パッチ適用ツールによる関数名の変更

ステップ 1:モデルに計画とパッチの出力を依頼

モデルに計画とパッチの出力を依頼
const response = await client.responses.create({
  model: "gpt-6-astra",
  input: fileContext,
  tools: [{ type: "apply_patch" }],
});

const patchCalls = response.output.filter(
  (item) => item.type === "apply_patch_call"
);

apply_patch_call オブジェクトの例

apply_patch_call オブジェクトの例
{
    "id": "apc_08f3d96c87a585390069118b594f7481a088b16cda7d9415fe",
    "type": "apply_patch_call",
    "status": "completed",
    "call_id": "call_Rjsqzz96C5xzPb0jUWJFRTNW",
    "operation": {
        "type": "update_file",
        "diff": "
@@
-def fib(n):
+def fibonacci(n):
    if n <= 1:
        return n
-    return fib(n-1) + fib(n-2)                                                  +    return fibonacci(n-1) + fibonacci(n-2),
",
        "path": "lib/fib.py"
    }
}

ステップ 2:パッチの適用と結果の返送

パッチの適用と結果の返送
const results = patchCalls.map((call) => {
  const { success, output } = applyOperation(call.operation);

  return {
    type: "apply_patch_call_output",
    call_id: call.call_id,
    status: success ? "completed" : "failed",
    output,
  };
});

const followup = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: response.id,
  input: results,
  tools: [{ type: "apply_patch" }],
});

console.log(followup.output_text);

ファイルが見つからないなどの理由でパッチの適用に失敗した場合は、status: "failed" を設定し、モデルが対処できるよう、役立つ情報を含む output 文字列を渡します。

apply_patch 呼び出しの失敗を報告
{
  "type": "apply_patch_call_output",
  "call_id": "call_cNWm41dB3RyQcLNOVTIPBWZU",
  "status": "failed",
  "output": "Could not apply patch to lib/foo.py — file not found on disk"
}

パッチ適用の操作

操作の種類目的ペイロード
create_filepath に新しいファイルを作成します。diff は、ファイルの全内容を表す V4A 形式の差分です。
update_filepath にある既存のファイルを変更します。diff は、追加、削除、置換を含む V4A 形式の差分です。
delete_filepath にあるファイルを削除します。diff はありません。ファイル全体を削除します。

V4A 形式の差分を解釈し、変更を適用するのは、実装するパッチハーネスの役割です。参考実装については、Python Agents SDK または TypeScript Agents SDK のコードを参照してください。

パッチハーネスの実装

apply_patch ツールを使用する場合、入力スキーマを指定する必要はありません。モデルは operation オブジェクトの構築方法を理解しています。実装側では、次の処理を行います。

  1. レスポンス内の操作の解析
    • レスポンス内で type: "apply_patch_call" が設定されている項目を探します。
    • 各呼び出しの operation.typeoperation.path を確認し、diff があればそれも確認します。
  2. ファイル操作の適用
    • create_fileupdate_file では、V4A 差分をファイルシステムまたはメモリ内のワークスペースに適用します。
    • delete_file では、path にあるファイルを削除します。
    • 各操作の成否と、ログやエラーメッセージを記録します。
  3. apply_patch_call_output イベントの返却
    • call_id に対して、以下の内容を含む apply_patch_call_output イベントを必ず 1 件だけ出力します。
      • 操作が正常に適用された場合は status: "completed"
      • エラーが発生した場合は status: "failed"(人が読んで理解できる短い output 文字列を含めます)

安全性と堅牢性

  • パスの検証:ディレクトリトラバーサルを防ぎ、編集を許可されたディレクトリに限定します。
  • バックアップ:パッチを適用する前に、ファイルをバックアップするか、作業用のコピーで変更を行うことを検討します。
  • エラー処理:パッチを適用できない場合は、必ず failed ステータスと、状況を説明する output 文字列を返します。
  • 原子性:全体を一括で成功または失敗とする方式(いずれかのパッチが失敗したらロールバック)にするか、ファイルごとに成否を扱う方式にするかを決めます。

Agents SDK でのパッチ適用ツールの使用

Agents SDK からパッチ適用ツールを使用することもできます。この場合も、実際のファイル操作を処理するハーネスの実装は必要ですが、差分の処理には applyDiff 関数を使用できます。

Agents SDK でのパッチ適用ツールの使用
import { applyDiff, Agent, run, applyPatchTool } from "@openai/agents";

class WorkspaceEditor {
  async createFile(operation) {
    // convert the diff to the file content
    const content = applyDiff("", operation.diff, "create");
    // write the file content to the file system
    return { status: "completed", output: `Created ${operation.path}` };
  }

  async updateFile(operation) {
    // read the file content from the file system
    const current = "";
    // convert the diff to the new file content
    const newContent = applyDiff(current, operation.diff);
    // write the updated file content to the file system
    return { status: "completed", output: `Updated ${operation.path}` };
  }

  async deleteFile(operation) {
    // delete the file from the file system
    return { status: "completed", output: `Deleted ${operation.path}` };
  }
}

const editor = new WorkspaceEditor();

const agent = new Agent({
  name: "Patch Assistant",
  model: "gpt-6-astra",
  instructions:
    "You can edit files inside the /tmp directory using the apply_patch tool.",
  tools: [
    applyPatchTool({
      editor,
      // could also be a function for you to determine if approval is needed
      needsApproval: true,
      onApproval: async (_ctx, _approvalItem) => {
        // create your own approval logic
        return { approve: true };
      },
    }),
  ],
});

const result = await run(
  agent,
  "Create tasks.md with a shopping checklist of 5 entries."
);

console.log(`\nFinal response:\n${result.finalOutput}`);

完全に動作するサンプルは GitHub で確認できます。

パッチ適用ツールの例 - TypeScript

TypeScript で Agents SDK のパッチ適用ツールを使用する例

パッチ適用ツールの例 - Python

Python で Agents SDK のパッチ適用ツールを使用する例

よくあるエラーへの対処

status: "failed" と明確な output メッセージを返し、モデルがエラーから復旧できるようにします。

ファイルが見つからないエラー
{
  "type": "apply_patch_call_output",
  "call_id": "call_abc",
  "status": "failed",
  "output": "Error: File not found at path 'lib/baz.py'"
}

モデルはこれらのエラーメッセージをもとに、プロンプト内のファイルを読み直したり、変更を簡略化したりして、次に生成する差分を調整できます。

ベストプラクティス

  • ファイルに関する明確なコンテキストの提供
    • Responses API を呼び出す際は、例のようにファイルのスナップショットをインラインで含めるか、shell ツールなど、ファイルシステムを探索するためのツールをモデルに提供します。
  • shell ツールとの併用の検討
    • shell ツールと併用すると、モデルはファイルシステムのディレクトリの探索、ファイルの読み取り、grep によるキーワード検索を行えるため、エージェントとしてファイルを見つけて編集できます。
  • 対象を絞った小さな差分の推奨
    • システム指示で、大規模な書き直しよりも、対象を絞った最小限の編集を行うようモデルを促します。
  • 変更が問題なく適用されたことの確認
    • 一連のパッチを適用したら、テストやリンターを実行し、失敗した内容を次の input でモデルに伝えて修正できるようにします。

使用上の注意

API の対応状況 対応モデル
GPT-5.5
GPT-5.4
GPT-5.2
GPT-5.1