Dal modello all’agente: dotare la Responses API di un ambiente informatico

Attualmente stiamo passando dall’uso di modelli, che eccellono in compiti specifici, all’uso di agenti capaci di gestire flussi di lavoro complessi. Utilizzando prompt con i modelli, puoi accedere solo all’intelligenza appresa durante l’addestramento. Tuttavia, fornire al modello un ambiente informatico consente una gamma molto più ampia di casi d’uso, come eseguire servizi, richiedere dati da API o generare artefatti più utili come fogli di calcolo o report.

Quando si prova a costruire agenti emergono alcuni problemi pratici: dove archiviare i file intermedi, come evitare di incollare tabelle molto grandi in un prompt, come fornire accesso alla rete al flusso di lavoro senza creare problemi di sicurezza e come gestire timeout e tentativi senza dover costruire un sistema di workflow da zero.

Invece di lasciare agli sviluppatori il compito di costruire i propri ambienti di esecuzione, abbiamo creato i componenti necessari per dotare l' API Responses⁠(si apre in una nuova finestra) di un ambiente informatico capace di eseguire in modo affidabile attività del mondo reale.

La Responses API di OpenAI, insieme allo strumento shell e a un’area di lavoro container ospitata, è progettata per affrontare questi problemi pratici. Il modello propone passaggi e comandi; la piattaforma li esegue in un ambiente isolato con un file system per input e output, archiviazione strutturata opzionale (come SQLite) e accesso alla rete limitato. 

In questo articolo analizzeremo come abbiamo creato un ambiente informatico per gli agenti e condivideremo alcune prime lezioni su come utilizzarlo per flussi di lavoro di produzione più veloci, ripetibili e sicuri.

Un buon flusso di lavoro di un agente inizia con un ciclo di esecuzione serrato: il modello propone un’azione come leggere file o recuperare dati tramite API, la piattaforma la esegue e il risultato alimenta il passaggio successivo. Inizieremo con lo strumento shell—il modo più semplice per vedere questo ciclo in azione—e poi esamineremo l’area di lavoro del container, il networking, le skill riutilizzabili e la compattazione del contesto.

Per comprendere lo strumento shell è utile capire innanzitutto come un modello linguistico utilizza gli strumenti in generale, ad esempio per chiamare una funzione o interagire con un computer. Durante l’addestramento, a un modello vengono mostrati esempi di come gli strumenti vengono utilizzati e degli effetti risultanti, passo dopo passo. Questo aiuta il modello a imparare quando utilizzare uno strumento e come utilizzarlo. Quando diciamo «usare uno strumento», intendiamo che il modello in realtà propone soltanto una chiamata allo strumento. Il modello non può eseguire la chiamata autonomamente.

Lo strumento shell rende il modello molto più potente: interagisce con un computer tramite la riga di comando per eseguire un’ampia gamma di attività, dalla ricerca di testo all’invio di richieste API sul computer. Basato su strumenti Unix familiari, il nostro strumento di shell può fare tutto ciò che ci si aspetta, con utility come grep, curl e awk disponibili immediatamente.

Rispetto al nostro attuale strumento di interpretazione del codice, che esegue solo Python, lo strumento shell consente una gamma molto più ampia di casi d’uso, come l’esecuzione di programmi Go o Java o l’avvio di un server NodeJS. Questa flessibilità consente al modello di svolgere attività agentiche complesse.

Da solo, un modello può soltanto proporre comandi shell, ma come vengono eseguiti questi comandi? È necessario un orchestratore per ottenere l’output del modello, invocare gli strumenti e restituire la risposta dello strumento al modello in un ciclo finché l’attività non è completata.

La Responses API è il modo in cui gli sviluppatori interagiscono con i modelli OpenAI. Quando viene utilizzata con strumenti personalizzati, la Responses API restituisce il controllo al client e il client necessita di una propria infrastruttura per eseguire gli strumenti. Tuttavia, questa API può anche orchestrare l'interazione tra il modello e gli strumenti ospitati fin da subito. 

Quando la Responses API riceve un prompt, costruisce il contesto del modello: prompt dell’utente, stato della conversazione precedente e istruzioni degli strumenti. Affinché l’esecuzione della shell funzioni, il prompt deve menzionare l’uso dello strumento shell e il modello selezionato deve essere addestrato a proporre comandi shell: i modelli GPT‑5.2 e successivi sono addestrati per questo. Con tutto questo contesto, il modello decide l’azione successiva. Se sceglie l’esecuzione tramite shell, restituisce uno o più comandi shell al servizio della Responses API. Il servizio API inoltra questi comandi al runtime del container, trasmette in streaming l’output della shell e lo fornisce al modello nel contesto della richiesta successiva. Il modello può quindi esaminare i risultati, emettere comandi successivi oppure produrre una risposta finale. La Responses API ripete questo ciclo finché il modello non restituisce un completamento senza ulteriori comandi shell.

Quando la Responses API esegue un comando shell, mantiene una connessione in streaming con il servizio container. Man mano che viene prodotto output, l’API lo inoltra al modello quasi in tempo reale affinché il modello possa decidere se attendere altro output, eseguire un altro comando o passare a una risposta finale.

Il modello può proporre più comandi shell in un unico passaggio e la Responses API può eseguirli in parallelo utilizzando sessioni container separate. Ogni sessione trasmette l’output in streaming in modo indipendente e l’API multiplexa questi flussi in output strutturati degli strumenti da utilizzare come contesto. In altre parole, il ciclo dell’agente può parallelizzare il lavoro, ad esempio cercando file, recuperando dati e convalidando risultati intermedi.

Quando il comando comporta operazioni sui file o elaborazione dei dati, l’output della shell può diventare molto grande e consumare il budget di contesto senza aggiungere segnali utili. Per controllare questo comportamento, il modello specifica un limite di output per comando. La Responses API applica questo limite e restituisce un risultato delimitato che preserva sia l’inizio sia la fine dell’output, indicando al contempo i contenuti omessi. Ad esempio, potresti limitare l’output a 1.000 caratteri, mantenendo l’inizio e la fine:

testo all'inizio ... 1000 caratteri troncati ... testo alla fine

Insieme, l’esecuzione concorrente e l’output limitato rendono il ciclo dell’agente sia rapido sia efficiente in termini di contesto, così il modello può continuare a ragionare sui risultati pertinenti invece di essere sopraffatto dai log grezzi del terminale.

Un possibile problema dei cicli degli agenti è che le attività possono durare a lungo. Le attività di lunga durata riempiono la finestra di contesto, che è importante per mantenere il contesto tra i turni e tra gli agenti. Immagina un agente che richiama una skill, riceve una risposta, aggiunge chiamate agli strumenti e riepiloghi del ragionamento—la finestra di contesto limitata si riempie rapidamente. Per evitare di perdere il contesto importante mentre l’agente continua a essere eseguito, serve un modo per conservare i dettagli chiave ed eliminare tutto ciò che è superfluo. Invece di richiedere agli sviluppatori di progettare e mantenere sistemi personalizzati di riepilogo o gestione dello stato, abbiamo introdotto la compattazione nativa nella Responses API, progettata per allinearsi al comportamento del modello e al modo in cui è stato addestrato.

I nostri modelli più recenti sono addestrati ad analizzare lo stato della conversazione precedente e produrre un elemento di compattazione che preserva lo stato precedente rilevante in una rappresentazione crittografata efficiente in termini di token. Dopo la compattazione, la finestra di contesto successiva consiste in questo elemento di compattazione e nelle porzioni ad alto valore della finestra precedente. Questo consente ai flussi di lavoro di proseguire in modo coerente oltre i limiti della finestra di contesto, anche in sessioni estese multi-step guidate da strumenti. Codex si basa su questo meccanismo per sostenere attività di programmazione di lunga durata e l’esecuzione iterativa degli strumenti senza degradare la qualità.

La compattazione è disponibile sia integrata lato server sia tramite l’endpoint autonomo `/compact`. La compattazione lato server consente di configurare una soglia e il sistema gestisce automaticamente la tempistica della compattazione, eliminando la necessità di logiche complesse lato client. Consente una finestra di contesto di input effettiva leggermente più ampia per tollerare piccoli superamenti immediatamente prima della compattazione, in modo che le richieste vicine al limite possano comunque essere elaborate e compattate invece di essere rifiutate. Con l’evoluzione dell’addestramento dei modelli, anche la soluzione di compattazione nativa si evolve a ogni nuova versione dei modelli OpenAI.

Codex ci ha aiutato a costruire il sistema di compattazione fungendo al tempo stesso da primo utilizzatore. Quando un’istanza di Codex incontrava un errore di compattazione, avviavamo una seconda istanza per indagare. Il risultato è stato che Codex ha ottenuto un sistema di compattazione nativo ed efficace semplicemente lavorando sul problema. Questa capacità di Codex di analizzare e migliorare se stesso è diventata una parte particolarmente interessante del lavoro in OpenAI. La maggior parte degli strumenti richiede solo che l’utente impari a usarli; Codex impara insieme a noi.

Ora esaminiamo stato e risorse. Il container non è soltanto un luogo in cui eseguire comandi, ma anche il contesto di lavoro del modello. All’interno del container il modello può leggere file, interrogare database e accedere a sistemi esterni nel rispetto dei controlli delle policy di rete.

La prima parte del contesto del container è il file system per caricare, organizzare e gestire le risorse. Abbiamo sviluppato API per container e file⁠(si apre in una nuova finestra) per fornire al modello una mappa dei dati disponibili e aiutarlo a scegliere operazioni sui file mirate invece di eseguire scansioni ampie e poco efficienti.

Un anti-pattern comune consiste nell’inserire tutti gli input direttamente nel contesto del prompt. Man mano che gli input aumentano, riempire eccessivamente il prompt diventa costoso e difficile da gestire per il modello. Un approccio migliore consiste nel preparare le risorse nel file system del container e lasciare che il modello decida cosa aprire, analizzare o trasformare tramite comandi shell. Proprio come gli esseri umani, anche i modelli funzionano meglio con informazioni organizzate.

La seconda parte del contesto del container sono i database. In molti casi suggeriamo agli sviluppatori di archiviare i dati strutturati in database come SQLite e interrogarli. Invece di copiare un intero foglio di calcolo nel prompt, ad esempio, si può fornire al modello una descrizione delle tabelle—quali colonne esistono e cosa rappresentano—e lasciare che recuperi le righe necessarie.

Ad esempio, se chiedi «Quali prodotti hanno registrato un calo delle vendite questo trimestre?», il modello può interrogare just le righe pertinenti invece di analizzare l’intero foglio di calcolo. Questo approccio è più veloce, meno costoso e più scalabile per dataset di grandi dimensioni.

La terza parte del contesto del container è l’accesso alla rete, una componente essenziale dei carichi di lavoro degli agenti. Il flusso di lavoro di un agente potrebbe dover recuperare dati in tempo reale, chiamare API esterne o installare pacchetti. Allo stesso tempo, concedere ai container un accesso a Internet senza restrizioni può essere rischioso: può esporre informazioni a siti web esterni, entrare involontariamente in contatto con sistemi interni sensibili o di terze parti, oppure rendere più difficile prevenire perdite di credenziali ed esfiltrazione di dati.

Per affrontare queste preoccupazioni senza limitare l’utilità degli agenti, abbiamo progettato container ospitati che utilizzano un proxy di uscita sidecar. Tutte le richieste di rete in uscita passano attraverso un livello centralizzato di policy che applica allowlist e controlli di accesso mantenendo al contempo il traffico osservabile. Per le credenziali utilizziamo l’iniezione di segreti con ambito di dominio al momento dell’uscita. Il modello e il container vedono solo segnaposto, mentre i valori segreti reali rimangono fuori dal contesto visibile al modello e vengono applicati solo alle destinazioni approvate. Questo riduce il rischio di perdita di dati consentendo comunque chiamate esterne autenticate.

I comandi shell sono potenti, ma molte attività ripetono gli stessi pattern a più passaggi. Gli agenti devono riscoprire il flusso di lavoro a ogni esecuzione—ripianificando, riemettendo comandi e riapprendendo le convenzioni—con conseguenti risultati incoerenti e spreco di esecuzione Agent skills⁠(si apre in una nuova finestra) racchiudono questi pattern in componenti riutilizzabili e componibili. In concreto, una skill è un bundle di cartelle che include ‘SKILL.md⁠(si apre in una nuova finestra)’ (contenente metadati e istruzioni) insieme a eventuali risorse di supporto, come specifiche API e asset dell’interfaccia utente.

Questa struttura si integra naturalmente con l’architettura di runtime descritta in precedenza. Il container fornisce file persistenti e contesto di esecuzione, mentre lo strumento shell fornisce l’interfaccia di esecuzione. Con entrambi disponibili, il modello può individuare i file delle skill utilizzando comandi shell (`ls`, `cat`, etc.) quando necessario, interpretare le istruzioni ed eseguire gli script delle skill all’interno dello stesso ciclo dell’agente.

Forniamo API⁠(si apre in una nuova finestra) per gestire le skill nella piattaforma OpenAI. Gli sviluppatori caricano e archiviano le cartelle delle skill come bundle versionati, che possono essere recuperati successivamente tramite ID della skill. Prima di inviare il prompt al modello, la Responses API carica la skill e la include nel contesto del modello. Questa sequenza è deterministica:

1. Recuperare i metadati della skill, inclusi nome e descrizione.
2. Recuperare il bundle della skill, copiarlo nel container e decomprimerlo.
3. Aggiornare il contesto del modello con i metadati della skill e il percorso nel container.

Quando decide se una skill è pertinente, il modello esplora progressivamente le istruzioni ed esegue gli script tramite comandi shell nel container.

Per mettere insieme tutti gli elementi: la Responses API fornisce l’orchestrazione, lo shell tool fornisce azioni eseguibili, il hosted container fornisce un contesto di runtime persistente, le skills stratificano una logica di workflow riutilizzabile e la compaction consente a un agente di funzionare a lungo con il contesto di cui ha bisogno.

Con queste primitive, un singolo prompt può espandersi in un flusso di lavoro end-to-end: individuare la skill giusta, recuperare i dati, trasformarli in uno stato strutturato locale, interrogarli in modo efficiente e generare artefatti durevoli. 

Il diagramma seguente mostra come questo sistema funziona per creare un foglio di calcolo a partire da dati in tempo reale.

Per un esempio approfondito di come combinare lo strumento shell e l’ambiente informatico per flussi di lavoro end-to-end, consulta il nostro post del blog per sviluppatori⁠(si apre in una nuova finestra) e il cookbook⁠(si apre in una nuova finestra) che illustrano come creare un pacchetto di una skill ed eseguirla tramite la Responses API.

Siamo entusiasti di vedere cosa costruiranno gli sviluppatori con questo set di primitive. I modelli linguistici sono pensati per fare molto più che generare testo, immagini e audio–continueremo a far evolvere la nostra piattaforma per renderla sempre più capace di gestire attività complesse del mondo reale su larga scala.