Agents API da OpenAI: como funciona o serviço gerenciado de agentes sobre o Codex harness

A OpenAI anunciou a Agents API, um serviço gerenciado para construir e rodar agentes na nuvem em cima do mesmo Codex harness que ela usa nos próprios produtos. A proposta é que você vá da ideia a um agente funcionando mais rápido: você constrói e executa agentes na nuvem com o Codex harness, e a OpenAI cuida de orquestração, sessões longas e gerenciamento de contexto. O anúncio saiu na Developer Community da OpenAI e a API entrou em beta pública, oferecendo um toolkit para criar e rodar agentes na nuvem, construído sobre o Codex harness, com foco em agentes de longa duração, orquestração em tempo real, uso de ferramentas e infraestrutura escalável.

Este artigo explica o que dá para entender do mecanismo a partir da documentação atual, o que já é possível reproduzir, onde a coisa quebra e o que ainda não está claro. Como o anúncio original é curto, boa parte do que segue vem do guia oficial em platform.openai.com/docs/guides/agents-sdk e da Developer Community.

O que a Agents API é (e o que ela não é)

A OpenAI hoje oferece dois caminhos para rodar agentes: a Agents API (serviço gerenciado) e o Agents SDK (biblioteca que você roda no seu processo). A diferença é onde a orquestração acontece e quem guarda estado entre as tarefas. Você escolhe um runtime com base em onde a orquestração deve rodar e quem deve gerenciar o estado entre tarefas: a Agents API roda o Codex harness e administra a infraestrutura do agente para que você foque no que os agentes fazem.

Já o SDK é o oposto: ele dá à sua aplicação controle sobre deploy, armazenamento, aprovações e integração de runtime, e o runner dele lida com o loop do agente e os handoffs. Então a decisão prática é: quer entregar a orquestração para a OpenAI ou quer rodar no seu próprio processo?

A Agents API não é um modelo novo. Ela é a camada de execução (o “harness”) empacotada como serviço. A Agents API usa o mesmo Codex harness que roda por baixo das próprias ferramentas da OpenAI, como o ChatGPT for Work. Isso importa porque o harness é justamente a parte que decide como o modelo raciocina em loop, chama ferramenta, retoma sessão e comprime contexto. É diferente de trocar de modelo.

Como o Codex harness funciona por baixo

Vale gastar um parágrafo no harness em si, porque ele é o motor da Agents API. Um harness, nesse contexto, é o “runtime” que executa o loop de um agente: recebe uma tarefa, chama o modelo, interpreta se ele quer usar ferramenta, executa a ferramenta, devolve o resultado para o modelo e repete até chegar a um ponto de parada. O harness administra o loop de execução dos agentes, incluindo compreensão de tarefa, retenção de memória em conversas longas, streaming de eventos em tempo real, invocação de ferramentas, interrompibilidade, sincronização de status e fluxos de aprovação com humano no loop.

O código do harness, aliás, é aberto. Em agosto de 2026 a OpenAI abriu o código do harness sob licença Apache-2.0, permitindo modificar, embutir e comercializar o framework sem depender de uma interface de chat genérica. A Agents API é a versão gerenciada disso: em vez de você subir o app-server, cuidar de sandbox, persistir sessões e integrar MCP na mão, você chama uma API HTTP e recebe agentes rodando.

O que a versão gerenciada entrega em cima do harness

A documentação lista, especificamente, quatro coisas que a Agents API dá pronto. A Agents API roda o Codex harness e administra a infraestrutura do agente, e inclui compactação automática de contexto, orquestração multi-agente, chamada programática de ferramentas e suporte a servidores MCP. Vale destrinchar cada um:

• Compactação automática de contexto: conversas longas estouram a janela do modelo. A abordagem é substituir a história longa por uma lista mais curta e equivalente. O OpenAIResponsesCompactionSession usa a Responses API para substituir uma história longa por uma lista mais curta e equivalente de itens de conversa, e a cada turno persistido o runner passa o último responseId para runCompaction, que chama responses.compact quando o hook de decisão retorna true. A Agents API faz isso por você, sem você ter que decidir quando comprimir.
• Orquestração multi-agente (subagentes): em vez de um agente único fazendo tudo em série, você delega partes da tarefa a subagentes que rodam em paralelo. O harness permite que agentes lidem com tarefas complexas, incluindo rodar código, gerenciar contexto ao longo de sessões longas e coordenar subagentes, e a API introduz suporte multi-agente para paralelizar cargas de trabalho delegando tarefas a múltiplos subagentes. Segundo Jack Weissenberger, CTO da Ciridae citado no anúncio, essa feature cortou latência em 4x nos fluxos deles. Vale marcar: esse número é um caso reportado por um cliente, não é benchmark.
• Chamada programática de ferramentas: em vez de o modelo decidir cada tool call em cada turno, dá para roteirizar o encadeamento em código, o que reduz idas e vindas com o modelo.
• Suporte a MCP: Model Context Protocol, o protocolo aberto que a Anthropic definiu e que virou padrão de fato para expor ferramentas a agentes. Se você já tem servidores MCP internos, plugam sem adaptação.

Onde rodam os agentes

A Agents API não obriga a usar sandboxes da OpenAI. Uma parte-chave é a flexibilidade: desenvolvedores podem fazer deploy usando os sandboxes gerenciados da OpenAI ou a própria infraestrutura, com integrações de parceiros como Cloudflare, DigitalOcean e Oracle. Essa modularidade permite ajustar agentes a workflows específicos, com opções de compute, storage e configuração de custo customizadas. Ou seja: dá para separar quem faz a orquestração (OpenAI) de onde o código do agente efetivamente executa (você).

Como isso muda o que você escreve na prática

Para dar concretude, vale contrastar com o padrão do Agents SDK, que é o que a maior parte das pessoas conhece hoje. O loop no SDK é assim:

import { Agent, MemorySession, run } from "@openai/agents";

const agent = new Agent({
 name: "Tour guide",
 instructions: "Answer with compact travel facts.",
});

const session = new MemorySession();

// primeira pergunta
const firstTurn = await run(agent, "What city is the Golden Gate Bridge in?", { session });

// segunda pergunta, mesma sessão, contexto preservado
const secondTurn = await run(agent, "What state is it in?", { session });

Esse snippet vem direto do guia “Running agents” da OpenAI. Uma execução do SDK é um turno em nível de aplicação: o runner fica em loop até chegar a um ponto de parada real, chamando o modelo do agente atual com o input preparado, inspecionando a saída e, se o modelo produziu tool calls, executando-as e continuando. Repare que aqui você mantém o processo Node vivo, você guarda a sessão em memória (ou em SQLite, ou no que for) e você gerencia falhas.

Na Agents API, esse loop vira estado do lado do servidor. Uma sessão da Agents API, uma sessão do SDK, uma conversation da Responses e uma sandbox são recursos diferentes, e você deve seguir as instruções de estado e limpeza do runtime que escolher. Essa frase da documentação é importante: são quatro conceitos parecidos, mas com ciclo de vida distinto, e misturar os quatro no mesmo agente é o tipo de coisa que gera bug silencioso.

Sessões longas de verdade

O ponto de venda mais forte da Agents API é a sessão longa gerenciada. Se você já tentou rodar um agente que precisa esperar horas por uma aprovação humana, sabe que manter o processo vivo, tratar reconexão e reidratar contexto dá trabalho. O harness já resolve isso do lado do servidor, e a Agents API expõe isso como serviço. O servidor unificado mantém sessões longas e pedidos de aprovação consistentes entre interfaces cliente.

Onde isso quebra ou não vale a pena

Alguns pontos honestos, alguns baseados na documentação, outros no bom senso de engenharia:

• Lock-in de runtime. A Agents API é gerenciada pela OpenAI. Se amanhã você quiser trocar de provedor de modelo, o harness open-source ainda existe, mas a versão gerenciada não é portável. Vale para qualquer serviço gerenciado, e vale aqui.
• Modelo continua sendo custo à parte. Você pode rodar, modificar e comercializar o código do harness sob Apache 2.0, mas a inferência dos modelos ainda exige acesso à API da OpenAI ou termos elegíveis de assinatura do Codex. Ou seja, gerenciar o loop não te custa infra, mas continua custando tokens.
• Complexidade conceitual. Como notei acima, existem pelo menos quatro recursos com nome parecido (sessão da Agents API, sessão do SDK, conversation da Responses, sandbox). Documentação em beta significa que a fronteira entre eles vai mexer.
• Debugabilidade. Loops de agente já são difíceis de debugar quando rodam no seu processo. Quando rodam gerenciados, você depende do observability que o serviço expõe. A documentação menciona uma seção específica de “Agents API observability and usage” para session accounting, mas o quanto isso é suficiente para investigar um caso patológico só dá para dizer usando.
• Sessões longas viram fatura longa. Compactação automática ajuda, mas um agente que fica de pé por dias, se não tiver política clara de encerramento, acumula custo. É um alerta genérico de arquitetura, não um dado do produto.

O que ainda não dá para afirmar

O anúncio original é curto e boa parte da documentação técnica ainda está sendo publicada. Alguns pontos que deliberadamente não afirmei acima:

• Latência real da orquestração gerenciada versus rodar o app-server localmente. Não há números comparáveis publicados.
• Limites de duração de sessão, limites de subagentes concorrentes e limites de tamanho de contexto após compactação. Não estão claros no material público consultado.
• Preço. O anúncio menciona que o serviço é gerenciado, mas não há tabela de preço específica da Agents API separada do custo de tokens dos modelos subjacentes.
• SLA e garantias de disponibilidade em beta. Beta pública normalmente significa “sem SLA formal”, mas isso precisa ser confirmado no contrato.
• O caso reportado de “latência 4x menor com subagentes” citado pela Ciridae é um relato de cliente, não um benchmark reproduzível.

Como testar isso você mesmo

Um caminho curto para formar opinião sem investir muito:

• Comece pelo Agents SDK, não pela Agents API. Rode o exemplo de duas perguntas em sequência com MemorySession (o snippet acima). Isso te dá o modelo mental do loop.
• Adicione uma ferramenta simples via function calling (por exemplo, uma função que consulta uma API pública de clima). Observe no log quantas voltas o modelo dá antes de parar.
• Troque MemorySession por SQLiteSession para ver persistência entre execuções do processo. O guia oficial mostra que sessões diferentes mantêm históricos de conversa separados, e que agentes diferentes podem compartilhar a mesma sessão.
• Só depois disso, migre o mesmo agente para a Agents API. A diferença que você deve sentir é: o estado da sessão deixa de morar no seu processo e passa a viver no serviço. Meça latência dos dois lados antes de decidir.
• Se você já usa MCP internamente, plugue um servidor MCP existente. O suporte nativo é justamente um dos pontos da Agents API.

O critério para adotar não é “é novo, vamos usar”. É: o custo de manter um harness rodando no meu ambiente é maior do que o custo de depender do serviço gerenciado? Se você já tem infraestrutura de workers duráveis (Temporal, Dapr, Restate, fila própria), talvez a Agents API não resolva tanto quanto parece. Se você está começando do zero e o agente precisa viver por horas ou dias, ela remove trabalho real.

Fontes: anúncio original na Developer Community da OpenAI (community.openai.com/t/introducing-the-agents-api-and-hosted-sandboxes), guia oficial da Agents API em platform.openai.com/docs/guides/agents-sdk, cobertura do Blockchain.News sobre o beta público, e documentação do Codex harness open-source publicada em agosto de 2026.