A escolha é sobre quem executa o loop do agente e quem mantém o estado. A Agents API entrega à OpenAI o harness e as sessões duráveis; o Agents SDK executa o loop dentro da aplicação; a Responses API oferece chamadas de modelo e ferramentas para montar a orquestração com mais liberdade. As três rotas podem integrar ferramentas, mas não transferem as mesmas responsabilidades operacionais.
A OpenAI anunciou a Agents API em 10 de setembro de 2026, em beta público. A comparação abaixo reflete a documentação oficial consultada em 23 de setembro de 2026; recursos, preços e limitações de uma versão beta podem mudar. Consulte o anúncio e a comparação de runtimes antes de fechar o desenho.
Matriz de decisão: estado, ferramentas e controle
| Critério | Agents API | Agents SDK | Responses API |
|---|---|---|---|
| Loop e hospedagem | Harness Codex gerenciado pela OpenAI. | Runner do SDK na sua aplicação. | Loop e integração definidos pela sua aplicação. |
| Esforço de integração | Baixo na comparação oficial. | Médio na comparação oficial. | Alto para um agente construído do zero. |
| Estado entre tarefas | Configuração, turnos e itens de uma sessão durável. | Armazenamento próprio, sessões do SDK ou estado do Responses. | Histórico manual, encadeamento de respostas ou Conversations. |
| Ferramentas e MCP | MCP conectado pelo serviço ou ambiente; funções tratadas pela aplicação. | Ferramentas, MCP e integrações configuradas no código. | Ferramentas hospedadas, funções da aplicação e MCP. |
| Sandbox | Hospedado pela OpenAI, autohospedado ou ausente. | Runtime próprio e integrações com provedores de sandbox. | Ambiente próprio para ferramentas executadas pela aplicação. |
| Aprovações | Política e bloqueio nas fronteiras das ferramentas e integrações. | Interrupções de execução para revisão e retomada. | Bloqueio explícito no aplicativo; fluxo de aprovação MCP quando usado. |
| Observabilidade | Eventos, histórico, logs, traces e uso por turno. | Tracing do SDK e instrumentação da aplicação. | Telemetria do modelo e instrumentação do loop da aplicação. |
| Controle operacional | Você configura o agente e o ambiente; a OpenAI opera o harness. | Você opera runner, armazenamento, ferramentas e implantação. | Você determina a orquestração e os detalhes de cada chamada. |
As classificações de esforço são as da tabela oficial da OpenAI, não medições de prazo ou custo de um projeto. A linha sobre aprovações descreve o desenho operacional exigido para ações sensíveis, não uma garantia de bloqueio automático em todas as ferramentas.
Agents API: harness e sessões gerenciados
Na Agents API, a OpenAI opera o harness Codex, a orquestração, a compactação de contexto e a recuperação. A aplicação cria uma sessão, envia tarefas e acompanha eventos; pode continuar o trabalho sem reconstruir a conversa inteira. O ambiente pode ser openai_hosted, self_hosted ou none. Sem ambiente, não há workspace nem execução de comandos do sandbox, embora ferramentas remotas e funções possam continuar disponíveis conforme a configuração.
O MCP HTTP pode se conectar pelo serviço da OpenAI ou pelo ambiente; MCP via stdio exige ambiente. Funções da aplicação ainda precisam de um handler que execute a chamada e devolva o resultado. Em sandbox autohospedado, você provisiona, reconecta e encerra a infraestrutura, mas o harness continua gerenciado pela OpenAI. Detalhes de MCP e arquitetura de ambientes.
Agents SDK: o loop no código da aplicação
O Agents SDK, disponível para TypeScript e Python, executa o loop, chama ferramentas e coordena handoffs no runtime da aplicação. A equipe decide implantação, armazenamento, conectividade privada, provedores e política de aprovação. Para manter a conversa, pode usar histórico próprio, sessões do SDK ou estratégias de continuação do Responses. O recurso de agentes com sandbox do SDK está em beta e depende da integração de ambiente escolhida.
Para ações sensíveis, o SDK oferece guardrails e interrupções de aprovação: a execução pausa, retorna o estado retomável e só prossegue após decisão explícita. O tracing integrado registra chamadas ao modelo, ferramentas, handoffs e guardrails; a aplicação deve complementar com métricas, alertas e política de retenção próprias.
Responses API: construir a orquestração por chamadas
A Responses API atende à integração direta com o modelo, ferramentas hospedadas, funções da aplicação e MCP. Se a solução precisa de um agente, o time define quando chamar o modelo, como executar ferramentas, quais resultados reinserir no contexto, quando interromper e como retomar. É uma rota para fluxos pequenos e delimitados ou para equipes que já têm uma orquestração própria e não querem adotar um runner de agentes.
Continuação não significa estado durável idêntico ao da Agents API: a aplicação pode fornecer histórico, usar previous_response_id ou Conversations, observando as regras de armazenamento e retenção de cada recurso. Para MCP remoto, há solicitações de aprovação configuráveis; funções com efeitos externos precisam de uma checagem antes da execução no código da aplicação. Veja estado de conversa, function calling e aprovação de MCP.
Escolha pelo caso de uso, não pelo nome da API
- Tarefa longa com arquivos, comandos e retomada: avalie a Agents API com sandbox e sessão durável; confirme limites do beta e responsabilidade sobre o ambiente escolhido.
- Aplicação com regras próprias, rede privada e várias especialidades: avalie o Agents SDK, cuja execução fica no seu serviço e aceita ferramentas, handoffs e aprovação integrada.
- Extração estruturada ou fluxo curto com poucos passos: uma integração direta com Responses pode evitar uma camada de orquestração que não traz benefício concreto.
- Fluxo empresarial já orquestrado: Responses preserva o controle do loop existente; Agents SDK pode ajudar se houver necessidade de runner, handoffs e tracing integrados.
- Ação irreversível, como envio, exclusão ou pagamento: em qualquer rota, coloque autorização, validação e auditoria junto ao ponto que efetivamente executa a ação.
Quatro verificações antes de entrar em produção
1. Defina o recurso que guarda cada tipo de estado
Separe o histórico de mensagens, o estado de uma execução pausada, os arquivos do sandbox e os artefatos publicados. Uma sessão da Agents API, uma sessão do SDK, uma Conversation e um ambiente de execução não são equivalentes. Registre IDs, política de expiração, retomada, exclusão e recuperação em caso de falha.
2. Modele as ferramentas com privilégios mínimos
Liste quais chamadas apenas leem dados e quais provocam efeitos externos. Restrinja credenciais, rede e escopo de cada ferramenta. Um pedido de aprovação MCP não substitui a autorização para uma função própria; o handler deve validar identidade, argumentos e permissão antes da ação. Não entregue segredos permanentes ao código produzido pelo agente.
3. Planeje eventos, custos e falhas
Na Agents API, use eventos, webhooks, histórico e traces de sessão; o uso por turno é de melhor esforço e não representa necessariamente a fatura final. No SDK, examine traces do runner. Em Responses, acompanhe as chamadas do modelo e também cada etapa do loop que você construiu. Meça latência, tentativas, falhas de ferramentas, aprovações pendentes e custo por tarefa concluída.
4. Confira residência de dados e maturidade
Na data desta análise, a documentação informa que a Agents API oferece residência de dados apenas nos Estados Unidos e não suporta Zero Data Retention, mesmo com sandbox autohospedado. A Agents API e os agentes com sandbox do SDK estão em beta. Valide os controles exigidos pelo projeto, os termos e a documentação mais recente antes de assumir equivalência regulatória entre rotas.
Checklist para uma prova de arquitetura
- Escreva uma tarefa real e seus critérios de sucesso, incluindo qualidade, duração e custo.
- Identifique quem será responsável pelo loop, sessões, armazenamento e ambiente.
- Liste ferramentas, servidores MCP e acessos privados, com permissões por operação.
- Teste uma execução normal, uma falha de ferramenta e a retomada após interrupção.
- Bloqueie no executor uma ação sensível até receber aprovação verificável.
- Inspecione traces e logs para reconstruir chamadas, decisões e efeitos externos.
- Compare o custo total da tarefa, incluindo modelos, ferramentas, sandbox e infraestrutura própria.
- Verifique residência de dados, retenção, exclusão e mudanças previstas nos componentes beta.
Regra de decisão: use a rota gerenciada quando o ganho principal for delegar o harness e manter sessões longas; use o SDK quando o loop precisa viver na aplicação; use Responses quando o produto exige compor o próprio fluxo de chamadas. A escolha só está pronta quando o teste demonstra retomada, aprovação, observabilidade e controle de custos no ambiente real.
