apply_patch ツールを使うと、GPT-5.1 が構造化された差分を用いて、コードベース内のファイルを作成、更新、削除できます。モデルは編集内容を提案するだけでなく、パッチ操作を出力します。アプリケーションがその操作を適用し、結果をモデルに返すことで、複数のステップにわたってコードの編集を繰り返すワークフローを実現できます。
利用場面
apply_patch の代表的な利用場面は次のとおりです。
- 複数ファイルのリファクタリング :多数のファイルにまたがるシンボルの名前変更、ヘルパーの抽出、モジュールの再編成を一度に行います。
- バグ修正 :問題の診断と正確なパッチの出力の両方をモデルに任せます。
- テストとドキュメントの生成 :コードの変更に合わせて、新しいテストファイル、フィクスチャ、ドキュメントを作成します。
- 移行と機械的な編集 :API の移行、型注釈、書式の修正など、定型的な更新を繰り返し適用します。
リポジトリと希望する変更内容をテキストで説明できれば、通常は apply_patch で対応する差分を生成できます。
Responses API でのパッチ適用ツールの使用
Responses API で apply_patch を使用する際の大まかな流れは次のとおりです。
apply_patchツールを指定して Responses API を呼び出しinputに利用可能なファイルのコンテキスト(またはその要約)を含めてモデルに提供するか、ファイルシステムを探索するためのツールをモデルに提供します。tools=[{"type": "apply_patch"}]でツールを有効にします。
- モデルから 1 つ以上のパッチ操作を受け取り
- レスポンスの出力には、1 つ以上の
apply_patch_callオブジェクトが含まれます。 - 各呼び出しは、作成、更新、削除のいずれか 1 つのファイル操作を表します。
- レスポンスの出力には、1 つ以上の
- 環境内でのパッチの適用
- 次の処理を行うパッチハーネスまたはスクリプトを実行します。
- 各
apply_patch_callのoperationの差分を解釈 - 作業ディレクトリまたはリポジトリにパッチを適用
- 各パッチの成否と、ログやエラーメッセージを記録
- 各
- 次の処理を行うパッチハーネスまたはスクリプトを実行します。
- パッチの適用結果をモデルに報告
previous_response_idを指定するか、会話の項目をinputに再度渡して、Responses API をもう一度呼び出します。- 各
call_idに対応するapply_patch_call_outputイベントを含めます。このイベントにはstatusと、任意のoutput文字列を含めます。 - 必要に応じてモデルが編集を続けられるよう、
tools=[{"type": "apply_patch"}]を維持します。
- モデルによる編集の継続または変更内容の説明
- モデルは追加の
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 オブジェクトの例
{
"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 文字列を渡します。
{
"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_file | path に新しいファイルを作成します。 | diff は、ファイルの全内容を表す V4A 形式の差分です。 |
update_file | path にある既存のファイルを変更します。 | diff は、追加、削除、置換を含む V4A 形式の差分です。 |
delete_file | path にあるファイルを削除します。 | diff はありません。ファイル全体を削除します。 |
V4A 形式の差分を解釈し、変更を適用するのは、実装するパッチハーネスの役割です。参考実装については、Python Agents SDK または TypeScript Agents SDK のコードを参照してください。
パッチハーネスの実装
apply_patch ツールを使用する場合、入力スキーマを指定する必要はありません。モデルは operation オブジェクトの構築方法を理解しています。実装側では、次の処理を行います。
- レスポンス内の操作の解析
- レスポンス内で
type: "apply_patch_call"が設定されている項目を探します。 - 各呼び出しの
operation.typeとoperation.pathを確認し、diffがあればそれも確認します。
- レスポンス内で
- ファイル操作の適用
create_fileとupdate_fileでは、V4A 差分をファイルシステムまたはメモリ内のワークスペースに適用します。delete_fileでは、pathにあるファイルを削除します。- 各操作の成否と、ログやエラーメッセージを記録します。
apply_patch_call_outputイベントの返却- 各
call_idに対して、以下の内容を含むapply_patch_call_outputイベントを必ず 1 件だけ出力します。- 操作が正常に適用された場合は
status: "completed" - エラーが発生した場合は
status: "failed"(人が読んで理解できる短いoutput文字列を含めます)
- 操作が正常に適用された場合は
- 各
安全性と堅牢性
- パスの検証:ディレクトリトラバーサルを防ぎ、編集を許可されたディレクトリに限定します。
- バックアップ:パッチを適用する前に、ファイルをバックアップするか、作業用のコピーで変更を行うことを検討します。
- エラー処理:パッチを適用できない場合は、必ず
failedステータスと、状況を説明するoutput文字列を返します。 - 原子性:全体を一括で成功または失敗とする方式(いずれかのパッチが失敗したらロールバック)にするか、ファイルごとに成否を扱う方式にするかを決めます。
Agents SDK でのパッチ適用ツールの使用
Agents SDK からパッチ適用ツールを使用することもできます。この場合も、実際のファイル操作を処理するハーネスの実装は必要ですが、差分の処理には applyDiff 関数を使用できます。
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 で Agents SDK のパッチ適用ツールを使用する例
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'"
}{
"type": "apply_patch_call_output",
"call_id": "call_abc",
"status": "failed",
"output": "Error: Invalid Context:\n@@ def fib(n):"
}モデルはこれらのエラーメッセージをもとに、プロンプト内のファイルを読み直したり、変更を簡略化したりして、次に生成する差分を調整できます。
ベストプラクティス
- ファイルに関する明確なコンテキストの提供
- Responses API を呼び出す際は、例のようにファイルのスナップショットをインラインで含めるか、
shellツールなど、ファイルシステムを探索するためのツールをモデルに提供します。
- Responses API を呼び出す際は、例のようにファイルのスナップショットをインラインで含めるか、
shellツールとの併用の検討shellツールと併用すると、モデルはファイルシステムのディレクトリの探索、ファイルの読み取り、grep によるキーワード検索を行えるため、エージェントとしてファイルを見つけて編集できます。
- 対象を絞った小さな差分の推奨
- システム指示で、大規模な書き直しよりも、対象を絞った最小限の編集を行うようモデルを促します。
- 変更が問題なく適用されたことの確認
- 一連のパッチを適用したら、テストやリンターを実行し、失敗した内容を次の
inputでモデルに伝えて修正できるようにします。
- 一連のパッチを適用したら、テストやリンターを実行し、失敗した内容を次の
使用上の注意
| API の対応状況 | 対応モデル |
|---|---|
| GPT-5.5 GPT-5.4 GPT-5.2 GPT-5.1 |