La herramienta apply_patch permite que GPT-5.1 cree, actualice y elimine archivos en tu base de código mediante diffs estructurados. En lugar de limitarse a sugerir cambios, el modelo genera operaciones de parche que tu aplicación aplica y cuyos resultados luego devuelve al modelo, lo que permite flujos de trabajo iterativos de edición de código en varios pasos.
Cuándo usarla
Algunos casos comunes en los que usarías apply_patch:
- Refactorización de varios archivos – Cambia nombres de símbolos, extrae funciones auxiliares o reorganiza módulos en varios archivos a la vez.
- Corrección de errores – Haz que el modelo diagnostique problemas y genere parches precisos.
- Generación de pruebas y documentación – Crea nuevos archivos de prueba, fixtures y documentación junto con los cambios de código.
- Migraciones y cambios mecánicos – Aplica actualizaciones repetitivas y estructuradas (migraciones de API, anotaciones de tipos, correcciones de formato, etc.).
Si puedes describir tu repositorio y el cambio deseado por escrito, apply_patch por lo general puede generar los diffs correspondientes.
Usar la herramienta Aplicar parches con la API Responses
A grandes rasgos, usar apply_patch con la API Responses consiste en lo siguiente:
- Llama a la API Responses con la herramienta
apply_patch- Proporciona al modelo contexto sobre los archivos disponibles (o un resumen) en
input, o dale herramientas para explorar tu sistema de archivos. - Habilita la herramienta con
tools=[{"type": "apply_patch"}].
- Proporciona al modelo contexto sobre los archivos disponibles (o un resumen) en
- Deja que el modelo devuelva una o más operaciones de parche
- La salida de Response incluye uno o más objetos
apply_patch_call. - Cada llamada describe una sola operación sobre un archivo: crear, actualizar o eliminar.
- La salida de Response incluye uno o más objetos
- Aplica los parches en tu entorno
- Ejecuta un arnés de ejecución de parches o un script que:
- Interprete el diff de
operationde cadaapply_patch_call. - Aplique el parche a tu directorio de trabajo o repositorio.
- Registre si cada parche se aplicó correctamente, junto con los registros o mensajes de error que se generen.
- Interprete el diff de
- Ejecuta un arnés de ejecución de parches o un script que:
- Devuelve al modelo los resultados de los parches
- Vuelve a llamar a la API Responses, ya sea con
previous_response_ido pasando de nuevo los elementos de la conversación eninput. - Incluye un evento
apply_patch_call_outputpor cadacall_id, con unstatusy una cadenaoutputopcional. - Mantén
tools=[{"type": "apply_patch"}]para que el modelo pueda seguir editando si es necesario.
- Vuelve a llamar a la API Responses, ya sea con
- Deja que el modelo continúe o explique los cambios
- El modelo puede generar más operaciones
apply_patch_call, o - Proporcionar una explicación para el usuario sobre qué cambió y por qué.
- El modelo puede generar más operaciones
Ejemplo: cambiar el nombre de una función con la herramienta Aplicar parches
Paso 1: pide al modelo que planifique y genere parches
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"
);Ejemplo de objeto 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"
}
}Paso 2: aplica el parche y devuelve los resultados
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 un parche falla (por ejemplo, porque no se encuentra el archivo), establece status: "failed" e incluye una cadena output útil para que el modelo pueda recuperarse del error:
{
"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"
}Operaciones de aplicación de parches
| Tipo de operación | Propósito | Carga útil |
|---|---|---|
create_file | Crea un archivo nuevo en path. | diff es un diff V4A que representa el contenido completo del archivo. |
update_file | Modifica un archivo existente en path. | diff es un diff V4A con adiciones, eliminaciones o reemplazos. |
delete_file | Elimina un archivo en path. | Sin diff; elimina el archivo por completo. |
Tu arnés de ejecución de parches se encarga de interpretar el formato de diff V4A y aplicar los cambios. Para ver implementaciones de referencia, consulta el código del Agents SDK para Python o del Agents SDK para TypeScript.
Implementar el arnés de ejecución de parches
Al usar la herramienta apply_patch, no proporcionas un esquema de entrada; el modelo sabe cómo construir objetos operation. Tu tarea consiste en lo siguiente:
- Analiza las operaciones de Response
- Busca en Response los elementos con
type: "apply_patch_call". - Para cada llamada, inspecciona
operation.type,operation.pathydiff, si está presente.
- Busca en Response los elementos con
- Aplica las operaciones de archivos
- Para
create_fileyupdate_file, aplica el diff V4A al sistema de archivos o al espacio de trabajo en memoria. - Para
delete_file, elimina el archivo ubicado enpath. - Registra si cada operación se completó correctamente y guarda los registros o mensajes de error.
- Para
- Devuelve eventos
apply_patch_call_output- Para cada
call_id, emite exactamente un eventoapply_patch_call_outputcon:status: "completed"si la operación se aplicó correctamente.status: "failed"si encontraste un error (incluye una cadenaoutputbreve y comprensible para las personas).
- Para cada
Seguridad y robustez
- Validación de rutas: evita los ataques de recorrido de directorios y restringe las ediciones a los directorios permitidos.
- Copias de seguridad: considera crear copias de seguridad de los archivos (o trabajar en una copia temporal) antes de aplicar los parches.
- Manejo de errores: devuelve siempre el estado
failedcon una cadenaoutputinformativa cuando no se puedan aplicar los parches. - Atomicidad: decide si quieres una semántica de “todo o nada” (revertir los cambios si falla algún parche) o resultados de éxito o error por archivo.
Usar la herramienta para aplicar parches con el Agents SDK
Como alternativa, puedes usar el Agents SDK para acceder a la herramienta para aplicar parches. Aún tendrás que implementar el arnés de ejecución que realiza las operaciones de archivos, pero puedes usar la función applyDiff para procesar los 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}`);Puedes encontrar ejemplos completos y funcionales en GitHub.
Ejemplo de cómo usar la herramienta para aplicar parches con el Agents SDK en TypeScript
Ejemplo de cómo usar la herramienta para aplicar parches con el Agents SDK en Python
Manejo de errores comunes
Usa status: "failed" junto con un mensaje output claro para ayudar al modelo a recuperarse del error.
{
"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):"
}El modelo puede ajustar los siguientes diffs en función de estos mensajes de error (por ejemplo, volviendo a leer un archivo incluido en tu prompt o simplificando un cambio).
Prácticas recomendadas
- Proporciona un contexto claro sobre los archivos
- Cuando llames a la API Responses, incluye una instantánea de tus archivos directamente en la solicitud (como en el ejemplo) o proporciona al modelo herramientas para explorar tu sistema de archivos (como la herramienta
shell).
- Cuando llames a la API Responses, incluye una instantánea de tus archivos directamente en la solicitud (como en el ejemplo) o proporciona al modelo herramientas para explorar tu sistema de archivos (como la herramienta
- Considera usarla junto con la herramienta
shell- Al usarla junto con la herramienta
shell, el modelo puede explorar directorios del sistema de archivos, leer archivos y buscar palabras clave con grep, lo que permite localizar y editar archivos mediante agentes.
- Al usarla junto con la herramienta
- Promueve diffs pequeños y específicos
- En las instrucciones del sistema, orienta al modelo hacia ediciones mínimas y específicas en lugar de reescrituras extensas.
- Asegúrate de que los cambios se apliquen sin problemas
- Después de una serie de parches, ejecuta tus pruebas o linters e incluye los fallos en el siguiente
inputpara que el modelo pueda corregirlos.
- Después de una serie de parches, ejecuta tus pruebas o linters e incluye los fallos en el siguiente
Notas de uso
| Disponibilidad en las API | Modelos compatibles |
|---|---|
| GPT-5.5 GPT-5.4 GPT-5.2 GPT-5.1 |