Verwende apply_patch mit der Responses API, damit das Modell das Erstellen, Ändern und Löschen von Dateien in Form strukturierter Diffs vorschlagen kann. Deine Anwendung führt jede Operation aus und meldet das jeweilige Ergebnis zurück. Die Beispiele verwenden gpt-6-astra.
Einsatzmöglichkeiten
Du kannst apply_patch für die folgenden Aufgaben verwenden.
- Dateiübergreifendes Refactoring. Benenne Symbole um, lagere Hilfsfunktionen aus oder ordne Module in mehreren Dateien gleichzeitig neu.
- Fehlerbehebung. Lass das Modell Probleme diagnostizieren und gezielte Patches ausgeben.
- Tests und Dokumentation erstellen. Erstelle zusammen mit den Codeänderungen neue Testdateien, Fixtures und Dokumentation.
- Migrationen und gleichförmige Änderungen. Führe wiederkehrende, strukturierte Änderungen durch, etwa API-Migrationen, das Ergänzen von Typannotationen oder Formatierungskorrekturen.
Wenn du dein Repository und die gewünschte Änderung in Worten beschreiben kannst, kann apply_patch in der Regel die passenden Diffs erzeugen.
apply_patch mit der Responses API verwenden
So verwendest du apply_patch mit der Responses API:
- Rufe die Responses API mit dem Tool
apply_patchauf- Gib dem Modell in
inputInformationen zu den verfügbaren Dateien oder eine Zusammenfassung. Alternativ kannst du ihm Tools geben, mit denen es dein Dateisystem erkunden kann. - Aktiviere das Tool mit
tools=[{"type": "apply_patch"}].
- Gib dem Modell in
- Lass das Modell eine oder mehrere Patch-Operationen zurückgeben
- Die API-Antwort enthält ein oder mehrere Objekte vom Typ
apply_patch_call. - Jeder Aufruf beschreibt genau eine Dateioperation: eine Datei erstellen, ändern oder löschen.
- Die API-Antwort enthält ein oder mehrere Objekte vom Typ
- Wende die Patches in deiner Umgebung an
- Führe die folgenden Schritte mit einem Patch-Harness oder einem Skript aus:
- Werte den Diff in
operationfür jedenapply_patch_callaus. - Wende den Patch auf dein Arbeitsverzeichnis oder Repository an.
- Halte für jeden Patch fest, ob er erfolgreich war, und erfasse etwaige Protokolle oder Fehlermeldungen.
- Werte den Diff in
- Führe die folgenden Schritte mit einem Patch-Harness oder einem Skript aus:
- Melde die Ergebnisse an das Modell zurück
- Rufe die Responses API erneut auf. Verwende dazu entweder
previous_response_idoder übergib die bisherigen Konversationselemente erneut ininput. - Übermittle ein Ereignis vom Typ
apply_patch_call_outputfür jedecall_id. Gib darinstatusund optional eine Zeichenfolge inoutputan. - Behalte
tools=[{"type": "apply_patch"}]bei, damit das Modell den Code bei Bedarf weiterbearbeiten kann.
- Rufe die Responses API erneut auf. Verwende dazu entweder
- Lass das Modell weiterarbeiten oder die Änderungen erklären
- Das Modell kann weitere Operationen vom Typ
apply_patch_callausgeben. - Es kann auch verständlich erklären, was es geändert hat und warum.
- Das Modell kann weitere Operationen vom Typ
Beispiel: Eine Funktion mit apply_patch umbenennen
Schritt 1: Bitte das Modell, die Änderungen zu planen und Patches auszugeben
import OpenAI from "openai";
// Application-owned helper; see "Implementing the patch harness" in the guide.
// This demo only applies exact updates to the two in-memory files below.
import { applyOperation } from "../../support/apply-patch.mjs";
const client = new OpenAI();
const files = {
"lib/fib.py": `def fib(n):
if n <= 1:
return n
return fib(n - 1) + fib(n - 2)
`,
"run.py": `from lib.fib import fib
print(fib(42))
`,
};
const fileContext = `The user has the following files:
<BEGIN_FILES>
${Object.entries(files)
.map(([path, content]) => `===== ${path}\n${content}`)
.join("\n")}
<END_FILES>
Help me rename the fib() function to fibonacci().`;
let response = await client.responses.create({
model: "gpt-6-astra",
input: fileContext,
tools: [{ type: "apply_patch" }],
});
let patchCalls = response.output.filter(
(item) => item.type === "apply_patch_call"
);Beispiel für ein Objekt vom Typ 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"
}
}Schritt 2: Wende den Patch an und melde die Ergebnisse zurück
for (let turn = 0; patchCalls.length > 0; turn++) {
if (turn === 8) throw new Error("Patch workflow exceeded eight tool turns.");
const results = patchCalls.map((call): OpenAI.Responses.ResponseInputItem => {
const { success, output } = applyOperation(files, call.operation);
return {
type: "apply_patch_call_output",
call_id: call.call_id,
status: success ? "completed" : "failed",
output,
};
});
response = await client.responses.create({
model: "gpt-6-astra",
previous_response_id: response.id,
input: results,
tools: [{ type: "apply_patch" }],
});
patchCalls = response.output.filter(
(item) => item.type === "apply_patch_call"
);
}
console.log(response.output_text);
for (const [path, content] of Object.entries(files)) {
process.stdout.write(`===== ${path}\n${content}`);
}Wenn sich ein Patch nicht anwenden lässt, etwa weil die Datei fehlt, setze status: "failed". Beschreibe den Fehler in output, damit das Modell darauf reagieren kann:
{
"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"
}Patch-Operationen
| Operationstyp | Zweck | Nutzdaten |
|---|---|---|
create_file |
Eine neue Datei unter path erstellen. |
diff enthält einen V4A-Diff mit dem vollständigen Dateiinhalt. |
update_file |
Eine vorhandene Datei unter path ändern. |
diff enthält einen V4A-Diff mit Ergänzungen, Löschungen oder Ersetzungen. |
delete_file |
Die Datei unter path entfernen. |
Ohne diff. Lösche die Datei vollständig. |
Dein Patch-Harness wertet Diffs im V4A-Format aus und wendet die Änderungen an. Referenzimplementierungen findest du im Quellcode des Python Agents SDK und des TypeScript Agents SDK.
Den Patch-Harness implementieren
Beim Aufruf des Tools apply_patch gibst du kein Eingabeschema an. Das Modell weiß, wie es operation-Objekte erstellt. Deine Implementierung übernimmt folgende Aufgaben:
- Operationen aus der API-Antwort auslesen
- Suche in der Antwort nach Elementen mit
type: "apply_patch_call". - Prüfe für jeden Aufruf
operation.type,operation.pathund, falls vorhanden,diff.
- Suche in der Antwort nach Elementen mit
- Dateioperationen ausführen
- Wende bei
create_fileundupdate_fileden V4A-Diff auf das Dateisystem oder den Workspace im Arbeitsspeicher an. - Entferne bei
delete_filedie Datei unterpath. - Halte für jede Operation fest, ob sie erfolgreich war, und erfasse etwaige Protokolle oder Fehlermeldungen.
- Wende bei
- Ereignisse vom Typ
apply_patch_call_outputzurückgeben- Gib für jede
call_idgenau ein Ereignis vom Typapply_patch_call_outputmit dem passenden Status aus:status: "completed", wenn die Operation erfolgreich ausgeführt wurde.status: "failed", wenn ein Fehler aufgetreten ist. Beschreibe den Fehler kurz und verständlich inoutput.
- Gib für jede
Sicherheit und Robustheit
- Pfade validieren: Verhindere Directory-Traversal-Angriffe und beschränke Änderungen auf die zulässigen Verzeichnisse.
- Sicherungskopien: Überlege, ob du vor dem Anwenden der Patches die Dateien sichern oder in einer temporären Kopie arbeiten möchtest.
- Fehlerbehandlung: Wenn sich ein Patch nicht anwenden lässt, gib immer den Status
failedund eine aussagekräftige Meldung inoutputzurück. - Atomarität: Entscheide, ob du nach dem Alles-oder-nichts-Prinzip alle Änderungen rückgängig machst, sobald ein Patch fehlschlägt, oder ob du Erfolg und Fehlschlag für jede Datei separat behandelst.
apply_patch mit dem Agents SDK verwenden
Du kannst apply_patch auch über das Agents SDK verwenden. Den Harness für die eigentlichen Dateioperationen musst du weiterhin selbst implementieren. Für die Verarbeitung der Diffs kannst du die Funktion applyDiff verwenden.
import {
mkdirSync,
realpathSync,
lstatSync,
readFileSync,
writeFileSync,
unlinkSync,
} from "node:fs";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import {
applyDiff,
Agent,
run,
applyPatchTool,
type Editor,
type ApplyPatchResult,
} from "@openai/agents";
class WorkspaceEditor implements Editor {
root: string;
constructor(root = "workspace") {
mkdirSync(root, { recursive: true });
this.root = realpathSync(root);
}
path(name: string) {
const target = resolve(this.root, name);
const relativePath = relative(this.root, target);
if (
!relativePath ||
isAbsolute(relativePath) ||
relativePath === ".." ||
relativePath.startsWith(`..${sep}`)
) {
throw new Error("Patch paths must stay inside the workspace");
}
let current = this.root;
for (const part of relativePath.split(sep)) {
current = join(current, part);
if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink()) {
throw new Error("Patch paths must not traverse symbolic links");
}
}
return target;
}
async createFile(
operation: Parameters<Editor["createFile"]>[0]
): Promise<ApplyPatchResult> {
const path = this.path(operation.path);
const content = applyDiff("", operation.diff, "create");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, content, { encoding: "utf8", flag: "wx" });
return { status: "completed", output: `Created ${operation.path}` };
}
async updateFile(
operation: Parameters<Editor["updateFile"]>[0]
): Promise<ApplyPatchResult> {
const path = this.path(operation.path);
const content = applyDiff(readFileSync(path, "utf8"), operation.diff);
writeFileSync(path, content, "utf8");
return { status: "completed", output: `Updated ${operation.path}` };
}
async deleteFile(
operation: Parameters<Editor["deleteFile"]>[0]
): Promise<ApplyPatchResult> {
unlinkSync(this.path(operation.path));
return { status: "completed", output: `Deleted ${operation.path}` };
}
}
const editor = new WorkspaceEditor();
const agent = new Agent({
name: "Patch Assistant",
model: "gpt-6-astra",
instructions:
"Use apply_patch to edit files in the workspace. Supply paths relative to that workspace.",
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}`);Vollständige, lauffähige Beispiele findest du auf GitHub.
So verwendest du apply_patch mit dem Agents SDK in TypeScript
So verwendest du apply_patch mit dem Agents SDK in Python
Häufige Fehler behandeln
Gib status: "failed" und eine verständliche Meldung in output zurück, damit das Modell auf den Fehler reagieren kann.
{
"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):"
}Anhand dieser Fehlermeldungen kann das Modell spätere Diffs anpassen, etwa indem es eine Datei aus deinem Prompt erneut liest oder eine Änderung vereinfacht.
Bewährte Vorgehensweisen
- Gib dem Modell klare Informationen zu den Dateien
- Übermittle beim Aufruf der Responses API den aktuellen Inhalt deiner Dateien direkt in der Eingabe (wie im Beispiel) oder gib dem Modell Tools, mit denen es dein Dateisystem erkunden kann, etwa das Tool
shell.
- Übermittle beim Aufruf der Responses API den aktuellen Inhalt deiner Dateien direkt in der Eingabe (wie im Beispiel) oder gib dem Modell Tools, mit denen es dein Dateisystem erkunden kann, etwa das Tool
- Erwäge die Kombination mit dem Tool
shell- Mit dem Tool
shellkann das Modell Verzeichnisse durchsuchen, Dateien lesen und mit grep nach Stichwörtern suchen. So kann es relevante Dateien selbstständig finden und bearbeiten.
- Mit dem Tool
- Rege kleine, gezielte Diffs an
- Fordere das Modell in deinen Systemanweisungen auf, Änderungen klein zu halten und gezielt vorzunehmen, statt große Teile des Codes neu zu schreiben.
- Prüfe, ob die Änderungen fehlerfrei übernommen wurden
- Führe nach einer Reihe von Patches deine Tests oder Linter aus. Übermittle etwaige Fehler im nächsten
input, damit das Modell sie beheben kann.
- Führe nach einer Reihe von Patches deine Tests oder Linter aus. Übermittle etwaige Fehler im nächsten
Nutzungshinweise
| API-Verfügbarkeit | Unterstützte Modelle |
|---|---|