OpenAI publica la documentació de l'Agents API: sessions que no es perden i l'arnès del Codex com a servei

Què és, exactament, el que s'obre

L'Agents API permet que una aplicació faci servir l'arnès del Codex a través d'una API que gestiona OpenAI. La paraula clau és «gestiona»: segons la documentació, OpenAI s'ocupa de les sessions, de l'orquestració, de la compactació del context i de la recuperació, mentre que l'aplicació que integra el servei hi aporta les eines i tria l'entorn d'execució.

Els agents treballen dins d'un sandbox: allà executen codi, editen fitxers, es connecten a servidors MCP i generen artefactes. No parlem, doncs, d'un model que retorna text, sinó d'un procés capaç d'actuar sobre un sistema de fitxers i sobre serveis externs.

Per començar, la documentació inclou dos exemples complets: crear i executar un script que generi un arbre de directoris en un sandbox allotjat per OpenAI, i comparar notes de versió amb uns quants subagents que després apleguen les seves troballes en una sola resposta.

Quatre conceptes: Agent, Environment, Session, Events

L'API es basa en quatre peces. L'Agent defineix el model, les instruccions, les eines i els servidors MCP disponibles. L'Environment és un sandbox o una màquina opcional on l'agent accedeix a fitxers, carrega skills i executa ordres. La Session és una instància duradora d'un agent que va avançant en les seves tasques i atén entrades noves. I els Events i els Items són, respectivament, allò que s'envia a l'agent i allò que ell produeix durant la sessió.

El cicle de vida que descriu la documentació té quatre passos. Primer es crea la sessió i OpenAI n'aprovisiona l'entorn. Després se li encarrega una tasca: quan l'entorn és a punt, l'entrada de l'usuari engega un torn de feina. Tot seguit se'n segueix el progrés, ja sigui rebent la sortida en streaming o bé amb webhooks que avisen quan l'agent acaba o quan necessita que algú hi intervingui. I, finalment, es continua o es reorienta la feina, enviant una altra tasca a la mateixa sessió o guiant l'agent durant el torn que té entre mans.

En la modalitat allotjada per OpenAI, l'aplicació envia entrades i rep esdeveniments; OpenAI executa l'agent i aprovisiona i administra el seu sandbox. Per a la configuració i els límits de cada modalitat, la documentació remet a les opcions d'entorn.

Què ofereix l'arnès gestionat

La documentació enumera què sap fer l'arnès gestionat del Codex: executar ordres i codi en un sandbox; aplicar les skills i les instruccions que toquin en cada cas; connectar-se a dades externes amb eines o via MCP; deixar que l'usuari reorienti (steering) l'agent mentre treballa; resumir el que ja s'ha fet per no desbordar la finestra de context; partir la feina en subtasques i repartir-les entre subagents; i reprendre una sessió allà on s'havia quedat.

Tot això es configura en crear la sessió. L'exemple en Python de la documentació defineix un agent amb el model gpt-6-astra, instruccions per respondre preguntes tècniques basant-se en l'MCP de documentació d'OpenAI i en web search, eines de programmatic_tool_calling, un servidor MCP declarat per transport HTTP contra https://developers.openai.com/mcp i un bloc multi_agent amb fins a quatre subagents en paral·lel.

En aquest mateix exemple l'entorn és de tipus self_hosted, amb un workspace_directory que apunta a /workspace i un capability_directories que assenyala /workspace/capabilities/skills. La crida retorna un identificador de sessió amb el qual es pot continuar treballant.

Casos d'ús i aplicacions de referència

A banda dels exemples mínims, OpenAI publica aplicacions completes que ensenyen fins on arriba la idea: un agent de resposta a incidents que investiga alertes i demana aprovació abans d'executar accions de recuperació; un bot de Slack que atén peticions amb les eines de treball connectades; un analista de dades que respon preguntes sobre un magatzem de dades amb SQL de només lectura; un investigador d'issues de GitHub que reprodueix els bugs notificats i hi publica les seves troballes; i un revisor de documents que s'ajuda de skills de política i d'agents especialitzats.

El patró es repeteix: autonomia amb límits i punts de control humans. L'agent d'incidents, per exemple, demana aprovació explícita abans de qualsevol acció de recuperació, i l'analista de dades només pot llegir, mai escriure.

Preus, dades i la lletra petita

Fer servir agents no afegeix cap tarifa pròpia: l'ús del model es cobra al preu d'API del model triat, les eines d'OpenAI apliquen les seves tarifes estàndard i els sandboxes allotjats per OpenAI es facturen a les tarifes estàndard de contenidor.

El que més pesa en qualsevol desplegament corporatiu són les restriccions sobre les dades, i aquí la documentació no deixa marge: de moment l'Agents API només ofereix residència de dades als Estats Units i no admet Zero Data Retention (ZDR, retenció zero de dades). Hi afegeix, a més, un matís que val la pena llegir dues vegades: triar un sandbox self-hosted tampoc no fa que l'Agents API sigui elegible per a ZDR.

Sí que es poden esborrar les sessions i els artefactes publicats quan ja no fan falta. Per als detalls sobre residència i retenció, la documentació remet a la secció de controls de dades de la plataforma d'OpenAI.