Orientações sobre modelos

Introdução

O GPT-6 Astra é nosso modelo mais inteligente até agora, com desempenho de ponta em uso do computador, navegação, engenharia de software, ciência e trabalho profissional. Ele se destaca na execução de fluxos de trabalho com várias etapas que envolvem código, navegadores e software profissional. Em diversas avaliações, o Astra alcança resultados melhores usando substancialmente menos tokens de saída, o que resulta em um custo estimado de API por tarefa menor que o dos modelos anteriores, apesar do preço mais alto por token.

O GPT-6 Astra também é nosso modelo mais alinhado até agora. Ele se destaca por agir com cuidado, respeitar os limites da tarefa e se comunicar com transparência. Quando as instruções deixam margem para interpretação, ele usa o contexto disponível para preencher lacunas rotineiras e faz perguntas específicas quando a resposta pode mudar o resultado. Ele incorpora novos requisitos, muda de rumo quando solicitado e responde a perguntas paralelas sem perder de vista a tarefa como um todo.

Para desenvolver com o Astra, defina model como gpt-6-astra em uma requisição à Responses API.

Novidades

• Chamada assíncrona de ferramentas: O GPT-6 Astra pode continuar raciocinando, chamar outras ferramentas ou responder a partes independentes de uma solicitação enquanto seu aplicativo executa uma ferramenta. Defina async: true em uma função ou ferramenta personalizada e retorne o resultado quando estiver pronto, usando o call_id original. Seu aplicativo continua responsável por executar a ferramenta e gerenciar o trabalho pendente. Consulte Chamada assíncrona de ferramentas para ver o uso básico e um padrão de ferramenta de espera definido pelo desenvolvedor.
• Orientação durante o turno: Envie instruções adicionais do usuário enquanto o GPT-6 Astra trabalha, como uma correção ou uma mudança nos requisitos. Por meio de uma conexão WebSocket, a Responses API preserva o trabalho concluído e inclui a atualização em uma continuação. Consulte Orientação durante o turno para saber mais sobre o fluxo de eventos e o tratamento dos resultados das ferramentas.
• Altere o raciocínio durante a conversa preservando o cache: Adicione um item de entrada configuration_update para aumentar o esforço de raciocínio em trabalhos difíceis ou reduzi-lo em solicitações rotineiras de acompanhamento, sem reescrever o prefixo original do prompt. O esforço de raciocínio atualizado se aplica até que outro item de entrada configuration_update o substitua. Consulte Altere o raciocínio durante a conversa para ver exemplos e informações de compatibilidade.
• Monitoramento de desalinhamento: Como parte das nossas salvaguardas reforçadas para o GPT-6 Astra, nossos sistemas monitoram o desalinhamento de forma assíncrona e disparam alertas quando necessário. Consulte Monitoramento de desalinhamento para mais informações.
• Limitações: O GPT-6 Astra não oferece suporte ao esforço de raciocínio none. O modo Fast não está disponível para o GPT-6 Astra com residência de dados na UE.

O GPT-6 Astra também oferece suporte aos recursos de API já disponíveis no GPT-5.6, incluindo uso do computador, Saídas estruturadas, streaming, Chamada programática de ferramentas, orquestração de múltiplos agentes, cache de prompts, raciocínio persistido, compactação e modo Pro.

Práticas recomendadas para criação de prompts

O GPT-6 Astra é mais inteligente e capaz que modelos anteriores, como o GPT-5.6 Sol, e também apresenta padrões de comportamento que podem ser otimizados com prompts voltados ao seu caso de uso.

Comportamento do GPT-6 Astra

• Iniciativa e persistência – O modelo foi projetado para colaborar de forma mais eficaz e, por isso, tem maior propensão a fazer perguntas ao usuário quando informações adicionais podem mudar significativamente o resultado. Isso pode levá-lo a parar quando o usuário espera que ele faça suposições razoáveis e continue trabalhando.
• Seguimento de instruções – O GPT-6 Astra segue instruções em geral melhor que nossos modelos anteriores, dando a você maior controle sobre seu comportamento. Ele pode ser mais sensível a instruções contidas em habilidades e outros arquivos, como AGENTS.md. Recomendamos fortemente auditar as habilidades e os outros arquivos acessíveis ao modelo em busca de instruções que possam influenciar seu comportamento.
• Personalidade e estilo de escrita – O modelo tende a produzir respostas detalhadas e formatadas e pode usar expressões recorrentes em diferentes sessões. Especifique o estilo de escrita e a estrutura de que seu aplicativo precisa.
• Delegação a subagentes – O modelo pode delegar com menos frequência do que seria desejável para seu fluxo de trabalho. Especifique quando e em que medida ele deve usar subagentes para trabalhar em paralelo.
• Testes e verificação – Em tarefas de programação, o modelo tende a testar minuciosamente antes de considerar uma tarefa concluída. Em tarefas menores, isso pode resultar em testes mais abrangentes do que o necessário.

Iniciativa e persistência

O GPT-6 Astra geralmente mantém a coerência durante tarefas longas melhor que o GPT-5.6 Sol e os modelos anteriores. Ele também tem maior propensão a pedir esclarecimentos em situações nas quais os modelos anteriores fariam suposições.

Para incentivar um trabalho mais autônomo, comece com este prompt:

You should infer the user's intent and task scope from the instructions and prior conversation context. Your job is to bias towards action and carry the user's intended task to completion.

When the user expresses intent to perform new work or fix an existing issue, persist until the user's intended goal is complete. Progress autonomously towards the user's goal (e.g. creating isolated worktrees / checkouts if needed, resolving merge conflicts, read-only actions, creating draft PRs etc.) unless they are clearly destructive or irreversible.

Quando a intenção do usuário não está clara, o modelo tem maior propensão a pedir esclarecimentos para prosseguir. Instrua o modelo a continuar quando o prompt do usuário implicar autorização:

When the user's prompt indicates a request for action, such as "can you...", "I want to...", "help me..." and similar expressions, treat these as instructions to do the work and take action. Do not stop at acknowledging capability (e.g. "Yes…"), proposing a plan, or offering to continue. Do not settle for a partial or "helpful enough" solution that does not fully satisfy the user's task to save time, effort or tokens. If a task requires sustained work, complete all the necessary work until the intended outcome is fulfilled.

Instrua o modelo a pedir aprovação somente depois de preparar um resultado concreto que possa ser revisado. Isso evita que a tarefa seja bloqueada antes de o modelo fazer o trabalho que está ao seu alcance e costuma acelerar a conclusão da tarefa.

Before asking the user clarifying questions, you should complete the work that is already authorized from context and necessary to make the proposed action concrete and reviewable. The user should be approving a concrete, reviewable result. For example, before deploying a change, writing to an external application, merging a PR or publishing a site, do all the required work first so that user approval is the final step. You don't need user permission for reversible tasks, read-only actions, reviews or fixes, or anything for which authorization is provided earlier in the session or strongly implied from the task instruction.

Do not introduce unsolicited warnings, disclaimers, approval flows, or safety/compliance checklists due to hypothetical risk.

Por padrão, o modelo também tende a fazer perguntas que não interrompem o trabalho enquanto ele avança. Ajuste esses prompts ao nível de autonomia de que seu aplicativo precisa.

Seguimento de instruções

O GPT-6 Astra tem mais facilidade para seguir instruções longas, mas também pode ser mais sensível às informações presentes no contexto. Por exemplo, orientações pouco claras ou conflitantes em um arquivo de habilidade podem levar o modelo a pausar e bloquear o trabalho prematuramente. Deixe explícita a prioridade das instruções do usuário e das habilidades.

The user's instructions take precedence over guidelines provided in a skill. If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

Pedir ao modelo que identifique a habilidade e a instrução que o levaram a pausar ou mudar de rumo também pode ser uma forma eficaz de dar transparência ao seu comportamento.

If a skill causes you to ask for permission or confirmation, pause, leave requested work unfinished, or diverge from the user's intent, name and link to the exact SKILL.md file you read, quote the relevant instruction, and briefly explain how it applies. Distinguish explicit skill requirements from your interpretation of guidelines.

Use este prompt para encontrar orientações que influenciam o comportamento sem serem mencionadas ou que entram em conflito quando seu aplicativo carrega muitas habilidades e arquivos de instruções, como AGENTS.md.

Personalidade e estilo de escrita

O GPT-6 Astra tende a usar listas, tabelas e Markdown para facilitar a leitura rápida das respostas. Se seu aplicativo precisa de texto corrido com menos formatação, especifique essa preferência.

Default to using clear, concise paragraphs, each developing one main idea. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.

Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs. Let each sentence build on what came before. Develop the points that matter and provide enough support to be useful.

Para comunicação técnica, o prompt a seguir ajuda a equilibrar uma linguagem clara e coerente com a adequação à área de conhecimento:

Use plain language over jargon, and reference technical details only to the degree that it helps illustrate an idea or your work to the user. Communicate complex concepts in a clear and cohesive manner, and calibrate your writing to the level of background knowledge assumed from the user's prompt and context.

Para reduzir o uso de jargões e frases feitas na escrita, comece com este prompt:

Avoid using slop words or phrases like "Bottom Line:" in conclusions, "delve," "foster," "leverage," "it's worth noting," "importantly," "Question? Answer." or "This isn't about X. It's about Y.", "genuinely" or hyphenated compound descriptions and adjectives. Do not use concluding summary statements such as "In short:..", "The simplest mental model is:...".

State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results. Do not use contrastive framing such as "X, not Y" or "X—not Y" that introduces an unprompted alternative that the user didn't ask about. Avoid invented compound labels like "exact-head checks" and "editorial-row layouts", vague qualifiers, and canned transitions; use plain verbs and prepositions to state the actual relationship directly.

Delegação a subagentes

O GPT-6 Astra é treinado para dividir e delegar trabalho a subagentes que atuam em paralelo. Se você está implementando um sistema de múltiplos agentes no seu harness, use o prompt a seguir para ajustar quanto trabalho o GPT-6 Astra deve delegar:

If at any point you can parallelize work by delegating tasks to another agent (no matter if you are the root or subagent), you should do so using collaboration tools if it could save time or improve quality.

Mensagens entre agentes podem conter erros de gramática ou espaçamento. Use este prompt para facilitar a leitura dessas mensagens:

Messages that you send to other agents and your final answer may be read by a human, so ensure they are legible. Always put proper spaces between words and/or numbers.

O modelo tende a responder bem a prompts que indicam como e quando delegar trabalho a subagentes. Ajuste esse comportamento ao seu harness e à sua implementação de múltiplos agentes.

Testes e verificação

Em tarefas de programação, ajuste a quantidade de testes e verificações ao que a alteração exige. Isso pode ajudar a evitar testes desnecessários ou verificações repetidas em pequenas alterações.

Do not write tests for reversible, low-impact changes that mirror the implementation. If you do choose to verify your work with tests, make sure that the tests are meaningful and necessary to verify implementation.

Run tests appropriate to the change and complete required checks. Once those pass, broaden or repeat testing only when new changes, failures, or unresolved concerns justify it; otherwise, continue toward completing the task.

Início rápido de migração

Migre com o Codex

O Codex pode aplicar as alterações recomendadas neste guia com a habilidade de Documentação da OpenAI.

$openai-docs migrate this project to GPT-6 Astra

Para usar essa habilidade em outros agentes de programação, baixe-a do repositório do Codex.

Atualize os parâmetros da API e do modelo

Defina model como gpt-6-astra e verifique os seguintes pontos:

• Esforço de raciocínio: Se você usa none ou minimal atualmente, comece com low e compare os resultados. Caso contrário, mantenha o esforço de raciocínio efetivamente em uso. Use reasoning.effort em Responses ou reasoning_effort em Chat Completions.
• Chamada de ferramentas: Use a Responses API. O GPT-6 Astra oferece suporte a Chat Completions, mas a chamada de ferramentas exige Responses.
• Parâmetros sem suporte: Remova temperature, top_p e top_logprobs. Para Chat Completions, remova também logprobs. Para Responses, remova message.output_text.logprobs de include.
• Modo Fast: Para residência de dados na UE, use o processamento Padrão. O GPT-6 Astra não oferece suporte a service_tier: "fast" ou service_tier: "priority" com residência de dados na UE. O modo Fast para o GPT-6 Astra não inclui um SLA de latência. Consulte Compatibilidade do modo Fast.
• Alteração do esforço de raciocínio: Se seu aplicativo altera o esforço entre respostas, use itens configuration_update em requisições padrão com um único agente. Mantenha reasoning.effort inalterado no nível da requisição para preservar o prefixo do prompt para uso do cache. Verifique os limites de compatibilidade antes de adotar esse recurso.
• Cache de prompts: Ao migrar do GPT-5.5 ou de versões anteriores, substitua prompt_cache_retention por prompt_cache_options.ttl definido como "30m". Confira as mudanças no cache de prompts, incluindo os pontos de delimitação do cache e a cobrança por gravação no cache.
• Pausas desnecessárias para aprovação: Se o modelo pedir aprovação repetidamente antes de prosseguir, use as orientações sobre iniciativa e persistência para solicitar uma execução mais autônoma. Consulte o restante de Práticas recomendadas para criação de prompts para ver orientações sobre seguimento de instruções, estilo de escrita, delegação a subagentes e testes.

Introdução

O GPT-5.6 estabelece um novo patamar de qualidade e eficiência para fluxos de trabalho complexos em produção. O GPT-5.6 é especialmente eficiente no uso de tokens e aprimora a estética do frontend, incluindo layout, hierarquia visual e decisões de design.

O GPT-5.6 também apresenta uma nova nomenclatura. O alias gpt-5.6 direciona as solicitações para gpt-5.6-sol, o modelo com a capacidade do modelo principal. Use gpt-5.6-terra para obter alto desempenho a um preço menor e gpt-5.6-luna para processar grandes volumes de trabalho com eficiência.

Ao migrar do GPT-5.5 ou do GPT-5.4, comece com a configuração de raciocínio que você usa atualmente nesses modelos. Em seguida, teste essa mesma configuração e um nível abaixo em tarefas representativas. O GPT-5.6 muitas vezes consegue manter ou melhorar a qualidade com menos tokens, mas a melhor configuração depende da sua carga de trabalho.

Novidades

• Chamada programática de ferramentas: o GPT-5.6 pode escrever JavaScript para chamar ferramentas elegíveis, passar resultados entre chamadas e processar saídas intermediárias em um ambiente de execução hospedado. Use a chamada programática de ferramentas em fluxos de trabalho de escopo delimitado que usam muitas ferramentas e não exigem uma nova decisão do modelo entre as etapas. A chamada programática de ferramentas é compatível com ZDR e não tem custos adicionais de contêiner.
• Múltiplos agentes [beta]: o recurso de múltiplos agentes permite que uma instância do GPT-5.6 coordene vários subagentes em paralelo e sintetize seus resultados. Assim como o modo Ultra no Codex, isso pode reduzir o tempo total de execução e melhorar o desempenho em tarefas complexas que podem ser claramente divididas em frentes de trabalho independentes. O recurso de múltiplos agentes está disponível em versão beta na Responses API enquanto o aprimoramos com base no feedback dos desenvolvedores.
• Cache explícito de prompts: o GPT-5.6 permite marcar exatamente quais prefixos reutilizáveis de prompts a OpenAI armazena em cache. Você ainda pode usar o cache automático no modo implícito. A OpenAI cobra pelas gravações em cache 1,25× o preço da entrada sem cache, enquanto as leituras do cache continuam com desconto. Saiba como configurar o cache de prompts.
• Raciocínio persistido: o GPT-5.6 pode reutilizar itens de raciocínio disponíveis entre turnos para melhorar a qualidade em conversas com vários turnos e a eficiência do cache. Use reasoning.context para selecionar o comportamento. Saiba como preservar o raciocínio entre chamadas.
• Esforço de raciocínio Max: o GPT-5.6 oferece suporte ao esforço de raciocínio max para tarefas exigentes que precisam de mais exploração e verificação. Se você usa xhigh atualmente, compare as duas configurações em cargas de trabalho representativas.
• Modo Pro: o GPT-5.6 pode realizar mais processamento para melhorar a confiabilidade em tarefas difíceis e retornar uma única resposta final. Ative esse modo com reasoning.mode: "pro" quando a qualidade for mais importante do que a latência e o uso de tokens. Saiba como usar o modo Pro.
• Eficiência no uso de tokens: o GPT-5.6 alcança desempenho de modelo principal com menos tokens de saída.
• Design de frontend: o GPT-5.6 cria sites e aplicativos mais bem-acabados e fáceis de usar, com melhorias no layout, na hierarquia visual e nas decisões de design.
• Compreensão da intenção: o GPT-5.6 consegue inferir melhor, a partir do contexto, o objetivo por trás da solicitação do usuário e o nível de trabalho esperado, de modo que muitas vezes você não precisa prescrever cada etapa. Continue fornecendo o contexto do domínio, as restrições obrigatórias, os limites de aprovação e os critérios de sucesso. Informe ao modelo quando uma ambiguidade importante deve motivar uma pergunta.
• Nível de detalhe original da imagem: o GPT-5.6 preserva as dimensões da imagem com o nível de detalhe original ou auto, exceto quando uma das dimensões ultrapassa 65.535 pixels; nesse caso, a imagem é reduzida para respeitar esse limite. A API rejeita imagens que ainda excedam o limite de 30.000 patches, em vez de redimensioná-las para se adequar a ele. Imagens grandes podem usar mais tokens de entrada e aumentar a latência. Saiba como escolher um nível de detalhe da imagem.

Salvaguardas

Ao usar modelos GPT-5.6, os usuários podem se deparar com salvaguardas que bloqueiam ou recusam algumas solicitações com base em classificadores de uso indevido nas áreas cibernética e biológica, executados em tempo real durante a geração das saídas do modelo. Outras solicitações podem levar mais tempo porque a geração é pausada por vários segundos durante a transmissão enquanto esses classificadores revisam as saídas de forma síncrona. Ocasionalmente, as salvaguardas podem intervir em trabalhos legítimos, principalmente em áreas de uso duplo, nas quais atividades defensivas e ofensivas podem parecer semelhantes à primeira vista.

Se o seu aplicativo atende usuários finais individuais, envie um safety_identifier estável e que preserve a privacidade em cada solicitação. Consulte Implementar identificadores de segurança para obter orientações.

Aprimoramos continuamente essas salvaguardas para que sejam robustas e eficazes diante de tentativas adversariais, preservando o acesso a trabalhos legítimos, como revisão de código, pesquisa de vulnerabilidades, desenvolvimento de patches, depuração, educação em segurança e testes defensivos.

Início rápido da migração

Migre com o Codex

O Codex pode aplicar as alterações recomendadas neste guia com a habilidade OpenAI Docs.

$openai-docs migrate this project to the GPT-5.6 model family

Para usar essa habilidade em outros agentes de programação, baixe-a do repositório de habilidades da OpenAI.

Atualize os parâmetros da API e do modelo

• Escolha o modelo de destino para a carga de trabalho. Use gpt-5.6-sol para obter a capacidade do modelo principal, gpt-5.6-terra para equilibrar inteligência e custo ou gpt-5.6-luna para processar grandes volumes de trabalho com eficiência. O alias gpt-5.6 direciona as solicitações para gpt-5.6-sol.
• Use a Responses API para fluxos de trabalho com raciocínio, chamadas de ferramentas e vários turnos.
• Defina reasoning.effort de forma deliberada. O GPT-5.6 oferece suporte a none, low, medium, high, xhigh e max.
  • Se estiver migrando do GPT-5.5 ou do GPT-5.4, mantenha o esforço de raciocínio atual como referência e depois compare com um nível abaixo.
  • Se você usa none, mantenha essa configuração como referência de latência e teste também low quando o fluxo de trabalho se beneficiar do raciocínio ou do uso de ferramentas.
  • Use medium como ponto de partida equilibrado e low para cargas de trabalho sensíveis à latência.
  • Use high ou xhigh quando mais raciocínio produzir um ganho de qualidade comprovado por medições.
  • Reserve max para as cargas de trabalho mais difíceis que priorizam a qualidade. Compare max e xhigh para encontrar o melhor equilíbrio entre qualidade, latência e custo para seu caso de uso.
• Para usar o modo Pro, mantenha o modelo GPT-5.6 selecionado e defina reasoning.mode como pro na Responses API; não mude para um slug de modelo Pro separado. Escolha reasoning.effort de forma independente. Se você omitir esse parâmetro, o GPT-5.6 usará medium por padrão nos modos padrão e Pro. Consulte modo de raciocínio para ver um exemplo de solicitação e detalhes de cobrança.
• Configure o raciocínio persistido com base em quanto do raciocínio anterior ainda é relevante. Os modelos GPT-5.6 usam all_turns por padrão; os modelos anteriores usam current_turn.
  • Omita reasoning.context ou defina-o como auto para usar all_turns, o padrão do GPT-5.6. Verifique o campo reasoning.context da resposta para confirmar o modo efetivamente usado.
  • Defina reasoning.context como all_turns quando os objetivos, as premissas e as prioridades da tarefa permanecerem estáveis entre os turnos.
  • Com all_turns, continue usando previous_response_id para disponibilizar ao modelo o raciocínio das respostas anteriores.
  • Ao gerenciar o histórico manualmente, preserve e reenvie as entradas anteriores do usuário e todos os itens de saída das respostas. Para store: false ou zero retenção de dados, reenvie os itens de raciocínio criptografados que a API retorna por padrão.
  • Defina reasoning.context como current_turn quando o raciocínio anterior não for mais relevante.
• Revise o cache de prompts. Não é necessário alterar o código para continuar usando o cache implícito. Como as gravações em cache do GPT-5.6 custam 1,25× o preço da entrada sem cache, monitore cached_tokens e cache_write_tokens para entender o custo líquido. Use pontos de interrupção explícitos ou prompt_cache_options.mode: "explicit" para evitar gravações desnecessárias e substitua prompt_cache_retention por prompt_cache_options.ttl.
• Para usar a chamada programática de ferramentas, adicione a ferramenta programmatic_tool_calling e habilite as ferramentas elegíveis com allowed_callers. Atualize seu aplicativo para lidar com itens program, chamadas de função feitas pelo programa e itens program_output, preservando o call_id e o vínculo de caller de cada chamada. Consulte o guia de chamada programática de ferramentas para ver exemplos de solicitações e de continuação.
  • Avalie o desempenho do fluxo de trabalho com PTC habilitado em tarefas representativas. Compare o sucesso das tarefas, a completude da resposta final, as evidências exigidas, o total de tokens, a latência e o custo. Reduzir chamadas, turnos ou saídas intermediárias só representa uma melhoria quando a resposta final continua atendendo ao padrão de qualidade exigido.

Práticas recomendadas para criação de prompts

Prefira prompts mais enxutos

Remover instruções e exemplos repetidos e simplificar as descrições das ferramentas pode melhorar o desempenho nas tarefas e a eficiência no uso de tokens. Em uma amostra de execuções de avaliações internas de agentes de programação, configurações com prompts de sistema mais enxutos melhoraram as pontuações das avaliações em cerca de 10–15%, reduzindo o total de tokens em 41–66% e o custo em 33–67%. Os resultados variam conforme a carga de trabalho, portanto, considere essas faixas como indicativas e valide as alterações em tarefas representativas do seu próprio aplicativo.

Para simplificar os prompts sem perder orientações importantes:

• Comece com um prompt e um conjunto de ferramentas que já funcionem. Remova um grupo de instruções, exemplos ou ferramentas por vez e execute novamente as mesmas avaliações.
• Declare cada instrução uma única vez.
• Disponibilize apenas as ferramentas relevantes para a tarefa e mantenha suas descrições concisas e precisas.
• Mantenha exemplos e orientações de estilo quando eles expressarem um requisito do produto ou corrigirem uma lacuna identificada por medições.
• Monitore o contexto tanto no início de uma execução quanto à medida que a conversa cresce. Sessões longas podem amplificar o conteúdo repetido de prompts e ferramentas.

Defina os limites de autonomia e aprovação

O GPT-5.6 pode ser proativo e persistente ao executar tarefas com várias etapas. Defina o nível de ação que cada solicitação autoriza para que o modelo possa continuar realizando trabalho seguro e dentro do escopo sem pausas desnecessárias, mas pare antes de ações externas, destrutivas, custosas ou que ampliem o escopo.

Uma política sucinta costuma ser suficiente:

For requests to answer, explain, review, diagnose, or plan, inspect the relevant
materials and report the result. Do not implement changes unless the request also
asks for them.

For requests to change, build, or fix, make the requested in-scope local changes
and run relevant non-destructive validation without asking first.

Require confirmation for external writes, destructive actions, purchases, or a
material expansion of scope.

Nomeie explicitamente as ações locais seguras, como ler arquivos, inspecionar logs, editar código dentro do escopo e executar testes. Mantenha a política em um só lugar e declare cada regra uma única vez. Repetir instruções como “pergunte primeiro”, “não faça alterações” ou “aguarde aprovação” pode causar pedidos de aprovação desnecessários para ações seguras e esperadas.

Defina o tamanho e o estilo das respostas

Por padrão, o GPT-5.6 tende a ser mais conciso que o GPT-5.5. Ao migrar, verifique se instruções genéricas de brevidade, como “Seja conciso” ou “Responda de forma breve”, ainda são úteis. Elas podem ser desnecessárias para algumas tarefas e, às vezes, tornar as respostas curtas demais. Mantenha-as quando produzirem de forma consistente a saída de que seu aplicativo precisa.

Para ter um controle mais consistente entre solicitações, use text.verbosity para definir o nível de detalhe padrão e, em seguida, use o prompt para os requisitos específicos da tarefa.

Defina um padrão com text.verbosity

Escolha low, medium ou high como nível de detalhe padrão de uma solicitação. No prompt, especifique o tamanho, a estrutura ou o conteúdo obrigatório para a tarefa. Consulte Configurar text.verbosity para ver um exemplo de uso da API.

Especifique o que uma resposta curta deve incluir

Quando uma tarefa pedir uma resposta mais curta, identifique as informações que o modelo deve preservar e os detalhes que pode omitir. Por exemplo:

Lead with the conclusion. Include the evidence needed to support it, any material
caveat, and the next action. Omit secondary detail and repetition.

Keep all required facts, decisions, caveats, and next steps. Trim introductions,
repetition, generic reassurance, and optional background first.

Isso dá ao modelo uma ordem clara de prioridades: preservar o conteúdo necessário para concluir a tarefa e, depois, remover os detalhes menos relevantes.

Defina o tom

Descrições genéricas como “amigável” ou “empático” podem ser ambíguas. Descreva as escolhas de escrita que definem o tom do seu produto, como o grau de objetividade da resposta, quando reconhecer um problema e se cabe tranquilizar o usuário ou incluir uma despedida.

State the answer directly. If the user reports a problem, acknowledge the
specific issue before giving the next step. Use reassurance only when it is
relevant. Omit generic praise and unnecessary sign-offs.

Modo Pro

Escolha o modo Pro quando a qualidade for a prioridade

O modo Pro é um modo de execução da Responses API em que o modelo realiza mais trabalho em uma solicitação antes de retornar uma única resposta final. Ele pode aumentar a confiabilidade em tarefas difíceis, mas aumenta a latência e soma os tokens desse trabalho ao uso informado. Esses tokens são cobrados pelas tarifas padrão de tokens do modelo selecionado.

Use o modo Pro quando uma pequena melhoria de qualidade fizer uma diferença relevante no resultado e a tarefa for difícil o suficiente para se beneficiar, como otimização complexa, programação ou revisão de alto valor, ou análise aprofundada com critérios claros de avaliação. Prefira o modo padrão para tarefas rotineiras, sensíveis à latência ou de alto volume, e sempre que suas avaliações não mostrarem um ganho significativo com o modo Pro.

O modo de raciocínio e o esforço de raciocínio são independentes. O modo Pro funciona com qualquer modelo GPT-5.6 e os níveis de esforço de raciocínio que ele suporta. Comece com o mesmo modelo e nível de esforço usados como referência no modo padrão e compare as configurações em tarefas representativas, em vez de presumir que o maior esforço sempre oferece o melhor equilíbrio.

Configure o modo Pro na API

Ative o modo Pro na solicitação à API. Mantenha o mesmo prompt focado no resultado que você usa no modo padrão: informe o objetivo, o contexto relevante, as restrições, as evidências necessárias, os critérios de sucesso e o formato de saída. Você não precisa pedir ao modelo que “use o modo Pro”, “pense mais” ou gere várias respostas candidatas.

Por exemplo:

Review this database migration plan for failure modes that could cause data loss
or extended downtime. For each finding, cite the relevant step, estimate impact
and likelihood, and recommend a specific mitigation. Return the five most
important risks in severity order.

Compare qualidade e custo

Compare os modos padrão e Pro nas mesmas tarefas representativas. Meça o sucesso das tarefas, a completude das respostas, as evidências necessárias, o total de tokens, a latência e o custo. Use o modo Pro de forma seletiva, quando o ganho de qualidade ou confiabilidade justificar o trabalho adicional do modelo.

Saiba mais no guia de modo de raciocínio.

Chamada programática de ferramentas

Escolha a chamada programática de ferramentas conforme as características da tarefa

A chamada programática de ferramentas (PTC) funciona melhor em fluxos de trabalho de escopo delimitado, nos quais o código pode processar vários resultados de ferramentas ou grandes saídas intermediárias e retornar um resultado estruturado muito menor. Use-a para filtragem, junção, classificação, deduplicação, agregação, validação ou outros tipos de processamento previsível.

Chamadas múltiplas, paralelas ou dependentes, por si só, não justificam o uso da chamada programática de ferramentas. Prefira chamadas diretas de ferramentas, sem PTC, quando:

• Uma única chamada for suficiente
• As saídas intermediárias já forem pequenas
• Cada resultado puder mudar a próxima decisão do modelo
• Uma ação exigir aprovação
• A saída final precisar preservar citações ou artefatos nativos

Adapte as instruções de roteamento à tarefa

Não conte apenas com a disponibilidade de ferramentas ou com instruções genéricas como “use a chamada programática de ferramentas com eficiência” para que o modelo escolha o caminho correto. Quando tanto as chamadas diretas quanto as programáticas estiverem disponíveis, informe explicitamente:

• Qual etapa de escopo delimitado deve usar a chamada programática de ferramentas.
• Quais ferramentas ela pode chamar.
• O esquema exato de saída e as evidências necessárias.
• Os limites de concorrência, novas tentativas e interrupção.
• Quais tarefas devem continuar usando chamadas diretas.

As descrições das ferramentas devem documentar os campos e tipos de retorno esperados e o comportamento em caso de erro. Se o modelo não conseguir determinar a estrutura do retorno antes de escrever o programa, prefira chamadas diretas de ferramentas para que ele possa inspecionar o resultado antes de decidir como usá-lo.

Se os dois caminhos forem necessários, defina um único ponto claro de transição e instrua o modelo a não alternar entre os caminhos nem repetir tarefas já concluídas.

Por exemplo:

<tool_orchestration>
Use Programmatic Tool Calling for [bounded stage] using only [eligible tools].
Run independent calls concurrently when safe. Use only documented tool input
and output fields.

Process and reduce the intermediate results, then emit exactly [output schema],
including the evidence needed for the final answer.

Stop when [condition] is met. Retry transient failures at most [R] times.
Do not repeat completed calls or perform side-effecting actions. If a required
result is still missing, return a clear structured failure.

Use direct tool calls for [semantic judgment, approval, or final validation].
</tool_orchestration>

Avalie a resposta final

O item program_output e a message final do assistente são saídas distintas; teste ambos. Em teoria, um programa pode retornar os registros corretos enquanto a mensagem omite um campo obrigatório, uma citação ou uma ressalva.

Compare as chamadas diretas e programáticas nas mesmas tarefas representativas. Verifique se a resposta final está correta, completa e inclui as evidências necessárias. Depois, compare o total de tokens, a latência, o custo, as chamadas, os turnos e as novas tentativas. Considere a redução no uso de recursos uma melhoria somente se a resposta continuar passando nas suas avaliações existentes.

Saiba mais no guia de chamada programática de ferramentas.

Introdução

O GPT-5.5 eleva o padrão dos fluxos de trabalho complexos em produção. É uma ótima opção para casos de uso de programação, agentes que usam ferramentas intensivamente, assistentes com respostas fundamentadas, recuperação em contextos longos, fluxos que transformam especificações de produto em planos e fluxos voltados ao cliente nos quais a qualidade da execução e o refinamento das respostas são essenciais.

Para aproveitar ao máximo o GPT-5.5, trate-o como uma nova família de modelos que exige ajustes, e não como um substituto direto do gpt-5.2 ou do gpt-5.4. Comece a migração com uma nova base, em vez de reaproveitar todas as instruções de um conjunto antigo de prompts. Comece com o menor prompt que preserve o contrato do produto e, depois, ajuste o esforço de raciocínio, a verbosidade, as descrições das ferramentas e o formato de saída com base em exemplos representativos.

O GPT-5.5 oferece suporte a todos os recursos da API que já estavam disponíveis no GPT-5.4, incluindo cache de prompts, ferramentas hospedadas, pesquisa de ferramentas, compactação e tratamento de phase para itens do assistente reenviados manualmente.

Consulte Práticas recomendadas para criação de prompts para ver exemplos de padrões eficazes de criação de prompts.

Novidades

• Raciocínio mais eficiente: o GPT-5.5 alcança bons resultados com menos tokens de raciocínio do que os modelos anteriores, mesmo com o mesmo esforço de raciocínio. Isso é especialmente útil em fluxos de trabalho complexos, com uso intensivo de ferramentas ou várias etapas, nos quais a economia de tokens se acumula.
• Melhor execução de tarefas com prompts focados no resultado: o GPT-5.5 é melhor em trabalhar a partir de um objetivo claro, respeitar restrições e transformar a intenção do produto em próximos passos concretos. Descreva o resultado esperado, os critérios de sucesso, os efeitos colaterais permitidos, as regras sobre evidências e a estrutura da saída. Evite orientar o processo passo a passo, a menos que o caminho exato seja importante.
• Uso de ferramentas mais eficaz e preciso: o GPT-5.5 é especialmente útil em ambientes com muitas ferramentas, fluxos de serviço com várias etapas e tarefas de longa duração executadas por agentes. Ele tende a ser mais preciso na seleção de ferramentas e no uso de argumentos.
• O tom costuma ser mais refinado, mas pode ser mais direto: o GPT-5.5 costuma produzir respostas mais acolhedoras e fáceis de ler, com menos instruções auxiliares no prompt.

Mudanças de comportamento

1. O esforço de raciocínio agora usa medium por padrão: o GPT-5.5 usa o esforço de raciocínio medium por padrão. Considere medium o ponto de partida recomendado para equilibrar qualidade, confiabilidade, latência e custo. Em fluxos de trabalho sensíveis à latência, avalie low antes de none quando o uso de ferramentas, o planejamento, a pesquisa ou a tomada de decisões em várias etapas ainda forem importantes. Reserve none para tarefas nas quais a latência é crítica e que não exigem raciocínio nem várias chamadas de ferramentas encadeadas, como interações simples por voz, recuperação rápida de informações e classificação. Aumente para high ou xhigh somente quando as avaliações mostrarem um ganho mensurável de qualidade que justifique a latência e o custo adicionais. Consulte a documentação de modelos de raciocínio para saber mais sobre as configurações recomendadas.

   Um esforço de raciocínio maior não é automaticamente melhor. Se a tarefa tiver instruções conflitantes, critérios de parada pouco definidos ou acesso a ferramentas sem limites claros, um esforço maior pode levar a raciocínio excessivo, pesquisas desnecessárias ou queda na qualidade da saída. Aumente o esforço somente quando as avaliações mostrarem um ganho mensurável de qualidade.

2. As entradas de imagem preservam mais detalhes visuais por padrão: o GPT-5.5 atualiza o tratamento padrão das entradas de imagem para preservar mais detalhes visuais e melhorar o desempenho do uso do computador. Quando image_detail não é definido ou está definido como auto, o modelo agora usa o comportamento original, preservando as imagens sem redimensionamento até 10.240.000 pixels ou um limite de 6.000 pixels por dimensão. Para high, especifique o valor diretamente; ele preserva as imagens sem redimensionamento até 2.500.000 pixels ou um limite de 2.048 pixels por dimensão. Agora, low prioriza o uso eficiente do contexto e redimensiona de forma mais agressiva do que os modelos anteriores as imagens que ultrapassam o limite de 512 pixels por dimensão. Consulte a documentação de imagens e visão.

3. Melhor cumprimento de instruções: o GPT-5.5 interpreta os prompts de forma literal e minuciosa, permitindo instruções específicas e descritivas quando o produto as exige. Defina critérios de sucesso e regras de parada, especialmente para fluxos de trabalho de longa duração, com uso intensivo de ferramentas ou coleta de evidências. Consulte Escreva prompts focados no resultado e Mantenha o nível adequado de especificidade.

4. O estilo padrão é mais conciso e direto: o GPT-5.5 tende a ser eficiente, direto e orientado a tarefas por padrão. Isso é útil para muitos fluxos de trabalho em produção, mas experiências voltadas ao cliente ou de conversação podem precisar de orientações explícitas sobre personalidade, cordialidade, justificativas e formatação. Use text.verbosity de forma deliberada: medium é o padrão, e low costuma ser um ponto de partida melhor para respostas concisas. Consulte Práticas recomendadas para criação de prompts.

5. Fluxos de trabalho de programação precisam de uma orquestração mais robusta: o GPT-5.5 é mais adequado a tarefas complexas de programação que exigem planejamento, uso de ferramentas, navegação pela base de código, verificação e execução em várias etapas. Para agentes de programação, seja explícito sobre reutilização, delegação a subagentes, expectativas de testes, critérios de aceitação e quando continuar ou pedir ajuda.

Início rápido da migração

Migração automatizada com o Codex

O Codex pode aplicar as mudanças recomendadas neste guia com a habilidade OpenAI Docs.

$openai-docs migrate this project to gpt-5.5

Para usar essa habilidade em outros agentes de programação, baixe-a do repositório de habilidades da OpenAI.

Parâmetros da API e do modelo

• Atualize o slug do modelo para gpt-5.5.
• Use a Responses API para qualquer caso de uso que envolva raciocínio, chamadas de ferramentas ou múltiplos turnos.
• Ajuste reasoning.effort. Use low para um raciocínio eficiente, medium para um ponto de equilíbrio na curva de latência e desempenho, high para tarefas agênticas complexas que exigem raciocínio difícil e nas quais a latência é menos importante, e xhigh para as tarefas agênticas assíncronas mais difíceis ou avaliações que testam os limites da inteligência do modelo. Consulte a documentação de modelos de raciocínio.
• Para configurar respostas mais concisas, defina text.verbosity como low. No GPT-5.5, isso resultará em respostas proporcionalmente mais concisas do que a verbosidade low no GPT-5.4.
• Para fluxos de trabalho com uso intensivo de ferramentas ou de longa duração, verifique se o aplicativo trata corretamente phase, os preâmbulos e o reenvio de itens do assistente.
• Compare com outros modelos a precisão, o consumo de tokens e a latência de ponta a ponta.

Criação de prompts

• Declare o resultado esperado e os critérios de sucesso.
• Reduza ou remova as orientações detalhadas sobre o processo passo a passo. Deixe o GPT-5.5 escolher o caminho, a menos que o produto exija um caminho específico.
• Remova as definições de esquema de saída do prompt sempre que possível. Use Saídas estruturadas em seu lugar.
• Otimize o prompt para o uso de cache: partes estáticas primeiro, partes dinâmicas por último.
• Remova a data atual. O modelo já sabe a data atual em UTC.
• Revise e otimize seus prompts com as Práticas recomendadas para criação de prompts.

Como usar modelos de raciocínio

Estas orientações se aplicam aos modelos da série GPT-5 e vale retomá-las sempre que as equipes migrarem cargas de trabalho para modelos de raciocínio. O GPT-5.5 mantém muitas capacidades que surgiram em modelos anteriores, mas ainda vale revisá-las se você estiver migrando de um modelo GPT-5 anterior, do GPT-4.1 ou de um modelo de raciocínio como o o3.

As equipes podem deixar esses recursos passar despercebidos porque eles estão, em parte, na configuração e na orquestração da API, e não no próprio prompt. Em conjunto, a Responses API, os controles de raciocínio, a verbosidade, as saídas estruturadas, o cache de prompts, o design das ferramentas, as ferramentas hospedadas e o gerenciamento de estado ajudam os modelos de raciocínio a oferecer seu melhor desempenho em inteligência, confiabilidade, latência e custo.

• Responses API: o GPT-5.5 funciona melhor na Responses API. Use previous_response_id para gerenciar o estado em múltiplos turnos. Em fluxos sem estado ou com zero retenção de dados, reenvie a cada turno os itens de saída relevantes que foram retornados. Consulte Como passar o contexto da resposta anterior para mais detalhes.
• Esforço de raciocínio: use reasoning.effort para escolher entre low, medium, high ou xhigh. O padrão é medium, mas muitas cargas de trabalho terão bom desempenho com low. Reserve none para casos de uso nos quais a baixa latência é mais importante do que a inteligência. Consulte Modelos de raciocínio para recomendações detalhadas.
• Verbosidade: use text.verbosity para controlar o tamanho da saída. Trate o tamanho da resposta final separadamente da qualidade do raciocínio; especifique limites de palavras, quantidades de seções, larguras de tabelas ou saída somente em JSON quando necessário.
• Saídas estruturadas: evite descrever no prompt o esquema de saída esperado. Use Saídas estruturadas para obter validação automática e maior precisão.
• Cache de prompts: o cache de prompts funciona automaticamente para prompts longos elegíveis e pode reduzir a latência e o custo dos tokens de entrada. Para maximizar os acertos de cache, mantenha o conteúdo estável no início da solicitação. Coloque o contexto dinâmico específico do usuário perto do final. Monitore usage.prompt_tokens_details.cached_tokens para medir a reutilização. Use um valor estável de prompt_cache_key para solicitações que compartilham um prefixo reutilizável. A chave ajuda a direcionar solicitações relacionadas para o mesmo cache e é importante para otimizar as taxas de acerto de cache no GPT-5.5. Para grupos com tráfego intenso, siga as orientações para distribuir o tráfego entre mais chaves.
• Chamadas de ferramentas: o GPT-5.5 oferece suporte aos mesmos padrões de chamadas de ferramentas do GPT-5.4, incluindo ferramentas de função e fluxos de trabalho de agentes com uso intensivo de ferramentas. Coloque a maior parte das orientações específicas de cada ferramenta na própria descrição: o que ela faz, quando usá-la, entradas obrigatórias, efeitos colaterais, segurança de novas tentativas e tipos de erro comuns. Adicione contexto específico de ferramentas às instruções de sistema somente quando ele se aplicar a várias ferramentas ou alterar de forma relevante a política de operação do agente.
• Ferramentas hospedadas e pesquisa de ferramentas: dê preferência às ferramentas hospedadas pela OpenAI quando forem adequadas ao fluxo de trabalho, como pesquisa na Web, pesquisa de arquivos, Code Interpreter, geração de imagens e uso do computador. As ferramentas hospedadas reduzem o esforço de orquestração personalizada e mantêm os padrões comuns de uso de ferramentas alinhados à Responses API e ao Agents SDK. Use ferramentas de função personalizadas quando precisar chamar seus próprios sistemas, aplicar efeitos colaterais específicos do domínio ou disponibilizar fluxos de trabalho internos de negócio. Para catálogos grandes de ferramentas, considere usar a pesquisa de ferramentas para adiar o carregamento das definições de ferramentas e carregar apenas o subconjunto relevante.
• Preâmbulos de ferramentas: os preâmbulos podem melhorar a experiência do usuário no chat, pois ele vê uma atualização inicial útil sobre o andamento antes de o modelo gerar a resposta final. Eles também facilitam acompanhar o uso de ferramentas: o modelo pode informar o que está prestes a verificar ou fazer e, depois, continuar a partir desse mesmo estado do assistente quando os resultados das ferramentas chegarem.
• Tratamento de phase: se o aplicativo gerencia manualmente o estado da Responses API, reenviando itens de saída a cada turno em vez de usar previous_response_id, preserve o parâmetro phase nos itens de saída retornados pelo assistente e reenvie-o sem alterações. Isso é especialmente importante ao usar esforço de raciocínio, preâmbulos ou chamadas repetidas de ferramentas. Consulte Parâmetro de fase.
• Compactação: para agentes de longa duração, use a compactação da conversa e do estado de forma deliberada. Preserve as ações concluídas, as premissas em vigor, os IDs, os resultados das ferramentas, os impedimentos não resolvidos e o próximo objetivo concreto.
• Agents SDK: para novos sistemas agênticos, use os padrões mais recentes do Agents SDK para orquestração de ferramentas, rastreamento, transferências de controle e gerenciamento de estado, em vez de reconstruir a orquestração do zero.
• Data atual: o GPT-5.5 sabe a data atual em UTC. Você não precisa adicionar a data atual às instruções de sistema. Adicione contexto explícito de data ou fuso horário somente quando o aplicativo precisar de um fuso horário específico do negócio, uma data de entrada em vigor de uma política, a data local do usuário ou outro ponto de referência diferente de UTC.

Práticas recomendadas para criação de prompts

O GPT-5.5 funciona melhor quando os prompts definem o resultado e dão ao modelo espaço para escolher um caminho eficiente até a solução. Em comparação com modelos anteriores, muitas vezes é possível usar prompts mais curtos e mais orientados a resultados: descreva o que caracteriza um bom resultado, quais restrições importam, quais evidências estão disponíveis e o que a resposta final deve conter.

Evite reaproveitar todas as instruções de um conjunto antigo de prompts. Prompts legados costumam especificar o processo em excesso porque os modelos anteriores precisavam de mais ajuda para manter o foco. Com o GPT-5.5, isso pode acrescentar ruído, restringir o espaço de busca do modelo ou levar a respostas excessivamente mecânicas.

Os padrões apresentados aqui são pontos de partida. Adapte-os à interface do seu produto, às ferramentas, às avaliações e aos objetivos de experiência do usuário.

Personalidade e comportamento

O estilo padrão do GPT-5.5 é eficiente, direto e orientado a tarefas. Isso é útil para sistemas em produção: as respostas mantêm o foco, o comportamento é mais fácil de orientar e o modelo evita prolongar a conversa sem necessidade.

Para assistentes voltados ao cliente, fluxos de suporte, experiências de orientação e outros produtos de conversação, defina tanto a personalidade quanto o estilo de colaboração.

• A personalidade controla como o assistente se expressa: tom, cordialidade, objetividade, formalidade, humor, empatia e nível de refinamento.
• O estilo de colaboração controla como o assistente trabalha: quando faz perguntas, quando adota premissas, quão proativo deve ser, quanto contexto fornece, quando verifica o trabalho e como lida com incertezas ou riscos.

Mantenha ambos breves. As instruções de personalidade devem moldar a experiência do usuário. As instruções de colaboração devem moldar o comportamento na execução das tarefas. Nenhuma delas deve substituir objetivos claros, critérios de sucesso, regras de uso de ferramentas ou condições de parada.

Exemplo de bloco de personalidade para um assistente estável e focado em tarefas:

# Personality
You are a capable collaborator: approachable, steady, and direct. Assume the user is competent and acting in good faith, and respond with patience, respect, and practical helpfulness.

Prefer making progress over stopping for clarification when the request is already clear enough to attempt. Use context and reasonable assumptions to move forward. Ask for clarification only when the missing information would materially change the answer or create meaningful risk, and keep any question narrow.

Stay concise without becoming curt. Give enough context for the user to understand and trust the answer, then stop. Use examples, comparisons, or simple analogies when they make the point easier to grasp. When correcting the user or disagreeing, be candid but constructive. When an error is pointed out, acknowledge it plainly and focus on fixing it.

Match the user's tone within professional bounds. Avoid emojis and profanity by default, unless the user explicitly asks for that style or has clearly established it as appropriate for the conversation.

Exemplo de bloco de personalidade para um assistente expressivo e colaborativo:

# Personality
Adopt a vivid conversational presence: intelligent, curious, playful when appropriate, and attentive to the user's thinking. Ask good questions when the problem is blurry, then become decisive once there is enough context.

Be warm, collaborative, and polished. Conversation should feel easy and alive, but not chatty for its own sake. Offer a real point of view rather than merely mirroring the user, while staying responsive to their goals and constraints.

Be thoughtful and grounded when the task calls for synthesis or advice. State a clear recommendation when you have enough context, explain important tradeoffs, and name uncertainty without becoming evasive.

Para produtos mais expressivos, inclua explicitamente cordialidade, curiosidade, humor ou um ponto de vista, mas mantenha o bloco curto. Use a personalidade para moldar a experiência, não para compensar objetivos pouco claros ou a falta de instruções sobre a tarefa.

Reduza o tempo até o primeiro token visível com um preâmbulo

Em aplicativos com streaming, os usuários percebem quanto tempo leva para a primeira resposta visível aparecer. O GPT-5.5 pode dedicar tempo ao raciocínio, ao planejamento ou à preparação de chamadas de ferramentas antes de emitir texto visível.

Para tarefas mais longas ou que fazem uso intenso de ferramentas, instrua o modelo a começar com um preâmbulo curto: uma breve atualização visível que reconheça a solicitação e indique o primeiro passo. Isso pode melhorar a percepção de agilidade sem alterar a tarefa em si.

Use esse padrão quando a tarefa puder exigir mais de uma etapa, precisar de chamadas de ferramentas ou envolver um fluxo de trabalho de agente de longa duração.

Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences.

Para agentes de programação que disponibilizam fases distintas de mensagem, você pode ser mais explícito:

You must always start with an intermediary update before any content in the analysis channel if the task will require calling tools. The user update should acknowledge the request and explain your first step.

Prompts focados no resultado e condições de parada

O GPT-5.5 tem seu melhor desempenho quando o prompt define o resultado desejado, os critérios de sucesso, as restrições e o contexto disponível, e então deixa o modelo escolher o caminho.

Para muitas tarefas, descreva aonde quer chegar em vez de detalhar cada etapa. Isso dá ao modelo espaço para escolher a pesquisa, a ferramenta ou a estratégia de raciocínio adequada à tarefa.

Prefira esta abordagem:

Resolve the customer's issue end to end.

Success means:
- the eligibility decision is made from the available policy and account data
- any allowed action is completed before responding
- the final answer includes completed_actions, customer_message, and blockers
- if evidence is missing, ask for the smallest missing field

Evite regras absolutas desnecessárias. Prompts antigos costumam usar instruções rígidas como ALWAYS, NEVER, must e only para controlar o comportamento do modelo. Use essas palavras para requisitos realmente invariáveis, como regras de segurança, campos obrigatórios de saída ou ações que nunca devem acontecer. Para decisões que exigem discernimento, como quando pesquisar, pedir esclarecimentos, usar uma ferramenta ou continuar iterando, prefira regras de decisão.

Evite esse estilo de instrução, a menos que todas as etapas sejam realmente necessárias:

First inspect A, then inspect B, then compare every field, then think through
all possible exceptions, then decide which tool to call, then call the tool,
then explain the entire process to the user.

Adicione condições de parada explícitas:

Resolve the user query in the fewest useful tool loops, but do not let loop minimization outrank correctness, accessible fallback evidence, calculations, or required citation tags for factual claims.

After each result, ask: "Can I answer the user's core request now with useful evidence and citations for the factual claims?" If yes, answer.

Defina como agir na falta de evidências:

Use the minimum evidence sufficient to answer correctly, cite it precisely, then stop.

Formatação

O GPT-5.5 permite um alto grau de controle sobre o formato e a estrutura da saída. Use esse controle quando ele melhorar a compreensão ou a adequação ao produto.

Configure text.verbosity, descreva o formato de saída esperado e reserve estruturas mais elaboradas para os casos em que elas melhoram a compreensão ou em que a interface do produto precisa de um artefato estável. O valor padrão de text.verbosity na API é medium; use low quando preferir respostas mais curtas e concisas.

Formatação simples e conversacional:

Let formatting serve comprehension. Use plain paragraphs as the default format for normal conversation, explanations, reports, documentation, and technical writeups. Keep the presentation clean and readable without making the structure feel heavier than the content.

Use headers, bold text, bullets, and numbered lists sparingly. Reach for them when the user requests them, when the answer needs clear comparison or ranking, or when the information would be harder to scan as prose. Otherwise, favor short paragraphs and natural transitions.

Respect formatting preferences from the user. If they ask for a terse answer, minimal formatting, no bullets, no headers, or a specific structure, follow that preference unless there is a strong reason not to.

Adicione orientações explícitas sobre o público e a extensão do texto:

Write for a senior business audience. Keep the answer under 400 words. Use short paragraphs and only include bullets when they improve scannability. Prioritize the conclusion first, then the reasoning, then caveats.

Para edição, reescrita, resumos ou mensagens voltadas a clientes, diga ao modelo o que preservar antes de pedir que ele melhore o estilo. Esse padrão é útil quando você quer refinar o texto sem torná-lo mais longo.

Preserve the requested artifact, length, structure, and genre first. Quietly improve clarity, flow, and correctness. Do not add new claims, extra sections, or a more promotional tone unless explicitly requested.

Fundamentação, citações e limites de recuperação

Para obter respostas fundamentadas, as orientações sobre citações devem fazer parte do prompt. Defina o que precisa de respaldo, o que constitui evidência suficiente e como o modelo deve agir quando faltarem evidências. A ausência de evidências não deve se transformar automaticamente em um “não” apresentado como fato. Para mais detalhes e exemplos, consulte o guia de formatação de citações.

Adicione um limite explícito de recuperação

Os limites de recuperação são regras para encerrar a pesquisa. Eles indicam ao modelo quando já há evidências suficientes.

For ordinary Q&A, start with one broad search using short, discriminative keywords. If the top results contain enough citable support for the core request, answer from those results instead of searching again.

Make another retrieval call only when:
- The top results do not answer the core question.
- A required fact, parameter, owner, date, ID, or source is missing.
- The user asked for exhaustive coverage, a comparison, or a comprehensive list.
- A specific document, URL, email, meeting, record, or code artifact must be read.
- The answer would otherwise contain an important unsupported factual claim.

Do not search again to improve phrasing, add examples, cite nonessential details, or support wording that can safely be made more generic.

Mecanismos de proteção para a redação criativa

Para tarefas de redação, diga ao modelo quais afirmações devem vir de fontes e quais partes podem ser escritas com liberdade criativa. Isso é especialmente importante para slides, textos de lançamento, resumos para clientes, roteiros de fala, textos breves para a liderança e construção de narrativas.

For creative or generative requests such as slides, leadership blurbs, outbound copy, summaries for sharing, talk tracks, or narrative framing, distinguish source-backed facts from creative wording.

- Use retrieved or provided facts for concrete product, customer, metric, roadmap, date, capability, and competitive claims, and cite those claims.
- Do not invent specific names, first-party data claims, metrics, roadmap status, customer outcomes, or product capabilities to make the draft sound stronger.
- If there is little or no citable support, write a useful generic draft with placeholders or clearly labeled assumptions rather than unsupported specifics.

Engenharia de frontend e senso estético

Para trabalhos de frontend, consulte as instruções de exemplo para conhecer formas práticas de orientar a qualidade da interface. Elas abordam o contexto do produto e do usuário, o alinhamento com o sistema de design, a usabilidade da primeira tela, controles familiares, estados esperados, comportamento responsivo e padrões comuns de interfaces geradas que devem ser evitados, como seções de destaque genéricas, cartões aninhados, gradientes decorativos, textos de instrução visíveis e layouts quebrados.

Instrua o modelo a verificar o próprio trabalho

Dê ao GPT-5.5 acesso a ferramentas que permitam verificar as saídas quando a validação for possível.

Para agentes de programação, peça comandos concretos de validação:

After making changes, run the most relevant validation available:
- targeted unit tests for changed behavior
- type checks or lint checks when applicable
- build checks for affected packages
- a minimal smoke test when full validation is too expensive

If validation cannot be run, explain why and describe the next best check.

Para artefatos visuais, peça uma inspeção após a renderização:

Render the artifact before finalizing. Inspect the rendered output for layout, clipping, spacing, missing content, and visual consistency. Revise until the rendered output matches the requirements.

Para tarefas de engenharia e planejamento, torne os planos de implementação rastreáveis:

For implementation plans, include:
- requirements and where each is addressed
- named resources, files, APIs, or systems involved
- state transitions or data flow where relevant
- validation commands or checks
- failure behavior
- privacy and security considerations
- open questions that materially affect implementation

Parâmetro de fase

A partir do GPT-5.4, fluxos de trabalho da Responses de longa duração ou que fazem uso intenso de ferramentas podem usar os valores de phase dos itens do assistente para distinguir atualizações intermediárias de respostas finais. O GPT-5.5 usa o mesmo padrão.

Se você usar previous_response_id, a API preservará automaticamente o estado anterior do assistente. Se o aplicativo reenviar manualmente os itens de saída do assistente na próxima solicitação, preserve cada valor original de phase e reenvie-o sem alterações. Isso é especialmente importante quando uma resposta inclui preâmbulos, chamadas repetidas de ferramentas ou uma resposta final após atualizações intermediárias do assistente.

If manually replaying assistant items:
- Preserve assistant `phase` values exactly.
- Use `phase: "commentary"` for intermediate user-visible updates.
- Use `phase: "final_answer"` for the completed answer.
- Do not add `phase` to user messages.

Estrutura sugerida para o prompt

Use esta estrutura como ponto de partida para prompts complexos. Mantenha cada seção curta. Adicione detalhes apenas quando eles mudarem o comportamento.

Role: [1-2 sentences defining the model's function, context, and job]

# Personality
[tone, demeanor, and collaboration style]

# Goal
[user-visible outcome]

# Success criteria
[what must be true before the final answer]

# Constraints
[policy, safety, business, evidence, and side-effect limits]

# Output
[sections, length, and tone]

# Stop rules
[when to retry, fallback, abstain, ask, or stop]

Introdução

O GPT-5.4 foi lançado como um modelo de fronteira para uso profissional na API e no Codex. Ele ajuda desenvolvedores a analisar informações complexas, criar software para produção e automatizar fluxos de trabalho com várias etapas.

Na geração GPT-5.4, o gpt-5.4 é o modelo de uso geral para fluxos de trabalho que alternam entre engenharia de software, raciocínio, escrita e uso de ferramentas.

Este guia apresenta os principais recursos da família de modelos GPT-5 e mostra como aproveitar ao máximo o GPT-5.4.

Novidades

Em comparação com o modelo anterior, GPT-5.2, o GPT-5.4 apresenta melhorias em:

• Programação, compreensão de documentos, uso de ferramentas e cumprimento de instruções
• Percepção de imagens e tarefas multimodais
• Execução de tarefas de longa duração e fluxos de trabalho de agentes com várias etapas
• Eficiência no uso de tokens e desempenho de ponta a ponta em cargas de trabalho com uso intensivo de ferramentas
• Pesquisa na Web e síntese de várias fontes para informações difíceis de encontrar
• Fluxos de trabalho empresariais com uso intensivo de documentos e planilhas nas áreas de atendimento ao cliente, análise de dados e finanças

O GPT-5.4 traz as capacidades de programação do GPT-5.3-Codex para nosso principal modelo de fronteira. Desenvolvedores podem gerar código com qualidade de produção, criar interfaces de front-end refinadas, seguir padrões específicos do repositório e lidar com alterações em vários arquivos com menos novas tentativas. Ele também já vem com uma personalidade bem definida para programação, reduzindo o tempo que as equipes gastam ajustando prompts.

Em cargas de trabalho agênticas, o GPT-5.4 reduz o tempo total de execução de trajetórias com várias etapas e frequentemente conclui tarefas com menos tokens e chamadas de ferramentas. Isso torna os agentes mais ágeis e reduz o custo de operar fluxos de trabalho complexos em escala na API e no Codex.

Novos recursos do GPT-5.4

Assim como os modelos GPT-5 anteriores, o GPT-5.4 oferece suporte a ferramentas personalizadas, parâmetros para controlar a verbosidade e o raciocínio e uma lista de ferramentas permitidas. O GPT-5.4 também introduz várias capacidades que facilitam a criação de sistemas de agentes poderosos, o trabalho com volumes maiores de informações e a execução de fluxos de trabalho automatizados mais confiáveis:

• tool_search na API: O GPT-5.4 aprimora a pesquisa de ferramentas em ecossistemas maiores com o carregamento adiado de ferramentas. Isso permite pesquisar ferramentas, carrega apenas as definições relevantes, reduz o uso de tokens e melhora a precisão da seleção de ferramentas em implantações reais. Saiba mais no guia de pesquisa de ferramentas.
• Janela de contexto de 1M de tokens: O GPT-5.4 oferece suporte a uma janela de contexto de até 1M de tokens, facilitando a análise de bases de código inteiras, extensas coleções de documentos ou trajetórias prolongadas de agentes em uma única solicitação. Saiba mais na seção Janela de contexto de 1M.
• Uso do computador integrado: O GPT-5.4 é o primeiro modelo da linha principal com capacidades integradas de uso do computador, permitindo que agentes interajam diretamente com software para concluir, verificar e corrigir tarefas em um ciclo de criação, execução, verificação e correção. Saiba mais no guia de uso do computador.
• Suporte nativo à compactação: O GPT-5.4 é o primeiro modelo da linha principal treinado para oferecer suporte à compactação, permitindo trajetórias mais longas de agentes e preservando o contexto essencial.

Atualizações de modelos, API e recursos

Nesta geração de modelos, o gpt-5.4 é o modelo de uso geral tanto para tarefas variadas quanto para programação. Para problemas mais difíceis, o gpt-5.4-pro usa mais recursos computacionais para pensar por mais tempo e fornecer respostas mais consistentes.

Para variantes menores e mais rápidas, comece com o gpt-5.4-mini ou o gpt-5.4-nano.

Para escolher o modelo mais adequado ao seu caso de uso, considere estas vantagens e limitações:

Menor esforço de raciocínio

O parâmetro reasoning.effort controla quantos tokens de raciocínio o modelo gera antes de produzir uma resposta. Modelos de raciocínio anteriores, como o o3, ofereciam suporte apenas a low, medium e high: low priorizava a velocidade e o uso de menos tokens, enquanto high priorizava um raciocínio mais aprofundado.

O GPT-5.2 e o GPT-5.4 oferecem suporte a none como o menor esforço de raciocínio para interações com menor latência. Essa é a configuração padrão de ambos os modelos. Se precisar de mais raciocínio, aumente gradualmente até medium e avalie os resultados.

Com o esforço de raciocínio definido como none, a criação de prompts é importante. Para melhorar a qualidade do raciocínio do modelo, mesmo com as configurações padrão, incentive-o a “pensar” ou a descrever as etapas que seguirá antes de responder.

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.4",
  input:
    "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  reasoning: {
    effort: "none",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
    reasoning={"effort": "none"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-5.4",
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?")},
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortNone},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.NONE).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-5.4",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.None,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem(
        "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    )
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  reasoning: { effort: :minimal },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
        "model": "gpt-5.4",
        "input": "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
        "reasoning": {
                "effort": "none"
        }
}'

Verbosidade

A verbosidade determina quantos tokens de saída são gerados. Reduzir o número de tokens diminui a latência geral. Embora a abordagem de raciocínio do modelo permaneça praticamente a mesma, ele encontra maneiras de responder de forma mais concisa, o que pode melhorar ou piorar a qualidade da resposta, dependendo do seu caso de uso. Veja alguns cenários para os dois extremos de verbosidade:

• Alta verbosidade: Use quando precisar que o modelo forneça explicações detalhadas de documentos ou faça uma refatoração extensa de código.
• Baixa verbosidade: Ideal para situações em que você quer respostas concisas ou geração de código com foco específico, como consultas SQL.

O GPT-5 passou a permitir configurar essa opção como high, medium ou low. No GPT-5.4, a verbosidade continua configurável e o padrão é medium.

Ao gerar código com o GPT-5.4, os níveis de verbosidade medium e high produzem código mais longo e estruturado, com explicações no próprio código, enquanto a verbosidade low produz código mais curto e conciso, com o mínimo de comentários.

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.4",
  input:
    "What is the answer to the ultimate question of life, the universe, and everything?",
  text: {
    verbosity: "low",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="What is the answer to the ultimate question of life, the universe, and everything?",
    text={"verbosity": "low"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.4",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the answer to the ultimate question of life, the universe, and everything?")},
		Text:  responses.ResponseTextConfigParam{Verbosity: responses.ResponseTextConfigVerbosityLow},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseTextConfig;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  text: { verbosity: :low },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
  "model": "gpt-5.4",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

Você ainda pode orientar a verbosidade por meio de prompts depois de defini-la como low na API. O parâmetro de verbosidade define uma faixa geral de tokens no nível do prompt do sistema, mas, dentro dessa faixa, a saída se adapta tanto aos prompts do desenvolvedor quanto aos do usuário.

Janela de contexto de 1M

A janela de contexto de 1M de tokens foi introduzida com o GPT-5.4, facilitando a análise de bases de código inteiras, extensas coleções de documentos ou trajetórias prolongadas de agentes em uma única solicitação.

Temos preços padrão distintos para solicitações com menos de 272K e com mais de 272K tokens, disponíveis na documentação de preços. Se você usar o modo Fast, qualquer prompt com mais de 272K tokens será processado automaticamente com as tarifas padrão.

Os preços de contexto longo se aplicam em conjunto com outros ajustes de preço, como os de residência de dados e processamento em lote.

Temos limites de taxa diferentes para solicitações com menos de 272K tokens e com mais de 272K tokens; essas informações estão disponíveis na página do modelo GPT-5.4.

Como usar ferramentas com o GPT-5.4

O GPT-5.4 foi pós-treinado para usar ferramentas específicas. Consulte a documentação de ferramentas para orientações mais específicas.

Ferramenta de uso do computador

O uso do computador permite que o GPT-5.4 opere software pela interface do usuário, analisando capturas de tela e retornando ações estruturadas para o seu harness executar. É uma boa opção para fluxos de trabalho no navegador ou no desktop em que uma pessoa poderia concluir a tarefa pela interface, como navegar em um site, preencher formulários ou validar se uma alteração realmente funcionou.

Use a ferramenta em um navegador isolado ou em uma VM e mantenha a supervisão humana em ações de alto impacto. O guia completo aborda o ciclo integrado da Responses API, padrões de harness personalizados e configurações baseadas em execução de código.

Ferramenta de pesquisa de ferramentas

A pesquisa de ferramentas permite que o GPT-5.4 adie o carregamento de grandes conjuntos de ferramentas até o momento da execução, carregando apenas as definições necessárias. Isso é especialmente útil quando você tem muitas funções, namespaces ou ferramentas MCP e quer reduzir o uso de tokens, preservar o desempenho do cache e diminuir a latência sem expor todos os esquemas logo de início.

Use a pesquisa de ferramentas hospedada quando as ferramentas candidatas já forem conhecidas no momento da requisição, ou a pesquisa de ferramentas executada pelo cliente quando seu aplicativo precisar decidir dinamicamente o que carregar. O guia completo também aborda práticas recomendadas para namespaces, servidores MCP e carregamento adiado.

Ferramentas personalizadas

Quando a família de modelos GPT-5 foi lançada, introduzimos um novo recurso chamado ferramentas personalizadas, que permite aos modelos enviar qualquer texto bruto como entrada de uma chamada de ferramenta, mantendo a possibilidade de restringir as saídas, se desejado. Esse comportamento das ferramentas continua no GPT-5.4.

Entradas em formato livre

Defina sua ferramenta com type: custom para permitir que os modelos enviem entradas de texto simples diretamente às suas ferramentas, sem se limitar ao JSON estruturado. O modelo pode enviar qualquer texto bruto, como código, consultas SQL, comandos de shell, arquivos de configuração ou textos longos em prosa, diretamente à sua ferramenta.

12345{
  "type": "custom",
  "name": "code_exec",
  "description": "Executes arbitrary python code"
}

Restringindo as saídas

O GPT-5.4 oferece suporte a gramáticas livres de contexto (CFGs) para ferramentas personalizadas, permitindo que você forneça uma gramática Lark para restringir as saídas a uma sintaxe ou DSL específica. Anexar uma CFG, por exemplo, uma gramática SQL ou de uma DSL, garante que o texto do assistente siga sua gramática.

Isso permite chamadas de ferramenta precisas e restritas ou respostas estruturadas, além de impor formatos sintáticos rigorosos ou específicos de um domínio diretamente na chamada de função do GPT-5.4, melhorando o controle e a confiabilidade em domínios complexos ou com restrições.

Práticas recomendadas para ferramentas personalizadas

• Escreva descrições de ferramentas concisas e explícitas. O modelo escolhe o que enviar com base na sua descrição; indique explicitamente se quiser que ele sempre chame a ferramenta.
• Valide as saídas no servidor. Strings em formato livre são poderosas, mas exigem proteções contra injeção ou comandos inseguros.

Ferramentas permitidas

O parâmetro allowed_tools em tool_choice permite passar N definições de ferramentas, mas restringir o modelo a apenas M (< N) delas. Liste seu conjunto completo de ferramentas em tools e, em seguida, use um bloco allowed_tools para indicar o subconjunto e especificar um modo: auto (o modelo pode escolher qualquer uma delas) ou required (o modelo deve chamar uma delas).

Ao separar todas as ferramentas possíveis do subconjunto que pode ser usado agora, você ganha mais segurança, previsibilidade e um cache de prompts mais eficiente. Também evita soluções frágeis de engenharia de prompt, como uma ordem de chamadas fixa no código. O GPT-5.4 chama ou exige funções específicas dinamicamente durante a conversa, reduzindo o risco de uso não intencional de ferramentas em contextos longos.

12345678910{
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "get_weather" },
      { "type": "function", "name": "search_docs" }
    ]
  }
}

Para uma visão geral mais detalhada de todos esses novos recursos, consulte as orientações de criação de prompts para o GPT-5.4.

Preâmbulos

Preâmbulos são explicações breves e visíveis para o usuário que o GPT-5.4 gera antes de chamar qualquer ferramenta ou função, descrevendo sua intenção ou seu plano, por exemplo, “por que estou chamando esta ferramenta”. Eles aparecem após a cadeia de pensamento e antes da chamada de ferramenta em si, facilitando a compreensão e a depuração do raciocínio do modelo e permitindo orientá-lo com precisão.

Ao permitir que o GPT-5.4 “pense em voz alta” antes de cada chamada de ferramenta, os preâmbulos aumentam a precisão das chamadas (e o sucesso geral das tarefas) sem aumentar excessivamente a sobrecarga de raciocínio. Para habilitar preâmbulos, adicione uma instrução de sistema ou de desenvolvedor, por exemplo: “Antes de chamar uma ferramenta, explique por que está chamando-a.” O GPT-5.4 adiciona uma justificativa concisa a cada chamada de ferramenta especificada. O modelo também pode gerar várias mensagens entre chamadas de ferramentas, o que pode melhorar a experiência de interação, especialmente em casos de uso com raciocínio mínimo ou sensíveis à latência.

Para saber mais sobre o uso de preâmbulos, consulte o cookbook de criação de prompts para o GPT-5.

Início rápido de migração

O GPT-5.4 funciona melhor com a Responses API, que permite preservar o contexto de raciocínio entre turnos para melhorar o desempenho. Veja abaixo como migrar do seu modelo ou API atual.

Migrando de outros modelos para o GPT-5.4

Embora o modelo deva substituir o GPT-5.2 praticamente sem ajustes, há algumas mudanças importantes a destacar. Consulte as orientações de criação de prompts para o GPT-5.4 para saber quais atualizações específicas fazer nos seus prompts.

Usar modelos GPT-5 com a Responses API proporciona maior inteligência graças ao design da API. A Responses API pode passar a CoT do turno anterior ao modelo. Isso resulta em menos tokens de raciocínio gerados, taxas de acerto de cache mais altas e menor latência. Para saber mais, consulte um guia aprofundado sobre os benefícios da Responses API.

Ao migrar de um modelo mais antigo da OpenAI para o GPT-5.4, comece experimentando níveis de raciocínio e estratégias de criação de prompts. Use o otimizador de prompts para atualizar seus prompts para o GPT-5.4 com base nas práticas recomendadas atuais e, depois, siga estas orientações específicas para cada modelo:

• gpt-5.2: gpt-5.4 com as configurações padrão foi projetado para substituí-lo sem ajustes.
• o3: gpt-5.4 com raciocínio medium ou high. Comece com raciocínio medium e ajuste os prompts; depois, aumente para high se não estiver obtendo os resultados desejados.
• gpt-4.1: gpt-5.4 com raciocínio none. Comece com none e ajuste seus prompts; aumente o nível se precisar de melhor desempenho.
• o4-mini ou gpt-4.1-mini: gpt-5.4-mini com ajustes nos prompts é uma ótima opção de substituição.
• gpt-4.1-nano: gpt-5.4-nano com ajustes nos prompts é uma ótima opção de substituição.

Novo parâmetro phase

Para fluxos de longa duração ou com uso intensivo de ferramentas do GPT-5.4 na Responses API, use o campo phase da mensagem do assistente para evitar encerramentos prematuros e outros comportamentos incorretos.

phase é opcional na API, mas recomendamos fortemente seu uso. Use phase: "commentary" para atualizações intermediárias do assistente (como preâmbulos antes de chamadas de ferramentas) e phase: "final_answer" para a resposta concluída. Não adicione phase às mensagens do usuário.

A ausência ou a perda de phase pode fazer com que preâmbulos sejam tratados como respostas finais nesses fluxos de trabalho. Para mais orientações e exemplos, consulte o guia de criação de prompts para o GPT-5.4.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.4",
  input: [
    {
      role: "assistant",
      phase: "commentary",
      content:
        "I’ll inspect the logs and then summarize root cause and remediation.",
    },
    {
      role: "assistant",
      phase: "final_answer",
      content: "Root cause: cache invalidation race.",
    },
    {
      role: "user",
      content: "Great—now give me a rollout-safe fix plan.",
    },
  ],
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input=[
        {
            "role": "assistant",
            "phase": "commentary",
            "content": "I’ll inspect the logs and then summarize root cause and remediation.",
        },
        {
            "role": "assistant",
            "phase": "final_answer",
            "content": "Root cause: cache invalidation race.",
        },
        {
            "role": "user",
            "content": "Great—now give me a rollout-safe fix plan.",
        },
    ],
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	commentary := responses.ResponseInputItemParamOfMessage(
		"I’ll inspect the logs and then summarize root cause and remediation.",
		responses.EasyInputMessageRoleAssistant,
	)
	commentary.OfMessage.Phase = responses.EasyInputMessagePhaseCommentary
	finalAnswer := responses.ResponseInputItemParamOfMessage(
		"Root cause: cache invalidation race.",
		responses.EasyInputMessageRoleAssistant,
	)
	finalAnswer.OfMessage.Phase = responses.EasyInputMessagePhaseFinalAnswer

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.4",
		Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
			commentary,
			finalAnswer,
			responses.ResponseInputItemParamOfMessage("Great—now give me a rollout-safe fix plan.", responses.EasyInputMessageRoleUser),
		}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.MEDIUM).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  reasoning: { effort: :medium },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

Compatibilidade de parâmetros do GPT-5.4

Os parâmetros a seguir só são compatíveis com o GPT-5.4 quando o esforço de raciocínio está definido como none:

• temperature
• top_p
• logprobs

Requisições que incluam esses campos gerarão um erro no GPT-5.4 ou GPT-5.2 com qualquer outra configuração de esforço de raciocínio, ou em modelos GPT-5 mais antigos, como gpt-5, gpt-5-mini ou gpt-5-nano.

Para obter resultados semelhantes com um esforço de raciocínio mais alto ou com outro modelo da família GPT-5, experimente estes parâmetros alternativos:

• Profundidade do raciocínio: reasoning: { effort: "none" | "low" | "medium" | "high" | "xhigh" }
• Verbosidade da saída: text: { verbosity: "low" | "medium" | "high" }
• Tamanho da saída: max_output_tokens

Migrando de Chat Completions para a Responses API

A maior diferença, e o principal motivo para migrar de Chat Completions para a Responses API ao usar o GPT-5.4, é o suporte à passagem da cadeia de pensamento (CoT) entre turnos. Veja uma comparação completa das APIs.

A passagem de CoT está disponível apenas na Responses API, e observamos que ela resulta em maior inteligência, menos tokens de raciocínio gerados, maiores taxas de acerto do cache e menor latência. A maioria dos outros parâmetros permanece equivalente, embora a formatação seja diferente. Veja como os novos parâmetros são tratados de forma diferente em Chat Completions e na Responses API:

Esforço de raciocínio

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  "reasoning": {
    "effort": "none"
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    }
  ],
  "reasoning_effort": "none"
}'

Verbosidade

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "What is the answer to the ultimate question of life, the universe, and everything?"
    }
  ],
  "verbosity": "low"
}'

Ferramentas personalizadas

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry",
  "tools": [
    {
      "type": "custom",
      "name": "code_exec",
      "description": "Executes arbitrary Python code"
    }
  ]
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry"
    }
  ],
  "tools": [
    {
      "type": "custom",
      "custom": {
        "name": "code_exec",
        "description": "Executes arbitrary Python code"
      }
    }
  ]
}'

Práticas recomendadas para criação de prompts

Entenda o comportamento do GPT-5.4

Onde o GPT-5.4 se destaca

O GPT-5.4 tende a ter um desempenho especialmente bom nestas áreas:

• Alta fidelidade à personalidade e ao tom, com menos desvios ao longo de respostas extensas
• Robustez em fluxos de trabalho agênticos, com maior tendência a persistir em trabalhos de várias etapas, tentar novamente e concluir ciclos de agentes de ponta a ponta
• Síntese rica em evidências, especialmente em fluxos de trabalho com contexto longo ou várias ferramentas
• Cumprimento de instruções em prompts modulares, baseados em habilidades e estruturados em blocos quando o contrato é explícito
• Análise de contexto longo com entradas extensas, desorganizadas ou compostas por vários documentos
• Chamadas de ferramentas em lote ou em paralelo, mantendo a precisão das chamadas
• Fluxos de trabalho com planilhas, finanças e Excel que exigem cumprimento de instruções, fidelidade à formatação e autoverificação mais rigorosa

Onde prompts explícitos ainda ajudam

Mesmo com esses pontos fortes, o GPT-5.4 se beneficia de orientações mais explícitas em algumas situações recorrentes:

• Roteamento de ferramentas com pouco contexto no início de uma sessão, quando a seleção de ferramentas pode ser menos confiável
• Fluxos de trabalho que consideram dependências e precisam de verificações explícitas dos pré-requisitos e das etapas subsequentes
• Seleção do esforço de raciocínio, em que um esforço maior nem sempre é melhor e a escolha certa depende das características da tarefa, não da intuição
• Tarefas de pesquisa que exigem coleta criteriosa de fontes e citações consistentes
• Ações irreversíveis ou de alto impacto que exigem verificação antes da execução
• Ambientes de terminal ou de agentes de programação em que os limites de uso das ferramentas devem permanecer claros

Esses padrões são comportamentos típicos observados, não garantias. Comece com o menor prompt que passe nas suas avaliações e adicione blocos apenas quando eles corrigirem um modo de falha identificado por medições.

Use padrões fundamentais de prompts

Mantenha as saídas compactas e estruturadas

Para melhorar a eficiência no uso de tokens com o GPT-5.4, limite a verbosidade e exija uma saída estruturada por meio de contratos de saída claros. Na prática, isso funciona como uma camada adicional de controle junto ao parâmetro verbosity na Responses API, permitindo orientar tanto o quanto o modelo escreve quanto a forma como ele estrutura a saída.

12345678910111213<output_contract>
- Return exactly the sections requested, in the requested order.
- If the prompt defines a preamble, analysis block, or working section, do not treat it as extra output.
- Apply length limits only to the section they are intended for.
- If a format is required (JSON, Markdown, SQL, XML), output only that format.
</output_contract>

<verbosity_controls>
- Prefer concise, information-dense writing.
- Avoid repeating the user's request.
- Keep progress updates brief.
- Do not shorten the answer so aggressively that required evidence, reasoning, or completion checks are omitted.
</verbosity_controls>

Defina padrões claros para dar continuidade às tarefas

Os usuários frequentemente mudam a tarefa, o formato ou o tom durante a conversa. Para manter o assistente alinhado, defina regras claras sobre quando prosseguir, quando perguntar e como as instruções mais recentes substituem os padrões anteriores.

Use uma política padrão de execução até a conclusão como esta:

12345678<default_follow_through_policy>
- If the user’s intent is clear and the next step is reversible and low-risk, proceed without asking.
- Ask permission only if the next step is:
  (a) irreversible,
  (b) has external side effects (for example sending, purchasing, deleting, or writing to production), or
  (c) requires missing sensitive information or a choice that would materially change the outcome.
- If proceeding, briefly state what you did and what remains optional.
</default_follow_through_policy>

Deixe explícita a prioridade das instruções:

123456<instruction_priority>
- User instructions override default style, tone, formatting, and initiative preferences.
- Safety, honesty, privacy, and permission constraints do not yield.
- If a newer user instruction conflicts with an earlier one, follow the newer instruction.
- Preserve earlier instructions that do not conflict.
</instruction_priority>

As instruções de desenvolvedor ou de sistema com prioridade mais alta continuam sendo obrigatórias.

Orientação: Quando as instruções mudarem durante a conversa, comunique a atualização de forma explícita, com escopo definido e aplicação localizada. Informe o que mudou, o que continua valendo e se a mudança afeta a próxima interação ou o restante da conversa.

Lide com atualizações de instruções durante a conversa

Para atualizações durante a conversa, use mensagens de orientação explícitas e com escopo definido que indiquem:

1. Escopo
2. O que substituir
3. O que manter

<task_update>
For the next response only:
- Do not complete the task.
- Only produce a plan.
- Keep it to 5 bullets.

All earlier instructions still apply unless they conflict with this update.
</task_update>

Se a própria tarefa mudar, diga isso diretamente:

<task_update>
The task has changed.
Previous task: complete the workflow.
Current task: review the workflow and identify risks only.

Rules for this turn:
- Do not execute actions.
- Do not call destructive tools.
- Return exactly:
  1. Main risks
  2. Missing information
  3. Recommended next step
</task_update>

Exija persistência no uso de ferramentas quando a correção do resultado depender disso

Use regras explícitas para que o uso de ferramentas seja completo, respeite as dependências e siga um ritmo adequado, especialmente em fluxos de trabalho nos quais ações posteriores dependem de recuperação de informações ou verificações anteriores. Uma falha comum é pular pré-requisitos porque o estado final correto parece óbvio.

O GPT-5.4 pode ser menos confiável na seleção de ferramentas no início de uma sessão, quando ainda há pouco contexto. Inclua no prompt a exigência de cumprir pré-requisitos, verificar dependências e definir a finalidade exata do uso de cada ferramenta.

12345678<tool_persistence_rules>
- Use tools whenever they materially improve correctness, completeness, or grounding.
- Do not stop early when another tool call is likely to materially improve correctness or completeness.
- Keep calling tools until:
  (1) the task is complete, and
  (2) verification passes (see <verification_loop>).
- If a tool returns empty or partial results, retry with a different strategy.
</tool_persistence_rules>

Isso é especialmente importante em fluxos de trabalho nos quais a ação final depende de etapas anteriores de consulta ou recuperação de informações. Uma das falhas mais comuns é pular pré-requisitos porque o estado final pretendido parece óbvio.

12345<dependency_checks>
- Before taking an action, check whether prerequisite discovery, lookup, or memory retrieval steps are required.
- Do not skip prerequisite steps just because the intended final action seems obvious.
- If the task depends on the output of a prior step, resolve that dependency first.
</dependency_checks>

Peça execução em paralelo quando as tarefas forem independentes e o tempo total de execução importar. Peça execução sequencial quando dependências, ambiguidades ou ações irreversíveis forem mais importantes que a velocidade.

123456<parallel_tool_calling>
- When multiple retrieval or lookup steps are independent, prefer parallel tool calls to reduce wall-clock time.
- Do not parallelize steps that have prerequisite dependencies or where one result determines the next action.
- After parallel retrieval, pause to synthesize the results before making more calls.
- Prefer selective parallelism: parallelize independent evidence gathering, not speculative or redundant tool use.
</parallel_tool_calling>

Exija a execução completa de tarefas de longa duração

Em fluxos de trabalho com várias etapas, uma falha comum é a execução incompleta: o modelo encerra o trabalho após cobrir apenas parte do escopo, deixa passar itens de um lote ou considera definitivos os resultados de uma recuperação de informações vazia ou limitada. O GPT-5.4 se torna mais confiável quando o prompt define regras explícitas de conclusão e o comportamento de recuperação em caso de falha.

É possível cobrir o escopo por meio de recuperação de informações sequencial ou paralela, mas as regras de conclusão devem permanecer explícitas em ambos os casos.

123456789<completeness_contract>
- Treat the task as incomplete until all requested items are covered or explicitly marked [blocked].
- Keep an internal checklist of required deliverables.
- For lists, batches, or paginated results:
  - determine expected scope when possible,
  - track processed items or pages,
  - confirm coverage before finalizing.
- If any item is blocked by missing data, mark it [blocked] and state exactly what is missing.
</completeness_contract>

Para fluxos de trabalho em que a recuperação de informações costuma retornar resultados vazios, parciais ou com ruído:

1234567891011<empty_result_recovery>
If a lookup returns empty, partial, or suspiciously narrow results:
- do not immediately conclude that no results exist,
- try at least one or two fallback strategies,
  such as:
  - alternate query wording,
  - broader filters,
  - a prerequisite lookup,
  - or an alternate source or tool,
- Only then report that no results were found, along with what you tried.
</empty_result_recovery>

Adicione um ciclo de verificação antes de ações de alto impacto

Quando o fluxo de trabalho parecer concluído, adicione uma etapa simples de verificação antes de retornar a resposta ou realizar uma ação irreversível. Isso ajuda a identificar requisitos não atendidos, problemas de fundamentação e desvios de formato antes de efetivar o resultado.

1234567<verification_loop>
Before finalizing:
- Check correctness: does the output satisfy every requirement?
- Check grounding: are factual claims backed by the provided context or tool outputs?
- Check formatting: does the output match the requested schema or style?
- Check safety and irreversibility: if the next step has external side effects, ask permission first.
</verification_loop>

12345<missing_context_gating>
- If required context is missing, do NOT guess.
- Prefer the appropriate lookup tool when the missing context is retrievable; ask a minimal clarifying question only when it is not.
- If you must proceed, label assumptions explicitly and choose a reversible action.
</missing_context_gating>

Para agentes que executam ações ativamente, adicione um breve roteiro de execução:

12345<action_safety>
- Pre-flight: summarize the intended action and parameters in 1-2 lines.
- Execute via tool.
- Post-flight: confirm the outcome and any validation that was performed.
</action_safety>

Lide com fluxos de trabalho especializados

Escolha explicitamente o nível de detalhe da imagem para visão e uso do computador

Se o seu fluxo de trabalho depender de precisão visual, especifique o nível detail da imagem no prompt ou na integração, em vez de depender de auto. Use high para a compreensão padrão de imagens com alta fidelidade. Use original para imagens grandes, densas ou que exijam precisão espacial, especialmente em tarefas de uso do computador, localização, OCR e precisão de cliques com gpt-5.4 e modelos futuros. Use low apenas quando a velocidade e o custo forem mais importantes que os detalhes finos. Para saber mais sobre os níveis de detalhe de imagem, consulte o guia de Imagens e visão.

Restrinja a pesquisa e as citações às evidências recuperadas

Quando a qualidade das citações importar, deixe explícitos tanto os limites das fontes quanto os requisitos de formato. Isso ajuda a reduzir referências inventadas, afirmações sem respaldo e desvios no formato das citações.

123456<citation_rules>
- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.
</citation_rules>

123456<grounding_rules>
- Base claims only on provided context or tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or say you cannot support the claim.
- If a statement is an inference rather than a directly supported fact, label it as an inference.
</grounding_rules>

Se o seu aplicativo exigir citações no corpo do texto, exija citações no corpo do texto. Se exigir notas de rodapé, exija notas de rodapé. O essencial é fixar o formato e impedir que o modelo improvise referências sem respaldo.

Modo de pesquisa

Oriente o GPT-5.4 a adotar um modo de pesquisa disciplinado. Use esse padrão para tarefas de pesquisa, revisão e síntese. Não o imponha a tarefas curtas de execução ou a transformações determinísticas simples.

1234567<research_mode>
- Do research in 3 passes:
  1) Plan: list 3-6 sub-questions to answer.
  2) Retrieve: search each sub-question and follow 1-2 second-order leads.
  3) Synthesize: resolve contradictions and write the final answer with citations.
- Stop only when more searching is unlikely to change the conclusion.
</research_mode>

Se o ambiente do host usar uma ferramenta de pesquisa específica ou exigir uma etapa de envio, combine esse padrão com o contrato de finalização do host.

Imponha formatos de saída rígidos

Para SQL, JSON ou outras saídas sensíveis a erros de análise sintática, instrua o GPT-5.4 a gerar apenas o formato de destino e a verificá-lo antes de concluir.

<structured_output_contract>
- Output only the requested format.
- Do not add prose or markdown fences unless they were requested.
- Validate that parentheses and brackets are balanced.
- Do not invent tables or fields.
- If required schema information is missing, ask for it or return an explicit error object.
</structured_output_contract>

Se você estiver extraindo regiões de documentos ou caixas de OCR, defina o sistema de coordenadas e adicione uma verificação de desvios:

<bbox_extraction_spec>
- Use the specified coordinate format exactly, such as [x1,y1,x2,y2] normalized to 0..1.
- For each box, include page, label, text snippet, and confidence.
- Add a vertical-drift sanity check so boxes stay aligned with the correct line of text.
- If the layout is dense, process page by page and do a second pass for missed items.
</bbox_extraction_spec>

Mantenha explícitos os limites das ferramentas em agentes de programação e de terminal

Em agentes de programação, o GPT-5.4 funciona melhor quando as regras de acesso ao shell e de edição de arquivos são inequívocas. Isso é especialmente importante quando você disponibiliza ferramentas como Shell ou Aplicar patch.

Atualizações para o usuário

O GPT-5.4 funciona bem com atualizações breves e focadas nos resultados. Reutilize o padrão de atualizações para o usuário do guia do 5.2, mas combine-o com requisitos explícitos de conclusão e verificação.

Especificação recomendada para as atualizações:

123456<user_updates_spec>
- Only update the user when starting a new major phase or when something changes the plan.
- Each update: 1 sentence on outcome + 1 sentence on next step.
- Do not narrate routine tool calls.
- Keep the user-facing status short; keep the work exhaustive.
</user_updates_spec>

Para orientações mais específicas sobre agentes de programação, consulte a seção Padrões de criação de prompts para tarefas de programação abaixo.

Padrões de criação de prompts para tarefas de programação

Autonomia e persistência

O GPT-5.4 geralmente é mais minucioso do início ao fim do que os modelos anteriores da linha principal em tarefas de programação e uso de ferramentas, de modo que costuma ser menos necessário incluir instruções explícitas como “verifique tudo”. Ainda assim, para mudanças de alto risco, como as que envolvem produção, migrações ou segurança, mantenha uma instrução simples de verificação.

12345<autonomy_and_persistence>
Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.

Unless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
</autonomy_and_persistence>

Atualizações intermediárias

Envie poucas atualizações, com informações relevantes. Em tarefas de programação, prefira atualizar o usuário nos momentos-chave.

1234567891011121314<user_updates_spec>
- Intermediary updates go to the `commentary` channel.
- User updates are short updates while you are working. They are not final answers.
- Use 1-2 sentence updates to communicate progress and new information while you work.
- Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done -", "Got it", or "Great question") or similar framing.
- Before exploring or doing substantial work, send a user update explaining your understanding of the request and your first step. Avoid commenting on the request or starting with phrases such as "Got it" or "Understood."
- Provide updates roughly every 30 seconds while working.
- When exploring, explain what context you are gathering and what you learned. Vary sentence structure so the updates do not become repetitive.
- When working for a while, keep updates informative and varied, but stay concise.
- When work is substantial, provide a longer plan after you have enough context. This is the only update that may be longer than 2 sentences and may contain formatting.
- Before file edits, explain what you are about to change.
- While thinking, keep the user informed of progress without narrating every tool call. Even if you are not taking actions, send frequent progress updates rather than going silent, especially if you are thinking for more than a short stretch.
- Keep the tone of progress updates consistent with the assistant's overall personality.
</user_updates_spec>

Formatação

O GPT-5.4 costuma adotar uma formatação mais estruturada por padrão e pode usar listas com marcadores em excesso. Se quiser uma resposta final simples e organizada, restrinja explicitamente a estrutura das listas.

Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections or if you use : just include the line you might usually render using a nested bullet immediately after it. For numbered lists, only use the `1. 2. 3.` style markers (with a period), never `1)`.

Tarefas de frontend

Use isso apenas quando orientações adicionais de frontend forem úteis.

123456789101112131415161718<frontend_tasks>
When doing frontend design tasks, avoid generic, overbuilt layouts.

Use these hard rules:
- One composition: The first viewport must read as one composition, not a dashboard, unless it is a dashboard.
- Brand first: On branded pages, the brand or product name must be a hero-level signal, not just nav text or an eyebrow. No headline should overpower the brand.
- Brand test: If the first viewport could belong to another brand after removing the nav, the branding is too weak.
- Full-bleed hero only: On landing pages and promotional surfaces, the hero image should usually be a dominant edge-to-edge visual plane or background. Do not default to inset hero images, side-panel hero images, rounded media cards, tiled collages, or floating image blocks unless the existing design system clearly requires them.
- Hero budget: The first viewport should usually contain only the brand, one headline, one short supporting sentence, one CTA group, and one dominant image. Do not place stats, schedules, event listings, address blocks, promos, "this week" callouts, metadata rows, or secondary marketing content there.
- No hero overlays: Do not place detached labels, floating badges, promo stickers, info chips, or callout boxes on top of hero media.
- Cards: Default to no cards. Never use cards in the hero unless they are the container for a user interaction. If removing a border, shadow, background, or radius does not hurt interaction or understanding, it should not be a card.
- One job per section: Each section should have one purpose, one headline, and usually one short supporting sentence.
- Real visual anchor: Imagery should show the product, place, atmosphere, or context.
- Reduce clutter: Avoid pill clusters, stat strips, icon rows, boxed promos, schedule snippets, and competing text blocks.
- Use motion to create presence and hierarchy, not noise. Ship 2-3 intentional motions for visually led work, and prefer Framer Motion when it is available.

Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
</frontend_tasks>

123456<terminal_tool_hygiene>
- Only run shell commands via the terminal tool.
- Never "run" tool names as shell commands.
- If a patch or edit tool exists, use it directly; do not attempt it in bash.
- After changes, run a lightweight verification step such as ls, tests, or a build before declaring the task done.
</terminal_tool_hygiene>

Localização em documentos e caixas de OCR

Para tarefas de bbox, explicite as convenções de coordenadas e adicione testes de desvio.

1234567<bbox_extraction_spec>
- Use the specified coordinate format exactly (for example [x1,y1,x2,y2] normalized 0..1).
- For each bbox, include: page, label, text snippet, confidence.
- Add a vertical-drift sanity check:
  - ensure bboxes align with the line of text (not shifted up or down).
- If dense layout, process page by page and do a second pass for missed items.
</bbox_extraction_spec>

Use as orientações de integração com o ambiente de execução e a API

Para agentes de longa duração ou que usam ferramentas intensivamente, o contrato do ambiente de execução importa tanto quanto o contrato do prompt.

Parâmetro de fase

Para GPT-5.4, gpt-5.3-codex e modelos posteriores da Responses, o campo phase pode ajudar nos poucos fluxos de longa duração ou de uso intensivo de ferramentas em que preâmbulos ou outras atualizações intermediárias do assistente são confundidos com a resposta final.

• phase é opcional na API, mas é altamente recomendado. O servidor pode tentar inferir esse valor da melhor forma possível, mas preservar e reenviar phase explicitamente é sempre melhor.
• Use phase para agentes de longa duração ou que usam ferramentas intensivamente e podem emitir comentários antes de chamadas de ferramentas ou de uma resposta final.
• Preserve phase ao reenviar itens anteriores do assistente para que o modelo consiga distinguir os comentários sobre o trabalho em andamento da resposta concluída. Isso é especialmente importante em fluxos com várias etapas que incluem preâmbulos, atualizações relacionadas a ferramentas ou várias mensagens do assistente no mesmo turno.
• Não adicione phase às mensagens do usuário.
• Se você usar previous_response_id, esse costuma ser o caminho mais simples, pois a OpenAI geralmente consegue recuperar o estado anterior sem que seja necessário reenviar manualmente os itens do assistente.
• Se você reenviar o histórico do assistente por conta própria, preserve os valores originais de phase.
• A ausência ou perda de phase pode fazer com que preâmbulos sejam interpretados como respostas finais e prejudicar o comportamento nessas tarefas de várias etapas.

Preserve o comportamento em sessões longas

A compactação permite janelas de contexto efetivas significativamente maiores. Com isso, as conversas dos usuários podem continuar por muitos turnos sem atingir os limites de contexto nem sofrer degradação de desempenho decorrente de contextos longos, e os agentes podem executar sequências muito extensas de ações que ultrapassam uma janela de contexto típica em tarefas complexas e de longa duração.

Se você usa Compactação na Responses API, compacte após marcos importantes, trate os itens compactados como estado opaco e mantenha os prompts funcionalmente idênticos após a compactação. O endpoint é compatível com ZDR e retorna um item encrypted_content que você pode passar em solicitações futuras. O GPT-5.4 tende a manter mais coerência e confiabilidade em conversas mais longas, com vários turnos, apresentando menos falhas à medida que as sessões se estendem.

Para mais orientações, consulte a referência da API de /responses/compact.

Controle a personalidade em fluxos de trabalho voltados ao cliente

É possível orientar o GPT-5.4 com mais eficácia quando você separa a personalidade persistente dos controles de escrita específicos de cada resposta. Isso é especialmente útil em fluxos de trabalho voltados ao cliente, como e-mails, respostas de suporte, comunicados e conteúdo no estilo de blog.

• Personalidade (persistente): define o tom, o nível de detalhamento e o estilo de tomada de decisão padrão ao longo da sessão.
• Controles de escrita (por resposta): definem o canal, o registro de linguagem, a formatação e a extensão de um artefato específico.
• Lembrete: a personalidade não deve se sobrepor aos requisitos de saída específicos da tarefa. Se o usuário pedir JSON, retorne JSON.

Para produzir uma prosa natural e de alta qualidade, os controles mais eficazes são:

• Defina uma persona clara para o modelo.
• Especifique o canal e o tom emocional.
• Proíba explicitamente a formatação quando quiser prosa.
• Use limites rígidos de extensão.

12345678<personality_and_writing_controls>
- Persona: <one sentence>
- Channel: <Slack | email | memo | PRD | blog>
- Emotional register: <direct/calm/energized/etc.> + "not <overdo this>"
- Formatting: <ban bullets/headers/markdown if you want prose>
- Length: <hard limit, e.g. <=150 words or 3-5 sentences>
- Default follow-through: if the request is clear and low-risk, proceed without asking permission.
</personality_and_writing_controls>

Para mais padrões de personalidade que você pode usar diretamente, consulte o Cookbook de personalidades em prompts.

Modo de memorando profissional

Para memorandos, revisões e outras tarefas de redação profissional, instruções gerais de escrita muitas vezes não bastam. Esses fluxos de trabalho se beneficiam de orientações explícitas sobre especificidade, convenções da área, síntese e grau de certeza adequado.

12345678<memo_mode>
- Write in a polished, professional memo style.
- Use exact names, dates, entities, and authorities when supported by the record.
- Follow domain-specific structure if one is requested.
- Prefer precise conclusions over generic hedging.
- When uncertainty is real, tie it to the exact missing fact or conflicting source.
- Synthesize across documents rather than summarizing each one independently.
</memo_mode>

Esse modo é especialmente útil para textos jurídicos, de políticas, de pesquisa e voltados a executivos, nos quais o objetivo não é apenas fluência, mas também síntese rigorosa e conclusões claras.

Ajuste o raciocínio e a migração

Trate o esforço de raciocínio como um ajuste final

Não existe um esforço de raciocínio ideal para todas as tarefas. Trate-o como um ajuste final, não como a principal forma de melhorar a qualidade. Em muitos casos, prompts mais bem elaborados, contratos de saída claros e ciclos leves de verificação proporcionam grande parte do desempenho que as equipes buscariam com níveis mais altos de raciocínio.

Configurações padrão recomendadas:

• none: Ideal para tarefas rápidas, sensíveis a custo e latência, nas quais o modelo não precisa pensar.
• low: Funciona bem para tarefas sensíveis à latência nas quais um pouco de raciocínio pode gerar um ganho significativo de precisão, especialmente com instruções complexas.
• medium ou high: Reserve para tarefas que realmente exigem raciocínio mais aprofundado e podem tolerar o aumento de latência e custo. Escolha entre eles com base no ganho de desempenho que o raciocínio adicional traz à sua tarefa.
• xhigh: Evite como padrão, a menos que suas avaliações mostrem benefícios claros. É mais adequado para tarefas longas, agênticas e que exigem muito raciocínio, nas quais a inteligência máxima importa mais do que a velocidade ou o custo.

Na prática, a maioria das equipes deve adotar none, low ou medium como padrão.

Comece com none para cargas de trabalho focadas na execução, como etapas de fluxos de trabalho, extração de campos, triagem de suporte e transformações estruturadas curtas.

Comece com medium ou um nível superior para cargas de trabalho com muita pesquisa, como síntese de contextos longos, revisão de vários documentos, resolução de conflitos e redação de estratégias. Com medium e um prompt bem elaborado, você pode obter um ótimo desempenho.

Para cargas de trabalho com GPT-5.4, none já pode ter um bom desempenho em tarefas de seleção de ações e uso disciplinado de ferramentas. Se sua carga de trabalho depende de interpretação de nuances, como requisitos implícitos, ambiguidades ou recuperação após chamadas de ferramenta canceladas, comece com low ou medium.

Antes de aumentar o esforço de raciocínio, adicione:

• <completeness_contract>
• <verification_loop>
• <tool_persistence_rules>

Se o modelo ainda parecer literal demais ou parar na primeira resposta plausível, adicione um incentivo à iniciativa antes de aumentar o esforço de raciocínio:

12345<dig_deeper_nudge>
- Don’t stop at the first plausible answer.
- Look for second-order issues, edge cases, and missing constraints.
- If the task is safety or accuracy critical, perform at least one verification step.
</dig_deeper_nudge>

Migre prompts para o GPT-5.4 com uma mudança por vez

Siga a mesma disciplina de fazer uma mudança por vez do guia do 5.2: primeiro troque o modelo, fixe reasoning_effort, execute avaliações e depois faça ajustes iterativos.

Estes pontos de partida funcionam bem para muitas migrações:

Orientações para os modelos menores gpt-5.4-mini e gpt-5.4-nano

É fácil orientar o comportamento de gpt-5.4-mini e gpt-5.4-nano, mas eles têm menos probabilidade do que modelos maiores de inferir etapas ausentes, resolver ambiguidades implicitamente ou apresentar as saídas como você pretendia, a menos que você especifique esse comportamento diretamente. Na prática, os prompts para modelos menores costumam ser um pouco mais longos e explícitos.

Como gpt-5.4-mini se diferencia

• gpt-5.4-mini é mais literal e faz menos suposições.
• Ele tem um bom desempenho quando a tarefa está claramente estruturada, mas é menos eficaz em fluxos de trabalho implícitos e ao lidar com ambiguidades.
• Por padrão, ele pode tentar manter a conversa com uma pergunta adicional, a menos que você impeça esse comportamento explicitamente.

Criação de prompts para gpt-5.4-mini

• Coloque as regras essenciais primeiro.
• Especifique a ordem completa de execução quando o uso de ferramentas ou os efeitos colaterais forem relevantes.
• Não confie apenas em "você DEVE". Use uma estrutura de apoio, como etapas numeradas, regras de decisão e definições explícitas de ações.
• Separe "execute a ação" de "relate a ação".
• Mostre o fluxo correto, não apenas o formato final.
• Defina explicitamente como lidar com ambiguidades: quando perguntar, abster-se ou prosseguir.
• Especifique diretamente a apresentação: extensão da resposta, se deve fazer uma pergunta adicional, estilo das citações e ordem das seções.
• Tenha cuidado com output nothing else. Prefira instruções com escopo definido, como after the final JSON, output nothing further.

Criação de prompts para gpt-5.4-nano

• Use gpt-5.4-nano apenas para tarefas específicas e com escopo bem delimitado.
• Prefira saídas restritas: rótulos, enumerações, JSON curto ou modelos fixos.
• Evite a orquestração em várias etapas, a menos que o fluxo seja extremamente restrito.
• Encaminhe tarefas ambíguas ou que exijam muito planejamento para um modelo mais capaz, em vez de sobrecarregar gpt-5.4-nano com instruções.

Uma boa estrutura padrão

1. Tarefa
2. Regra essencial
3. Ordem exata das etapas
4. Casos extremos ou comportamento ao pedir esclarecimentos
5. Formato de saída
6. Um exemplo correto

Evite

• Próximas etapas implícitas
• Casos extremos não especificados
• Prompts que contêm apenas esquemas para fluxos de trabalho com ferramentas
• Instruções genéricas sem estrutura

Pesquisa na Web e pesquisa aprofundada

Se você estiver migrando especificamente um agente de pesquisa, faça estas atualizações no prompt antes de aumentar o esforço de raciocínio:

• Adicione <research_mode>
• Adicione <citation_rules>
• Adicione <empty_result_recovery>
• Aumente reasoning_effort em um nível somente após corrigir o prompt.

Você pode começar pelo bloco de pesquisa do 5.2 e depois adicionar critérios de validação de citações e contratos de finalização conforme necessário.

O GPT-5.4 tem um desempenho especialmente bom quando a tarefa exige coleta de evidências em várias etapas, síntese de contextos longos e contratos explícitos no prompt. Na prática, as mudanças de maior impacto nos prompts são escolher o esforço de raciocínio de acordo com as características da tarefa, definir formatos exatos de saída e citação, adicionar regras de uso de ferramentas que considerem as dependências e explicitar os critérios de conclusão. O modelo costuma ter bom desempenho sem ajustes, mas é mais confiável quando os prompts especificam claramente como pesquisar, como verificar e o que caracteriza a conclusão da tarefa.

Próximos passos

• Consulte Atualizações de modelos, API e recursos para obter detalhes sobre capacidades dos modelos, parâmetros e compatibilidade da API.
• Leia Engenharia de prompt para conhecer estratégias mais amplas de criação de prompts que se aplicam a diferentes famílias de modelos.
• Leia Compactação se estiver criando sessões de longa duração com o GPT-5.4 na Responses API.

Leitura complementar

Guia de criação de prompts para GPT-5.3-Codex

Artigo do blog sobre GPT-5.4

Guia de frontend com GPT-5

Família de modelos GPT-5: guia de novos recursos

Cookbook sobre modelos de raciocínio

Comparação entre Responses API e Chat Completions

Introdução

O GPT-5.3-Codex avança a fronteira da inteligência e da eficiência na programação agêntica. Siga este guia com atenção para obter o melhor desempenho possível deste modelo. Este guia é voltado a quem usa o modelo diretamente pela API para ter o máximo de personalização; também oferecemos o SDK do Codex para integrações mais simples.

Na API, o modelo ajustado para o Codex é gpt-5.3-codex (consulte a página do modelo).

Novidades

• Mais rápido e eficiente no uso de tokens: usa menos tokens de raciocínio para concluir uma tarefa. Recomendamos o esforço de raciocínio “médio” como uma opção versátil para programação interativa, equilibrando inteligência e velocidade.
• Mais inteligência e autonomia em tarefas de longa duração: o Codex pode trabalhar de forma autônoma por horas para concluir suas tarefas mais difíceis. Você pode usar o esforço de raciocínio high ou xhigh para essas tarefas.
• Suporte nativo à compactação: a compactação permite raciocinar por várias horas sem atingir os limites de contexto e manter conversas mais longas com o usuário sem precisar iniciar novas sessões de chat.
• O Codex também tem um desempenho muito melhor em ambientes PowerShell e Windows.

Início rápido de migração

Se você já tem uma implementação funcional do Codex, este modelo deve funcionar bem com poucas atualizações. Porém, se estiver partindo de um prompt e um conjunto de ferramentas otimizados para modelos da série GPT-5 ou para um modelo de terceiros, recomendamos mudanças mais significativas. A melhor implementação de referência é nosso agente codex-cli, totalmente de código aberto, disponível no GitHub. Clone esse repositório e use o Codex (ou qualquer agente de programação) para fazer perguntas sobre a implementação. Trabalhando com clientes, também aprendemos a personalizar harnesses de agentes além dessa implementação específica.

Principais etapas para migrar seu harness para o codex-cli:

1. Atualize seu prompt: se possível, use nosso prompt padrão do Codex-Max como base e faça acréscimos pontuais a partir dele.

   1. Os trechos mais importantes são os que abordam autonomia e persistência, exploração da base de código, uso de ferramentas e qualidade do frontend.

   2. Remova também todas as instruções para que o modelo apresente um plano inicial, preâmbulos ou outras atualizações de status durante a execução, pois isso pode fazer com que o modelo pare abruptamente antes de concluir a execução.

2. Atualize suas ferramentas, incluindo nossa implementação de apply_patch e as outras práticas recomendadas abaixo. Essa é uma das principais formas de obter o melhor desempenho.

Atualizações do modelo, da API e dos recursos

• O gpt-5.3-codex é otimizado para tarefas de programação agêntica no Codex ou em ambientes semelhantes.
• Ele está disponível na Responses API.
• reasoning.effort aceita low, medium, high e xhigh.
• As ferramentas compatíveis incluem chamada de função, pesquisa na Web, shell hospedado e habilidades.

Práticas recomendadas para criação de prompts

Prompt inicial recomendado

Este prompt começou como o prompt padrão do GPT-5.1-Codex-Max e foi otimizado com base em avaliações internas de correção, completude e qualidade das respostas, uso correto de ferramentas e paralelismo, além de propensão a agir. Se você estiver executando avaliações com este modelo, recomendamos aumentar a autonomia ou solicitar um modo “não interativo” no prompt, embora, no uso real, possa ser desejável pedir mais esclarecimentos.

You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.


# General

- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
- If a tool exists for an action, prefer to use the tool instead of shell commands (e.g `read_file` over `cat`). Strictly avoid raw `cmd`/terminal when a dedicated tool exists. Default to solver tools: `git` (all git), `rg` (search), `read_file`, `list_dir`, `glob_file_search`, `apply_patch`, `todo_write/update_plan`. Use `cmd`/`run_terminal_cmd` only when no listed tool can perform the action.
- When multiple tool calls can be parallelized (e.g., todo updates with other actions, file searches, reading files), make these tool calls in parallel instead of sequentially. Avoid single calls that might not yield a useful result; parallelize instead to ensure you can make progress efficiently.
- Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form "Lxxx:LINE_CONTENT", e.g. "L123:LINE_CONTENT". Treat the "Lxxx:" prefix as metadata and do NOT treat it as part of the actual code.
- Default expectation: deliver working code, not just a plan. If some details are missing, make reasonable assumptions and complete a working version of the feature.


# Autonomy and Persistence

- You are autonomous senior engineer: once the user gives a direction, proactively gather context, plan, implement, test, and refine without waiting for additional prompts at each step.
- Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
- Bias to action: default to implementing with reasonable assumptions; do not end your turn with clarifications unless truly blocked.
- Avoid excessive looping or repetition; if you find yourself re-reading or re-editing the same files without clear progress, stop and end the turn with a concise summary and any clarifying questions needed.


# Code Implementation

- Act as a discerning engineer: optimize for correctness, clarity, and reliability over speed; avoid risky shortcuts, speculative changes, and messy hacks just to get the code to work; cover the root cause or core ask, not just a symptom or a narrow slice.
- Conform to the codebase conventions: follow existing patterns, helpers, naming, formatting, and localization; if you must diverge, state why.
- Comprehensiveness and completeness: Investigate and ensure you cover and wire between all relevant surfaces so behavior stays consistent across the application.
- Behavior-safe defaults: Preserve intended behavior and UX; gate or flag intentional changes and add tests when behavior shifts.
- Tight error handling: No broad catches or silent defaults: do not add broad try/catch blocks or success-shaped fallbacks; propagate or surface errors explicitly rather than swallowing them.
  - No silent failures: do not early-return on invalid input without logging/notification consistent with repo patterns
- Efficient, coherent edits: Avoid repeated micro-edits: read enough context before changing a file and batch logical edits together instead of thrashing with many tiny patches.
- Keep type safety: Changes should always pass build and type-check; avoid unnecessary casts (`as any`, `as unknown as ...`); prefer proper types and guards, and reuse existing helpers (e.g., normalizing identifiers) instead of type-asserting.
- Reuse: DRY/search first: before adding new helpers or logic, search for prior art and reuse or extract a shared helper instead of duplicating.
- Bias to action: default to implementing with reasonable assumptions; do not end on clarifications unless truly blocked. Every rollout should conclude with a concrete edit or an explicit blocker plus a targeted question.


# Editing constraints

- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
- You may be in a dirty git worktree.
    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
    * If the changes are in unrelated files, just ignore them and don't revert them.
- Do not amend a commit unless explicitly requested to do so.
- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.


# Exploration and reading files

- **Think first.** Before any tool call, decide ALL files/resources you will need.
- **Batch everything.** If you need multiple files (even from different places), read them together.
- **multi_tool_use.parallel** Use `multi_tool_use.parallel` to parallelize tool calls and only this.
- **Only make sequential calls if you truly cannot know the next file without seeing a result first.**
- **Workflow:** (a) plan all needed reads → (b) issue one parallel batch → (c) analyze results → (d) repeat if new, unpredictable reads arise.
- Additional notes:
    - Always maximize parallelism. Never read files one-by-one unless logically unavoidable.
    - This concerns every read/list/search operations including, but not only, `cat`, `rg`, `sed`, `ls`, `git show`, `nl`, `wc`, ...
    - Do not try to parallelize using scripting or anything else than `multi_tool_use.parallel`.


# Plan tool

When using the planning tool:
- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
- Do not make single-step plans.
- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
- Unless asked for a plan, never end the interaction with only a plan. Plans guide your edits; the deliverable is working code.
- Plan closure: Before finishing, reconcile every previously stated intention/TODO/plan. Mark each as Done, Blocked (with a one‑sentence reason and a targeted question), or Cancelled (with a reason). Do not end with in_progress/pending items. If you created todos via a tool, update their statuses accordingly.
- Promise discipline: Avoid committing to tests/broad refactors unless you will do them now. Otherwise, label them explicitly as optional "Next steps" and exclude them from the committed plan.
- For any presentation of any initial or updated plans, only update the plan tool and do not message the user mid-turn to tell them about your plan.


# Special user requests

- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.
- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.


# Frontend tasks

When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
Aim for interfaces that feel intentional, bold, and a bit surprising.
- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
- Ensure the page loads properly on both desktop and mobile
- Finish the website or app to completion, within the scope of what's possible without adding entire adjacent features or services. It should be in a working state for a user to run and test.

Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.


# Presenting your work and final message

You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.

- Default: be very concise; friendly coding teammate tone.
- Format: Use natural language with high-level headings.
- Ask only when needed; suggest ideas; mirror the user's style.
- For substantial work, summarize clearly; follow final‑answer formatting.
- Skip heavy formatting for simple confirmations.
- Don't dump large files you've written; reference paths only.
- No "save/copy this file" - User is on the same machine.
- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
- For code changes:
  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
- The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result.

## Final answer structure and style guidelines

- Plain text; CLI handles styling. Use structure only when it helps scanability.
- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
- File References: When referencing files in your response follow the below rules:
  * Use inline code to make file paths clickable.
  * Each reference should have a stand-alone path, even if it's the same file.
  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
  * Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
  * Do not use URIs like file://, vscode://, or https://.
  * Do not provide range of lines
  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5

Atualizações para o usuário durante a execução

A família de modelos Codex pode apresentar atualizações para o usuário enquanto trabalha. Nas versões do codex anteriores ao gpt-5.3-codex, essas atualizações são geradas pelo sistema e não podem ser controladas por prompts. Por isso, recomendamos não adicionar ao prompt instruções sobre planos intermediários ou mensagens ao usuário nessas versões. A partir do gpt-5.3-codex, essas atualizações são mais comunicativas e fornecem mais informações essenciais sobre o que está acontecendo e por quê. Elas funcionam de forma semelhante às mensagens intermediárias de outros modelos da série GPT-5 e podem ser orientadas por prompts, conforme a seção Preâmbulos e personalidade abaixo.

Como usar agents.md

O Codex-cli lista automaticamente esses arquivos e os insere na conversa; o modelo foi treinado para seguir essas instruções rigorosamente.

1. Os arquivos são lidos de ~/.codex e de cada diretório entre a raiz do repositório e o diretório de trabalho atual (CWD), com nomes alternativos opcionais e um limite de tamanho.
2. Eles são combinados em ordem, e as instruções dos diretórios posteriores prevalecem sobre as dos anteriores.
3. Cada trecho combinado é apresentado ao modelo como uma mensagem separada com o papel de usuário, da seguinte forma:

# AGENTS.md instructions for <directory>
<INSTRUCTIONS>
...file contents...
</INSTRUCTIONS>

Detalhes adicionais

• Cada arquivo encontrado se torna uma mensagem separada com o papel de usuário que começa com # AGENTS.md instructions for <directory>, em que <directory> é o caminho (relativo à raiz do repositório) da pasta de origem do arquivo.
• As mensagens são inseridas perto do início do histórico da conversa, antes do prompt do usuário, da raiz até os diretórios mais profundos: primeiro as instruções globais, depois as da raiz do repositório e, em seguida, as de cada diretório mais profundo. Se um AGENTS.override.md tiver sido usado, o nome de seu diretório ainda aparecerá no cabeçalho (por exemplo, # AGENTS.md instructions for backend/api), deixando o contexto claro no registro da conversa.

Compactação

A compactação permite janelas de contexto efetivamente muito maiores. Assim, as conversas com o usuário podem continuar por muitos turnos sem atingir os limites da janela de contexto nem sofrer perda de desempenho devido ao contexto longo, e os agentes podem realizar sequências de execução muito extensas, que ultrapassam uma janela de contexto típica, em tarefas complexas e de longa duração. Uma versão mais limitada disso já era possível com estruturas auxiliares ad hoc e resumos de conversas, mas nossa implementação nativa, disponível pela Responses API, é integrada ao modelo e tem alto desempenho.

Como funciona:

1. Você usa a Responses API como já faz hoje, enviando itens de entrada que incluem chamadas de ferramentas, entradas do usuário e mensagens do assistente.
2. Quando sua janela de contexto ficar grande, você pode chamar /compact para gerar uma nova janela de contexto compactada. Observe dois pontos:
   1. A janela de contexto enviada a /compact deve caber na janela de contexto do seu modelo.
   2. O endpoint é compatível com ZDR e retornará um item “encrypted_content” que você pode passar em solicitações futuras.
3. Nas chamadas seguintes ao endpoint /responses, você pode passar sua lista atualizada e compactada de itens da conversa (incluindo o item de compactação adicionado). O modelo preserva as informações essenciais do estado anterior usando menos tokens de conversa.

Para obter detalhes sobre o endpoint, consulte nossa documentação de /responses/compact.

Ferramentas

1. Recomendamos enfaticamente usar nossa implementação exata de apply_patch, pois o modelo foi treinado para ter excelente desempenho com esse formato de diff. Para comandos de terminal, recomendamos nossa ferramenta shell; para itens de planejamento e tarefas pendentes, nossa ferramenta update_plan deve oferecer o melhor desempenho.
2. Se você preferir que seu agente use mais ferramentas que ofereçam funções semelhantes às do terminal (como file_read() em vez de chamar `sed` no terminal), este modelo pode chamá-las de forma confiável no lugar do terminal (seguindo as instruções abaixo)
3. Outras ferramentas, incluindo pesquisa semântica, servidores MCP e ferramentas personalizadas, podem funcionar, mas exigem mais ajustes e experimentação.

Apply_patch

A maneira mais fácil de implementar apply_patch é usar nossa implementação nativa na Responses API, mas você também pode usar nossa implementação de ferramenta de formato livre com gramática livre de contexto. As duas são demonstradas abaixo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146# Sample script to demonstrate the server-defined apply_patch tool

import json
from pprint import pprint
from typing import cast

from openai import OpenAI
from openai.types.responses import ResponseInputParam, ToolParam

client = OpenAI()

## Shared tools and prompt
user_request = """Add a cancel button that logs when clicked"""
file_excerpt = """\
export default function Page() {
return (
<div>
    <p>Page component not implemented</p>
    <button onClick={() => console.log("clicked")}>Click me</button>
</div>
);
}
"""

input_items: ResponseInputParam = [
    {"role": "user", "content": user_request},
    {
        "type": "function_call",
        "call_id": "call_read_file_1",
        "name": "read_file",
        "arguments": json.dumps({"path": ("/app/page.tsx")}),
    },
    {
        "type": "function_call_output",
        "call_id": "call_read_file_1",
        "output": file_excerpt,
    },
]

read_file_tool: ToolParam = cast(
    ToolParam,
    {
        "type": "function",
        "name": "read_file",
        "description": "Reads a file from disk",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
)

### Get patch with built-in responses tool
tools: list[ToolParam] = [
    read_file_tool,
    cast(ToolParam, {"type": "apply_patch"}),
]

response = client.responses.create(
    model="gpt-5.3-codex",
    input=input_items,
    tools=tools,
    parallel_tool_calls=False,
)

for item in response.output:
    if item.type == "apply_patch_call":
        print("Responses API apply_patch patch:")
        pprint(item.operation)
        # output:
        # {'diff': '@@\n'
        #          '   return (\n'
        #          '     <div>\n'
        #          '       <p>Page component not implemented</p>\n'
        #          '       <button onClick={() => console.log("clicked")}>Click me</button>\n'
        #          '+      <button onClick={() => console.log("cancel clicked")}>Cancel</button>\n'
        #          '     </div>\n'
        #          '   );\n'
        #          ' }\n',
        #  'path': '/app/page.tsx',
        #  'type': 'update_file'}

### Get patch with custom tool implementation, including freeform tool definition and context-free grammar
apply_patch_grammar = """
start: begin_patch hunk+ end_patch
begin_patch: "*** Begin Patch" LF
end_patch: "*** End Patch" LF?

hunk: add_hunk | delete_hunk | update_hunk
add_hunk: "*** Add File: " filename LF add_line+
delete_hunk: "*** Delete File: " filename LF
update_hunk: "*** Update File: " filename LF change_move? change?

filename: /(.+)/
add_line: "+" /(.*)/ LF -> line

change_move: "*** Move to: " filename LF
change: (change_context | change_line)+ eof_line?
change_context: ("@@" | "@@ " /(.+)/) LF
change_line: ("+" | "-" | " ") /(.*)/ LF
eof_line: "*** End of File" LF

%import common.LF
"""

tools_with_cfg: list[ToolParam] = [
    read_file_tool,
    cast(
        ToolParam,
        {
            "type": "custom",
            "name": "apply_patch_grammar",
            "description": "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": apply_patch_grammar,
            },
        },
    ),
]

response_cfg = client.responses.create(
    model="gpt-5.3-codex",
    input=input_items,
    tools=tools_with_cfg,
    parallel_tool_calls=False,
)

for item in response_cfg.output:
    if item.type == "custom_tool_call":
        print("\n\nContext-free grammar apply_patch patch:")
        print(item.input)
        #  Output
        # *** Begin Patch
        # *** Update File: /app/page.tsx
        # @@
        #      <div>
        #        <p>Page component not implemented</p>
        #        <button onClick={() => console.log("clicked")}>Click me</button>
        # +      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
        #      </div>
        #    );
        #  }
        # *** End Patch

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60require "openai"

client = OpenAI::Client.new

input = <<~PROMPT
  Add a cancel button next to the save button in app/page.tsx.
  Current file contents:
  export default function Page() { return <button>Save</button>; }
PROMPT
response = client.responses.create(
  model: "gpt-5.3-codex", input: input,
  tools: [{ type: :apply_patch }], parallel_tool_calls: false
)
response.output.each do |item|
  pp(item.operation) if item.is_a?(OpenAI::Responses::ResponseApplyPatchToolCall)
end

APPLY_PATCH_GRAMMAR = <<~GRAMMAR

  start: begin_patch hunk+ end_patch
  begin_patch: "*** Begin Patch" LF
  end_patch: "*** End Patch" LF?

  hunk: add_hunk | delete_hunk | update_hunk
  add_hunk: "*** Add File: " filename LF add_line+
  delete_hunk: "*** Delete File: " filename LF
  update_hunk: "*** Update File: " filename LF change_move? change?

  filename: /(.+)/
  add_line: "+" /(.*)/ LF -> line

  change_move: "*** Move to: " filename LF
  change: (change_context | change_line)+ eof_line?
  change_context: ("@@" | "@@ " /(.+)/) LF
  change_line: ("+" | "-" | " ") /(.*)/ LF
  eof_line: "*** End of File" LF

  %import common.LF

GRAMMAR

response = client.responses.create(
  model: "gpt-5.3-codex", input: input,
  tools: [
    {
      type: :custom,
      name: "apply_patch",
      description: "Apply a patch to update files.",
      format: {
        type: :grammar,
        syntax: :lark,
        definition: APPLY_PATCH_GRAMMAR
      }
    }
  ],
  parallel_tool_calls: false
)
response.output.each do |item|
  puts(item.input) if item.is_a?(OpenAI::Responses::ResponseCustomToolCall)
end

Os objetos de patch da ferramenta da Responses API podem ser implementados seguindo este exemplo, e os patches da ferramenta de formato livre podem ser aplicados com a lógica da nossa implementação canônica de apply_patch.py para o GPT-5.

Shell_command

Esta é nossa ferramenta de shell padrão. Observamos um desempenho melhor com comandos do tipo “string” do que com uma lista de comandos.

1234567891011121314151617181920212223242526272829303132333435{
  "type": "function",
  "function": {
    "name": "shell_command",
    "description": "Runs a shell command and returns its output.\n- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "command": {
          "type": "string",
          "description": "The shell script to execute in the user's default shell"
        },
        "workdir": {
          "type": "string",
          "description": "The working directory to execute the command in"
        },
        "timeout_ms": {
          "type": "number",
          "description": "The timeout for the command in milliseconds"
        },
        "with_escalated_permissions": {
          "type": "boolean",
          "description": "Whether to request escalated permissions. Set to true if command needs to be run without sandbox restrictions"
        },
        "justification": {
          "type": "string",
          "description": "Only set if with_escalated_permissions is true. 1-sentence explanation of why we want to run this command."
        }
      },
      "required": ["command"],
      "additionalProperties": false
    }
  }
}

Se você estiver usando o Windows PowerShell, atualize a descrição da ferramenta para esta versão.

Runs a shell command and returns its output. The arguments you pass will be invoked via PowerShell (e.g., ["pwsh", "-NoLogo", "-NoProfile", "-Command", "<cmd>"]). Always fill in workdir; avoid using cd in the command string.

Você pode consultar o codex-cli para ver a implementação de exec_command, que inicia um PTY de longa duração quando você precisa de saída em streaming, REPLs ou sessões interativas; e de write_stdin, que permite enviar mais pressionamentos de teclas (ou apenas consultar a saída) para uma sessão existente de exec_command.

Atualizar plano

Esta é nossa ferramenta padrão de tarefas pendentes; personalize-a como preferir. Consulte a seção ## Plan tool do nosso prompt inicial para obter instruções adicionais sobre como manter a organização e ajustar o comportamento.

123456789101112131415161718192021222324252627282930313233343536{
  "type": "function",
  "function": {
    "name": "update_plan",
    "description": "Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "explanation": {
          "type": "string"
        },
        "plan": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "step": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "description": "One of: pending, in_progress, completed"
              }
            },
            "additionalProperties": false,
            "required": ["step", "status"]
          },
          "description": "The list of steps"
        }
      },
      "additionalProperties": false,
      "required": ["plan"]
    }
  }
}

View_image

Esta é uma função básica usada no codex-cli para que o modelo visualize imagens.

12345678910111213141516171819{
  "type": "function",
  "function": {
    "name": "view_image",
    "description": "Attach a local image (by filesystem path) to the conversation context for this turn.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Local filesystem path to an image file"
        }
      },
      "additionalProperties": false,
      "required": ["path"]
    }
  }
}

Ferramentas dedicadas que encapsulam comandos de terminal

Se você preferir que seu agente codex use ferramentas que encapsulam comandos de terminal (como uma ferramenta dedicada list_dir(‘.’) em vez de terminal(‘ls .’)), isso geralmente funciona bem. Observamos os melhores resultados quando o nome da ferramenta, os argumentos e a saída são o mais próximos possível dos do comando subjacente, para que correspondam ao máximo à distribuição dos dados de treinamento do modelo (que foi treinado principalmente com uma ferramenta dedicada de terminal). Por exemplo, se você perceber que o modelo usa git pelo terminal e preferir que ele use uma ferramenta dedicada, constatamos que criar uma ferramenta correspondente e adicionar ao prompt uma instrução para usar somente essa ferramenta para comandos git eliminou completamente o uso do terminal pelo modelo para esses comandos.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36GIT_TOOL = {
    "type": "function",
    "name": "git",
    "description": (
        "Execute a git command in the repository root. Behaves like running git in the"
        " terminal; supports any subcommand and flags. The command can be provided as a"
        " full git invocation (e.g., `git status -sb`) or just the arguments after git"
        " (e.g., `status -sb`)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "command": {
                "type": "string",
                "description": (
                    "The git command to execute. Accepts either a full git invocation or"
                    " only the subcommand/args."
                ),
            },
            "timeout_sec": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1800,
                "description": "Optional timeout in seconds for the git command.",
            },
        },
        "required": ["command"],
    },
}

TOOLS = [GIT_TOOL]

PROMPT_TOOL_USE_DIRECTIVE = (
    "- Strictly avoid raw `cmd`/terminal for Git operations. Use the dedicated "
    "`git` tool instead."
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28require "json"

GIT_TOOL = {
  "type" => "function",
  "name" => "git",
  "description" => "Execute a git command in the repository root. Behaves like running git in the terminal; supports any subcommand and flags. The command can be provided as a full git invocation (e.g., `git status -sb`) or just the arguments after git (e.g., `status -sb`).",
  "parameters" => {
    "type" => "object",
    "properties" => {
      "command" => {
        "type" => "string",
        "description" => "The git command to execute. Accepts either a full git invocation or only the subcommand/args."
      },
      "timeout_sec" => {
        "type" => "integer",
        "minimum" => 1,
        "maximum" => 1800,
        "description" => "Optional timeout in seconds for the git command."
      }
    },
    "required" => ["command"]
  }
}

TOOLS = [GIT_TOOL]
PROMPT_TOOL_USE_DIRECTIVE = "- Strictly avoid raw `cmd`/terminal for Git operations. Use the dedicated `git` tool instead."
puts(JSON.generate(TOOLS))
puts(PROMPT_TOOL_USE_DIRECTIVE)

Outras ferramentas personalizadas (pesquisa na Web, busca semântica, memória etc.)

O modelo não foi necessariamente pós-treinado para se destacar no uso dessas ferramentas, mas também observamos bons resultados com elas. Para aproveitar ao máximo essas ferramentas, recomendamos:

1. Escolher nomes de ferramentas e argumentos que sejam semanticamente tão precisos quanto possível. Por exemplo, “search” é ambíguo, mas “semantic_search” indica claramente o que a ferramenta faz, distinguindo-a de outras ferramentas de busca que você possa ter. “Query” seria um bom nome de parâmetro para essa ferramenta.
2. Explique claramente no prompt quando, por que e como usar essas ferramentas, incluindo exemplos de uso adequado e inadequado.
3. Também pode ser útil apresentar os resultados em um formato diferente das saídas que o modelo costuma receber de outras ferramentas. Por exemplo, os resultados do ripgrep devem ter uma aparência diferente dos resultados de busca semântica para evitar que o modelo volte a hábitos antigos.

Chamadas paralelas de ferramentas

No codex-cli, quando as chamadas paralelas de ferramentas estão habilitadas, a requisição à Responses API define parallel_tool_calls: true, e o seguinte trecho é adicionado às instruções do sistema:

## Exploration and reading files

- **Think first.** Before any tool call, decide ALL files/resources you will need.
- **Batch everything.** If you need multiple files (even from different places), read them together.
- **multi_tool_use.parallel** Use `multi_tool_use.parallel` to parallelize tool calls and only this.
- **Only make sequential calls if you truly cannot know the next file without seeing a result first.**
- **Workflow:** (a) plan all needed reads → (b) issue one parallel batch → (c) analyze results → (d) repeat if new, unpredictable reads arise.

**Additional notes**:
- Always maximize parallelism. Never read files one-by-one unless logically unavoidable.
- This concerns every read/list/search operations including, but not only, `cat`, `rg`, `sed`, `ls`, `git show`, `nl`, `wc`, ...
- Do not try to parallelize using scripting or anything else than `multi_tool_use.parallel`.

Observamos que ordenar os itens de chamadas paralelas de ferramentas e suas respostas da seguinte forma é útil e se aproxima mais dos padrões vistos pelo modelo no treinamento:

function_call
function_call
function_call_output
function_call_output

Truncamento de respostas de ferramentas

Recomendamos truncar as respostas de chamadas de ferramentas da seguinte forma para se aproximar ao máximo dos padrões vistos pelo modelo no treinamento:

• Limite a 10 mil tokens. Você pode estimar essa quantidade com baixo custo computacional calculando num_bytes/4.
• Se atingir o limite de truncamento, use metade dos tokens disponíveis para o início, metade para o fim e trunque o meio com …3 tokens truncated…

Novos recursos do GPT-5.3 Codex

Mensagens de preâmbulo

A Responses API inclui um parâmetro phase destinado a evitar o encerramento prematuro e outros comportamentos inadequados quando o prompt solicita mensagens de preâmbulo. A implementação correta desse parâmetro é obrigatória para gpt-5.3-codex; caso contrário, pode haver uma queda significativa de desempenho.

Fase

Para oferecer melhor suporte a mensagens de preâmbulo com gpt-5.3-codex, a Responses API inclui um campo phase projetado para evitar o encerramento prematuro de tarefas mais demoradas e outros comportamentos inadequados.

Valores

phase assume um dos seguintes valores:

• null
• "commentary"
• "final_answer"

Onde aparece

Você receberá phase nos itens de saída do assistente (por exemplo, output_item.done). Sua integração deve persistir os itens de saída do assistente, incluindo seu phase, e reenviar esses itens nas requisições seguintes.

Importante: phase só é compatível com itens do assistente. Não adicione phase a mensagens do usuário.

Como é usado nas etapas seguintes

Quando o modelo marca um item de saída com:

• phase: "commentary": a mensagem correspondente do assistente deve ser tratada como conteúdo de comentário ou preâmbulo.
• phase: "final_answer": a mensagem correspondente do assistente deve ser tratada como a resposta final de encerramento.

Preservar corretamente phase nos itens do assistente é obrigatório para gpt-5.3-codex. Se os metadados de phase do assistente forem descartados durante a reconstrução do histórico, pode haver uma queda significativa de desempenho.

Preâmbulos e personalidade

Preâmbulos são mensagens enviadas junto com chamadas de ferramentas para atualizar o usuário durante a execução: resumos breves e legíveis do progresso e das intenções que mantêm o usuário informado sem transformar a conversa em um log de chamadas de ferramentas. Os preâmbulos do GPT-5.3-Codex foram ajustados para apresentar as seguintes características:

• Confirme o entendimento e depois apresente um plano antes de qualquer chamada de ferramenta (1 frase de confirmação e 1–2 frases para o plano).
• Mantenha a maioria das atualizações em 1–2 frases e use atualizações mais longas apenas ao atingir marcos relevantes.
• Frequência: procure atualizar a cada 1–3 etapas de execução; requisito mínimo: pelo menos uma atualização a cada 6 etapas ou 10 chamadas de ferramentas.
• Conteúdo de cada atualização: resultados e impacto até o momento, próximas 1–3 etapas e dúvidas em aberto ou aprendizados, quando houver.
• Tom: como uma pessoa colaborando com você, com pouca formalidade; evite títulos, rótulos de status e linguagem de log.

Personalidade (Amigável ou Pragmático)

A personalidade define o tom geral e a postura de colaboração, indo além dos aspectos práticos dos preâmbulos (frequência, extensão e fundamentação). Ela afeta a escolha de palavras, a disposição do modelo para explicar vantagens e desvantagens e o grau de cordialidade na interação.

O aplicativo Codex e a CLI oferecem suporte a duas personalidades, apresentadas aqui como exemplos de implementação para seu harness.

Amigável

• Uma colaboração mais humana, com espírito de parceria.
• Um pouco mais de confirmação do entendimento, tranquilização e contextualização.
• Mais adequado quando explicações ao longo do processo ajudam o usuário a se orientar (primeiros passos, tarefas ambíguas, alterações com riscos maiores).

Exemplo de trecho de prompt da personalidade Amigável do codex-cli

Você pode usar esse trecho no seu prompt de sistema para orientar a personalidade do modelo na programação em par.

# Personality

You optimize for team morale and being a supportive teammate as much as code quality. You communicate warmly, check in often, and explain concepts without ego. You excel at pairing, onboarding, and unblocking others. You create momentum by making collaborators feel supported and capable.

## Values
You are guided by these core values:
* Empathy: Interprets empathy as meeting people where they are - adjusting explanations, pacing, and tone to maximize understanding and confidence.
* Collaboration: Sees collaboration as an active skill: inviting input, synthesizing perspectives, and making others successful.
* Ownership: Takes responsibility not just for code, but for whether teammates are unblocked and progress continues.

## Tone & User Experience
Your voice is warm, encouraging, and conversational. You use teamwork-oriented language such as "we" and "let’s"; affirm progress, and replaces judgment with curiosity. You use light enthusiasm and humor when it helps sustain energy and focus. The user should feel safe asking basic questions without embarrassment, supported even when the problem is hard, and genuinely partnered with rather than evaluated. Interactions should reduce anxiety, increase clarity, and leave the user motivated to keep going.

You are NEVER curt or dismissive.

You are a patient and enjoyable collaborator: unflappable when others might get frustrated, while being an enjoyable, easy-going personality to work with. Even if you suspect a statement is incorrect, you remain supportive and collaborative, explaining your concerns while noting valid points. You frequently point out the strengths and insights of others while remaining focused on working with others to accomplish the task at hand.

## Escalation
You escalate gently and deliberately when decisions have non-obvious consequences or hidden risk. Escalation is framed as support and shared responsibility-never correction-and is introduced with an explicit pause to realign, sanity-check assumptions, or surface tradeoffs before committing.

Pragmático

• Uma abordagem mais concisa, direta e focada em entregar.
• Menos floreios na interação; mais informações práticas por token.
• Mais adequado quando a latência ou a taxa de processamento são importantes, ou quando seus usuários já conhecem o fluxo de trabalho e querem apenas progresso e resultados.

Solução de problemas e criação de metaprompts

Padrões de falha comuns que temos acompanhado especificamente:

• Raciocínio excessivo ou muita demora até a primeira ação útil (chamada de ferramenta ou plano concreto).
• Atualizações de status artificiais, com linguagem de log, em vez de uma colaboração de programação em par.
• Formulações pouco naturais nos preâmbulos e vícios de linguagem repetitivos (“Bem observado”, “Ah”, “Entendi–” etc.).

Criação de metaprompts para correções específicas

Padrões de falha como os mencionados acima geralmente podem ser corrigidos por meio da criação de metaprompts. Ao final de um turno cujo desempenho ficou abaixo do esperado, você pode perguntar ao modelo como melhorar as próprias instruções. O prompt a seguir foi usado para produzir algumas das soluções para os problemas de raciocínio excessivo mencionados acima e pode ser adaptado às suas necessidades.

That was a high quality response, thanks! It seemed like it took you a while to finish responding though. Is there a way to clarify your instructions so you can get to a response as good as this faster next time? It’s extremely important to be efficient when providing these responses or users won’t get the most out of them in time. Let’s see if we can improve!
think through the response you gave above
read through your instructions starting from "" and look for anything that might have made you take longer to formulate a high quality response than you needed
write out targeted (but generalized) additions/changes/deletions to your instructions to make a request like this one faster next time with the same level of quality

Ao criar metaprompts em um contexto específico, é importante gerar respostas algumas vezes, se possível, e prestar atenção aos elementos que elas têm em comum. Algumas melhorias ou alterações propostas pelo modelo podem ser específicas demais para aquela situação, mas muitas vezes é possível simplificá-las para chegar a uma melhoria geral. Recomendamos criar uma avaliação para medir se uma alteração no prompt melhora ou piora os resultados no seu caso de uso.

Alguns exemplos

• Para raciocínio excessivo ou inícios lentos: peça ao modelo que proponha alterações nas instruções para reduzir o tempo até a primeira chamada de ferramenta ou o primeiro plano concreto.
• Para preâmbulos com linguagem excessivamente parecida com a de logs: peça ao modelo que reescreva suas instruções de atualização ao usuário para atender às suas preferências específicas.

Introdução

O GPT-5.2 foi lançado como modelo principal de uso geral, tanto para tarefas gerais quanto agênticas. Em comparação com o GPT-5.1, ele trouxe melhorias em:

• Inteligência geral
• Cumprimento de instruções
• Precisão e eficiência no uso de tokens
• Multimodalidade, especialmente visão
• Geração de código, especialmente criação de interfaces de usuário no front-end
• Chamada de ferramentas e gerenciamento de contexto na API
• Compreensão e criação de planilhas

Diferentemente do modelo anterior, o GPT-5.1, o GPT-5.2 tem novos recursos para gerenciar o que o modelo "sabe" e "lembra", melhorando a precisão.

Este guia aborda os principais recursos da família de modelos GPT-5 e como aproveitar ao máximo o GPT-5.2.

Explore exemplos de programação

Explore alguns aplicativos de demonstração gerados inteiramente com um único prompt, sem escrever código à mão. Esses exemplos foram gerados pelo GPT-5.2 ou pelo nosso modelo principal anterior, o GPT-5.

Explore

Atualizações de modelos, API e recursos

A geração GPT-5.2 inclui gpt-5.2 para tarefas complexas que exigem amplo conhecimento do mundo, gpt-5.2-chat-latest para um comportamento alinhado ao ChatGPT e gpt-5.2-pro para problemas que se beneficiam de mais recursos computacionais.

Para um modelo menor, use gpt-5-mini.

Para escolher o modelo mais adequado ao seu caso de uso, considere estas vantagens e limitações:

Novos recursos do GPT-5.2

Assim como o GPT-5.1, o novo GPT-5.2 tem recursos de API como ferramentas personalizadas, parâmetros para controlar a verbosidade e o raciocínio, além de uma lista de ferramentas permitidas. As novidades da versão 5.2 são o nível de esforço de raciocínio xhigh, resumos concisos de raciocínio e uma nova forma de gerenciar o contexto usando compactação.

Este guia apresenta alguns dos principais recursos da família de modelos GPT-5 e como aproveitar ao máximo a versão 5.2 em particular.

Para tarefas de programação, o GPT-5.2-Codex é nossa variante otimizada para programação em fluxos de trabalho agênticos no Codex ou em ambientes semelhantes.

Menor esforço de raciocínio

O parâmetro reasoning.effort controla quantos tokens de raciocínio o modelo gera antes de produzir uma resposta. Modelos de raciocínio anteriores, como o o3, aceitavam apenas low, medium e high: low priorizava a velocidade e o uso de menos tokens, enquanto high priorizava um raciocínio mais aprofundado.

No GPT-5.2, a configuração mais baixa é none, para oferecer interações com menor latência. Essa é a configuração padrão do GPT-5.2. Se precisar de mais raciocínio, aumente gradualmente até medium e avalie os resultados.

Com o esforço de raciocínio definido como none, a criação de prompts é importante. Para melhorar a qualidade do raciocínio do modelo, mesmo com as configurações padrão, incentive-o a “pensar” ou a descrever suas etapas antes de responder.

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.2",
  input:
    "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  reasoning: {
    effort: "none",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    input="Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
    reasoning={"effort": "none"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-5.2",
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?")},
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortNone},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.NONE).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-5.2",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.None,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem(
        "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    )
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  reasoning: { effort: :minimal },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
        "model": "gpt-5.2",
        "input": "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
        "reasoning": {
                "effort": "none"
        }
}'

Verbosidade

A verbosidade determina quantos tokens de saída são gerados. Reduzir o número de tokens diminui a latência total. Embora a abordagem de raciocínio do modelo permaneça praticamente a mesma, ele encontra formas de responder de maneira mais concisa, o que pode melhorar ou piorar a qualidade da resposta, dependendo do seu caso de uso. Veja alguns cenários para os dois extremos do espectro de verbosidade:

• Verbosidade alta: Use quando precisar que o modelo forneça explicações detalhadas de documentos ou faça uma refatoração extensa de código.
• Verbosidade baixa: Ideal para situações em que você quer respostas concisas ou geração de código para tarefas específicas, como consultas SQL.

O GPT-5 tornou essa opção configurável com os valores high, medium ou low. No GPT-5.2, a verbosidade continua configurável e o valor padrão é medium.

Ao gerar código com o GPT-5.2, os níveis de verbosidade medium e high produzem código mais longo e estruturado, com explicações no próprio código, enquanto o nível low produz código mais curto e conciso, com o mínimo de comentários.

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.2",
  input:
    "What is the answer to the ultimate question of life, the universe, and everything?",
  text: {
    verbosity: "low",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    input="What is the answer to the ultimate question of life, the universe, and everything?",
    text={"verbosity": "low"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.2",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the answer to the ultimate question of life, the universe, and everything?")},
		Text:  responses.ResponseTextConfigParam{Verbosity: responses.ResponseTextConfigVerbosityLow},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseTextConfig;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("Explain the bug and propose a fix.")
        .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  text: { verbosity: :low },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
  "model": "gpt-5.2",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

Você ainda pode ajustar a verbosidade por meio de prompts após defini-la como low na API. O parâmetro de verbosidade define uma faixa geral de tokens no nível do prompt de sistema, mas, dentro dessa faixa, a saída se adapta tanto aos prompts do desenvolvedor quanto aos do usuário.

Como usar ferramentas com o GPT-5.2

O GPT-5.2 foi pós-treinado para usar ferramentas específicas. Consulte a documentação de ferramentas para obter orientações mais específicas.

A ferramenta de aplicar patch

A ferramenta apply_patch permite que o GPT-5.2 crie, atualize e exclua arquivos da 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, permitindo fluxos de trabalho iterativos de edição de código em várias etapas. Leia a documentação.

Internamente, essa implementação usa uma chamada de função de formato livre em vez de um formato JSON. Nos testes, a função nomeada reduziu as taxas de falha de apply_patch em 35%.

Ferramenta de shell

O GPT-5.2 oferece suporte ao shell local. A ferramenta de shell permite que o modelo interaja com seu computador local por meio de uma interface de linha de comando controlada. Leia a documentação para saber mais.

Ferramentas personalizadas

Quando a família de modelos GPT-5 foi lançada, apresentamos um novo recurso chamado ferramentas personalizadas, que permite aos modelos enviar qualquer texto bruto como entrada de uma chamada de ferramenta, mantendo a possibilidade de restringir as saídas. Esse comportamento das ferramentas permanece no GPT-5.2.

Entradas de formato livre

Defina sua ferramenta com type: custom para permitir que os modelos enviem entradas de texto simples diretamente às suas ferramentas, sem se limitar a JSON estruturado. O modelo pode enviar qualquer texto bruto, como código, consultas SQL, comandos de shell, arquivos de configuração ou textos longos em prosa, diretamente à sua ferramenta.

12345{
  "type": "custom",
  "name": "code_exec",
  "description": "Executes arbitrary python code"
}

Como restringir as saídas

O GPT-5.2 oferece suporte a gramáticas livres de contexto (CFGs) para ferramentas personalizadas, permitindo que você forneça uma gramática Lark para restringir as saídas a uma sintaxe ou DSL específica. Anexar uma CFG, por exemplo uma gramática SQL ou DSL, garante que o texto do assistente esteja de acordo com a sua gramática.

Isso permite chamadas de ferramentas precisas e sujeitas a restrições ou respostas estruturadas, além de possibilitar a imposição de formatos sintáticos rígidos ou específicos de um domínio diretamente nas chamadas de função do GPT-5.2, melhorando o controle e a confiabilidade em domínios complexos ou sujeitos a restrições.

Práticas recomendadas para ferramentas personalizadas