{"id":704,"date":"2026-09-10T18:34:43","date_gmt":"2026-09-10T21:34:43","guid":{"rendered":"https:\/\/yellowkode.com\/blog\/agents-api-openai-codex-harness-servico-gerenciado\/"},"modified":"2026-09-10T18:34:43","modified_gmt":"2026-09-10T21:34:43","slug":"agents-api-openai-codex-harness-servico-gerenciado","status":"publish","type":"post","link":"https:\/\/yellowkode.com\/blog\/agents-api-openai-codex-harness-servico-gerenciado\/","title":{"rendered":"Agents API da OpenAI: como funciona o servi\u00e7o gerenciado de agentes sobre o Codex harness"},"content":{"rendered":"

A OpenAI anunciou a Agents API, um servi\u00e7o gerenciado para construir e rodar agentes na nuvem em cima do mesmo Codex harness que ela usa nos pr\u00f3prios produtos. A proposta \u00e9 que voc\u00ea v\u00e1 da ideia a um agente funcionando mais r\u00e1pido: voc\u00ea constr\u00f3i e executa agentes na nuvem com o Codex harness, e a OpenAI cuida de orquestra\u00e7\u00e3o, sess\u00f5es longas e gerenciamento de contexto. O an\u00fancio saiu na Developer Community da OpenAI e a API entrou em beta p\u00fablica, oferecendo um toolkit para criar e rodar agentes na nuvem, constru\u00eddo sobre o Codex harness, com foco em agentes de longa dura\u00e7\u00e3o, orquestra\u00e7\u00e3o em tempo real, uso de ferramentas e infraestrutura escal\u00e1vel.<\/p>\n

Este artigo explica o que d\u00e1 para entender do mecanismo a partir da documenta\u00e7\u00e3o atual, o que j\u00e1 \u00e9 poss\u00edvel reproduzir, onde a coisa quebra e o que ainda n\u00e3o est\u00e1 claro. Como o an\u00fancio original \u00e9 curto, boa parte do que segue vem do guia oficial em platform.openai.com\/docs\/guides\/agents-sdk<\/code> e da Developer Community.<\/p>\n

O que a Agents API \u00e9 (e o que ela n\u00e3o \u00e9)<\/h2>\n

A OpenAI hoje oferece dois caminhos para rodar agentes: a Agents API (servi\u00e7o gerenciado) e o Agents SDK (biblioteca que voc\u00ea roda no seu processo). A diferen\u00e7a \u00e9 onde a orquestra\u00e7\u00e3o acontece e quem guarda estado entre as tarefas. Voc\u00ea escolhe um runtime com base em onde a orquestra\u00e7\u00e3o 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\u00ea foque no que os agentes fazem.<\/p>\n

J\u00e1 o SDK \u00e9 o oposto: ele d\u00e1 \u00e0 sua aplica\u00e7\u00e3o controle sobre deploy, armazenamento, aprova\u00e7\u00f5es e integra\u00e7\u00e3o de runtime, e o runner dele lida com o loop do agente e os handoffs. Ent\u00e3o a decis\u00e3o pr\u00e1tica \u00e9: quer entregar a orquestra\u00e7\u00e3o para a OpenAI ou quer rodar no seu pr\u00f3prio processo?<\/p>\n

A Agents API n\u00e3o \u00e9 um modelo novo. Ela \u00e9 a camada de execu\u00e7\u00e3o (o “harness”) empacotada como servi\u00e7o. A Agents API usa o mesmo Codex harness que roda por baixo das pr\u00f3prias ferramentas da OpenAI, como o ChatGPT for Work. Isso importa porque o harness \u00e9 justamente a parte que decide como o modelo raciocina em loop, chama ferramenta, retoma sess\u00e3o e comprime contexto. \u00c9 diferente de trocar de modelo.<\/p>\n

Como o Codex harness funciona por baixo<\/h2>\n

Vale gastar um par\u00e1grafo no harness em si, porque ele \u00e9 o motor da Agents API. Um harness, nesse contexto, \u00e9 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\u00e9 chegar a um ponto de parada. O harness administra o loop de execu\u00e7\u00e3o dos agentes, incluindo compreens\u00e3o de tarefa, reten\u00e7\u00e3o de mem\u00f3ria em conversas longas, streaming de eventos em tempo real, invoca\u00e7\u00e3o de ferramentas, interrompibilidade, sincroniza\u00e7\u00e3o de status e fluxos de aprova\u00e7\u00e3o com humano no loop.<\/p>\n

O c\u00f3digo do harness, ali\u00e1s, \u00e9 aberto. Em agosto de 2026 a OpenAI abriu o c\u00f3digo do harness sob licen\u00e7a Apache-2.0, permitindo modificar, embutir e comercializar o framework sem depender de uma interface de chat gen\u00e9rica. A Agents API \u00e9 a vers\u00e3o gerenciada disso: em vez de voc\u00ea subir o app-server<\/code>, cuidar de sandbox, persistir sess\u00f5es e integrar MCP na m\u00e3o, voc\u00ea chama uma API HTTP e recebe agentes rodando.<\/p>\n

O que a vers\u00e3o gerenciada entrega em cima do harness<\/h3>\n

A documenta\u00e7\u00e3o lista, especificamente, quatro coisas que a Agents API d\u00e1 pronto. A Agents API roda o Codex harness e administra a infraestrutura do agente, e inclui compacta\u00e7\u00e3o autom\u00e1tica de contexto, orquestra\u00e7\u00e3o multi-agente, chamada program\u00e1tica de ferramentas e suporte a servidores MCP. Vale destrinchar cada um:<\/p>\n

    \n
  • Compacta\u00e7\u00e3o autom\u00e1tica de contexto:<\/strong> conversas longas estouram a janela do modelo. A abordagem \u00e9 substituir a hist\u00f3ria longa por uma lista mais curta e equivalente. O OpenAIResponsesCompactionSession<\/code> usa a Responses API para substituir uma hist\u00f3ria longa por uma lista mais curta e equivalente de itens de conversa, e a cada turno persistido o runner passa o \u00faltimo responseId<\/code> para runCompaction<\/code>, que chama responses.compact<\/code> quando o hook de decis\u00e3o retorna true<\/code>. A Agents API faz isso por voc\u00ea, sem voc\u00ea ter que decidir quando comprimir.<\/li>\n
  • Orquestra\u00e7\u00e3o multi-agente (subagentes):<\/strong> em vez de um agente \u00fanico fazendo tudo em s\u00e9rie, voc\u00ea delega partes da tarefa a subagentes que rodam em paralelo. O harness permite que agentes lidem com tarefas complexas, incluindo rodar c\u00f3digo, gerenciar contexto ao longo de sess\u00f5es longas e coordenar subagentes, e a API introduz suporte multi-agente para paralelizar cargas de trabalho delegando tarefas a m\u00faltiplos subagentes. Segundo Jack Weissenberger, CTO da Ciridae citado no an\u00fancio, essa feature cortou lat\u00eancia em 4x nos fluxos deles. Vale marcar: esse n\u00famero \u00e9 um caso reportado por um cliente, n\u00e3o \u00e9 benchmark.<\/li>\n
  • Chamada program\u00e1tica de ferramentas:<\/strong> em vez de o modelo decidir cada tool call em cada turno, d\u00e1 para roteirizar o encadeamento em c\u00f3digo, o que reduz idas e vindas com o modelo.<\/li>\n
  • Suporte a MCP:<\/strong> Model Context Protocol, o protocolo aberto que a Anthropic definiu e que virou padr\u00e3o de fato para expor ferramentas a agentes. Se voc\u00ea j\u00e1 tem servidores MCP internos, plugam sem adapta\u00e7\u00e3o.<\/li>\n<\/ul>\n

    Onde rodam os agentes<\/h3>\n

    A Agents API n\u00e3o obriga a usar sandboxes da OpenAI. Uma parte-chave \u00e9 a flexibilidade: desenvolvedores podem fazer deploy usando os sandboxes gerenciados da OpenAI ou a pr\u00f3pria infraestrutura, com integra\u00e7\u00f5es de parceiros como Cloudflare, DigitalOcean e Oracle. Essa modularidade permite ajustar agentes a workflows espec\u00edficos, com op\u00e7\u00f5es de compute, storage e configura\u00e7\u00e3o de custo customizadas. Ou seja: d\u00e1 para separar quem faz a orquestra\u00e7\u00e3o (OpenAI) de onde o c\u00f3digo do agente efetivamente executa (voc\u00ea).<\/p>\n

    Como isso muda o que voc\u00ea escreve na pr\u00e1tica<\/h2>\n

    Para dar concretude, vale contrastar com o padr\u00e3o do Agents SDK, que \u00e9 o que a maior parte das pessoas conhece hoje. O loop no SDK \u00e9 assim:<\/p>\n

    import { Agent, MemorySession, run } from \"@openai\/agents\";\n\nconst agent = new Agent({\n name: \"Tour guide\",\n instructions: \"Answer with compact travel facts.\",\n});\n\nconst session = new MemorySession();\n\n\/\/ primeira pergunta\nconst firstTurn = await run(agent, \"What city is the Golden Gate Bridge in?\", { session });\n\n\/\/ segunda pergunta, mesma sess\u00e3o, contexto preservado\nconst secondTurn = await run(agent, \"What state is it in?\", { session });\n<\/code><\/pre>\n
    Esse snippet vem direto do guia “Running agents” da OpenAI. Uma execu\u00e7\u00e3o do SDK \u00e9 um turno em n\u00edvel de aplica\u00e7\u00e3o: o runner fica em loop at\u00e9 chegar a um ponto de parada real, chamando o modelo do agente atual com o input preparado, inspecionando a sa\u00edda e, se o modelo produziu tool calls, executando-as e continuando. Repare que aqui voc\u00ea<\/em> mant\u00e9m o processo Node vivo, voc\u00ea<\/em> guarda a sess\u00e3o em mem\u00f3ria (ou em SQLite, ou no que for) e voc\u00ea<\/em> gerencia falhas.<\/p>\n
    Na Agents API, esse loop vira estado do lado do servidor. Uma sess\u00e3o da Agents API, uma sess\u00e3o do SDK, uma conversation da Responses e uma sandbox s\u00e3o recursos diferentes, e voc\u00ea deve seguir as instru\u00e7\u00f5es de estado e limpeza do runtime que escolher. Essa frase da documenta\u00e7\u00e3o \u00e9 importante: s\u00e3o quatro conceitos parecidos, mas com ciclo de vida distinto, e misturar os quatro no mesmo agente \u00e9 o tipo de coisa que gera bug silencioso.<\/p>\n
    Sess\u00f5es longas de verdade<\/h3>\n
    O ponto de venda mais forte da Agents API \u00e9 a sess\u00e3o longa gerenciada. Se voc\u00ea j\u00e1 tentou rodar um agente que precisa esperar horas por uma aprova\u00e7\u00e3o humana, sabe que manter o processo vivo, tratar reconex\u00e3o e reidratar contexto d\u00e1 trabalho. O harness j\u00e1 resolve isso do lado do servidor, e a Agents API exp\u00f5e isso como servi\u00e7o. O servidor unificado mant\u00e9m sess\u00f5es longas e pedidos de aprova\u00e7\u00e3o consistentes entre interfaces cliente.<\/p>\n
    Onde isso quebra ou n\u00e3o vale a pena<\/h2>\n
    Alguns pontos honestos, alguns baseados na documenta\u00e7\u00e3o, outros no bom senso de engenharia:<\/p>\n
      \n
    • Lock-in de runtime.<\/strong> A Agents API \u00e9 gerenciada pela OpenAI. Se amanh\u00e3 voc\u00ea quiser trocar de provedor de modelo, o harness open-source ainda existe, mas a vers\u00e3o gerenciada n\u00e3o \u00e9 port\u00e1vel. Vale para qualquer servi\u00e7o gerenciado, e vale aqui.<\/li>\n
    • Modelo continua sendo custo \u00e0 parte.<\/strong> Voc\u00ea pode rodar, modificar e comercializar o c\u00f3digo do harness sob Apache 2.0, mas a infer\u00eancia dos modelos ainda exige acesso \u00e0 API da OpenAI ou termos eleg\u00edveis de assinatura do Codex. Ou seja, gerenciar o loop n\u00e3o te custa infra, mas continua custando tokens.<\/li>\n
    • Complexidade conceitual.<\/strong> Como notei acima, existem pelo menos quatro recursos com nome parecido (sess\u00e3o da Agents API, sess\u00e3o do SDK, conversation da Responses, sandbox). Documenta\u00e7\u00e3o em beta significa que a fronteira entre eles vai mexer.<\/li>\n
    • Debugabilidade.<\/strong> Loops de agente j\u00e1 s\u00e3o dif\u00edceis de debugar quando rodam no seu processo. Quando rodam gerenciados, voc\u00ea depende do observability que o servi\u00e7o exp\u00f5e. A documenta\u00e7\u00e3o menciona uma se\u00e7\u00e3o espec\u00edfica de “Agents API observability and usage” para session accounting<\/em>, mas o quanto isso \u00e9 suficiente para investigar um caso patol\u00f3gico s\u00f3 d\u00e1 para dizer usando.<\/li>\n
    • Sess\u00f5es longas viram fatura longa.<\/strong> Compacta\u00e7\u00e3o autom\u00e1tica ajuda, mas um agente que fica de p\u00e9 por dias, se n\u00e3o tiver pol\u00edtica clara de encerramento, acumula custo. \u00c9 um alerta gen\u00e9rico de arquitetura, n\u00e3o um dado do produto.<\/li>\n<\/ul>\n
      O que ainda n\u00e3o d\u00e1 para afirmar<\/h2>\n
      O an\u00fancio original \u00e9 curto e boa parte da documenta\u00e7\u00e3o t\u00e9cnica ainda est\u00e1 sendo publicada. Alguns pontos que deliberadamente n\u00e3o afirmei acima:<\/p>\n
        \n
      • Lat\u00eancia real da orquestra\u00e7\u00e3o gerenciada versus rodar o app-server<\/code> localmente. N\u00e3o h\u00e1 n\u00fameros compar\u00e1veis publicados.<\/li>\n
      • Limites de dura\u00e7\u00e3o de sess\u00e3o, limites de subagentes concorrentes e limites de tamanho de contexto ap\u00f3s compacta\u00e7\u00e3o. N\u00e3o est\u00e3o claros no material p\u00fablico consultado.<\/li>\n
      • Pre\u00e7o. O an\u00fancio menciona que o servi\u00e7o \u00e9 gerenciado, mas n\u00e3o h\u00e1 tabela de pre\u00e7o espec\u00edfica da Agents API separada do custo de tokens dos modelos subjacentes.<\/li>\n
      • SLA e garantias de disponibilidade em beta. Beta p\u00fablica normalmente significa “sem SLA formal”, mas isso precisa ser confirmado no contrato.<\/li>\n
      • O caso reportado de “lat\u00eancia 4x menor com subagentes” citado pela Ciridae \u00e9 um relato de cliente, n\u00e3o um benchmark reproduz\u00edvel.<\/li>\n<\/ul>\n
        Como testar isso voc\u00ea mesmo<\/h2>\n
        Um caminho curto para formar opini\u00e3o sem investir muito:<\/p>\n
          \n
        • Comece pelo Agents SDK, n\u00e3o pela Agents API. Rode o exemplo de duas perguntas em sequ\u00eancia com MemorySession<\/code> (o snippet acima). Isso te d\u00e1 o modelo mental do loop.<\/li>\n
        • Adicione uma ferramenta simples via function calling (por exemplo, uma fun\u00e7\u00e3o que consulta uma API p\u00fablica de clima). Observe no log quantas voltas o modelo d\u00e1 antes de parar.<\/li>\n
        • Troque MemorySession<\/code> por SQLiteSession<\/code> para ver persist\u00eancia entre execu\u00e7\u00f5es do processo. O guia oficial mostra que sess\u00f5es diferentes mant\u00eam hist\u00f3ricos de conversa separados, e que agentes diferentes podem compartilhar a mesma sess\u00e3o.<\/li>\n
        • S\u00f3 depois disso, migre o mesmo agente para a Agents API. A diferen\u00e7a que voc\u00ea deve sentir \u00e9: o estado da sess\u00e3o deixa de morar no seu processo e passa a viver no servi\u00e7o. Me\u00e7a lat\u00eancia dos dois lados antes de decidir.<\/li>\n
        • Se voc\u00ea j\u00e1 usa MCP internamente, plugue um servidor MCP existente. O suporte nativo \u00e9 justamente um dos pontos da Agents API.<\/li>\n<\/ul>\n
          O crit\u00e9rio para adotar n\u00e3o \u00e9 “\u00e9 novo, vamos usar”. \u00c9: o custo de manter um harness rodando no meu ambiente \u00e9 maior do que o custo de depender do servi\u00e7o gerenciado? Se voc\u00ea j\u00e1 tem infraestrutura de workers dur\u00e1veis (Temporal, Dapr, Restate, fila pr\u00f3pria), talvez a Agents API n\u00e3o resolva tanto quanto parece. Se voc\u00ea est\u00e1 come\u00e7ando do zero e o agente precisa viver por horas ou dias, ela remove trabalho real.<\/p>\n
          Fontes: an\u00fancio original na Developer Community da OpenAI (community.openai.com\/t\/introducing-the-agents-api-and-hosted-sandboxes<\/code>), guia oficial da Agents API em platform.openai.com\/docs\/guides\/agents-sdk<\/code>, cobertura do Blockchain.News sobre o beta p\u00fablico, e documenta\u00e7\u00e3o do Codex harness open-source publicada em agosto de 2026.<\/p>\n","protected":false},"excerpt":{"rendered":"
          Entenda como a Agents API da OpenAI roda o Codex harness como servi\u00e7o gerenciado, com sess\u00f5es longas, subagentes, MCP e sandboxes hospedados.<\/p>\n","protected":false},"author":2,"featured_media":703,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-704","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts\/704","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/comments?post=704"}],"version-history":[{"count":0,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/posts\/704\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/media\/703"}],"wp:attachment":[{"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/media?parent=704"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/categories?post=704"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/yellowkode.com\/blog\/wp-json\/wp\/v2\/tags?post=704"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}