OpenAI Agents API: o que o harness do Codex assume
A OpenAI aloja o ciclo do Codex para a sua aplicação. Explico as diferenças face ao SDK, a persistência das sessões e os custos que continuam a existir.
A Agents API da OpenAI, lançada em versão beta pública a 10 de setembro de 2026, permite usar a infraestrutura gerida do Codex noutras aplicações. A OpenAI executa o ciclo do agente, enquanto a aplicação fornece a tarefa e recebe resultados. A vantagem é construir menos infraestrutura à volta do modelo, mantendo a responsabilidade pelas ferramentas e pelos acessos. [1] [2]
Qual é a diferença face à Responses API e ao Agents SDK?
A diferença principal é quem executa o agente. Na Agents API, a OpenAI aloja o harness. Com o Agents SDK, o seu código executa uma framework que gere o ciclo. Ao usar diretamente a Responses API, a aplicação assume mais responsabilidade pelos passos entre as respostas do modelo. A documentação de arquitetura e do SDK da OpenAI distingue expressamente estas opções. [2] [9]
O harness é o software à volta do modelo que faz avançar uma tarefa: fornece contexto, chama ferramentas e determina quando é necessária outra chamada ao modelo. Uma chamada isolada é apenas parte desse trabalho. O anúncio da OpenAI inclui gestão de sessões, compactação de contexto e delegação paralela na oferta gerida. A compactação encurta o contexto acumulado para que o agente possa continuar à medida que a conversa cresce. [1]
| Responsabilidade | Responses API | Agents SDK | Agents API |
|---|---|---|---|
| Ciclo do agente | A sua aplicação | SDK no seu ambiente | Alojado pela OpenAI |
| Motivo habitual da escolha | Controlar cada passo | Usar uma framework de agentes | Usar um harness gerido |
| Regras da aplicação | Define-as você | Define-as você | Define-as você |
Vejo isto como uma decisão sobre a operação da aplicação. Se manter o ciclo está a atrasar o produto, entregá-lo à OpenAI pode ser útil. Se controlar cada transição é o que faz a aplicação funcionar, avalie essa troca antes de migrar. Uma API nova não torna obsoleta uma aplicação construída com o SDK.
Uma discussão em r/artificial, a 10 de setembro, mostrou ambas as reações: o interesse em transformar agentes em infraestrutura e as dúvidas sobre os limites do sandbox. É um ponto de partida mais útil do que perguntar se outra framework de agentes está na moda. A pergunta prática é que responsabilidades quer delegar. [8]
Uma sessão persistente conserva todos os ficheiros do agente?
Uma sessão persistente conserva a conversa e o trabalho guardado do agente, mas o ambiente de execução tem o seu próprio tempo de vida. A arquitetura da OpenAI separa a aplicação, o harness alojado e o ambiente. Tratar os três como um único computador permanente seria um erro. [2] [3]
O ambiente é onde as ferramentas executam código e acedem a um espaço de trabalho. Pode ser alojado pela OpenAI ou fornecido pelo programador. Um agente também pode funcionar sem esse ambiente: a opção documentada none não inclui Bash, a ferramenta apply-patch ou um sistema de ficheiros de trabalho, mas permite ferramentas MCP remotas por HTTP. MCP é o protocolo que liga o agente a ferramentas externas. [2]
A documentação de sessões indica que se deve reutilizar o identificador de sessão para continuar o trabalho. Também distingue os elementos guardados dos eventos em direto: uma transmissão interrompida não repete todos os eventos perdidos, pelo que a aplicação precisa de recuperar os elementos guardados ao restabelecer a ligação. É um detalhe técnico com uma consequência direta no produto. A interface tem de recuperar o estado real da tarefa, sem interpretar o silêncio como ausência de atividade. [3]
Para os ficheiros, definiria a entrega explicitamente: o que o agente deve produzir, para onde a aplicação o copiará e que resultado significa que a tarefa terminou. Este requisito pertence ao desenho do produto mesmo quando o fornecedor gere a sessão. Uma conversa bem-sucedida ainda não é um resultado entregue de forma fiável.
Os subagentes paralelos têm permissões independentes?
Os subagentes documentados partilham o sistema de ficheiros e o ambiente do coordenador e herdam os acessos configurados às ferramentas. Eu tratá-los-ia como trabalhadores dentro do mesmo perímetro de segurança. A OpenAI documenta também uma restrição específica da beta: os subagentes não suportam ferramentas de função. [4]
A distinção importa para desenhar a aplicação. Uma ferramenta de função disponibiliza funcionalidades próprias da sua aplicação; as ferramentas MCP remotas são outra via de integração. Se uma tarefa depende de uma função personalizada, não assuma que a delegação dá ao subagente as mesmas capacidades do coordenador. Confirme o acesso suportado antes de lhe atribuir a responsabilidade pelo resultado completo.
Começaria com tarefas independentes e resultados claros, como examinar módulos diferentes, mantendo a integração final no coordenador. Os ficheiros partilhados permitem cooperar, mas também criar alterações sobrepostas. O paralelismo é útil quando os resultados se combinam sem ser necessário desfazer o trabalho dos outros.
Também altera os custos. A OpenAI avisa que acrescentar subagentes pode aumentar o consumo de tokens. Uma execução mais curta pode envolver mais trabalho no total, pelo que «terminou mais cedo» e «custou menos» devem ser medidos separadamente. [4]
Que decisões sobre segurança e dados continuam a ser suas?
As permissões do ambiente continuam a importar porque o código executado pelo agente pode aceder aos ficheiros, credenciais e recursos de rede aí disponíveis. A orientação de segurança da OpenAI recomenda restringir o acesso de saída e manter a chave API da aplicação fora do ambiente de execução. Alojar o ciclo não determina que sistemas de negócio o agente pode alterar. [5]
Para um assistente de revisão de código, começaria pelo acesso ao repositório e por um local onde apresentar as constatações. Permitir implementações em produção ou alterações aos registos de clientes exigiria outra decisão de produto. O limite importante é a ação que a aplicação permite, não a prudência com que o agente se descreve.
Um serviço com estado pode adequar-se a um utilizador que regressa ou a uma tarefa contínua. A aplicação precisa então de definir conscientemente o ciclo de vida desse estado. Decidiria quando conservar ou eliminar as sessões como parte da funcionalidade, antes de as deixar acumular sem limite.
Quanto custa a Agents API?
A OpenAI afirma que a Agents API não acrescenta uma tarifa própria: os programadores pagam os tokens e as ferramentas utilizados. O orçamento relevante cobre, portanto, a tarefa inteira, incluindo chamadas repetidas ao modelo e trabalho delegado. Isso não torna gratuito um agente que continua a trabalhar durante horas. [1]
A página de preços separa os custos dos tokens dos custos das ferramentas. Os contentores de execução alojados são cobrados por recursos e tempo, enquanto ferramentas como a pesquisa na web podem acrescentar custos por chamada. A estimativa deve incluir o ambiente escolhido, não apenas os tokens de saída. [10]
A documentação de observabilidade acrescenta uma limitação aos contadores visíveis na aplicação. A utilização por sessão e turno pode estar incompleta ou mudar, e a OpenAI diz expressamente que estes valores não constituem uma fatura final. Servem para compreender uma execução, enquanto a despesa real deve ser conferida nos registos de faturação. [7]
A minha primeira avaliação seria uma tarefa pequena e repetível, com uma condição clara de conclusão. Registaria se o resultado passou a revisão, que ações externas ocorreram e quanto custou completar a tarefa. Depois compararia esses dados com a aplicação existente, incluindo o trabalho necessário para a manter.
A Agents API merece consideração quando operar a infraestrutura do agente se torna um peso para o produto. A primeira pergunta é concreta: que responsabilidades pelo ciclo, estado e execução pode a OpenAI assumir sem retirar o controlo de que a aplicação precisa?