GPT-6.2 Responses API: não edite o prefixo ou perca o raciocínio

A partir de GPT-6.2 Astra e Sol, editar o histórico anterior na Responses API descarta os itens de raciocínio seguintes. Mantenha o prefixo inalterado com turnos append-only, configuration_update, additional_tools e instruções na primeira mensagem developer, e valide com input_transformations e Prompt Cache Diagnostics.

Conteúdo
GPT-6.2 Responses API: não edite o prefixo ou perca o raciocínio

A partir de gpt-6.2-astra e gpt-6.2-sol, a OpenAI Responses API descarta itens de raciocínio após uma edição do prefixo no meio da conversa, um downgrade de modelo ou uma alteração de organização ou usuário final. Isso afeta todo desenvolvedor e toda equipe de agentes cujo código reescreve mensagens developer anteriores, corta resultados de ferramentas passados ou altera parâmetros de nível superior como reasoning.effort e tools entre turnos. Migre sua integração para um histórico input somente de acréscimo (append-only), use configuration_update e additional_tools para mudanças no meio da conversa e verifique input_transformations em cada resposta para confirmar que nenhum raciocínio saiu do contexto.

Escolha uma rota para chamadas GPT-6.2 na Responses API

GPT-6.2 Astra e Sol aceitam Chat Completions para texto, mas chamadas de ferramentas exigem a Responses API, e os controles de preservação de prefixo (configuration_update, additional_tools e input_transformations) existem apenas na Responses API. Escolha uma rota de API que exponha POST /v1/responses e combine com seu acesso e cobrança.

RotaRequisitosUnidade de cobrançaObservações da Responses APIQuando escolher
Gateway de API BetterTokenConta BetterToken, API Key do console e saldo para cobrança conforme o uso (o saldo pago adquirido não zera todo mês)Pela unidade de cobrança atual do modelo (tokens de entrada, saída e cache podem ter preços e regras distintos); veja os preços atuaishttps://www.bettertoken.ai/v1 (POST /v1/responses) lista gpt-6.2-astra e gpt-6.2-sol; teste antes com sua chave o replay sem estado com store: false e o repasse de configuration_update e input_transformationsQuando você quer acessar os modelos disponíveis com uma única API Key, com o uso cobrado do saldo, ou não consegue usar a cobrança direta da OpenAI
OpenAI API diretaConta OpenAI em país ou território compatível e cobrança de APIPor 1M de tokens de entrada, entrada em cache, escrita em cache e saídaDocumenta suporte nativo para configuration_update, input_transformations, prompt_cache_diagnostics, previous_response_id, janelas de conclusão em segundo plano e Zero Data Retention (ZDR) no nível da organizaçãoQuando você tem acesso direto à OpenAI e depende de estado hospedado na OpenAI, ZDR ou recursos beta documentados

Verifique o replay append-only e a detecção de prefixo na BetterToken

A BetterToken oferece uma rota de API compatível com OpenAI em https://www.bettertoken.ai/v1 (POST /v1/responses), autenticada com sua API Key do console da BetterToken. Em 2026-11-21, gpt-6.2-sol e gpt-6.2-astra constam como disponíveis no endpoint Responses. A BetterToken é uma plataforma multimodelo e camada de acesso via API, não um produto oficial da OpenAI. Sua referência da Responses API não verifica o repasse do replay criptografado sem estado com store: false, nem de configuration_update, input_transformations ou prompt_cache_diagnostics. Execute esta checagem controlada de dois turnos sem estado na sua chave antes de publicar em produção.

Exporte sua chave da BetterToken no Bash sem exibi-la no terminal:

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY

Envie o turno 1 com store: false e confirme que a resposta devolve pelo menos um item reasoning com encrypted_content. Em seguida, compare duas chamadas sem estado no turno 2: a chamada append_only reenvia o histórico anterior sem alterações, enquanto a chamada edited_control modifica apenas a primeira mensagem developer:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://www.bettertoken.ai/v1",
    timeout=120.0,
    max_retries=0,
)

model = "gpt-6.2-sol"  # Or "gpt-6.2-astra"
history = [
    {"role": "developer", "content": "You are a backend reviewer. Give concise engineering answers."},
    {"role": "user", "content": "Draft a two-step plan to add a non-blocking index on PostgreSQL."},
]

first = client.responses.create(
    model=model,
    store=False,
    reasoning={"effort": "low"},
    input=history,
)
reasoning_items = [item for item in first.output if item.type == "reasoning"]
if not reasoning_items:
    raise RuntimeError("Turn 1 returned no reasoning items; use a harder prompt or higher effort.")
if not all(getattr(item, "encrypted_content", None) for item in reasoning_items):
    raise RuntimeError("Stateless replay unverified: Turn 1 reasoning items lack encrypted_content.")

reasoning_ids = [item.id for item in reasoning_items]
first_output = [item.to_dict() for item in first.output]
follow_up = {"role": "user", "content": "List the failure modes and rollback steps for step 2."}

append_only = client.responses.create(
    model=model,
    store=False,
    reasoning={"effort": "low"},
    input=[*history, *first_output, follow_up],
)

edited_history = [{**history[0], "content": history[0]["content"] + " Be brief."}, history[1]]
edited_control = client.responses.create(
    model=model,
    store=False,
    reasoning={"effort": "low"},
    input=[*edited_history, *first_output, follow_up],
)

print("reasoning_ids:", reasoning_ids)
print("append_only:", append_only.status, getattr(append_only, "input_transformations", None))
print("edited_control:", edited_control.status, getattr(edited_control, "input_transformations", None))
print("append_only_cached_tokens:", append_only.usage.input_tokens_details.cached_tokens)

Analise quatro sinais antes de colocar o código em produção:

  • status == "completed" confirma apenas que a API aceitou e concluiu a requisição. Isso não prova que o gateway preservou o raciocínio entre turnos.
  • Confirme que a lista reasoning_ids montada pelo script a partir de first.output no turno 1 com store: false não está vazia e que cada item de raciocínio retornado pela API traz encrypted_content. Se o gateway omitir encrypted_content, trate o replay sem estado como não verificado, pois o turno 2 não consegue levar tokens de raciocínio criptografados entre upstreams diferentes.
  • Compare input_transformations nas duas chamadas do turno 2. Um repasse verificado traz uma entrada prefix_mismatch com um ID presente em reasoning_ids na resposta edited_control e nenhuma entrada em append_only. Se input_transformations vier None ou vazio nos dois testes, considere a verificação inconclusiva, porque o gateway pode não repassar esse campo.
  • Teste o repasse de configuration_update separadamente do teste de prefixo. Você pode conferir uma atualização de text.format enviando outra requisição de turno 2 que altere text.format para um JSON Schema estrito e checando se a saída segue esse esquema. A OpenAI não documenta nenhum campo de resposta que confirme uma atualização de reasoning.effort no meio da conversa (o campo reasoning.effort da resposta continua exibindo o valor do nível da requisição), portanto trate configuration_update para reasoning.effort como não verificado via BetterToken.

Para prompt caching, a OpenAI define um prefixo mínimo armazenável em cache de 1,024 tokens de entrada visíveis no GPT-5.6 e modelos posteriores como condição de elegibilidade. Observe append_only.usage.input_tokens_details.cached_tokens para medir a reutilização real quando seu prefixo reutilizável tiver pelo menos 1,024 tokens de entrada visíveis. Consulte os preços atuais para conferir as tarifas do modelo e as regras de cache antes de escalar.

Se preferir chamar a OpenAI diretamente, remova base_url, use OPENAI_API_KEY e siga o guia Keep the prefix unchanged da OpenAI.

Criar uma conta na BetterToken

O que conta como alteração de prefixo no GPT-6.2

O prefixo de um item de raciocínio é todo o histórico de conversa renderizado antes dele. No GPT-6.2, modificar esse histórico anterior faz a API descartar os itens de raciocínio que vêm depois da edição.

A OpenAI documenta duas categorias de alterações de prefixo:

  • Editar itens anteriores em input: encurtar o resultado de uma ferramenta, reescrever uma mensagem developer, reduzir o tamanho de imagens ou arquivos antigos ou substituir turnos anteriores por um resumo.
  • Alterar parâmetros no nível da requisição entre turnos: atualizar tools (adicionar, remover, reordenar ou editar esquemas e descrições), mudar text.format, mudar o reasoning.effort no nível superior ou alterar instructions em modelos anteriores ao GPT-6.2.

Segundo o guia Reasoning da OpenAI, prefix_mismatch ocorre no GPT-6.2 e versões seguintes quando você insere ou edita conteúdo antes de um item de raciocínio. Apagar itens inteiros sem editar os itens restantes, ou acrescentar itens após o item de raciocínio, não dispara prefix_mismatch por si só. Ainda assim, remover turnos antigos pode reduzir a reutilização do prompt cache, e o Prompt Cache Diagnostics pode relatar input_changed quando essa remoção impede o reaproveitamento.

Edições de prefixo formam um dos cinco motivos de remoção relatados em input_transformations:

reason da remoçãoQuando a API remove o item de raciocínio
prefix_mismatchNo GPT-6.2 e posteriores, houve inserção ou edição de conteúdo antes do item de raciocínio
end_user_mismatchNo GPT-6.2 e posteriores, safety_identifier difere entre a requisição que criou o item e a que o reutiliza, inclusive quando aparece em apenas uma das duas
model_mismatchVocê trocou de família de modelos ou fez downgrade dentro da mesma família (um upgrade dentro da mesma família preserva o raciocínio compatível se as demais checagens passarem)
organization_mismatchVocê reutilizou um item de outra organização ou de outro workspace sob outro usuário
turn_boundaryO item pertence a qualquer turno anterior enquanto o modelo usa apenas o raciocínio do turno atual (reasoning.context controla a elegibilidade nos modelos compatíveis)

O que acontece quando a API descarta itens de raciocínio

Uma requisição à Responses API pode terminar com sucesso mesmo quando a API remove itens de raciocínio da entrada do modelo, então essa perda passa despercebida se você não conferir input_transformations na resposta. Editar o prefixo no meio da conversa gera dois efeitos separados em produção:

  1. Impacto do raciocínio descartado: quando a API remove itens de raciocínio, o modelo pode precisar refazer parte do raciocínio anterior, o que pode aumentar o uso de tokens, o custo e a latência. Se o modelo não recuperar o raciocínio perdido, a qualidade da resposta também pode cair.
  2. Impacto na quebra do prefixo em cache: como o prompt caching compara as requisições a partir do início, editar o prefixo pode interromper a reutilização do cache desse ponto em diante, o que pode elevar os custos de entrada e deixar as respostas mais lentas.

As tarifas Standard da OpenAI consultadas em 2026-11-21 (para até 272,000 tokens de entrada) mostram o custo que falhas de cache podem acumular:

  • GPT-6.2 Astra (gpt-6.2-astra): $0.40/1M na entrada em cache contra $8/1M na entrada sem cache ($10/1M para escrita em cache de 30 minutos, $20/1M para escrita em cache de 12 horas) e $40/1M na saída.
  • GPT-6.2 Sol (gpt-6.2-sol): $0.10/1M na entrada em cache contra $2/1M na entrada sem cache ($2.50/1M para escrita em cache de 30 minutos, $5/1M para escrita em cache de 12 horas) e $10/1M na saída.

Acima de 272,000 tokens de entrada, a OpenAI dobra as tarifas de entrada e cache e cobra 1.5x a tarifa de saída de contexto curto para toda a requisição. Para decidir quando escritas de 12 horas compensam em prefixos estáveis, veja nosso guia de prompt caching de 12 horas da OpenAI.

Atualize parâmetros e contexto sem quebrar o prefixo

Troque edições no histórico existente por itens acrescentados ao final para manter o raciocínio e os prefixos em cache intactos entre turnos.

Altere reasoning.effort e text.format com configuration_update

Alterar reasoning.effort no nível superior pode reescrever instruções ocultas de sistema. Nos modelos GPT-6 e posteriores compatíveis no modo padrão de agente único, mantenha reasoning.effort e text.format inalterados no topo da requisição e acrescente um item configuration_update a input antes da próxima mensagem do usuário:

{
  "type": "configuration_update",
  "reasoning": {
    "effort": "high"
  },
  "text": {
    "format": {
      "type": "json_schema",
      "name": "migration_checks",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "safe": { "type": "boolean" },
          "rollback_sql": { "type": "string" }
        },
        "required": ["safe", "rollback_sql"],
        "additionalProperties": false
      }
    }
  }
}

Siga cinco regras ao usar configuration_update:

  • Um configuration_update continua valendo nos turnos seguintes até outra atualização substituí-lo. Atualizar apenas reasoning.effort preserva uma mudança anterior de text.format, e vice-versa.
  • O campo reasoning.effort no objeto de resposta continua relatando o valor do nível da requisição, e não o esforço atualizado.
  • Leve as atualizações adiante com previous_response_id, ou reenvie cada configuration_update em sua posição original quando gerenciar input manualmente.
  • O truncamento automático e o endpoint avulso /responses/compact rejeitam históricos que contenham itens configuration_update. Use context_management ou compaction_trigger (veja a seção de compactação abaixo).
  • Tanto gpt-6.2-astra quanto gpt-6.2-sol rejeitam reasoning.effort: "none". O guia Using GPT-6.2 da OpenAI recomenda começar com medium, ou usar low no lugar de none e minimal.

Adicione ou restrinja ferramentas sem alterar tools

Mantenha o array tools, os esquemas e a ordem no nível da requisição idênticos entre turnos. Ajuste as ferramentas disponíveis com três padrões seguros para o prefixo:

  • Defina tool_choice como "none" para desativar ferramentas em um turno sem remover tools.
  • Use tool_choice com allowed_tools para restringir quais ferramentas o modelo pode chamar em um turno:
{
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "get_weather" },
      { "type": "function", "name": "search_docs" }
    ]
  }
}
  • Acrescente um item additional_tools com papel developer para adicionar ferramentas no meio da conversa, ou use tool search com defer_loading: true para anexar as ferramentas descobertas ao final do contexto. As ferramentas dentro de additional_tools ficam disponíveis apenas após a posição desse item, então reenvie-o no mesmo lugar:
{
  "type": "additional_tools",
  "role": "developer",
  "tools": [
    {
      "type": "function",
      "name": "get_customer",
      "description": "Look up a customer by ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    }
  ]
}

Separe mensagens developer reutilizáveis de instructions no nível superior

A partir do GPT-6.2, a OpenAI anexa o campo superior instructions depois de input, além dos pontos elegíveis para cache. A OpenAI cobra esses tokens na tarifa de entrada sem cache em toda requisição mesmo que não mudem, e previous_response_id não carrega instructions de um turno para outro.

Organize as instruções conforme o escopo:

  • Coloque prompts de sistema reutilizáveis e políticas compartilhadas em uma mensagem developer como o primeiro item de input para permitir reaproveitamento no prompt caching.
  • Acrescente uma nova mensagem developer ao final de input ao atualizar instruções reutilizáveis no meio da conversa, em vez de editar a primeira.
  • Use o campo superior instructions apenas para orientações válidas somente na requisição atual.

Lide com compactação e saídas longas de ferramentas

Encurte saídas extensas de ferramentas e reduza imagens ou arquivos antes de enviá-los ao modelo pela primeira vez. Não corte itens antigos de forma retroativa.

A compactação altera o prefixo, o que dificulta evitar falhas de cache nesses turnos. Para sessões longas, o guia Compaction da OpenAI documenta dois caminhos:

  • Compactação automática (context_management com compact_threshold): a OpenAI mantém os itens de raciocínio seguintes apesar da mudança no prefixo. Se turnos anteriores contiverem configuration_update, a API emite um novo configuration_update logo após o item compaction e guarda as declarações de additional_tools dentro do item criptografado de compactação. Reenvie os itens de saída na mesma ordem.
  • Compactação explícita ou personalizada: o endpoint avulso /responses/compact rejeita históricos com configuration_update; ao chamar /responses/compact, omita instructions e passe a janela retornada na ordem original. Se o histórico usar configuration_update, inclua um item compaction_trigger em /responses e depois adicione um novo configuration_update repetindo cada campo alterado antes da próxima mensagem do usuário. Na compactação personalizada, coloque o resumo compactado no final do contexto em vez de substituir turnos antigos no meio, ou aceite o descarte dos itens de raciocínio.

Verifique a preservação do prefixo com input_transformations e Prompt Cache Diagnostics

Combine duas verificações na resposta: uma lista quais itens de raciocínio a API removeu da entrada do modelo, e a outra identifica o que quebrou o reaproveitamento do prompt cache.

1. Inspecione input_transformations em cada resposta

Na referência de criação da Responses API, input_transformations é um array opcional de objetos {id, action, reason, type} que lista, na ordem da entrada, os itens de raciocínio removidos da entrada do modelo (action é "removed" e type é "reasoning"). Quando reason for "prefix_mismatch", compare esse id com o item de raciocínio no output da resposta anterior que o retornou para localizar qual edição ocorreu antes dele.

2. Execute o Prompt Cache Diagnostics com comparison_response_id

Para entender por que usage.input_tokens_details.cached_tokens ficou abaixo do esperado, escolha uma resposta concluída recente da mesma organização, informe o id dela em prompt_cache_options.comparison_response_id e inspecione prompt_cache_diagnostics:

{
  "prompt_cache_diagnostics": {
    "type": "cache_miss",
    "reason": "tools_changed",
    "comparison_reusable_tokens": 5629,
    "cache_missed_tokens": 5629
  }
}

O guia Prompt cache diagnostics da OpenAI retorna prompt_cache_diagnostics.type como cache_hit, cache_miss, comparison_response_not_found ou unavailable. Em caso de cache_miss, o objeto traz reason e cache_missed_tokens (estimativa de tokens não reutilizados) e pode incluir comparison_reusable_tokens (contagem bruta de tokens do prefixo reutilizável da resposta de referência). O campo reason classifica a falha:

  • input_changed: a entrada anterior mudou, por exemplo ao inserir um timestamp ou ID de requisição em uma mensagem developer, ou ao editar, reordenar ou remover turnos antigos.
  • tools_changed: ferramentas foram adicionadas, removidas, reordenadas ou editadas.
  • reasoning_effort_changed ou text_format_changed: o campo superior reasoning.effort ou text.format mudou em vez de usar configuration_update.
  • model_changed, service_tier_changed, verbosity_changed, prompt_cache_key_changed ou context_compacted: houve mudança de modelo, service tier, verbosidade, chave de cache ou compactação.

Leve em conta cinco limites do diagnóstico: ele exige GPT-5.6 ou posterior e um prefixo reutilizável de pelo menos 1,024 tokens; relata apenas a primeira causa classificada que consegue identificar e pode não encontrar nenhuma; não gera custo extra e funciona com Zero Data Retention; com stream=True, leia prompt_cache_diagnostics em event.response dentro do evento response.completed; e o diagnóstico não comprova se o modelo reutilizou o raciocínio.

Observe estes detalhes em APIs personalizadas e gateways

Equipes que roteiam o GPT-6.2 por uma URL base personalizada ou por um gateway com vários upstreams devem conferir quatro pontos:

  1. Chame POST /v1/responses, não Chat Completions: GPT-6.2 Astra e Sol suportam Chat Completions para texto, mas chamadas de ferramentas, configuration_update, additional_tools e input_transformations exigem Responses. Para uma lista básica de migração, veja nosso guia de migração do GPT-6 Astra na Responses API.
  2. Reenvie o array input append-only completo em vez de depender apenas de previous_response_id: o roteamento inteligente da BetterToken envia requisições para os canais upstream disponíveis no momento, e um modelo com vários upstreams configurados pode fazer failover em caso de erro aplicável ou timeout (nem todo modelo possui vários upstreams, nem todo erro aciona failover e o sucesso não é garantido). O replay sem estado evita depender de estado mantido em um único upstream. Na API da OpenAI, Zero Data Retention (ZDR) é uma configuração no nível da organização para organizações aprovadas em endpoints e recursos elegíveis, distinta de definir store como false em uma requisição. Em ambos os modos sem estado (store: false ou organização com ZDR ativo, onde a OpenAI trata store como false), os itens de raciocínio em output incluem encrypted_content por padrão. A OpenAI ainda aceita o valor legado include: ["reasoning.encrypted_content"] por compatibilidade, mas não o exige. Reenvie todos os itens de output na ordem, mantenha safety_identifier idêntico entre turnos (ou omita-o em todos) para evitar end_user_mismatch e monitore organization_mismatch em input_transformations.
  3. Omita parâmetros de amostragem não suportados: nas chamadas Responses para gpt-6.2-astra e gpt-6.2-sol, omita os parâmetros de nível superior temperature, top_p e top_logprobs, e remova apenas message.output_text.logprobs de include.
  4. Restrinja janelas de conclusão em segundo plano às chamadas diretas à OpenAI: na Responses API da OpenAI, GPT-6.2 Astra e Sol não suportam service_tier: "flex". Para tarefas longas enviadas diretamente à API da OpenAI, use as janelas de conclusão de 2 horas ou 8 horas do modo em segundo plano (beta público), detalhadas em nosso guia de completion_window na Responses API. Janelas de conclusão em segundo plano não estão verificadas na documentação pública da Responses API da BetterToken, portanto teste ou roteie diretamente para a OpenAI se sua carga de trabalho depender delas.

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.

Começar grátis