Del model a l'agent: equipant l'API Responses amb un entorn informàtic

Actualment estem passant d'utilitzar models, que excel·leixen en tasques concretes, a utilitzar agents capaços de gestionar fluxos de treball complexos. Mitjançant indicacions als models, només podeu accedir a la intel·ligència entrenada. Tanmateix, donar al model un entorn informàtic pot aconseguir una gamma molt més àmplia de casos d'ús, com ara executar serveis, sol·licitar dades d'API o generar artefactes més útils com fulls de càlcul o informes.

Sorgeixen alguns problemes pràctics quan intenteu construir agents: on posar fitxers intermedis, com evitar enganxar taules grans en una indicació, com donar accés a la xarxa al flux de treball sense crear un maldecap de seguretat, i com gestionar temps d'espera i reintents sense haver de construir vosaltres mateixos un sistema de flux de treball.

En lloc de carregar als desenvolupadors la creació dels seus propis entorns d'execució, vam construir els components necessaris per equipar l'API Responses⁠(s'obre en una finestra nova) amb un entorn informàtic per executar de manera fiable tasques del món real.

L'API Responses d'OpenAI, juntament amb l'eina shell i un espai de treball de contenidor allotjat, està dissenyada per abordar aquests problemes pràctics. El model proposa passos i comandes; la plataforma els executa en un entorn aïllat amb un sistema de fitxers per a entrades i sortides, emmagatzematge estructurat opcional (com SQLite) i accés restringit a la xarxa. 

En aquest article, desglossarem com vam construir un entorn informàtic per a agents i compartirem algunes lliçons primerenques sobre com fer-lo servir per a fluxos de treball de producció més ràpids, més repetibles i més segurs.

Un bon flux de treball d'agent comença amb un bucle d'execució ajustat: el model proposa una acció com ara llegir fitxers o obtenir dades amb API, la plataforma l'executa i el resultat alimenta el pas següent. Començarem amb l'eina shell —la manera més senzilla de veure aquest bucle en acció— i després cobrirem l'espai de treball del contenidor, la xarxa, les habilitats reutilitzables i la compactació del context.

Per entendre l'eina shell, primer és útil entendre com un model de llenguatge fa servir eines en general: per fer coses com ara cridar una funció o interactuar amb un ordinador. Durant l'entrenament, es mostren al model exemples de com es fan servir les eines i els efectes resultants, pas a pas. Això ajuda el model a aprendre a decidir quan fer servir una eina i com fer-la servir. Quan diem «fer servir una eina», el que volem dir és que el model en realitat només proposa una crida d'eina. No pot executar la crida pel seu compte.

L'eina shell fa que el model sigui molt més potent: interactua amb un ordinador a través de la línia d'ordres per dur a terme una àmplia gamma de tasques, des de cercar text fins a enviar sol·licituds d'API al vostre ordinador. Basada en eines Unix conegudes, la nostra eina shell pot fer qualsevol cosa que espereu, amb utilitats com grep, curl i awk disponibles d'entrada.

En comparació amb el nostre intèrpret de codi existent, que només executa Python, l'eina shell permet una gamma molt més àmplia de casos d'ús, com ara executar programes Go o Java o iniciar un servidor NodeJS. Aquesta flexibilitat permet al model completar tasques agentives complexes.

Per si sol, un model només pot proposar comandes shell, però com s'executen aquestes comandes? Necessitem un orquestrador per obtenir la sortida del model, invocar eines i tornar a passar la resposta de l'eina al model en un bucle, fins que la tasca s'hagi completat.

L'API Responses és la manera com els desenvolupadors interactuen amb els models d'OpenAI. Quan es fa servir amb eines personalitzades, l'API Responses retorna el control al client i aquest necessita el seu propi arnés per executar les eines. Tanmateix, aquesta API també pot orquestrar entre el model i les eines allotjades des del primer moment. 

Quan l'API Responses rep una indicació, munta el context del model: indicació de l'usuari, estat previ de la conversa i instruccions d'eines. Perquè l'execució shell funcioni, la indicació ha d'esmentar l'ús de l'eina shell i el model seleccionat ha d'estar entrenat per proposar comandes shell —els models GPT‑5.2 i posteriors estan entrenats per a això. Amb tot aquest context, el model decideix l'acció següent. Si tria l'execució shell, retorna una o més comandes shell al servei de l'API Responses. El servei API reenvia aquestes comandes a l'entorn d'execució del contenidor, transmet en temps real la sortida shell i l'incorpora al context de la sol·licitud següent per al model. El model pot llavors inspeccionar els resultats, emetre comandes de seguiment o produir una resposta final. L'API Responses repeteix aquest bucle fins que el model retorna una finalització sense comandes shell addicionals.

Quan l'API Responses executa una comanda shell, manté una connexió de transmissió en temps real amb el servei de contenidors. A mesura que es produeix la sortida, l'API la retransmet al model gairebé en temps real perquè aquest pugui decidir si ha d'esperar més sortida, executar una altra comanda o passar a una resposta final.

El model pot proposar múltiples comandes shell en un sol pas, i l'API Responses les pot executar simultàniament fent servir sessions de contenidor separades. Cada sessió transmet la sortida de manera independent, i l'API multiplexa aquests fluxos de tornada en sortides d'eina estructurades com a context. En altres paraules, el bucle de l'agent pot paral·lelitzar feina, com ara cercar fitxers, obtenir dades i validar resultats intermedis.

Quan la comanda implica operacions amb fitxers o processament de dades, la sortida shell pot arribar a ser molt gran i consumir pressupostos de context sense afegir senyals útils. Per controlar-ho, el model especifica un límit de sortida per comanda. L'API Responses aplica aquest límit i retorna un resultat acotat que preserva tant l'inici com el final de la sortida, mentre marca el contingut omès. Per exemple, podeu limitar la sortida a 1.000 caràcters, amb inici i final preservats:

text al començament ... 1000 caràcters truncats ... text al final

En conjunt, l'execució concurrent i la sortida acotada fan que el bucle de l'agent sigui alhora ràpid i eficient pel que fa al context, de manera que el model pugui continuar raonant sobre resultats rellevants en lloc de veure's aclaparat per registres de terminal en brut.

Un possible problema dels bucles d'agent és que les tasques poden executar-se durant molt de temps. Les tasques de llarga durada omplen la finestra de context, que és important per proporcionar context entre torns i entre agents. Imagineu un agent cridant una habilitat, obtenint una resposta, afegint crides d'eina i resums de raonament: la finestra de context limitada s'omple ràpidament. Per evitar perdre el context important mentre l'agent continua executant-se, necessitem una manera de conservar els detalls clau i eliminar qualsevol cosa supèrflua. En lloc d'exigir als desenvolupadors que dissenyin i mantinguin sistemes personalitzats de resum o transport d'estat, hem afegit compactació nativa a l'API Responses, dissenyada per alinear-se amb la manera com es comporta el model i com ha estat entrenat.

Els nostres models més recents estan entrenats per analitzar l'estat de la conversa anterior i produir un element de compactació que preserva l'estat clau anterior en una representació xifrada i eficient en segments. Després de la compactació, la finestra de context següent consta d'aquest element de compactació i de les parts d'alt valor de la finestra anterior. Això permet que els fluxos de treball continuïn de manera coherent a través dels límits de la finestra, fins i tot en sessions prolongades de diversos passos i guiades per eines. Codex es basa en aquest mecanisme per sostenir tasques de programació de llarga durada i execució iterativa d'eines sense degradar la qualitat.

La compactació està disponible integrada al servidor o mitjançant un punt final independent `/compact`. La compactació del costat del servidor us permet configurar un llindar, i el sistema gestiona automàticament el moment de compactar, eliminant la necessitat de lògica complexa al client. Permet una finestra de context d'entrada efectiva lleugerament més gran per tolerar petits excessos just abans de la compactació, de manera que les sol·licituds properes al límit encara es puguin processar i compactar en lloc de ser rebutjades. A mesura que evoluciona l'entrenament del model, la solució de compactació nativa evoluciona amb ell en cada llançament de model d'OpenAI.

Codex ens va ajudar a construir el sistema de compactació mentre en feia d'usuari primerenc. Quan una instància de Codex topava amb un error de compactació, en posàvem en marxa una segona per investigar-ho. El resultat va ser que Codex va obtenir un sistema de compactació natiu i eficaç simplement treballant en el problema. Aquesta capacitat de Codex d'inspeccionar-se i refinar-se a si mateix s'ha convertit en una part especialment interessant de treballar a OpenAI. La majoria d'eines només requereixen que l'usuari aprengui a utilitzar-les; Codex aprèn amb nosaltres.

Ara cobrim l'estat i els recursos. El contenidor no és només un lloc on executar comandes, sinó també el context de treball del model. Dins del contenidor, el model pot llegir fitxers, consultar bases de dades i accedir a sistemes externs sota controls de polítiques de xarxa.

La primera part del context del contenidor és el sistema de fitxers per pujar, organitzar i gestionar recursos. Hem creat API de contenidors i fitxers⁠(s'obre en una finestra nova) per donar al model un mapa de les dades disponibles i ajudar-lo a triar operacions de fitxer específiques en lloc de fer escaneigs amplis i sorollosos.

Un antipatró habitual és empaquetar tota l'entrada directament al context de la indicació. A mesura que les entrades creixen, omplir massa la indicació esdevé car i difícil de navegar per al model. Un patró millor és preparar recursos al sistema de fitxers del contenidor i deixar que el model decideixi què obrir, analitzar o transformar amb comandes shell. Igual que els humans, els models treballen millor amb informació organitzada.

La segona part del context del contenidor són les bases de dades. En molts casos, suggerim als desenvolupadors que emmagatzemin dades estructurades en bases de dades com SQLite i les consultin. En lloc de copiar tot un full de càlcul a la indicació, per exemple, podeu donar al model una descripció de les taules —quines columnes existeixen i què signifiquen— i deixar que extregui les files que necessita.

Per exemple, si pregunteu «Quins productes han tingut una caiguda de vendes aquest trimestre?», el model pot consultar només les files rellevants en lloc d'escanejar tot el full de càlcul. Això és més ràpid, més barat i més escalable per a conjunts de dades grans.

La tercera part del context del contenidor és l'accés a la xarxa, una part essencial de les càrregues de treball d'agents. El flux de treball de l'agent pot necessitar obtenir dades en viu, cridar API externes o instal·lar paquets. Al mateix temps, donar als contenidors accés sense restriccions a internet pot ser arriscat: pot exposar informació a llocs web externs, tocar sense voler sistemes interns o de tercers sensibles, o dificultar la protecció contra filtracions de credencials i exfiltració de dades.

Per abordar aquestes preocupacions sense limitar la utilitat dels agents, vam crear contenidors allotjats perquè facin servir un proxy sidecar de sortida. Totes les sol·licituds de xarxa sortints passen per una capa de polítiques centralitzada que aplica llistes de permisos i controls d'accés mantenint alhora el trànsit observable. Pel que fa a les credencials, fem servir injecció de secrets amb àmbit de domini a la sortida. El model i el contenidor només veuen marcadors de posició, mentre que els valors bruts dels secrets romanen fora del context visible per al model i només s'apliquen a destinacions aprovades. Això redueix el risc de filtració i continua permetent crides externes autenticades.

Les comandes shell són potents, però moltes tasques repeteixen els mateixos patrons de diversos passos. Els agents han de redescobrir el flux de treball a cada execució —replanificant, tornant a emetre comandes i reaprenent convencions—, cosa que provoca resultats inconsistents i execució malgastada. Les habilitats d'agent⁠(s'obre en una finestra nova) empaqueten aquests patrons en blocs de construcció reutilitzables i combinables. En concret, una habilitat és un paquet de carpeta que inclou «SKILL.md⁠(s'obre en una finestra nova)» (que conté metadades i instruccions) més qualsevol recurs de suport, com ara especificacions d'API i actius d'IU.

Aquesta estructura encaixa de manera natural amb l'arquitectura d'execució que hem descrit abans. El contenidor proporciona fitxers persistents i context d'execució, i l'eina shell proporciona la interfície d'execució. Amb totes dues coses al seu lloc, el model pot descobrir fitxers d'habilitat fent servir comandes shell (`ls`, `cat`, etc.) quan ho necessita, interpretar instruccions i executar scripts d'habilitat dins del mateix bucle d'agent.

Proporcionem API⁠(s'obre en una finestra nova) per gestionar habilitats a la plataforma OpenAI. Els desenvolupadors pugen i emmagatzemen carpetes d'habilitats com a paquets versionats, que més endavant es poden recuperar mitjançant l'ID de l'habilitat. Abans d'enviar la indicació al model, l'API Responses carrega l'habilitat i la inclou al context del model. Aquesta seqüència és determinista:

1. Obtenir les metadades de l'habilitat, incloent-hi el nom i la descripció.
2. Obtenir el paquet de l'habilitat, copiar-lo al contenidor i desempaquetar-lo.
3. Actualitzar el context del model amb les metadades de l'habilitat i la ruta del contenidor.

Quan decideix si una habilitat és rellevant, el model n'explora progressivament les instruccions i n'executa els scripts mitjançant comandes shell al contenidor.

Per ajuntar totes les peces: l'API Responses proporciona orquestració, l'eina shell proporciona accions executables, el contenidor allotjat proporciona context d'execució persistent, les habilitats afegeixen lògica de flux de treball reutilitzable, i la compactació permet que un agent s'executi durant molt de temps amb el context que necessita.

Amb aquests primitives, una sola indicació es pot expandir a un flux de treball de cap a cap: descobrir l'habilitat adequada, obtenir dades, transformar-les en estat local estructurat, consultar-lo de manera eficient i generar artefactes duradors. 

El diagrama següent mostra com funciona aquest sistema per crear un full de càlcul a partir de dades en viu.

Per a un exemple aprofundit de la combinació de l'eina shell i l'entorn informàtic per a fluxos de treball de cap a cap, consulteu la nostra entrada del blog per a desenvolupadors⁠(s'obre en una finestra nova) i el cookbook⁠(s'obre en una finestra nova), que mostren com empaquetar una habilitat i executar-la mitjançant l'API Responses.

Ens fa il·lusió veure què construeixen els desenvolupadors amb aquest conjunt de primitives. Els models de llenguatge estan pensats per fer més que generar text, imatges i àudio: continuarem fent evolucionar la nostra plataforma perquè sigui més capaç de gestionar tasques complexes del món real a escala.