OpenAI Agents API vs Responses API vs Agents SDK vs AgentKit: Qual a melhor opção para desenvolver?

Esses quatro nomes estão em diferentes camadas, e uma pergunta os separa: quem executa o loop do agente? A Responses API é a chamada do modelo, e seu código executa o loop ao redor dela. O Agents SDK é uma biblioteca TypeScript e Python cujo executor executa o loop dentro do seu aplicativo. A Agents API, em beta público desde 10 de setembro de 2026, executa o harness Codex da OpenAI para você e mantém a sessão e, opcionalmente, o sandbox. AgentKit é o pacote de outubro de 2025 de Agent Builder, ChatKit, Connector Registry e Evals, e o Agent Builder está programado para ser desativado em 30 de novembro de 2026.

O DevDay em 29 de setembro adicionou o uso de computador à Agents API (veja o resumo do DevDay 2026), o que tornou a questão da nomenclatura mais difícil de ignorar. Abaixo: uma comparação lado a lado sobre loop, computação, estado, preço e maturidade, uma tabela de decisão e um caminho de migração de um loop Responses manual. Para um passo a passo prático de sessões e aprovações, leia o guia da OpenAI Agents API. Seja qual for sua escolha, a superfície HTTP é testável no Apidog.

Opções de agente OpenAI lado a lado

Fontes: comparação de runtime de agente da OpenAI, a visão geral da Agents API e a página de depreciações.

Quem executa o loop

Este é o eixo que decide a maioria das outras linhas.

Responses API: você a executa. Ferramentas hospedadas como pesquisa web, pesquisa de arquivos, interpretador de código e MCP remoto podem executar várias chamadas dentro de uma única solicitação, mas suas próprias funções retornam para você. Quando o modelo chama uma, você recebe um item function_call, o executa e envia um function_call_output com o mesmo call_id na próxima solicitação. Você decide quando parar, como armazenar o histórico (as respostas são armazenadas por padrão; store: false desativa isso), e quando compactar contextos longos com context_management e compact_threshold. O guia da Responses API e o guia de chamada de função cobrem esse loop.

Agents SDK: seu processo o executa. A documentação da OpenAI diz que o executor do SDK "lida com o loop do agente e as transferências", enquanto seu servidor é responsável pela implantação, implementações de ferramentas, armazenamento de estado e decisões de aprovação. Com os Sandbox Agents, o harness pode permanecer em sua infraestrutura enquanto os comandos são executados em um espaço de trabalho local Unix, Docker ou de provedor hospedado, de modo que a autenticação, os logs de auditoria e a revisão humana permaneçam fora do contêiner.

Agents API: a OpenAI o executa. O harness gerenciado lida com sessões, orquestração, compactação de contexto e recuperação, e adiciona subagentes, pesquisa de ferramentas e chamada programática de ferramentas. Servidores MCP remotos são chamados diretamente pela OpenAI. Seu código ainda lida com ferramentas de função: quando a sessão relata uma function_call em required_actions, você retorna um evento agent.session.input.tool_result com o turn_id e call_id.

A mesma tarefa, de ambas as maneiras:

# Responses API: uma chamada de modelo; seu código é o dono do loop
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "reasoning": {"effort": "low"},
    "tools": [{"type": "web_search"}],
    "input": "Summarize the breaking changes in the latest Node.js release."
  }'

# Agents API: uma sessão durável; OpenAI é a dona do loop
curl https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"model": "gpt-6-astra", "tools": [{"type": "web_search"}]},
    "environment": {"type": "none"},
    "input": "Summarize the breaking changes in the latest Node.js release."
  }'

Os exemplos da documentação da Agents API usam gpt-6-astra; eles não dizem se outros modelos são aceitos, então verifique antes de substituir por gpt-6.1-sol.

Computação, estado e custo

Computação. A Agents API pode provisionar e gerenciar um sandbox para toda a sessão: defina environment.type como openai_hosted, self_hosted ou none. Com o SDK, você escolhe e paga pelo provedor do sandbox. Com Responses, o código é executado onde você o executa, exceto pelas ferramentas hospedadas.

Estado. Uma sessão da Agents API mantém configuração, turnos e itens do lado da OpenAI, então um acompanhamento é um evento com o mesmo ID de sessão. Com Responses, você encadeia previous_response_id ou usa Conversas. Com o SDK, o estado reside no seu armazenamento ou nas sessões do SDK.

Custo. Os preços dos tokens são idênticos em todos os lugares, já que cada opção chama os mesmos modelos. A Agents API não cobra "taxas adicionais", mas contêineres hospedados custam de $0.03 (1 GB) a $0.48 (16 GB) por sessão de 20 minutos. O custo extra do SDK é sua própria hospedagem. O AgentKit não tem assinatura separada, conforme nosso explicador do AgentKit.

Dados. A Agents API suporta apenas residência de dados nos EUA e não suporta Zero Data Retention (ZDR), mesmo com um sandbox auto-hospedado. A página de controle de dados da OpenAI lista /v1/agents como não elegível para ZDR, com estado retido até ser excluído, enquanto /v1/responses é elegível para ZDR com limitações e disponível em endpoints regionais como eu.api.openai.com. Se ZDR ou residência na UE for um requisito, isso descarta a Agents API hoje.

AgentKit no final de 2026: o que resta

O AgentKit foi lançado em 6 de outubro de 2025 como quatro peças. Veja a situação de cada uma:

• Agent Builder: depreciação anunciada em 3 de junho de 2026; desligamento programado para 30 de novembro de 2026. O guia de migração da OpenAI exporta um workflow como código do Agents SDK, ou o recria como um ChatGPT Workspace Agent em Business, Enterprise ou Edu.
• Evals: as avaliações existentes se tornam somente leitura em 31 de outubro de 2026, e o painel e a API estão programados para serem desativados em 30 de novembro.
• ChatKit: permanece disponível para chat incorporado.
• Connector Registry: o painel de administração para conectores e servidores MCP em todos os produtos OpenAI.

Como o nosso guia do AgentKit explica, o caminho durável e code-first através do AgentKit é o Agents SDK.

Qual deles escolher para construir

Na AWS, o Bedrock Managed Agents, desenvolvido pela OpenAI, traz as capacidades centrais da Agents API para serem executadas nativamente na AWS. Para a configuração de MCP em qualquer caminho code-first, veja servidores MCP com agentes OpenAI.

Migrando do seu próprio loop Responses para a Agents API

Se você construiu um loop em Responses e quer que a OpenAI o execute:

1. Mapeie as peças. Instruções, modelo e ferramentas se movem para agent; seu contêiner se torna environment; seu armazenamento de conversa se torna um ID de sessão.
2. Mova os servidores MCP remotos para agent.tools. Coloque seus tokens em um cofre anexado com vault_ids, não em prompts.
3. Reescreva o tratamento de funções. Substitua seu loop function_call_output por um manipulador para agent.session.requires_action (stream) ou agent.session.action_required (webhook) que retorne agent.session.input.tool_result. Subagentes não podem chamar ferramentas de função, então mantenha-as no agente principal.
4. Exclua seu código de compactação. O harness compacta o contexto automaticamente.
5. Mude para eventos. Transmita os resultados dos turnos (agent.session.turn.completed, agent.session.turn.failed, agent.session.turn.cancelled) ou use webhooks. Uma sessão ociosa não significa sucesso.
6. Verifique as restrições. Residência apenas nos EUA, sem ZDR, e um cabeçalho beta.

Mantenha ambos em um projeto Apidog

Antes de mudar, execute o antigo e o novo lado a lado. Em um projeto Apidog, crie uma pasta Responses e uma pasta Agents API que compartilhem um ambiente com {{OPENAI_API_KEY}} e uma variável de modelo. Envie os mesmos prompts através de ambos, faça asserções sobre códigos de status e campos de saída obrigatórios, e abra o stream da Agents API como uma solicitação SSE para observar os eventos de turno. Salve as execuções como um cenário de teste e execute-o em CI com o Apidog CLI, para que uma mudança beta apareça como uma verificação falha. O guia de confiabilidade do agente de IA em produção abrange o que asserir. Baixe o Apidog para configurá-lo.

Perguntas Frequentes (FAQ)

A Agents API está substituindo a Responses API? Nenhuma depreciação foi anunciada. A visão geral dos agentes da OpenAI lista a Agents API, Agents SDK e Responses API como opções atuais para diferentes necessidades.

O OpenAI AgentKit está depreciado? Parcialmente. O Agent Builder e o Evals estão programados para serem desativados em 30 de novembro de 2026; o ChatKit permanece disponível.

O Agents SDK usa a Agents API? Não. O SDK é executado em seu aplicativo; a Agents API executa um harness gerenciado no serviço da OpenAI.

O que aconteceu com a Assistants API? A página de depreciações da OpenAI definiu sua remoção para 26 de agosto de 2026 e direciona os desenvolvedores para as APIs Responses e Conversations.

Qual opção é a mais barata? Os preços dos tokens são os mesmos em todas as opções. A diferença está nos contêineres hospedados na Agents API versus sua própria hospedagem com o SDK ou Responses.

Escolha um caminho esta semana

Escolha por quem deve executar o loop e, em seguida, prove isso com solicitações antes de escrever um aplicativo. Se você está começando do zero, experimente uma sessão da Agents API e compare sua saída com sua configuração atual de Responses no Apidog.