Responses API vs Chat Completions para Agentes: Escolhendo um Contrato

Para cargas de trabalho de agentes, a Responses API é a melhor opção padrão: ela oferece estado de conversação no lado do servidor via previous_response_id, itens de saída tipados em vez de um único blob de mensagem e eventos de streaming semânticos. Esses recursos reduzem o trabalho de gerenciamento que sua camada de orquestração teria que assumir. A Chat Completions continua sendo uma escolha válida quando você deseja controle total sobre o histórico de mensagens ou está integrando com ferramentas construídas em torno do formato de mensagem de chat da OpenAI, mas para agentes de chamada de ferramenta (tool-calling) de múltiplos turnos, a Responses é a escolha mais direta.

Ambos os endpoints estão documentados nas páginas de referência de modelos atuais para GPT-5.6 e GPT-5.5, e o contrato compartilhado de solicitação/resposta para a Responses está especificado na referência de criação da Responses.

Principais Pontos

• Chat Completions é gerenciado pelo chamador: você envia o array messages completo a cada solicitação e reconstrói o histórico por conta própria.
• Responses é assistido pelo servidor: você envia input mais instructions opcionais e pode encadear turnos com previous_response_id em vez de reenviar o histórico.
• A chamada de ferramentas difere estruturalmente: a Chat Completions aninha as chamadas em choices[0].message.tool_calls; a Responses as emite como itens tipados em um array output plano.
• Os resultados das ferramentas são correspondidos por tool_call_id (Chat) versus call_id em um item function_call_output (Responses).
• O streaming é baseado em deltas de chunks na Chat Completions versus eventos semânticos nomeados na Responses.
• O suporte a ferramentas hospedadas (busca na web, interpretador de código, busca de arquivos, etc.) depende do modelo em ambas as APIs; verifique a página do modelo antes de assumir a disponibilidade.

Comparação em Nível de Campo

Preocupação	Chat Completions	Responses
Endpoint	POST /v1/chat/completions	POST /v1/responses
Entrada principal	messages: [] (array completo a cada chamada)	input (string ou array de itens)
Orientação estilo sistema	messages[0].role = "system"	Campo instructions de nível superior
Continuação de múltiplos turnos	O chamador reenvia todo o histórico de messages	previous_response_id referencia o turno anterior no lado do servidor
Formato de saída	choices[0].message (objeto de mensagem única)	output: [], um array de itens tipados (mensagem, function_call, etc.)
Local da chamada de ferramenta	choices[0].message.tool_calls[]	Itens em output com type: "function_call"
Envio de resultado de ferramenta	Nova mensagem com role: "tool", tool_call_id	Item com type: "function_call_output", call_id
Streaming	Fragmentos chunk.choices[0].delta	Eventos nomeados (response.output_text.delta, response.completed, etc.)

previous_response_id: O que ele realmente faz

Na Chat Completions, a memória da conversação é de sua inteira responsabilidade. Cada solicitação deve incluir o histórico completo de mensagens, e o servidor não tem noção de um turno anterior. A Responses API, por outro lado, retorna um id em cada objeto de resposta. Se sua aplicação persistir esse id e passá-lo de volta como previous_response_id na próxima chamada, o servidor reconstrói o estado da conversação anterior do lado dele. Você só precisa enviar o novo input para o turno atual mais (opcionalmente) novas instructions. Isso transfere o gerenciamento de estado da sua camada de aplicação para a infraestrutura da OpenAI, o que é importante para agentes que fazem muitas chamadas sequenciais de ferramentas, pois você evita re-serializar e retransmitir um histórico crescente a cada salto.

A contrapartida é que seu aplicativo ainda precisa persistir o id em algum lugar durável (um armazenamento de sessão, uma linha de banco de dados) entre os turnos; a API não oferece retenção infinita ou busca sobre respostas passadas, ela apenas permite que você referencie a imediatamente anterior como um ponto de continuação.

Exemplos de Solicitação Atuais (gpt-5.6)

Chat Completions: você é dono do histórico completo:

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses: primeiro turno com instructions e input:

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses: turno de acompanhamento, sem reenvio de histórico:

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

Ciclo de Vida de Chamada de Função

Chat Completions:

1. O modelo retorna choices[0].message.tool_calls, cada um com um id e nome/argumentos da função.
2. Você executa a função localmente.
3. Você anexa a mensagem do assistente (com tool_calls) ao seu array messages, então anexa uma nova mensagem: { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. Você reenvia todo o array messages atualizado para continuar.

Responses:

1. O array output contém um item com type: "function_call", incluindo um call_id, name e arguments.
2. Você executa a função localmente.
3. Você envia uma nova solicitação com previous_response_id definido como o id da resposta anterior, e input contendo um item com type: "function_call_output", correspondendo ao call_id, e o resultado.
4. O servidor já reteve o contexto da chamada de função, então você não reenvia turnos anteriores.

A diferença estrutural entre itens de saída tipados planos e uma única mensagem com um array aninhado tende a simplificar a lógica de análise na Responses, já que você pode iterar o output e alternar com base no type em vez de investigar campos opcionais de uma mensagem.

Checklist de Decisão

• Construindo um agente de múltiplos turnos com chamadas de ferramenta? Use a Responses como padrão; previous_response_id remove o trabalho de gerenciamento de histórico.
• Precisa de controle exato sobre o que está no histórico (redação, sumarização personalizada, injeção de mensagens não padrão)? A Chat Completions oferece esse controle explicitamente, já que você monta o messages por conta própria.
• Migrando uma integração de Chat Completions existente? Pese o custo da refatoração em relação à economia no gerenciamento de estado; para chamadas de turno único e curta duração, o benefício é menor.
• Dependendo de ferramentas hospedadas (busca, interpretador de código, ferramentas de arquivo)? Verifique o suporte na página do modelo específico antes de se comprometer, já que a disponibilidade varia por modelo e endpoint.
• Precisa de streaming com semântica de eventos de granulação fina (ex: distinguir deltas de texto de deltas de chamada de ferramenta sem inspecionar o formato do delta)? Os eventos nomeados da Responses são mais explícitos do que os chunks de delta genéricos da Chat Completions.
• Trabalhando dentro de um framework ou SDK existente construído em torno de mensagens de chat? Confirme a maturidade do suporte a Responses antes de trocar de contrato no meio do projeto.

Agentes de múltiplos provedores e tradução de contrato

Agentes raramente permanecem em um único provedor por muito tempo. Um agente de codificação pode rotear para o Claude Sonnet 5 ou Kimi K2.7 Code para trabalho de implementação, recorrer ao DeepSeek V4 Flash ou Gemini 3.5 Flash para rascunhos baratos e, ocasionalmente, chamar o GLM-5.2 ou Qwen3.7 Plus para controle de custos de modelos de pesos abertos. Nenhum desses provedores necessariamente expõe o contrato de Chat Completions ou Responses da OpenAI nativamente.

É aqui que uma camada de roteamento se torna valiosa. A documentação do TokenLab em docs.tokenlab.sh descreve uma única superfície de API e chave usada para alcançar múltiplos provedores de modelos, o que elimina a necessidade de escrever manualmente uma integração de cliente separada por contrato de provedor. Nosso artigo relacionado sobre aliases de cabeçalho para compatibilidade de contrato aborda como os cabeçalhos de solicitação podem ser mapeados para que o código escrito para um formato de contrato possa alcançar modelos que não o suportam nativamente. Se você está construindo um chatbot ou agente que precisa chamar mais de uma família de modelos, nosso guia sobre construção de um chatbot de IA com uma única chave de API percorre a configuração em termos mais concretos.

Para a lista completa e atual de modelos alcançáveis através do TokenLab, incluindo as opções de fronteira, codificação e roteamento de baixo custo referenciadas acima, veja nossa página de modelos. Confirme a disponibilidade atual e quaisquer notas específicas de contrato lá antes de finalizar sua arquitetura, já que as linhas de modelos mudam com mais frequência do que os contratos de API.

Limitações

Este artigo não reafirma a referência de API exata em nível de campo da OpenAI para nenhum dos contratos, porque esses detalhes são versionados e podem mudar. Não trate o exemplo de formato de solicitação acima como código pronto para produção. Também não cobrimos o contrato nativo de cada provedor em profundidade aqui; Claude, Gemini, DeepSeek e GLM publicam suas próprias referências de API, e nenhum deles é obrigado a corresponder aos formatos de Chat Completions ou Responses da OpenAI. Se o seu agente precisa de garantias sobre a ordenação de chamadas de ferramenta, formatos de eventos de streaming ou comportamento de processamento em lote, verifique esses detalhes específicos na documentação atual do provedor nomeado, não neste artigo.

FAQ

A Responses API é uma substituta para a Chat Completions? A documentação de início rápido da OpenAI posiciona a Responses API como o caminho atual para novos desenvolvimentos, incluindo casos de uso de agentes, enquanto a Chat Completions permanece como parte da superfície de API documentada. Se a Chat Completions está obsoleta, descontinuada ou simplesmente é um legado em um determinado momento, é algo que você deve confirmar diretamente na documentação atual da OpenAI, já que o status de suporte pode mudar.

Outros provedores como Claude, Gemini ou DeepSeek usam os mesmos contratos? Não nativamente. Cada provedor define seu próprio formato de solicitação e resposta. Se você precisa executar um agente através de modelos da OpenAI e provedores como Claude Sonnet 5 ou DeepSeek V4 Pro, planeje uma camada de tradução em vez de assumir um contrato compartilhado.

Trocar de contrato altera a qualidade da saída do modelo? Não. O contrato é o transporte e a estrutura da solicitação e resposta, não o modelo em si. A qualidade da saída é governada por qual modelo você chama (por exemplo, GPT-5.5 versus Claude Sonnet 5), não por ter usado Chat Completions ou a Responses API para chamá-lo.

Se você está avaliando qual contrato e quais modelos se adequam ao seu agente, comece com uma pequena construção de teste contra os endpoints documentados do TokenLab e compare a sobrecarga de orquestração diretamente. Comece em docs.tokenlab.sh para executar essa comparação com sua própria carga de trabalho.