Crie uma camada de compatibilidade de API de respostas em um gateway de API de IA
Um gateway da API Responses não é apenas um proxy de conclusões de bate-papo com uma nova rota. Preserve itens de resposta, estado, chamadas de ferramentas, fluxos, continuidade de raciocínio, atribuição de uso e comportamento de downgrade com uma camada de compatibilidade de primeira classe.
Não implemente /v1/responses traduzindo cada solicitação em /v1/chat/completions e esperando que a forma esteja próxima o suficiente. Esse adaptador pode retornar texto, mas pode perder silenciosamente as partes com as quais os desenvolvedores se preocupam: itens de resposta, estado do servidor, chamadas de ferramentas, continuidade de raciocínio, eventos de ciclo de vida de fluxo, semântica de cancelamento e atribuição de uso em nível de item.
O objetivo prático é uma camada de compatibilidade que trate a API Responses como um protocolo mais rico. Mantenha o suporte de conclusões de bate-papo para clientes existentes, mas crie respostas como sua própria superfície de gateway com seu próprio modelo de estado, normalizador de fluxo, registro de chamadas de ferramenta, matriz de capacidade e regras de fallback.
O que é factual, o que é política e o que é previsão?
Fatos: a OpenAI descreve a API Responses como recursos unificadores que antes eram divididos entre completações de bate-papo e assistentes, incluindo suporte para ferramentas como pesquisa na Web, pesquisa de arquivos e uso de computador. A API expõe campos como previous_response_id, streaming, seleção de ferramentas e ferramentas integradas. A documentação do SDK mostra que previous_response_id pode fornecer continuidade de conversação, enquanto as instruções anteriores não são transportadas automaticamente e devem ser reenviadas quando ainda devem ser aplicadas. A referência de streaming da OpenAI inclui ciclo de vida de resposta e eventos de saída distintos, em vez de apenas deltas de token.
Recomendações: um gateway deve preservar essas semânticas em vez de simplificá-las por padrão. Ele deve rejeitar ou fazer downgrade explicitamente de solicitações quando um provedor de destino não puder oferecer suporte ao comportamento exigido.
Previsão: mais cargas de trabalho do agente dependerão da estrutura do item de resposta, dos rastreamentos de execução da ferramenta e do contexto de raciocínio com estado. Os gateways que modelam esses conceitos agora serão mais fáceis de estender do que os gateways que tratam as respostas como um ponto final cosmético.
Definir um contrato de compatibilidade separado para respostas
O primeiro erro de implementação é presumir que compatibilidade com OpenAI significa um esquema universal de solicitação e resposta. Na prática, /v1/chat/completions e /v1/responses devem ser contratos de compatibilidade separados.
Mantenha uma camada compartilhada de autenticação, cobrança, cota e roteamento, mas separe a camada de protocolo:
- Superfície de conclusões de bate-papo: mensagens, escolhas, deltas, chamadas de ferramentas em formato de bate-papo, comportamento legado do cliente.
- Superfície de respostas: itens de entrada, itens de saída, IDs de resposta, referências de respostas anteriores, eventos de ferramentas mais avançados, eventos de fluxo de ciclo de vida, campos relacionados ao raciocínio e estado final da resposta.
Esta divisão é importante para testes de conformidade. Um adaptador de provedor que passa nos testes de bate-papo ainda pode falhar nos testes de respostas porque não pode preservar previous_response_id, ordem de itens, estrutura de recusa, metadados de ferramentas hospedadas ou nomes de eventos de streaming.
Um contrato de compatibilidade mínima deve responder:
- Quais campos de solicitação são aceitos, rejeitados, transformados ou ignorados?
- Quais tipos de itens de resposta são preservados?
- Quais tipos de ferramentas são compatíveis com cada fornecedor e modelo?
- O provedor pode manter o estado de conversação ou o gateway deve mantê-lo?
- O que acontece quando
store=falseé solicitado? - Quais eventos de transmissão são garantidos?
- Como são registrados o cancelamento, o tempo limite e o uso parcial?
Se você já tem um gateway da AI API, trate o suporte do Responses como uma expansão de protocolo, não como um alias de rota.
Use um modelo de item de resposta canônico
A API Responses retorna mais de uma mensagem do assistente. Ele pode representar diferentes itens e eventos de saída. Seu gateway precisa de um modelo canônico interno antes de ser mapeado para qualquer provedor.
Um esquema de item interno prático pode começar assim:
Inclua os tipos de itens antes mesmo que cada fornecedor possa produzi-los. As categorias úteis incluem:
- Saída de texto
- Recusas
- Chamadas de função
- Saídas de função enviadas pelo aplicativo
- Resumos de raciocínio ou metadados relacionados ao raciocínio, quando disponíveis
- Referências de arquivo
- Pesquisa na Web, pesquisa de arquivos, uso do computador ou outros eventos de ferramentas hospedadas
- Metadados finais de uso e cobrança
O objetivo não é expor um esquema proprietário aos usuários. O objetivo é evitar que o gateway jogue fora informações antes de poder auditar, cobrar, transmitir, reproduzir ou transformá-las.
Crie um livro-razão estadual de propriedade do gateway
previous_response_id é o campo que mais expõe a diferença entre proxy de bate-papo sem estado e compatibilidade de respostas. Se um cliente fizer referência a uma resposta anterior, o gateway deverá saber o que esse ID significa, se o locatário tem permissão para usá-lo e se o provedor pode continuar a partir dele.
Crie um livro-razão estadual digitado por inquilino e ID de resposta:
Regra importante: não emule automaticamente previous_response_id reproduzindo o histórico completo do chat, a menos que o locatário tenha permitido explicitamente esse comportamento de retenção e custo. A repetição pode aumentar o custo do token, alterar a postura de privacidade e alterar o comportamento do modelo. É mais seguro retornar um erro de capacidade claro do que enviar silenciosamente o conteúdo da conversa armazenada que o aplicativo não esperava que você retivesse ou reutilizasse.
Modos de tratamento de estado
- Estado do provedor: o provedor upstream armazena contexto suficiente e o gateway mapeia IDs de resposta do gateway para IDs de resposta do provedor.
- Estado do gateway: o gateway armazena os itens anteriores necessários e reconstrói o contexto quando permitido.
- Sem estado: a solicitação usa
store=falseou a política do locatário proíbe a retenção.previous_response_iddeve ser rejeitado, a menos que o provedor possa honrar a solicitação sem retenção do gateway e a política permita isso.
Lembre-se também de que as instruções anteriores podem precisar ser reenviadas pelo cliente quando continuarem a ser aplicadas. O gateway não deve inventar instruções ocultas para compensar, a menos que esse comportamento faça parte de uma política explícita do locatário.
Validar ferramentas antes do envio
As respostas tornam o uso da ferramenta mais centralizado. Uma camada de compatibilidade deve lidar com duas categorias amplas:
- Ferramentas de aplicação: definições de funções fornecidas pelo cliente, executadas fora do provedor de modelo, com saídas enviadas de volta à API.
- Ferramentas do provedor hospedado: pesquisa na Web, pesquisa de arquivos, uso de computador, execução de código, aterramento ou ferramentas semelhantes executadas pelo provedor ou infraestrutura controlada por gateway.
Na entrada, valide os esquemas da ferramenta antes do roteamento:
- Rejeite antecipadamente o esquema JSON inválido.
- Aplicar tamanho máximo de esquema e profundidade de aninhamento.
- Verifique os nomes das ferramentas para verificar a compatibilidade do provedor.
- Aplique escopos de locatário, chave, usuário e ambiente.
- Exigir portas de aprovação para ferramentas que gravam dados, gastam dinheiro, acessam sistemas confidenciais ou chamam conectores externos.
Para chamada de função de aplicativo, exija um ID de chamada estável. O modelo emite uma chamada de função com call_id; o aplicativo envia a saída da ferramenta referenciando esse ID; o gateway registra ambos no mesmo rastreamento. Sem essa chave de junção, os registros de auditoria e as novas tentativas tornam-se ambíguos.
Para ferramentas hospedadas, reserve o orçamento antes do envio e liquide os custos depois. As ferramentas hospedadas podem adicionar cobranças fora da contabilidade de token comum, portanto, conecte o livro-razão da ferramenta ao faturamento unificado da API de IA em vez de ocultar esses custos dentro de um total genérico de chamada de modelo.
Normalizar o streaming como eventos, não como texto simbólico
Um proxy de bate-papo geralmente consegue encaminhar deltas de token. Um gateway de respostas não pode. O fluxo tem significado de ciclo de vida: uma resposta pode começar, os itens de saída podem começar e ser concluídos, o texto pode chegar em deltas, as chamadas de ferramenta podem ser montadas de forma incremental, o uso pode chegar no final ou durante o fluxo e a resposta pode falhar ou ser cancelada.
Defina um esquema de evento de gateway e mapeie cada fluxo de provedor nele:
evento: resposta_iniciada
dados: { "response_id": "gw_resp_123", "status": "in_progress" }
evento: output_item_starteddados: { "item_id": "item_1", "tipo": "texto" }
evento: text_delta
dados: { "item_id": "item_1", "delta": "Olá" }
evento: tool_call_delta
dados: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"pedido" }
evento: uso_delta
dados: { "output_tokens": 12 }
evento: concluído
dados: { "response_id": "gw_resp_123", "usage": { ... } }
Eventos normalizados recomendados:
response_startedoutput_item_startedoutput_item_completedtext_deltarecusa_deltatool_call_deltatool_result_receivedusage_deltaconcluídocanceladofalhou
Quando o cliente se desconectar, propague o cancelamento upstream se o provedor oferecer suporte. Registre o estado da resposta parcial de qualquer maneira. Se o provedor retornar posteriormente o uso final por meio de um retorno de chamada atrasado ou parte final, reconcilie o razão. A compatibilidade de streaming tem tanto a ver com contabilidade e ciclo de vida quanto com latência.
Crie uma matriz de capacidade do provedor
O roteamento multimodelo é útil somente quando o gateway entende o que pode ser roteado com segurança. Adicione recursos específicos de respostas ao seu catálogo de modelos:
O substituto deve ter reconhecimento de perdas. Se a solicitação exigir pesquisa na Web integrada e o provedor substituto não puder realizá-la, não responda silenciosamente sem pesquisar. Se a solicitação depender do contexto de raciocínio preservado e a rota substituta não puder preservá-la, retorne um erro de capacidade ou uma resposta de downgrade que o cliente optou explicitamente.
Uma opção de solicitação útil é:
Para casos de uso menos sensíveis, os locatários podem permitir downgrades específicos com perdas:
O gateway deve registrar a decisão de fallback de qualquer maneira. Isso torna possível a depuração posterior quando um agente se comporta de maneira diferente após uma interrupção do provedor ou um novo roteamento do modelo.
Uso de atributos em nível de resposta e item
As chamadas de resposta podem custar mais do que as conclusões de bate-papo equivalentes porque podem incluir execução de ferramenta, contexto mais longo, tokens de raciocínio, pesquisa de arquivos, pesquisa na Web ou instruções repetidas. Uma única contagem agregada de tokens não é suficiente para um painel de análise de uso da API AI.
Registre o uso em dois níveis:
- Nível de resposta: locatário, chave, usuário, modelo, provedor, latência, status final, tokens de entrada, tokens de saída, tokens de raciocínio quando relatados, custo total e rota de fallback.
- Nível do item/ferramenta: nome da ferramenta, ID da chamada, unidades de ferramentas hospedadas, IDs de arquivos, contagem de consultas de pesquisa, se disponível, latência da ferramenta, custo da ferramenta e resultado da política de aprovação.
Isso permite que os desenvolvedores respondam a perguntas concretas:
- O custo aumentou devido a um estado mais longo, esforço de raciocínio, chamadas de ferramentas ou substitutos?
- Qual locatário ou chave de API está gerando cobranças de ferramentas hospedadas?
- Qual resposta falhou após uma chamada de ferramenta, mas antes do texto final?
- Quais transmissões canceladas ainda geraram uso de upstream?
Trate a retenção e exclusão zero como um comportamento de primeira classe
O estado do lado do servidor é útil, mas altera as obrigações de retenção do gateway. Crie políticas na camada de protocolo em vez de tratá-las como uma configuração de registro.
Para cada solicitação de respostas, resolva:
- Política de retenção de locatários
- Preferência de
lojaem nível de solicitação - Compatibilidade de retenção do provedor
- Se a reprodução do gateway é permitida
- Se as entradas e saídas da ferramenta podem ser armazenadas
- Comportamento de expiração e exclusão do estado de resposta
Se a retenção estiver desabilitada, o gateway ainda poderá manter metadados operacionais mínimos: carimbos de data/hora, IDs, status, contagens de tokens, custos e decisões políticas. Evite armazenar prompts brutos, resultados completos da ferramenta ou histórico reconstruído, a menos que a política permita.
Acessórios de conformidade a serem adicionados antes do lançamento
Não confie em testes manuais de caminho feliz. Adicione acessórios que verificam o comportamento do protocolo em rotas OpenAI diretas, rotas adaptadas pelo provedor e cenários de fallback.
Conjunto mínimo de testes
- Resposta básica: o item de texto é retornado com ID de resposta e uso estáveis.
- Estado multiturno: a segunda solicitação faz referência a
previous_response_id; o gateway valida a propriedade do locatário e o modo de estado. - Instruções repetidas: verifique se as instruções omitidas não são inventadas silenciosamente pelo gateway.
- Ida e volta da chamada de função: o modelo emite o ID da chamada; o aplicativo envia a saída; a resposta final une os dois registros.
- Política de ferramenta hospedada: a ferramenta integrada não autorizada é bloqueada antes do envio.
- Ordem de streaming: início da resposta, início do item, deltas, conclusão do item, uso e conclusão são emitidos em ordem válida.
- Cancelamento de stream: a desconexão do cliente aciona o cancelamento do upstream onde há suporte e registra o uso parcial.
- Rejeição de fallback: provedor sem semântica de respostas obrigatórias retorna erro de capacidade.
- Ativação de fallback com perdas: a solicitação com perdas permitidas recebe um marcador de downgrade explícito.
- Modo de retenção zero: a reprodução do estado e a retenção de prompt do lado do gateway são bloqueadas.
Sequência de implementação recomendada
- Exponha uma rota beta. Adicione
/v1/responsessem alterar o comportamento de bate-papo existente. - Implemente primeiro a passagem para provedores com suporte nativo a respostas. Preserva IDs, itens, fluxos, uso e erros.
- Adicione o razão do estado. Mapeie IDs de gateway para IDs de provedores e imponha a propriedade do locatário.
- Adicione itens canônicos. Armazene metadados de itens necessários para auditoria, faturamento e reconstrução de fluxo.
- Adicione governança de ferramentas. Valide esquemas, aplique escopos e registre junções de chamadas de ferramentas.
- Adicione normalização de streaming. Converta streams específicos do provedor em eventos do ciclo de vida do gateway.
- Adicione roteamento com reconhecimento de capacidade. Permita apenas substitutos seguros por padrão.
- Adicione análises e liquidação de faturamento. Atribua token, raciocínio e uso de ferramentas separadamente.
- Publique notas de compatibilidade. Informe aos desenvolvedores quais campos são nativos, emulados, sem suporte ou com perdas.
Conclusão acionável
Uma camada de compatibilidade da API Responses deve preservar o significado do protocolo, e não apenas retornar um texto plausível. Construa-o em torno de cinco objetos duráveis: um modelo de item de resposta canônico, um livro-razão de estado de conversação, um livro-razão de chamadas de ferramenta, um normalizador de eventos de streaming e uma matriz de capacidade do provedor.
O padrão mais seguro é a compatibilidade estrita: se uma rota não puder preservar o estado, as ferramentas, o contexto de raciocínio, os eventos de fluxo ou o comportamento de retenção necessários, retornará um erro de capacidade claro. Adicione substituto com perdas de aceitação somente quando os desenvolvedores entenderem o que será descartado. Essa abordagem pode parecer menos conveniente do que o nivelamento automático, mas evita o pior modo de falha: um aplicativo que parece compatível enquanto perde silenciosamente a semântica que o fez usar a API Responses.