For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Aplicar parches

Permite que los modelos propongan diffs estructurados que tu integración aplica.

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:

  1. 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"}].
  2. 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.
  3. Aplica los parches en tu entorno
    • Ejecuta un arnés de ejecución de parches o un script que:
      • Interprete el diff de operation de cada apply_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.
  4. Devuelve al modelo los resultados de los parches
    • Vuelve a llamar a la API Responses, ya sea con previous_response_id o pasando de nuevo los elementos de la conversación en input.
    • Incluye un evento apply_patch_call_output por cada call_id, con un status y una cadena output opcional.
    • Mantén tools=[{"type": "apply_patch"}] para que el modelo pueda seguir editando si es necesario.
  5. 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é.

Ejemplo: cambiar el nombre de una función con la herramienta Aplicar parches

Paso 1: pide al modelo que planifique y genere parches

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

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

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:

Informa de una llamada fallida a 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"
}

Operaciones de aplicación de parches

Tipo de operaciónPropósitoCarga útil
create_fileCrea un archivo nuevo en path.diff es un diff V4A que representa el contenido completo del archivo.
update_fileModifica un archivo existente en path.diff es un diff V4A con adiciones, eliminaciones o reemplazos.
delete_fileElimina 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:

  1. Analiza las operaciones de Response
    • Busca en Response los elementos con type: "apply_patch_call".
    • Para cada llamada, inspecciona operation.type, operation.path y diff, si está presente.
  2. Aplica las operaciones de archivos
    • Para create_file y update_file, aplica el diff V4A al sistema de archivos o al espacio de trabajo en memoria.
    • Para delete_file, elimina el archivo ubicado en path.
    • Registra si cada operación se completó correctamente y guarda los registros o mensajes de error.
  3. Devuelve eventos apply_patch_call_output
    • Para cada call_id, emite exactamente un evento apply_patch_call_output con:
      • status: "completed" si la operación se aplicó correctamente.
      • status: "failed" si encontraste un error (incluye una cadena output breve y comprensible para las personas).

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 failed con una cadena output informativa 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.

Usar la herramienta para aplicar parches con el 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}`);

Puedes encontrar ejemplos completos y funcionales en GitHub.

Ejemplo de la herramienta para aplicar parches - TypeScript

Ejemplo de cómo usar la herramienta para aplicar parches con el Agents SDK en TypeScript

Ejemplo de la herramienta para aplicar parches - Python

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.

Error de archivo no encontrado
{
  "type": "apply_patch_call_output",
  "call_id": "call_abc",
  "status": "failed",
  "output": "Error: File not found at path 'lib/baz.py'"
}

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).
  • 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.
  • 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 input para que el modelo pueda corregirlos.

Notas de uso

Disponibilidad en las API Modelos compatibles
GPT-5.5
GPT-5.4
GPT-5.2
GPT-5.1