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 :
- 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"}].
- Fournissez au modèle du contexte sur les fichiers disponibles (ou un résumé) dans votre
- 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.
- La sortie de l’objet Response comprend un ou plusieurs objets
- Appliquez les patchs dans votre environnement
- Exécutez un harnais d’application de patchs ou un script qui :
- Interprète le diff de
operationpour chaqueapply_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.
- Interprète le diff de
- Exécutez un harnais d’application de patchs ou un script qui :
- 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 dansinput. - Incluez un événement
apply_patch_call_outputpour chaquecall_id, avec unstatuset, si nécessaire, une chaîneoutput. - Conservez
tools=[{"type": "apply_patch"}]pour que le modèle puisse continuer à apporter des modifications si nécessaire.
- Appelez à nouveau l’API Responses, soit avec
- 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.
- Le modèle peut produire d’autres opérations
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
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
{
"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
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 :
{
"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ération | Objectif | Charge utile |
|---|---|---|
create_file | Crée un nouveau fichier au chemin path. | diff est un diff V4A représentant le contenu complet du fichier. |
update_file | Modifie un fichier existant au chemin path. | diff est un diff V4A contenant des ajouts, des suppressions ou des remplacements. |
delete_file | Supprime 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 :
- 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.pathet tout éventueldiff.
- Parcourez l’objet Response pour trouver les éléments comportant
- Appliquez les opérations sur les fichiers
- Pour
create_fileetupdate_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’emplacementpath. - Consignez la réussite ou l’échec de chaque opération, ainsi que les éventuels journaux ou messages d’erreur.
- Pour
- Renvoyez des événements
apply_patch_call_output- Pour chaque
call_id, émettez exactement un événementapply_patch_call_outputavec :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îneoutputcompréhensible par une personne).
- Pour chaque
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
failedaccompagné d’une chaîneoutputexplicative 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.
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 avec l’Agents SDK en TypeScript
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.
{
"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):"
}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).
- 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
- 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.
- Associé à l’outil
- 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
inputpour que le modèle puisse les corriger.
- Après une série de patchs, exécutez vos tests ou vos linters et transmettez les erreurs dans le prochain
Notes d’utilisation
| Disponibilité dans les API | Modèles pris en charge |
|---|---|
| GPT-5.5 GPT-5.4 GPT-5.2 GPT-5.1 |