Agents API, SDK ou Responses API: como escolher

Três caminhos parecidos transferem responsabilidades diferentes

Uma equipe decide criar um agente para investigar chamados técnicos. O sistema deverá ler arquivos, consultar documentação, executar testes em ambiente isolado, pedir aprovação antes de qualquer correção e retomar o trabalho quando uma dependência voltar.

A primeira decisão parece simples: usar uma API da OpenAI. O problema é que existem caminhos com nomes próximos e contratos operacionais diferentes. Agents API, Agents SDK e Responses API permitem construir agentes, mas distribuem estado, execução, ferramentas e manutenção de maneiras próprias.

Escolher pelo exemplo de código mais curto costuma esconder a conta que aparecerá em produção. A equipe precisa saber quem mantém o loop do agente, onde o trabalho roda, como uma sessão continua, que dados ficam no fornecedor e quanto da infraestrutura será responsabilidade interna.

A documentação oficial da OpenAI consultada em 18 de setembro de 2026 apresenta os três caminhos assim:

a Agents API executa um harness Codex gerenciado pela OpenAI;
o Agents SDK executa o loop dentro da aplicação da empresa;
a Responses API oferece acesso mais direto aos modelos e às ferramentas, com maior responsabilidade de orquestração na aplicação.

A comparação serve para uma decisão de arquitetura. Os recursos citados podem mudar porque a Agents API está em beta pública e outros componentes também evoluem.

O que muda entre API, SDK e runtime

Uma API define como sistemas trocam solicitações e respostas. Um SDK fornece bibliotecas e abstrações para construir dentro de uma aplicação. Um runtime mantém a execução: chama o modelo, entrega ferramentas, acompanha estado, trata pausas e decide quando uma rodada terminou.

Essas camadas podem aparecer juntas. O Agents SDK usa APIs da OpenAI, mas mantém o runner dentro da aplicação. A Agents API oferece uma API para um runtime gerenciado. A Responses API permite montar um fluxo mais próximo das respostas do modelo e controlar a orquestração diretamente.

O artigo sobre harness de agentes de IA detalha os componentes que sustentam tarefas longas. Aqui, a pergunta é mais estreita: qual das três opções assume cada parte desse trabalho?

Comparativo rápido

| Critério | Agents API | Agents SDK | Responses API | |---|---|---|---| | uso principal | tarefas longas com harness gerenciado | agentes e workflows controlados pela aplicação | chamadas diretas e agentes montados sob medida | | onde roda o loop | infraestrutura gerenciada pela OpenAI | aplicação da empresa | aplicação da empresa, com recursos hospedados opcionais | | estado entre tarefas | sessões e itens mantidos pelo serviço | armazenamento escolhido pela aplicação ou estado de conversação | histórico, encadeamento ou Conversations configurados pela aplicação | | esforço de integração | menor | intermediário | maior | | ferramentas | serviços conectados, funções da aplicação, MCP e sandbox opcional | ferramentas configuradas na aplicação | ferramentas hospedadas ou executadas pela aplicação | | ambiente | sandbox OpenAI, ambiente próprio ou sem sandbox | runtime e provedor de sandbox escolhidos pela equipe | ambiente controlado pela aplicação | | controle operacional | menor sobre o harness, maior conveniência | equilíbrio entre abstração e controle | maior controle e maior carga de implementação |

"Menor esforço" não significa implantação pronta. A empresa ainda precisa definir processo, dados, permissões, critérios, observabilidade e responsável humano.

Quando a Agents API faz sentido

A Agents API foi anunciada em 10 de setembro de 2026 como beta pública. Ela oferece acesso ao harness Codex operado pela OpenAI. O serviço mantém sessões, orquestração, compactação de contexto e recuperação, enquanto a aplicação fornece ferramentas e escolhe o ambiente de execução.

Esse caminho tende a ajudar quando a tarefa:

dura além de uma chamada curta;
precisa continuar em várias etapas;
produz arquivos ou outros artefatos;
usa ferramentas e servidores MCP;
pode dividir trabalho entre subagentes;
precisa retomar depois de uma pausa;
justifica reduzir a carga de manter o harness internamente.

Um exemplo é um agente que investiga um incidente. Ele recebe evidências, executa verificações em sandbox, consulta fontes, prepara uma hipótese, pede aprovação e continua a partir do mesmo estado.

A conveniência vem acompanhada de condições importantes. A documentação oficial informa, na data desta verificação, que a Agents API oferece residência de dados apenas nos Estados Unidos e não suporta Zero Data Retention. Usar sandbox próprio não altera essa condição do serviço. Empresas com requisitos de retenção, localização ou sigilo precisam tratar esse ponto como critério de arquitetura.

Também existe dependência do harness gerenciado. A equipe controla ferramentas, instruções e ambiente dentro das opções disponíveis, mas não opera toda a camada que coordena a execução. Essa troca pode ser adequada para um processo e inadequada para outro.

Quando o Agents SDK faz sentido

O Agents SDK roda dentro da aplicação e oferece abstrações para agente, ferramentas, handoffs, guardrails, sessões e loop de execução. A equipe controla implantação, armazenamento, aprovações e integração com o restante do sistema.

Ele costuma ser uma opção forte quando a empresa precisa:

inserir o agente em uma aplicação existente;
controlar como ferramentas internas são chamadas;
escolher onde o estado será armazenado;
integrar aprovações à interface e às regras internas;
usar observabilidade própria;
combinar agentes com lógica determinística;
manter maior liberdade sobre ambiente e implantação.

O SDK reduz parte do código repetitivo do loop, mas a operação continua com a equipe. Disponibilidade, escalabilidade, persistência, filas, atualizações e recuperação precisam de uma solução compatível com o risco do processo.

Uma aplicação de atendimento, por exemplo, pode usar o SDK para triar uma solicitação, consultar uma base autorizada e preparar uma resposta. A aplicação mantém identidade, política, histórico e registro do caso. O runner cuida das rodadas entre modelo e ferramentas dentro dessa arquitetura.

Quando a Responses API faz sentido

A Responses API oferece uma camada mais direta para chamar modelos e usar ferramentas. Ela é adequada quando a equipe quer controlar o fluxo, a composição das mensagens, a execução das funções e a forma de persistir continuidade.

Esse caminho costuma caber melhor em situações como:

tarefa curta com poucas etapas;
integração que já possui seu próprio orquestrador;
necessidade de controlar cada chamada e transição;
fluxo determinístico com uma etapa de interpretação;
arquitetura que evita adotar um runtime completo;
requisitos específicos de telemetria ou armazenamento.

O preço do controle aparece na implementação. A aplicação precisa administrar o loop, encaminhar chamadas de ferramenta, tratar falhas, limitar tentativas e escolher uma estratégia de continuidade.

Para conversas e tarefas com várias rodadas, a documentação apresenta alternativas como histórico mantido pela aplicação, conversationId e previousResponseId. Misturar estratégias sem um desenho explícito pode duplicar contexto ou dificultar investigação.

Comece pela unidade de trabalho

A tecnologia fica mais fácil de comparar depois que a equipe escreve o trabalho completo.

Use uma ficha curta:

evento que inicia a execução;
unidade que será processada;
fontes necessárias;
ferramentas permitidas;
saída esperada;
duração e quantidade provável de etapas;
pausas e aprovações;
estado que precisa sobreviver;
dado que não pode sair de determinada fronteira;
condição de conclusão, cancelamento e retomada.

Considere um agente que revisa documentos de fornecedor. A unidade pode ser um dossiê. A entrada contém contrato, cadastro e política vigente. A saída é uma lista de divergências com fonte. A execução precisa parar quando falta um documento, não pode aprovar o fornecedor e deve preservar o estado durante uma pendência.

Com essa ficha, a escolha deixa de ser uma disputa abstrata entre produtos. A equipe consegue verificar se precisa de um harness gerenciado, de um runner dentro da aplicação ou de uma chamada direta inserida num workflow existente.

Compare estado e continuidade

Estado inclui tarefa atual, arquivos, resultados intermediários, decisões, aprovações e efeitos já confirmados. Histórico de conversa é apenas uma parte.

Na Agents API, sessões duráveis mantêm configuração, turnos e itens. O serviço também pode compactar contexto e retomar o trabalho. A equipe deve confirmar política de retenção, exclusão e disponibilidade dos registros necessários à auditoria.

No Agents SDK, o estado pode ficar em armazenamento escolhido pela aplicação, em sessões do SDK ou em mecanismos de conversação da API. Essa flexibilidade exige uma regra: cada conversa ou unidade deve usar uma estratégia principal de continuidade.

Na Responses API, a equipe monta o encadeamento. Esse controle pode reduzir abstrações, mas aumenta o risco de reenviar contexto demais, perder itens necessários ou repetir uma ação depois de falha.

O guia sobre sessões de agentes de IA ajuda a separar conversa, unidade de trabalho e ambiente de execução.

Compare ambiente e acesso a ferramentas

Um agente que apenas classifica texto exige menos ambiente que outro capaz de editar arquivos e executar comandos.

A Agents API aceita sandbox hospedado, ambiente próprio ou execução sem sandbox, conforme o caso e as opções do serviço. O Agents SDK integra o runtime e o provedor de sandbox escolhido pela aplicação. A Responses API deixa o ambiente sob responsabilidade da arquitetura da empresa, ainda que algumas ferramentas sejam hospedadas.

Para qualquer opção, trate cada ferramenta como uma permissão concreta. "Acesso ao CRM" é amplo. Prefira operações estreitas, como consultar oportunidade por identificador ou preparar uma atualização sem gravá-la.

Teste também a revogação. Uma credencial expirada deve impedir novas ações e alcançar trabalhos em curso quando o risco exigir. O artigo sandbox de execução para agentes de IA traz critérios de isolamento, rede e descarte.

Compare observabilidade antes do primeiro piloto

A equipe precisa reconstruir o que aconteceu em uma execução. Peça evidência para:

versão do agente e do modelo;
entrada e identidade do solicitante;
ferramentas disponibilizadas e chamadas;
fontes consultadas;
mudanças de estado;
pausas e aprovações;
subagentes criados;
custo e duração;
arquivos produzidos;
falha, cancelamento e retomada;
resultado registrado no sistema final.

Um produto pode mostrar bons traces técnicos e ainda não ligar a execução ao caso empresarial. Defina um identificador comum para atravessar sessão, ferramenta, fila e sistema de destino.

Considere portabilidade e saída

A decisão inicial deveria incluir o que acontece se a empresa mudar de runtime.

Liste os ativos que precisam ser exportáveis:

instruções e skills;
contratos das ferramentas;
conjunto de avaliações;
dados de sessão permitidos;
traces e métricas;
artefatos produzidos;
regras de aprovação;
configurações de ambiente;
inventário de dependências.

Nenhuma migração será perfeita. O objetivo é saber quais partes pertencem ao processo da empresa e quais dependem do fornecedor. Essa leitura evita descobrir tarde que avaliações, estado ou registros críticos ficaram presos numa camada fechada.

Uma matriz de decisão para o time

Dê uma resposta documentada a cada linha.

| Pergunta | Se a resposta for sim, observe | |---|---| | A tarefa dura muito e precisa retomar? | Agents API ou SDK com persistência bem desenhada | | A empresa quer que o fornecedor mantenha o harness? | Agents API | | O loop precisa rodar dentro da aplicação? | Agents SDK ou Responses API | | A equipe precisa controlar cada chamada? | Responses API | | Há aprovações e ferramentas internas complexas? | Agents SDK pode reduzir trabalho sem retirar controle | | O caso exige residência ou retenção incompatível com o serviço gerenciado? | descarte Agents API para esse caso ou redesenhe a fronteira | | A aplicação já possui orquestração e estado? | Responses API pode evitar uma camada redundante | | A equipe não consegue manter runtime, fila e recuperação? | harness gerenciado pode reduzir risco operacional, sujeito aos requisitos de dados |

A matriz orienta uma prova. Ela não substitui teste com o processo real.

Faça um piloto comparável

Escolha uma tarefa delimitada e execute os mesmos casos nas opções finalistas. Use dados sintéticos ou autorizados. Inclua caminho comum, entrada incompleta, ferramenta indisponível, aprovação demorada, cancelamento e retomada.

Registre:

esforço para implementar;
conclusão válida por classe;
tempo humano de revisão;
custo por unidade aceita;
qualidade do trace;
trabalho para recuperar falha;
facilidade de limitar ferramentas;
capacidade de exportar evidências;
manutenção esperada.

Evite testar apenas a resposta final. A arquitetura será cobrada quando a execução pausa, falha ou encontra um caso fora do padrão.

Fontes e limites desta comparação

Este guia foi verificado em 18 de setembro de 2026 contra as páginas oficiais Agents, Agents API overview e Running agents, além do anúncio Introducing the Agents API.

A comparação é documental. A Júpiter não executou, para este artigo, um benchmark entre as três opções nem afirma paridade de recursos. Confirme versão, preços, beta, região, retenção, limites e permissões na documentação e na conta usada pelo projeto antes de contratar ou implementar.

Checklist antes de escolher

A unidade de trabalho está definida?
A equipe sabe onde o loop deve rodar?
Estado e continuidade possuem uma estratégia principal?
O ambiente combina com a classificação dos dados?
Ferramentas têm operações estreitas e permissões técnicas?
Pausa, aprovação, cancelamento e retomada foram testados?
A observabilidade alcança o resultado empresarial?
Retenção e residência atendem aos requisitos?
Custos incluem ambiente, ferramentas, tentativas e revisão?
A equipe consegue manter a parte da infraestrutura que assumiu?
Existe plano de exportação e encerramento?
Um responsável humano responde pelo processo?

A escolha define quem carregará a operação

Agents API, Agents SDK e Responses API oferecem graus diferentes de conveniência e controle. O melhor caminho depende da tarefa, das fronteiras de dados, da capacidade técnica e da responsabilidade que a empresa aceita manter.

Defina o trabalho antes de escolher a camada. Compare estado, ambiente, ferramentas, observabilidade e saída. Depois faça um piloto com falhas e pausas reais. A arquitetura certa é aquela que a equipe consegue operar, investigar e interromper quando o agente sai do caminho previsto.