Van model naar agent: de Responses API uitrusten met een computeromgeving

We zitten momenteel in een verschuiving van het gebruik van modellen, die uitblinken in specifieke taken, naar het gebruik van agents die complexe workflows kunnen afhandelen. Door modellen te prompten, kun je alleen toegang krijgen tot getrainde intelligentie. Maar als je een model een computer geeft als werkomgeving wordt een veel breder scala aan usecases mogelijk, zoals het uitvoeren van services, het opvragen van data via API’s of het genereren van nuttigere artefacten zoals spreadsheets of rapporten.

Er duiken een paar praktische problemen op wanneer je agents probeert te bouwen: waar je tijdelijke bestanden moet opslaan, hoe je voorkomt dat je grote tabellen in een prompt plakt, hoe je de workflow netwerktoegang geeft zonder beveiligingsproblemen te creëren, en hoe je time-outs en herhaaldelijke pogingen afhandelt zonder zelf een workflowsysteem te bouwen.

In plaats van het aan ontwikkelaars over te laten om hun eigen uitvoeringsomgevingen te bouwen, hebben we de benodigde componenten ontwikkeld om de Responses API⁠(opent in een nieuw venster) uit te rusten met een computeromgeving waarmee real-world taken betrouwbaar kunnen worden uitgevoerd.

OpenAI’s Responses API, samen met de shell-tool en een gehoste werkruimte, is ontworpen om deze praktische problemen aan te pakken. Het model stelt stappen en commando's voor; het platform voert ze uit in een geïsoleerde omgeving met een bestandssysteem voor invoer en uitvoer, optionele gestructureerde opslag (zoals SQLite) en beperkte netwerktoegang. 

In deze post leggen we uit hoe we een computeromgeving voor agents hebben gebouwd en delen we enkele eerste lessen over hoe je die kunt gebruiken voor snellere, beter herhaalbare en veiligere productieprocessen.

Een goede agent-workflow begint met een strakke uitvoeringslus: het model stelt een actie voor, zoals bestanden lezen of data ophalen met een API, het platform voert die uit en het resultaat voedt de volgende stap. We beginnen met de shell-tool, de eenvoudigste manier om deze loop in actie te zien, en behandelen daarna de container-werkruimte, netwerken, herbruikbare vaardigheden en contextcompactie.

Om de shell-tool te begrijpen, is het eerst nuttig om te begrijpen hoe een model tools in het algemeen gebruikt: om dingen te doen zoals een functie aanroepen of communiceren met een computer. Tijdens de training krijgt een model stap voor stap voorbeelden te zien van hoe tools worden gebruikt en wat de resulterende effecten zijn. Dit helpt het model te leren beslissen wanneer het een tool moet gebruiken en hoe het die moet gebruiken. Wanneer we zeggen “een tool gebruiken”, bedoelen we dat het model eigenlijk alleen een tool call voorstelt. Het kan de call niet zelfstandig uitvoeren.

De shell-tool maakt het model aanzienlijk krachtiger: het communiceert met een computer via de command line om een breed scala aan taken uit te voeren, van het zoeken naar tekst tot het verzenden van API-requests op je computer. Onze shell-tool is gebouwd op vertrouwde Unix-tools en kan alles doen wat je zou verwachten, met hulpprogramma's zoals grep, curl en awk standaard beschikbaar.

Vergeleken met onze bestaande code-interpreter, die alleen Python uitvoert, maakt de shelltool een veel breder scala aan use-cases mogelijk, zoals het uitvoeren van Go- of Java-programma's of het starten van een NodeJS-server. Deze flexibiliteit stelt het model in staat om complexe agentic taken uit te voeren.

Op zichzelf kan een model alleen shellcommando's voorstellen, maar hoe worden deze commando's uitgevoerd? We hebben een orchestrator nodig om modeloutput op te halen, tools aan te roepen en de toolrespons in een loop terug te koppelen aan het model, totdat de taak is voltooid.

De Responses API is de manier waarop ontwikkelaars met OpenAI-modellen communiceren. Wanneer deze met custom tools wordt gebruikt, geeft de Responses API de controle terug aan de client, en heeft de client een eigen harness nodig om de tools uit te voeren. Deze API kan echter ook standaard de orkestratie verzorgen tussen het model en gehoste tools. 

Wanneer de Responses API een prompt ontvangt, stelt deze de context voor het model samen: gebruikersprompt, eerdere gespreksstatus en toolinstructies. Om shell-uitvoering te laten werken, moet de prompt vermelden dat de shell-tool wordt gebruikt en moet het geselecteerde model zijn getraind om shellcommando's voor te stellen. GPT‑5.2 en latere modellen zijn hiervoor getraind. Met al deze context beslist het model vervolgens over de volgende actie. Als het voor shell-uitvoering kiest, retourneert het een of meer shellcommando's aan de Responses API-service. De API-service stuurt die commando's door naar de container-runtime, streamt de shelluitvoer terug en voegt die toe aan de context van de volgende request aan het model. Het model kan vervolgens de resultaten inspecteren, vervolgopdrachten geven of een definitief antwoord produceren. De Responses API herhaalt deze lus totdat het model een completion retourneert zonder aanvullende shellcommando's.

Wanneer de Responses-API een shellcommando uitvoert, onderhoudt deze een streamingverbinding met de containerservice. Terwijl de uitvoer wordt geproduceerd, geeft de API deze bijna in real time door aan het model, zodat het model kan beslissen of het op meer uitvoer moet wachten, nog een opdracht moet uitvoeren of doorgaat naar een definitief antwoord.

Het model kan in één stap meerdere shellcommando's voorstellen en de Responses API kan ze gelijktijdig uitvoeren met afzonderlijke containersessies. Elke sessie streamt output onafhankelijk, en de API voegt die streams samen tot gestructureerde tooluitvoer als context. Met andere woorden, de agent-loop kan werk parallel uitvoeren, zoals bestanden doorzoeken, gegevens ophalen en tussentijdse resultaten valideren.

Wanneer de opdracht bestandsbewerkingen of gegevensverwerking omvat, kan de shell-uitvoer erg groot worden en contextbudgetten verbruiken zonder nuttige signalen toe te voegen. Om dit onder controle te houden, specificeert het model een uitvoerlimiet per opdracht. De Responses API handhaaft die limiet en retourneert een begrensd resultaat dat zowel het begin als het einde van de uitvoer behoudt, terwijl weggelaten inhoud wordt gemarkeerd. Je zou bijvoorbeeld de output kunnen beperken tot 1,000 tekens, met een behouden begin en einde:

tekst aan het begin ... 1000 tekens afgekapt ... tekst aan het einde

Samen maken gelijktijdige uitvoering en begrensde output de agent-loop zowel snel als context-efficiënt, zodat het model kan blijven redeneren over relevante resultaten in plaats van overweldigd te raken door ruwe terminal-logs.

Een mogelijk probleem met agent-loops is dat taken lang kunnen duren. Langdurige taken vullen het contextvenster, wat helpt om context te behouden tussen beurten en tussen agents. Stel je een agent voor die een skill aanroept, een antwoord krijgt en tool calls en samenvattingen van het redeneerproces toevoegt: het contextvenster raakt dan snel vol. Om te voorkomen dat we de belangrijke context verliezen terwijl de agent blijft draaien, hebben we een manier nodig om de belangrijkste details te behouden en alles wat overbodig is te verwijderen. In plaats van ontwikkelaars te verplichten om aangepaste samenvattings- of statusdragende systemen te ontwerpen en te onderhouden, hebben we native compaction toegevoegd aan de Responses API, ontworpen om aan te sluiten op hoe het model zich gedraagt en hoe het is getraind.

Onze nieuwste modellen zijn getraind om de status van eerdere conversaties te analyseren en een compaction-item te produceren dat de belangrijkste eerdere status behoudt in een versleutelde, token-efficiënte representatie. Na compressie bestaat het volgende contextvenster uit dit compaction-item en waardevolle delen van het eerdere venster. Hierdoor kunnen workflows samenhangend doorgaan over venstergrenzen heen, zelfs in uitgebreide sessies met meerdere stappen en toolgestuurde sessies. Codex gebruikt dit mechanisme om langdurige programmeertaken en iteratieve uitvoering van hulpmiddelen te ondersteunen zonder dat de kwaliteit achteruitgaat.

Compaction is beschikbaar als ingebouwde functie op de server of via een apart /compact-endpoint. Server-side compaction laat je een drempelwaarde configureren, en het systeem regelt de timing van het comprimeren automatisch, waardoor complexe client-side logica niet meer nodig is. Het maakt een iets groter effectief contextvenster voor invoer mogelijk om kleine overschrijdingen vlak voor compaction te tolereren, zodat verzoeken dicht bij de limiet nog steeds kunnen worden verwerkt en gecompacteerd in plaats van dat ze worden afgewezen. Naarmate modeltraining zich ontwikkelt, ontwikkelt de native compaction-oplossing zich mee bij elke OpenAI-modelrelease.

Codex hielp ons het compressiesysteem te bouwen en diende daarbij als een vroege gebruiker ervan. Wanneer één Codex-instantie tegen een fout aanliep bij compaction, startten we een tweede instantie op om dit te onderzoeken. Het resultaat was dat Codex een native, effectief systeem voor compaction kreeg door gewoon aan het probleem te werken. Dit vermogen van Codex om zichzelf te inspecteren en te verfijnen is een bijzonder interessant onderdeel geworden van het werken bij OpenAI. De meeste tools vereisen alleen dat de gebruiker leert hoe hij ze moet gebruiken; Codex leert met ons mee.

Laten we nu state en resources behandelen. De container is niet alleen een plek om opdrachten uit te voeren, maar ook de werkcontext voor het model. Binnen de container kan het model bestanden lezen, query's naar databases sturen en toegang krijgen tot externe systemen onder netwerkbeleidscontroles.

Het eerste deel van de containercontext is het bestandssysteem voor het uploaden, organiseren en beheren van bronnen. We hebben container- en bestands⁠(opent in een nieuw venster)-API's gebouwd om het model een kaart te geven van beschikbare gegevens en het te helpen gerichte bestandsbewerkingen te kiezen in plaats van brede scans uit te voeren met veel ruis.

Een veelvoorkomend anti-patroon is om alle invoer rechtstreeks in de promptcontext te stoppen. Naarmate inputs groeien, wordt het overvol maken van de prompt duur en moeilijk voor het model om te navigeren. Een beter patroon is om resources in het containerbestandssysteem te stagen en het model te laten beslissen wat het moet openen, parseren of transformeren met shellcommando's. Net als mensen werken modellen beter met georganiseerde informatie.

Het tweede onderdeel van de containercontext zijn databases. In veel gevallen raden we ontwikkelaars aan gestructureerde gegevens in databases zoals SQLite op te slaan en er query's op uit te voeren. In plaats van bijvoorbeeld een hele spreadsheet in de prompt te kopiëren, kun je het model een beschrijving geven van de tabellen, welke kolommen er zijn en wat ze betekenen, en het de rijen laten ophalen die het nodig heeft.

Bijvoorbeeld, als je vraagt: “Welke producten hadden dit kwartaal dalende verkopen?” kan het model alleen de relevante rijen opvragen in plaats van de hele spreadsheet te scannen. Dit is sneller, goedkoper, en beter schaalbaar voor grotere datasets.

Het derde onderdeel van de containercontext is netwerktoegang, een essentieel onderdeel van agent-workloads. De workflow van de agent moet mogelijk live data ophalen, externe API's aanroepen of pakketten installeren. Tegelijkertijd kan het riskant zijn om containers onbeperkte internettoegang te geven: het kan informatie blootstellen aan externe websites, onbedoeld gevoelige interne of externe systemen benaderen, of het moeilijker maken om lekken van credentials en data-exfiltratie te voorkomen.

Om deze zorgen weg te nemen zonder de bruikbaarheid van agents te beperken, hebben we gehoste containers gebouwd om een 'sidecar egress proxy' te gebruiken. Alle uitgaande netwerkverzoeken lopen via een gecentraliseerde beleidslaag die toestemmingslijsten en toegangscontroles handhaaft, terwijl het verkeer observeerbaar blijft. Voor credentials gebruiken we domeingebonden secret injection bij uitgaand verkeer. Het model en de container zien alleen placeholders, terwijl ruwe geheime waarden buiten de voor het model zichtbare context blijven en alleen worden toegepast voor goedgekeurde bestemmingen. Dit verkleint het risico op lekken, terwijl het nog steeds geauthenticeerde externe aanroepen mogelijk maakt.

Shellcommando's zijn krachtig, maar veel taken herhalen dezelfde meerstapse patronen. Agents moeten bij elke run de workflow opnieuw ontdekken, opnieuw plannen, opdrachten opnieuw geven en conventies opnieuw aanleren, wat leidt tot inconsistente resultaten en overbodige uitvoering. Agent-skills⁠(opent in een nieuw venster) bundelen die patronen in herbruikbare, combineerbare bouwstenen. Concreet gezegd is een skill een bundel folders die ‘SKILL.md⁠(opent in een nieuw venster)’ bevat (met metadata en instructies) plus eventuele ondersteunende middelen, zoals API-specificaties en assets voor de gebruikersinterface.

Deze structuur sluit op natuurlijke wijze aan bij de runtime-architectuur die we eerder hebben beschreven. De container biedt persistente bestanden en uitvoeringscontext, en de shell-tool biedt de uitvoeringsinterface. Met beide op hun plek kan het model skillbestanden ontdekken met behulp van shellcommando's (`ls`, `cat`, etc.) wanneer dat nodig is, instructies interpreteren en skillscripts uitvoeren, allemaal binnen dezelfde agent-loop.

We bieden API's⁠(opent in een nieuw venster) om skills te beheren in het OpenAI-platform. Ontwikkelaars uploaden skills en slaan ze op als versiegebonden bundels, die later kunnen worden opgehaald via de skill-ID. Voordat de prompt naar het model wordt verzonden, laadt de Responses API de skill en neemt deze op in de modelcontext. Deze sequentie is deterministisch:

1. De metadata van de skill wordt opgehaald, inclusief naam en beschrijving.
2. De skill-bundel wordt opgehaald en gekopieerd naar de container, waar die wordt uitgepakt.
3. Dan wordt de context van het model bijgewerkt met metadata voor skills en het containerpad.

Wanneer het model beslist of een skill relevant is, verkent het geleidelijk de instructies en voert het de scripts uit via shellcommando's in de container.

Om alles samen te brengen: de Responses API zorgt voor orkestratie, de shell-tool voor uitvoerbare acties, de hosted container voor een persistente runtimeomgeving, skills voegen herbruikbare workflowlogica toe, en compaction maakt het mogelijk dat een agent langdurig draait met de benodigde context.

Met deze bouwstenen kan één prompt uitgroeien tot een end-to-end workflow: de juiste skill vinden, data ophalen, omzetten naar een lokaal gestructureerde status, die efficiënt bevragen en duurzame artefacten genereren.

Het diagram hieronder laat zien hoe dit systeem werkt voor het maken van een spreadsheet op basis van live gegevens.

Voor een diepgaand voorbeeld van hoe je de shell tool en computeromgeving combineert voor end-to-end workflows, bekijk onze developerblog⁠(opent in een nieuw venster) en het cookbook⁠(opent in een nieuw venster), waarin wordt uitgelegd hoe je een skill verpakt en die uitvoert via de Responses API.

We zijn benieuwd wat ontwikkelaars gaan maken met deze set bouwstenen. Taalmodellen zijn bedoeld om meer te doen dan tekst, afbeeldingen en audio te genereren–we blijven ons platform verder ontwikkelen om capabeler te worden in het op schaal afhandelen van complexe taken in de praktijk.