For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Aplicar patch

Permita que os modelos proponham diffs estruturados para sua integração aplicar.

A ferramenta apply_patch permite que o GPT-5.1 crie, atualize e exclua arquivos na sua base de código usando diffs estruturados. Em vez de apenas sugerir edições, o modelo gera operações de patch que seu aplicativo aplica e cujos resultados informa ao modelo, viabilizando fluxos de trabalho iterativos de edição de código em várias etapas.

Quando usar

Alguns cenários comuns de uso de apply_patch:

  • Refatorações em vários arquivos – Renomeie símbolos, extraia funções auxiliares ou reorganize módulos em vários arquivos de uma só vez.
  • Correções de bugs – Peça ao modelo para diagnosticar problemas e gerar patches precisos.
  • Geração de testes e documentação – Crie novos arquivos de teste, fixtures e documentação junto com as alterações de código.
  • Migrações e edições mecânicas – Aplique atualizações repetitivas e estruturadas (migrações de API, anotações de tipo, correções de formatação etc.).

Se você consegue descrever seu repositório e a alteração desejada em texto, apply_patch geralmente consegue gerar os diffs correspondentes.

Use a ferramenta Aplicar patch com a Responses API

Em linhas gerais, o uso de apply_patch com a Responses API funciona assim:

  1. Chame a Responses API com a ferramenta apply_patch
    • Forneça ao modelo contexto sobre os arquivos disponíveis (ou um resumo) em input, ou disponibilize ferramentas para que ele explore seu sistema de arquivos.
    • Habilite a ferramenta com tools=[{"type": "apply_patch"}].
  2. Deixe o modelo retornar uma ou mais operações de patch
    • A saída do objeto Response inclui um ou mais objetos apply_patch_call.
    • Cada chamada descreve uma única operação de arquivo: criar, atualizar ou excluir.
  3. Aplique os patches no seu ambiente
    • Execute um harness de patches ou um script que:
      • Interprete o diff de operation para cada apply_patch_call.
      • Aplique o patch ao seu diretório de trabalho ou repositório.
      • Registre se cada patch foi aplicado com sucesso e quaisquer logs ou mensagens de erro.
  4. Informe ao modelo os resultados dos patches
    • Chame a Responses API novamente, usando previous_response_id ou reenviando os itens da conversa em input.
    • Inclua um evento apply_patch_call_output para cada call_id, com um status e uma string output opcional.
    • Mantenha tools=[{"type": "apply_patch"}] para que o modelo possa continuar editando, se necessário.
  5. Deixe o modelo continuar ou explicar as alterações
    • O modelo pode gerar mais operações apply_patch_call ou
    • Fornecer ao usuário uma explicação do que alterou e por quê.

Exemplo: renomear uma função com a ferramenta Aplicar patch

Etapa 1: peça ao modelo para planejar e gerar patches

Peça ao modelo para planejar e gerar patches
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"
);

Exemplo de objeto apply_patch_call

Exemplo 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"
    }
}

Etapa 2: aplique o patch e envie os resultados de volta

Aplique o patch e retorne os 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);

Se um patch falhar (por exemplo, porque o arquivo não foi encontrado), defina status: "failed" e inclua uma string output informativa para que o modelo possa se recuperar do erro:

Informe uma falha na chamada de 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"
}

Operações da ferramenta Aplicar patch

Tipo de operaçãoFinalidadePayload
create_fileCria um novo arquivo em path.diff é um diff V4A que representa todo o conteúdo do arquivo.
update_fileModifica um arquivo existente em path.diff é um diff V4A com adições, exclusões ou substituições.
delete_fileRemove um arquivo em path.Sem diff; exclui o arquivo por completo.

Seu harness de patches é responsável por interpretar o formato de diff V4A e aplicar as alterações. Para consultar implementações de referência, veja o código do Agents SDK para Python ou do Agents SDK para TypeScript.

Implementação do harness de patches

Ao usar a ferramenta apply_patch, você não fornece um esquema de entrada; o modelo sabe como construir objetos operation. Cabe a você:

  1. Interpretar as operações do objeto Response
    • Procurar no objeto Response os itens com type: "apply_patch_call".
    • Para cada chamada, inspecionar operation.type, operation.path e diff, se houver.
  2. Aplique operações em arquivos
    • Para create_file e update_file, aplique o diff V4A ao sistema de arquivos ou ao workspace em memória.
    • Para delete_file, remova o arquivo em path.
    • Registre se cada operação foi bem-sucedida e quaisquer logs ou mensagens de erro.
  3. Retorne eventos apply_patch_call_output
    • Para cada call_id, emita exatamente um evento apply_patch_call_output com:
      • status: "completed" se a operação foi aplicada com sucesso.
      • status: "failed" se ocorreu um erro (inclua uma string output curta e compreensível para uma pessoa).

Segurança e robustez

  • Validação de caminhos: Impeça a travessia de diretórios e restrinja as edições aos diretórios permitidos.
  • Backups: Considere fazer backup dos arquivos (ou trabalhar em uma cópia temporária) antes de aplicar patches.
  • Tratamento de erros: Sempre retorne o status failed com uma string output informativa quando não for possível aplicar os patches.
  • Atomicidade: Decida se deseja uma semântica de “tudo ou nada” (reverter tudo se algum patch falhar) ou resultados de sucesso ou falha por arquivo.

Use a ferramenta Aplicar patch com o Agents SDK

Como alternativa, você pode usar o Agents SDK para utilizar a ferramenta Aplicar patch. Você ainda precisará implementar o harness que executa as operações nos arquivos, mas poderá usar a função applyDiff para processar os diffs.

Use a ferramenta Aplicar patch com o 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}`);

Você encontra exemplos completos e funcionais no GitHub.

Exemplo da ferramenta Aplicar patch - TypeScript

Exemplo de como usar a ferramenta Aplicar patch com o Agents SDK em TypeScript

Exemplo da ferramenta Aplicar patch - Python

Exemplo de como usar a ferramenta Aplicar patch com o Agents SDK em Python

Tratamento de erros comuns

Use status: "failed" junto com uma mensagem clara em output para ajudar o modelo a se recuperar do erro.

Erro de arquivo não encontrado
{
  "type": "apply_patch_call_output",
  "call_id": "call_abc",
  "status": "failed",
  "output": "Error: File not found at path 'lib/baz.py'"
}

O modelo pode então ajustar os próximos diffs com base nessas mensagens de erro (por exemplo, relendo um arquivo no seu prompt ou simplificando uma alteração).

Práticas recomendadas

  • Forneça um contexto claro sobre os arquivos
    • Ao chamar a Responses API, inclua uma cópia do estado atual dos seus arquivos diretamente na entrada (como no exemplo) ou forneça ao modelo ferramentas para explorar seu sistema de arquivos (como a ferramenta shell).
  • Considere o uso em conjunto com a ferramenta shell
    • Em conjunto com a ferramenta shell, o modelo pode explorar diretórios do sistema de arquivos, ler arquivos e buscar palavras-chave com grep, o que permite localizar e editar arquivos de forma agêntica.
  • Incentive diffs pequenos e focados
    • Nas instruções de sistema, oriente o modelo a fazer edições mínimas e pontuais em vez de grandes reescritas.
  • Verifique se as alterações são aplicadas sem problemas
    • Após uma série de patches, execute seus testes ou linters e informe as falhas no próximo input para que o modelo possa corrigi-las.

Notas de uso

Disponibilidade da API Modelos compatíveis
GPT-5.5
GPT-5.4
GPT-5.2
GPT-5.1