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:
- 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"}].
- Forneça ao modelo contexto sobre os arquivos disponíveis (ou um resumo) em
- 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.
- A saída do objeto Response inclui um ou mais objetos
- Aplique os patches no seu ambiente
- Execute um harness de patches ou um script que:
- Interprete o diff de
operationpara cadaapply_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.
- Interprete o diff de
- Execute um harness de patches ou um script que:
- Informe ao modelo os resultados dos patches
- Chame a Responses API novamente, usando
previous_response_idou reenviando os itens da conversa eminput. - Inclua um evento
apply_patch_call_outputpara cadacall_id, com umstatuse uma stringoutputopcional. - Mantenha
tools=[{"type": "apply_patch"}]para que o modelo possa continuar editando, se necessário.
- Chame a Responses API novamente, usando
- Deixe o modelo continuar ou explicar as alterações
- O modelo pode gerar mais operações
apply_patch_callou - Fornecer ao usuário uma explicação do que alterou e por quê.
- O modelo pode gerar mais operações
Exemplo: renomear uma função com a ferramenta Aplicar patch
Etapa 1: 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
{
"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
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:
{
"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ção | Finalidade | Payload |
|---|---|---|
create_file | Cria um novo arquivo em path. | diff é um diff V4A que representa todo o conteúdo do arquivo. |
update_file | Modifica um arquivo existente em path. | diff é um diff V4A com adições, exclusões ou substituições. |
delete_file | Remove 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ê:
- 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.pathediff, se houver.
- Procurar no objeto Response os itens com
- Aplique operações em arquivos
- Para
create_fileeupdate_file, aplique o diff V4A ao sistema de arquivos ou ao workspace em memória. - Para
delete_file, remova o arquivo empath. - Registre se cada operação foi bem-sucedida e quaisquer logs ou mensagens de erro.
- Para
- Retorne eventos
apply_patch_call_output- Para cada
call_id, emita exatamente um eventoapply_patch_call_outputcom:status: "completed"se a operação foi aplicada com sucesso.status: "failed"se ocorreu um erro (inclua uma stringoutputcurta e compreensível para uma pessoa).
- Para cada
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
failedcom uma stringoutputinformativa 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.
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 de como usar a ferramenta Aplicar patch com o Agents SDK em TypeScript
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.
{
"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):"
}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).
- 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
- 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.
- Em conjunto com a ferramenta
- 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
inputpara que o modelo possa corrigi-las.
- Após uma série de patches, execute seus testes ou linters e informe as falhas no próximo
Notas de uso
| Disponibilidade da API | Modelos compatíveis |
|---|---|
| GPT-5.5 GPT-5.4 GPT-5.2 GPT-5.1 |