Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Patches anwenden

Lass Modelle strukturierte Diffs vorschlagen, die deine Integration anwendet.

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:

  1. Rufe die Responses API mit dem Tool apply_patch auf
    • Gib dem Modell in input Informationen 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"}].
  2. 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.
  3. Wende die Patches in deiner Umgebung an
    • Führe die folgenden Schritte mit einem Patch-Harness oder einem Skript aus:
      • Werte den Diff in operation für jeden apply_patch_call aus.
      • 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.
  4. Melde die Ergebnisse an das Modell zurück
    • Rufe die Responses API erneut auf. Verwende dazu entweder previous_response_id oder übergib die bisherigen Konversationselemente erneut in input.
    • Übermittle ein Ereignis vom Typ apply_patch_call_output für jede call_id. Gib darin status und optional eine Zeichenfolge in output an.
    • Behalte tools=[{"type": "apply_patch"}] bei, damit das Modell den Code bei Bedarf weiterbearbeiten kann.
  5. Lass das Modell weiterarbeiten oder die Änderungen erklären
    • Das Modell kann weitere Operationen vom Typ apply_patch_call ausgeben.
    • Es kann auch verständlich erklären, was es geändert hat und warum.

Beispiel: Eine Funktion mit apply_patch umbenennen

Schritt 1: Bitte das Modell, die Änderungen zu planen und Patches auszugeben

Das Modell auffordern, Ä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

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

Patch anwenden und Ergebnisse zurückmelden
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:

Einen fehlgeschlagenen Aufruf von apply_patch melden
{
  "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:

  1. 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.path und, falls vorhanden, diff.
  2. Dateioperationen ausführen
    • Wende bei create_file und update_file den V4A-Diff auf das Dateisystem oder den Workspace im Arbeitsspeicher an.
    • Entferne bei delete_file die Datei unter path.
    • Halte für jede Operation fest, ob sie erfolgreich war, und erfasse etwaige Protokolle oder Fehlermeldungen.
  3. Ereignisse vom Typ apply_patch_call_output zurückgeben
    • Gib für jede call_id genau ein Ereignis vom Typ apply_patch_call_output mit 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 in output.

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 failed und eine aussagekräftige Meldung in output zurü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.

apply_patch mit dem Agents SDK 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.

TypeScript-Beispiel für apply_patch

So verwendest du apply_patch mit dem Agents SDK in TypeScript

Python-Beispiel für apply_patch

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.

Fehler: Datei nicht gefunden
{
  "type": "apply_patch_call_output",
  "call_id": "call_abc",
  "status": "failed",
  "output": "Error: File not found at path 'lib/baz.py'"
}

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.
  • Erwäge die Kombination mit dem Tool shell
    • Mit dem Tool shell kann das Modell Verzeichnisse durchsuchen, Dateien lesen und mit grep nach Stichwörtern suchen. So kann es relevante Dateien selbstständig finden und bearbeiten.
  • 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.

Nutzungshinweise