For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale

Application de patchs

Permettez aux modèles de proposer des diffs structurés que votre intégration applique.

L’outil apply_patch permet à GPT-5.1 de créer, de modifier et de supprimer des fichiers dans votre base de code à l’aide de diffs structurés. Au lieu de simplement suggérer des modifications, le modèle produit des opérations de patch que votre application applique avant d’en communiquer les résultats au modèle. Vous pouvez ainsi mettre en place des workflows itératifs de modification de code en plusieurs étapes.

Quand l’utiliser

Voici quelques cas d’utilisation courants d’apply_patch :

  • Refactorisations sur plusieurs fichiers – Renommez des symboles, extrayez des fonctions utilitaires ou réorganisez des modules dans de nombreux fichiers à la fois.
  • Correction de bugs – Demandez au modèle de diagnostiquer les problèmes et de produire des patchs précis.
  • Génération de tests et de documentation – Créez de nouveaux fichiers de test, des fixtures et de la documentation en parallèle des modifications du code.
  • Migrations et modifications mécaniques – Appliquez des mises à jour répétitives et structurées (migrations d’API, annotations de types, corrections de mise en forme, etc.).

Si vous pouvez décrire votre dépôt et la modification souhaitée sous forme de texte, apply_patch peut généralement générer les diffs correspondants.

Utilisez l’outil d’application de patchs avec l’API Responses

Voici les grandes étapes de l’utilisation de apply_patch avec l’API Responses :

  1. Appelez l’API Responses avec l’outil apply_patch
    • Fournissez au modèle du contexte sur les fichiers disponibles (ou un résumé) dans votre input, ou donnez-lui des outils pour explorer votre système de fichiers.
    • Activez l’outil avec tools=[{"type": "apply_patch"}].
  2. Laissez le modèle renvoyer une ou plusieurs opérations de patch
    • La sortie de l’objet Response comprend un ou plusieurs objets apply_patch_call.
    • Chaque appel décrit une seule opération sur un fichier : création, modification ou suppression.
  3. Appliquez les patchs dans votre environnement
    • Exécutez un harnais d’application de patchs ou un script qui :
      • Interprète le diff de operation pour chaque apply_patch_call.
      • Applique le patch à votre répertoire de travail ou à votre dépôt.
      • Enregistre le succès ou l’échec de chaque patch, ainsi que les éventuels journaux ou messages d’erreur.
  4. Communiquez les résultats des patchs au modèle
    • Appelez à nouveau l’API Responses, soit avec previous_response_id, soit en renvoyant les éléments de votre conversation dans input.
    • Incluez un événement apply_patch_call_output pour chaque call_id, avec un status et, si nécessaire, une chaîne output.
    • Conservez tools=[{"type": "apply_patch"}] pour que le modèle puisse continuer à apporter des modifications si nécessaire.
  5. Laissez le modèle poursuivre ou expliquer les modifications
    • Le modèle peut produire d’autres opérations apply_patch_call, ou
    • Fournir à l’utilisateur une explication des modifications apportées et de leurs raisons.

Exemple : renommer une fonction avec l’outil d’application de patchs

Étape 1 : demandez au modèle de planifier les modifications et de produire des patchs

Demandez au modèle de planifier les modifications et de produire des patchs
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"
);

Exemple d’objet apply_patch_call

Exemple d’objet 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"
    }
}

Étape 2 : appliquez le patch et renvoyez les résultats

Appliquez le patch et renvoyez les résultats
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);

Si l’application d’un patch échoue (par exemple, si le fichier est introuvable), définissez status: "failed" et incluez une chaîne output informative pour permettre au modèle de corriger le problème :

Signalez l’échec d’un appel 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"
}

Opérations d’application de patchs

Type d’opérationObjectifCharge utile
create_fileCrée un nouveau fichier au chemin path.diff est un diff V4A représentant le contenu complet du fichier.
update_fileModifie un fichier existant au chemin path.diff est un diff V4A contenant des ajouts, des suppressions ou des remplacements.
delete_fileSupprime un fichier au chemin path.Aucun diff ; le fichier est entièrement supprimé.

Votre harnais d’application de patchs doit interpréter le format de diff V4A et appliquer les modifications. Pour des implémentations de référence, consultez le code de l’Agents SDK pour Python ou de l’Agents SDK pour TypeScript.

Implémentation du harnais d’application de patchs

Lorsque vous utilisez l’outil apply_patch, vous ne fournissez pas de schéma d’entrée : le modèle sait construire les objets operation. Vous devez :

  1. Extraire les opérations de l’objet Response
    • Parcourez l’objet Response pour trouver les éléments comportant type: "apply_patch_call".
    • Pour chaque appel, examinez operation.type, operation.path et tout éventuel diff.
  2. Appliquez les opérations sur les fichiers
    • Pour create_file et update_file, appliquez le diff V4A au système de fichiers ou à l’espace de travail en mémoire.
    • Pour delete_file, supprimez le fichier situé à l’emplacement path.
    • Consignez la réussite ou l’échec de chaque opération, ainsi que les éventuels journaux ou messages d’erreur.
  3. Renvoyez des événements apply_patch_call_output
    • Pour chaque call_id, émettez exactement un événement apply_patch_call_output avec :
      • status: "completed" si l’opération a été appliquée avec succès.
      • status: "failed" si vous avez rencontré une erreur (incluez une courte chaîne output compréhensible par une personne).

Sécurité et robustesse

  • Validation des chemins : empêchez les traversées de répertoires et limitez les modifications aux répertoires autorisés.
  • Sauvegardes : envisagez de sauvegarder les fichiers (ou de travailler sur une copie temporaire) avant d’appliquer les patchs.
  • Gestion des erreurs : renvoyez toujours un statut failed accompagné d’une chaîne output explicative lorsque les patchs ne peuvent pas être appliqués.
  • Atomicité : choisissez entre un fonctionnement « tout ou rien » (annulation de toutes les modifications si un patch échoue) et une gestion de la réussite ou de l’échec fichier par fichier.

Utilisez l’outil d’application de patchs avec l’Agents SDK

Vous pouvez également utiliser l’Agents SDK pour accéder à l’outil d’application de patchs. Vous devrez toujours implémenter le harnais qui effectue les opérations sur les fichiers, mais vous pouvez utiliser la fonction applyDiff pour traiter les diffs.

Utilisez l’outil d’application de patchs avec l’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}`);

Vous trouverez des exemples complets et fonctionnels sur GitHub.

Exemple d’utilisation de l’outil d’application de patchs - TypeScript

Exemple d’utilisation de l’outil d’application de patchs avec l’Agents SDK en TypeScript

Exemple d’utilisation de l’outil d’application de patchs - Python

Exemple d’utilisation de l’outil d’application de patchs avec l’Agents SDK en Python

Gestion des erreurs courantes

Utilisez status: "failed" avec un message output clair pour aider le modèle à corriger le problème.

Erreur : fichier introuvable
{
  "type": "apply_patch_call_output",
  "call_id": "call_abc",
  "status": "failed",
  "output": "Error: File not found at path 'lib/baz.py'"
}

Le modèle peut ensuite ajuster les prochains diffs en fonction de ces messages d’erreur (par exemple, en relisant un fichier inclus dans votre prompt ou en simplifiant une modification).

Bonnes pratiques

  • Fournissez un contexte clair sur les fichiers
    • Lorsque vous appelez l’API Responses, incluez directement un instantané de vos fichiers (comme dans l’exemple) ou fournissez au modèle des outils pour explorer votre système de fichiers (comme l’outil shell).
  • Envisagez de l’associer à l’outil shell
    • Associé à l’outil shell, cet outil permet au modèle d’explorer les répertoires du système de fichiers, de lire des fichiers et de rechercher des mots-clés avec grep, pour trouver et modifier des fichiers de manière agentique.
  • Encouragez les diffs courts et ciblés
    • Dans vos instructions système, incitez le modèle à effectuer des modifications minimales et ciblées plutôt que de vastes réécritures.
  • Vérifiez que les modifications s’appliquent correctement
    • Après une série de patchs, exécutez vos tests ou vos linters et transmettez les erreurs dans le prochain input pour que le modèle puisse les corriger.

Notes d’utilisation

Disponibilité dans les API Modèles pris en charge
GPT-5.5
GPT-5.4
GPT-5.2
GPT-5.1