Agentes de IA da OpenAI: Agents API ou Agents SDK?

A OpenAI lançou a Agents API gerenciada para agentes de IA em 10 de setembro de 2026. Escolha essa opção quando o maior custo operacional estiver em manter o estado das sessões, compactar o contexto e recuperar execuções. Prefira o Agents SDK quando a aplicação precisar controlar o runtime, a implantação e o caminho percorrido pelos dados. Na comparação entre OpenAI Agents API e Agents SDK, a decisão depende de controle e operação, já que o serviço gerenciado não cobra uma tarifa separada pelo harness.

Qual opção escolher para seus agentes de IA?

A OpenAI Agents API é a melhor escolha padrão para uma equipe enxuta de plataforma que coloca agentes de longa duração em produção. A OpenAI executa o harness do Codex, mantém a sessão e o trabalho salvo, compacta o contexto, coordena subagentes e permite retomar tarefas entre turnos assíncronos. Isso elimina uma categoria de trabalho de infraestrutura que raramente diferencia o produto. A OpenAI lançou o recurso em beta público em 10 de setembro de 2026 e afirma que ele está disponível para todos os desenvolvedores.

Para o fundador de uma startup com investimento captado, uma equipe pequena de backend e um agente de revisão de documentos que pode aguardar aprovações por horas, a sessão gerenciada vale mais do que controlar o loop. O tempo escasso da equipe de produto rende mais quando aplicado a políticas, ferramentas, avaliações e experiência do usuário.

O OpenAI Agents SDK faz mais sentido quando controlar o runtime é uma exigência, não uma preferência. Ele roda dentro da aplicação, que passa a responder pela implantação, pelo armazenamento, pela lógica de aprovação, pela implementação das ferramentas e pela estratégia de estado. Hoje, um CTO de uma empresa de médio porte sujeita a uma política obrigatória de Zero Data Retention deve seguir esse caminho, pois o beta público da Agents API não oferece suporte a ZDR.

Para um engenheiro sênior que já conta com uma frota consolidada de workers, telemetria personalizada e um caminho de recuperação testado, migrar apenas para deixar de manter um loop relativamente simples é uma troca ruim. O SDK preserva esse controle e ainda oferece agentes, ferramentas, handoffs, guardrails, sessões, revisão humana e tracing.

OpenAI Agents API ou Agents SDK: comparação rápida

A diferença oficial está em onde a orquestração roda e em quem controla o estado entre as tarefas. As duas opções podem acionar modelos e ferramentas da OpenAI; nenhuma delas torna gratuitos os tokens dos modelos.

Na prática, a virada é simples. Se o agente conclui uma solicitação curta dentro de um serviço já existente, a sobrecarga de controle do SDK pode ser mínima. Se ele edita arquivos, pausa para uma aprovação, sobrevive a desconexões, delega trabalho e retoma a atividade no dia seguinte, a API gerenciada elimina mais componentes a cada novo estado do ciclo de vida.

Harness e sandbox são decisões diferentes

A Agents API gerencia o loop de raciocínio, mas não obriga todas as ferramentas a rodarem na infraestrutura da OpenAI. A OpenAI chama esse loop gerenciado de harness do Codex: ele coordena chamadas ao modelo, uso de ferramentas, contexto, sessões e subagentes. Já o ambiente de execução é um recurso separado, no qual os comandos rodam e os arquivos ficam armazenados.

Esse ambiente pode não existir, ser hospedado pela OpenAI ou ser self-hosted. Sem ambiente, o harness ainda consegue chamar servidores MCP remotos e enviar chamadas de função para a aplicação, mas não conta com Bash integrado, ferramenta de apply-patch nem arquivos de workspace. Em um sandbox hospedado pela OpenAI, a empresa provisiona o workspace Linux. Em um ambiente self-hosted, o executor da aplicação roda comandos e operações de arquivo solicitados pelo harness gerenciado. O guia de arquitetura deixa essa separação explícita.

Entender essa diferença evita dois erros caros. Primeiro, optar pelo Agents SDK apenas porque o código precisa rodar na própria VPC é precipitado: a Agents API pode se conectar a um ambiente self-hosted. Segundo, escolher a Agents API supondo que a OpenAI executará tudo também é precipitado: os handlers de funções da aplicação continuam rodando no código da empresa, e um executor self-hosted deixa provisionamento, reconexão, encerramento e persistência de arquivos sob responsabilidade dela.

Em um fluxo privado de análise de dados, o harness gerenciado poderia enviar chamadas de função SQL a um serviço da aplicação sem receber acesso a um shell de uso geral. Para um agente de programação, poderia usar um sandbox hospedado pela OpenAI. Para um sistema proprietário de build, poderia se conectar a um worker isolado da própria empresa. São três padrões de execução sob uma única camada de orquestração gerenciada.

Agentes de IA de longa duração: a Agents API leva vantagem

A Agents API vence quando a tarefa tem um ciclo de vida mais longo do que uma única requisição da aplicação. Uma sessão retém a configuração do agente, a conversa e o trabalho salvo. Uma nova entrada inicia um turno assíncrono se a sessão estiver ociosa ou redireciona o turno ativo enquanto ele está em execução. A aplicação pode acompanhar um stream ou receber mudanças de estado por webhooks.

A OpenAI também gerencia a compactação do contexto quando a sessão se aproxima do limite. Compactar significa substituir detalhes antigos por uma representação menor que preserva o necessário, permitindo que o agente continue trabalhando por várias janelas de contexto. A ideia é simples de explicar e difícil de operar bem: o resumo retido precisa preservar decisões, resultados de ferramentas e trabalho pendente sem carregar para sempre todos os tokens anteriores.

A recuperação é a vantagem menos óbvia. Streams de eventos não reproduzem eventos perdidos. Depois de uma desconexão, a aplicação recupera a sessão e seus itens salvos e então continua a partir do registro durável, em vez de reconstruir um turno do agente usando a memória do processo. O guia de sessões documenta a diferença entre um turno concluído, um turno com falha, um cancelamento e uma sessão que está apenas ociosa.

Imagine um agente de revisão de contratos para o fundador de uma startup com investimento captado. Ele lê um documento, pede a um subagente especialista que compare cláusulas, pausa para aprovação do jurídico, recebe uma correção mais tarde e produz um artefato. O valor do produto está na revisão. Reproduzir sessões, compactar contexto, lidar com streams interrompidos e recuperar turnos são custos operacionais. É esse tipo de carga que a API gerenciada foi criada para absorver.

O limite mais delicado está na precisão contábil. Agentes podem fazer várias chamadas de modelo, enquanto agentes raiz, subagentes, novas tentativas, ferramentas e sandboxes contribuem para o custo. A OpenAI afirma que os campos de uso da Agents API são estimativas de melhor esforço, podem ser nulos ou mudar depois e não representam a fatura final. Tokens de raciocínio contam como tokens de saída, enquanto entradas em cache continuam sendo cobradas. Use o guia de uso para depuração e depois concilie os valores com os dados de faturamento ao aplicar controles financeiros.

O dashboard também faz parte dessa fronteira de observabilidade. A consulta detalhada de traces e a exportação de traces para serviços externos não estão disponíveis pela API para clientes no beta público. Se o pipeline de telemetria exige exportação programática de todos os traces, essa lacuna pesa mais que um dashboard gerenciado bem-acabado.

Controle de runtime e implantação: o Agents SDK vence

O Agents SDK vence quando a aplicação precisa decidir exatamente como uma execução começa, pausa, retoma, armazena estado, distribui ferramentas e falha. O runner executa o loop do agente e os handoffs, mas esse loop fica dentro do serviço. Assim, o código do produto pode aplicar a cada transição suas próprias transações, filas, limites de requisição, registros de aprovação e telemetria.

O SDK está disponível para TypeScript e Python, e o repositório em Python usa a licença MIT. Portanto, o pacote não cobra uma licença por usuário. Chamadas a modelos da OpenAI, ferramentas hospedadas, provedores de sandbox e a computação usada pela aplicação continuam sendo custos separados. O guia do SDK o posiciona para aplicações code-first que controlam implantação, armazenamento, aprovações e integração com o runtime.

O estado é flexível, não automático. Uma aplicação com o SDK pode reproduzir result.history, persistir uma sessão do SDK em armazenamento próprio, vincular um ID do OpenAI Conversations ou encadear a execução a partir do ID de uma resposta anterior da Responses API. Cada alternativa tem sua utilidade, mas o guia de execução de agentes alerta que combinar a reprodução local com estado gerenciado no servidor pode duplicar o contexto se as camadas não forem reconciliadas deliberadamente.

Essa flexibilidade se paga em um serviço interno regulado. É possível incluir uma aprovação e a continuação do agente na mesma transação do banco de dados, manter o estado em uma região aprovada, executar ferramentas atrás de controles de rede privada e integrar a execução do agente a um sistema de jobs existente. Também é possível incorporar modelos ou provedores por meio da camada de modelos do SDK, sem transformar o harness gerenciado do Codex no limite permanente da orquestração.

A barreira é assumir a operação. Uma queda de processo vira um problema de retomada para a equipe. A entrega duplicada na fila vira um problema de idempotência. O crescimento do histórico, a política de compactação, as novas tentativas de ferramentas, as migrações de estado e o rollback de implantação também passam a ser problemas da equipe. O SDK dá controle sobre tudo isso, e esse controle só tem valor quando a aplicação realmente o utiliza.

Comparação de custos: não há tarifa separada pelo harness

A conta de tokens e ferramentas hospedadas é a mesma quando os dois runtimes usam o mesmo modelo da OpenAI, a mesma combinação de tokens e as mesmas chamadas de ferramentas. Os preços foram verificados nas páginas ao vivo da OpenAI em 11 de setembro de 2026. Na modalidade padrão com contexto curto, o GPT-6 Astra custa $10.00 por 1 milhão de tokens de entrada e $50.00 por 1 milhão de tokens de saída. A busca na web custa $10.00 por 1,000 chamadas, além dos tokens do conteúdo encontrado cobrados pela tarifa do modelo escolhido. A Agents API gerenciada não acrescenta nenhuma tarifa própria.

Veja uma carga de trabalho normalizada. São premissas, não dados observados em produção:

• 1,000 jobs de agentes por mês.
• Cada job consome, no total, 10,000 tokens de entrada sem cache e 2,000 tokens de saída no GPT-6 Astra. O conteúdo retornado pela busca está incluído na cota de entrada.
• Cada job faz uma chamada de busca na web.
• O cenário hospedado da Agents API abre uma nova sessão de container de 1 GB por job, cobrada à tarifa publicada de $0.03. Reutilizar um sandbox reduziria esse item.
• O cenário com SDK usa um worker compartilhado que, por premissa, custa $40 por mês e tem capacidade suficiente. Armazenamento, rede e mão de obra não entram na conta.

A parcela do modelo é $0.10 de entrada mais $0.10 de saída, ou $0.20 por job. Na combinação presumida de 12,000 tokens, o valor equivale a $0.0167 por 1,000 tokens de modelo combinados. Uma chamada de busca na web acrescenta $0.01, levando o gasto comum com a OpenAI a $0.21 por job.

Com 1,000 jobs, a Agents API com um novo container hospedado de 1 GB para cada job custa $240: são $210 pelo uso comum de modelo e busca, mais $30 pelos containers. O cenário com SDK custa $250: os mesmos $210 de uso da OpenAI, mais o worker presumido de $40. No gasto direto, os containers hospedados vencem nesse volume baixo.

Com 10,000 jobs, o cenário gerenciado e hospedado chega a $2,400: $2,100 de gasto comum mais $300 em containers. O cenário com SDK chega a $2,140 com o worker compartilhado presumido. O ponto de virada do custo direto de computação é de 1,334 novas sessões de container por mês, a primeira quantidade inteira em que $0.03 por sessão supera $40.

O cenário mais importante é o da Agents API self-hosted. Se ela usar o mesmo worker presumido de $40, o total para 10,000 jobs também será de $2,140. O harness do Codex continua gerenciado, mas a conta da execução empata com a do SDK porque a OpenAI não acrescenta tarifa pelo harness.

A conta financeira ainda ignora a maior variável: o tempo de engenharia. Acima do ponto de virada, economizar $260 por mês em computação é irrelevante se o SDK consumir várias horas de trabalho da equipe de plataforma. Abaixo dele, manter um sistema maduro com o SDK pode custar quase nada.

Para aplicar limites rígidos de orçamento em qualquer uma das arquiteturas, combine as estimativas de carga com as proteções no nível do projeto apresentadas em Controles de orçamento para APIs de agentes de IA em 2026. Uma estimativa serve para planejamento, não para impor o limite.

Migração para a Agents API: quanto custa sair do SDK

Sair do Agents SDK para a Agents API é uma migração de runtime, não uma simples troca de nome de pacote. As definições dos agentes e os schemas das ferramentas podem parecer familiares, mas IDs de sessão, sessões do SDK, conversas da Responses API, sessões da Agents API e sandboxes são recursos diferentes. Trate o estado como dados que atravessam uma fronteira, e não como um identificador que será transferido intacto.

1. 1

   Congele o contrato de comportamento

   Registre as instruções atuais do agente, os schemas das ferramentas, os pontos de aprovação, o formato da saída, o orçamento de tokens e a política de falhas. Mantenha o modelo e as ferramentas fixos durante a comparação para não confundir uma mudança de qualidade com uma melhoria de runtime.

2. 2

   Mapeie a configuração de agentes e ferramentas

   Transfira o modelo, as instruções, as conexões MCP e as definições de funções para a configuração da Agents API. Os handlers de funções da aplicação ainda precisam de um serviço que receba chamadas e devolva resultados; eles não passam a ser hospedados apenas porque a orquestração migrou.

3. 3

   Defina a fronteira do estado

   Inicie as novas conversas como sessões da Agents API e armazene seus IDs junto aos registros de conversas da aplicação. Mantenha os históricos legados do SDK acessíveis durante a transição. Se o contexto antigo precisar continuar, transforme apenas o estado de negócio necessário em uma entrada explícita, em vez de fingir que uma sessão do SDK é uma sessão da Agents API.

4. 4

   Substitua a infraestrutura do ciclo de vida

   Troque o ponto de entrada do runner dentro do processo pela criação de sessões, eventos, itens salvos, ações obrigatórias, webhooks, cancelamento e exclusão. Adicione idempotência a cada webhook e resultado de função, porque o estado gerenciado não elimina da borda da aplicação o risco de entregas duplicadas.

5. 5

   Rode em paralelo e teste regressões

   Execute o mesmo conjunto de avaliações nos dois caminhos. Compare sucesso da tarefa, total de tokens de entrada e saída, chamadas de ferramentas, tempo decorrido, comportamento de recuperação e intervenção humana. Só desloque o tráfego depois que o novo caminho cumprir o contrato anterior.

Um orçamento ilustrativo de migração torna a troca concreta. Considere um fluxo existente com três ferramentas de função, sessões persistentes e aprovação humana. Aloque 24 horas de engenharia a $150 por hora: 6 horas para configuração e mapeamento de ferramentas, 8 para sessões e ciclo de vida, 6 para webhooks, recuperação e idempotência, e 4 para regressão e verificação de custos. É um custo único de $3,600.

Se, por premissa, compactação, recuperação, sessões e orquestração gerenciadas pouparem 6 horas de engenharia por mês, a economia de mão de obra será de $900 mensais, com retorno em quatro meses. Se o caminho atual com o SDK exigir apenas atenção ocasional, o retorno pode desaparecer. As premissas são o ponto central: o que justifica a migração é a redução do trabalho operacional, não um token mais barato.

Quem não deve migrar para a Agents API?

Não migre se os controles de dados do beta público não passarem pela análise da área de compras. A visão geral atual da Agents API informa que a residência de dados está limitada aos Estados Unidos e que Zero Data Retention não é compatível. Um sandbox self-hosted não muda essa política, pois o harness e a sessão continuam no serviço gerenciado.

Continue no Agents SDK se qualquer uma destas condições for verdadeira:

• O runtime precisa rodar sob um scheduler personalizado, um limite transacional ou uma meta de latência controlada diretamente pela aplicação.
• As políticas de armazenamento, exportação de traces ou residência de dados não se encaixam no beta público gerenciado.
• O agente depende da flexibilidade de provedores ou de uma abstração de modelos que não deve ficar vinculada ao harness do Codex.
• O sistema atual com o SDK já tem compactação, recuperação, observabilidade e implantação confiáveis, com pouca manutenção recorrente.
• A maior parte do trabalho é curta e stateless, de modo que uma sessão durável gerenciada elimina pouca infraestrutura.

O beta público também exige uma decisão sobre o estágio da versão. A OpenAI afirma que fará iterações rápidas antes da disponibilidade geral. Uma equipe com calendário rígido de gestão de mudanças pode preferir avaliar agora e migrar depois que o contrato se estabilizar.

Também há situações em que o SDK deve ser evitado. Uma startup enxuta não deveria escolhê-lo apenas para escapar de um lock-in teórico enquanto reconstrói, nos bastidores, sessões, recuperação, ciclo de vida do sandbox e orquestração. Controle que o produto nunca usa vira dívida de manutenção.

Para agentes que precisam executar código, compare a camada de ambiente separadamente em Melhores sandboxes de código para agentes de IA em 2026. A escolha do sandbox não responde quem deve controlar o estado da orquestração.

Resultados de clientes são indicativos, não universais

Os primeiros números favorecem o caminho gerenciado, mas são relatos de clientes publicados no post de lançamento da OpenAI em 10 de setembro, e não um benchmark independente e controlado. A SafetyKit relatou uma redução de 60% no custo por caso. A Hypha informou uma queda de 86% nas respostas com falha dos agentes depois de separar o harness gerenciado de seu sandbox. A Ciridae registrou aumento na pontuação de avaliação de 0.71 para 0.85 e redução de latência de 4x.

Esses resultados comprovam que a fronteira do runtime pode fazer diferença. Eles não determinam quanto a sua migração economizará, pois o post não normaliza a arquitetura anterior dos clientes, a combinação de modelos, o volume de tokens, a dificuldade das tarefas nem o trabalho de engenharia. Use esses relatos para justificar uma avaliação paralela, não uma projeção.

Perguntas frequentes sobre OpenAI Agents API e Agents SDK

Por que usar o OpenAI Agents SDK?

Use o OpenAI Agents SDK quando a aplicação precisar controlar diretamente a implantação, o armazenamento, as decisões de aprovação, a implementação das ferramentas e o loop do runtime. Ele oferece os componentes de agentes da OpenAI sem transferir a orquestração para a Agents API gerenciada.

Qual é melhor para mim: OpenAI Agents SDK ou PydanticAI?

Essa é uma comparação distinta entre frameworks. Primeiro, decida se a OpenAI deve gerenciar o harness do Codex por meio da Agents API ou se a aplicação deve controlar o runtime via SDK; depois, compare os frameworks de SDK dentro do segundo caminho.

Qual é o melhor SDK para agentes de IA?

Nenhum SDK é o melhor para todas as arquiteturas. O OpenAI Agents SDK se encaixa bem quando seu loop em TypeScript ou Python, suas ferramentas, handoffs, guardrails, sessões e integrações com a OpenAI atendem à aplicação e a equipe quer controlar a implantação.

O OpenAI Agents SDK é grátis?

O Agents SDK para Python usa a licença MIT, portanto o pacote não cobra licença. Ainda é preciso pagar por chamadas de modelo, ferramentas pagas, serviços de sandbox e pela infraestrutura que executa a aplicação.

Como usar o OpenAI Agents SDK?

Instale o pacote oficial para TypeScript ou Python, defina um agente com instruções e ferramentas, escolha uma única estratégia de estado e execute-o dentro da aplicação. Acrescente aprovações, persistência, tracing e sandbox apenas quando o fluxo precisar desses recursos.

Quanto custa um agente da OpenAI?

Some tokens de entrada, entrada em cache, saída, chamadas de ferramentas, computação do sandbox ou da aplicação, serviços de terceiros e trabalho operacional. Não há tarifa separada pelo harness da Agents API; sob as premissas deste artigo, o ponto de virada do custo direto do ambiente ocorre em 1,334 novas sessões mensais de container de 1 GB, na comparação com um worker compartilhado de $40.

A API da OpenAI é gratuita ou paga?

O uso dos modelos e das ferramentas pagas da OpenAI API é cobrado conforme a tabela de preços da API. Um plano do ChatGPT é um contrato de produto separado e não cobre o uso de API por uma aplicação criada com Agents API ou Agents SDK.

Por que pagar $20 pelo ChatGPT?

Essa é uma decisão de assinatura do ChatGPT, não uma escolha entre Agents API e SDK. A assinatura dá acesso ao produto ChatGPT nos termos do plano; o uso da OpenAI API é cobrado separadamente.

O OpenAI Agent Builder é gratuito ou pago?

O Agent Builder estava incluído no preço padrão dos modelos da API, mas não é nenhum dos runtimes comparados aqui. A OpenAI afirma que está descontinuando o Agent Builder e que o desligamento está programado para 30 de novembro de 2026.

O que fazer na próxima segunda-feira

Escolha um fluxo de longa duração na próxima semana e faça uma comparação paralela. Mantenha constantes o modelo, as instruções, o orçamento de tokens, as ferramentas e o conjunto de avaliações. Coloque as novas conversas de teste na Agents API, preserve os históricos dos usuários no caminho do SDK e use o mesmo ambiente de execução nos dois lados se quiser isolar o valor do harness gerenciado.

Registre o sucesso das tarefas, o total de tokens, as chamadas de ferramentas pagas, as sessões faturadas do sandbox, os incidentes de recuperação, a intervenção humana e o tempo de engenharia. Escolha a Agents API se o trabalho eliminado de sessões e recuperação compensar o controle cedido. Mantenha o Agents SDK se o serviço gerenciado não atender a um requisito de dados ou se economizar tempo operacional insuficiente para recuperar o custo da migração.

Antes de trocar o runtime de um agente, baixe a Lista de verificação para auditoria de workflows de IA.