Dentro il ciclo dell'agente Codex: lezioni dal rilascio Android di 28 giorni di Datadog e Sora

Codex ha consegnato l'app Android di Sora con quattro ingegneri in 28 giorni. In Datadog, oggi oltre mille ingegneri si affidano ad esso per individuare difetti a livello di sistema che i revisori umani tendevano a lasciarsi sfuggire. Entrambe le storie nascono dalla stessa architettura: un ciclo di controllo apparentemente semplice, che avvolge un modello linguistico, un insieme di strumenti e un ambiente sandbox.

Se stai costruendo un assistente di programmazione AI, una pipeline di generazione media, o qualsiasi agente che debba agire sul mondo, il ciclo dell'agente Codex è il riferimento più pulito che puoi studiare oggi. Questo articolo percorre integralmente il suo funzionamento, cosa ne fanno effettivamente i team di produzione, e come lo stesso schema architetturale si trasferisce agli agenti di generazione media che puoi costruire su hiapi.

Questo articolo si basa sugli articoli di ingegneria pubblici di OpenAI: "Come funziona il ciclo dell'agente Codex" (gennaio 2026), il case study Datadog e la retrospettiva sulla consegna di Sora Android. I prezzi della piattaforma Hiapi citati di seguito sono aggiornati a 2026-06.

Cos'è esattamente il ciclo dell'agente

Il ciclo dell'agente è il flusso di controllo tra te, il modello linguistico e gli strumenti che il modello è autorizzato a chiamare. Dal punto di vista dell'utente, un "turno" sembra semplicemente un messaggio in chat che entra e uno che esce. Ma sotto il cofano, un singolo turno può contenere più andate e ritorni tra il modello e gli strumenti esterni.

La forma di un turno:

1. Preparazione del prompt. L'agente assembla il prompt di sistema, le istruzioni a livello di progetto (in Codex sono i file AGENTS.md), la cronologia della conversazione e il nuovo messaggio dell'utente.
2. Ragionamento. Il modello restituisce un messaggio finale dell'assistente, oppure una chiamata a uno strumento.
3. Se è una chiamata a uno strumento, l'agente la esegue nella sandbox, cattura il risultato, lo aggiunge alla conversazione, e torna al passo 2.
4. Se è un messaggio finale dell'assistente — qualcosa come "Ho aggiunto l'architecture.md che mi hai chiesto" — il turno termina e il controllo torna all'utente.

La caratteristica chiave è che l'"output" non è solo il messaggio dell'assistente che vedi nel terminale. Gran parte dell'output reale sono gli effetti collaterali delle chiamate agli strumenti: i file scritti, i test eseguiti, i pacchetti installati. Il messaggio dell'assistente è solo il segnale di terminazione.

Ecco perché il ciclo dell'agente non è solo "una chat con qualche passo in più". La chat ha un solo andata e ritorno per turno. Il ciclo dell'agente, invece, può completare decine di cicli "ragionamento → strumento → ragionamento" in un singolo turno, e l'utente vede solo il messaggio conclusivo.

Tre caratteristiche che rendono il ciclo veloce

Un'implementazione ingenua del ciclo di cui sopra funziona, ma dopo pochi turni diventa lenta e costosa. Il design di Codex risolve questo problema con tre idee degne di essere riprese.

1. Caching dei prefissi sulle Responses API. Ogni volta che l'agente parla con il modello, il prompt inizia con lo stesso lungo prefisso: prima il prompt di sistema, poi AGENTS.md, poi la conversazione precedente. La prima richiesta calcola e memorizza nella cache lo stato chiave-valore interno al modello corrispondente a quel prefisso. Le richieste successive nella stessa sessione saltano il ricalcolo per qualsiasi prefisso condiviso.

Una conseguenza pratica: non modificare AGENTS.md a metà sessione. Il prompt di sistema è di solito il blocco più grande nella cache, e modificarlo invalida la cache per il resto della sessione. Gli stessi ingegneri di Codex lo elencano come la causa più comune di rallentamenti "auto-inflitti".

2. I risultati delle chiamate agli strumenti restano dentro il ciclo, non si sovrappongono ad esso. Ogni output di uno strumento viene aggiunto alla stessa conversazione. Sembra ovvio, ma significa che il modello ha memoria completa di ogni comando che ha eseguito, ogni errore che ha visto, ogni file che ha ispezionato — senza che tu debba fare alcun riassunto manuale. Il costo è che la finestra di contesto cresce rapidamente; Codex lo gestisce con la compressione automatica quando la conversazione diventa troppo lunga.

3. La terminazione viene rilevata dalla forma dell'output del modello, non contando i turni. L'agente non ha una rete di sicurezza basata su un numero massimo di iterazioni. Finché il modello continua a emettere chiamate agli strumenti, continua a ciclare; non appena il modello emette un normale messaggio dell'assistente, si ferma immediatamente. Questa decisione è affidata al modello, il che mantiene snello il codice di orchestrazione.

Caso uno: Datadog usa il ciclo per la revisione del codice a livello di sistema

Il punto più utile del case study Datadog è che ti dice in cosa il ciclo dell'agente eccelle in produzione, e in cosa non eccelle.

Il team AI Developer Experience di Datadog voleva un agente di revisione del codice capace di individuare il tipo di difetti che i revisori umani si lasciano sfuggire — non lint, non stile, ma regressioni tra servizi, dirupi di prestazioni e modifiche che avrebbero riprodotto guasti reali. Hanno osservato che la maggior parte degli strumenti precedenti si comportava come un "linter avanzato". Segnalavano solo schemi superficiali all'interno di un singolo diff. Non avevano alcun modello del sistema circostante.

Per validare l'agente prima del rollout, il team ha costruito un framework di test per il replay dei guasti: hanno ricostruito le pull request che avevano causato guasti passati, le hanno date in pasto a Codex come se fossero arrivate di nuovo in revisione, e poi hanno chiesto agli ingegneri di turno se il commento di Codex avrebbe cambiato l'esito.

Il risultato pubblicato è: Codex ha fornito feedback nuovo e utile su circa il 22% dei guasti storici — più di qualsiasi altro strumento valutato dal team. Poiché ogni pull request era già passata attraverso la revisione umana, quel test misurava essenzialmente "ciò che i revisori si erano lasciati sfuggire".

Oggi oltre 1.000 ingegneri Datadog lo usano su ogni PR. Gli ingegneri rispondono ai commenti con 👍/👎 e o modificano il codice, o saltano il suggerimento allegando una motivazione. La scelta di design interessante è che Datadog misura l'impatto tramite canali laterali — post degli ingegneri su Slack che menzionano scoperte utili — invece che con metriche formali interne allo strumento. Il team considera l'agente un potenziamento, non un guardiano; presenta segnali, e l'umano prende ancora la decisione.

Lo schema da trarre: il ciclo dell'agente è più bravo a ragionare sull'intero sistema (dipendenze, test, servizi correlati) che non solo sul diff immediato. Questo richiede dargli gli strumenti giusti e i giusti permessi di lettura. Il ciclo dell'agente è il telaio; la superficie degli strumenti e il contesto di progetto sono ciò che determina se riesce a presentare il rischio reale.

Caso due: consegnare Sora per Android in 28 giorni

La storia di Sora Android è una prova ancora più audace. Tra l'8 ottobre e il 5 novembre 2025, un team di quattro ingegneri ha usato Codex per portare Sora da "solo iOS" a un rilascio pubblico Android — un ciclo di 28 giorni, con una build per i dipendenti interni al giorno 18, e il rilascio pubblico dieci giorni dopo. L'app ha raggiunto la vetta del Google Play Store; gli utenti hanno creato oltre un milione di video nelle prime 24 ore. Tasso di crash-free al rilascio: 99,9%.

Il team ha spiegato francamente cosa ha funzionato e — cosa più utile — cosa non ha funzionato.

Cosa non ha funzionato è stato il prompt ovvio: "Costruisci l'app Android di Sora basandoti sul codice iOS. Inizia." Ci hanno provato, e l'hanno presto abbandonato. Il prodotto era tecnicamente funzionante, ma l'esperienza del prodotto era mediocre. Per usare le loro parole, Codex "non è ancora bravo a dedurre ciò che non gli viene detto" e fatica a fare "profondo giudizio architetturale" senza guida.

Cosa ha funzionato è stato trattare Codex come un traduttore semantico tra piattaforme, e costruirgli attorno un'impalcatura solida:

• Hanno prima stabilito gli schemi architetturali del progetto — navigazione, dependency injection, rete — e scritto a mano alcune funzionalità di esempio. Queste hanno fissato lo standard per il resto del codice.
• Hanno usato i file AGENTS.md per codificare le convenzioni del team, mantenendo coerente l'output di Codex.
• Hanno fatto riferimento frequentemente a Codex il codice Swift iOS e il backend esistente, chiedendogli di generare Kotlin semanticamente equivalente. Il loro riassunto è: "Il futuro del cross-platform è Codex."
• Hanno trattato Codex come un "ingegnere senior appena assunto" — l'umano si occupa di architettura, progettazione del sistema ed esperienza utente; Codex si assume il lavoro pesante entro confini chiari.

Secondo quanto riportato, la percentuale di codice generato da Codex si avvicina all'85%, e in quattro settimane hanno consumato un budget di circa 5 miliardi di token.

Ci sono due lezioni facili da sottovalutare. Primo, la qualità dell'agente è limitata da quanto bene costruisci l'impalcatura: esempi, AGENTS.md, confini chiari. Secondo, per progetti greenfield, "un piccolo team più un agente capace" batte "espandere il numero di ingegneri" — l'osservazione di Fred Brooks ha finalmente trovato un controesempio nelle mani giuste.

Gli schemi trasferibili

Spogliati dei dettagli specifici della revisione del codice e della consegna Android, restano quattro schemi che ogni team che costruisce agenti dovrebbe copiare.

Stabilisci gli schemi prima di estenderti. Che si tratti di schemi di navigazione (Sora) o di cosa conta come "modifica rischiosa" (Datadog), il lavoro umano avviene in anticipo. Le funzionalità di esempio e un AGENTS.md stabile sono il modo in cui trasmetti questi schemi a ogni turno successivo — e sono esattamente ciò che il caching dei prefissi premia.

Dai all'agente la superficie di strumenti giusta, non la più grande. I revisori di Datadog hanno bisogno di leggere tra i servizi. Il traduttore di Sora ha bisogno di leggere il codice sorgente iOS e il backend. Entrambi i team hanno curato con attenzione la superficie di lettura. Un elenco di strumenti più ampio non è sinonimo di migliore.

Lascia che l'umano si occupi dell'architettura e l'agente dell'implementazione. Entrambi i case study convergono su questa divisione del lavoro. L'umano stabilisce le decisioni strutturali; l'agente riempie entro confini chiari. Invertire questa divisione è esattamente dove i team sprecano tempo.

Misura per risultati, non per metriche dello strumento. Datadog osserva deliberatamente le reazioni su Slack e gli esiti dei guasti, non il tasso di output dell'agente stesso. Questo mantiene onesto l'obiettivo di ottimizzazione. Uno strumento di revisione del codice che produce molti commenti ma non cambia il comportamento dei guasti non è uno strumento utile.

Applicare il ciclo agli agenti di generazione media

L'architettura del ciclo dell'agente non è esclusiva del codice. Ovunque tu abbia bisogno che un modello agisca, osservi e iteri, si applica lo stesso flusso di controllo.

La piattaforma hiapi espone tutti i modelli di generazione media tramite un endpoint asincrono unificato — POST /v1/tasks crea un'attività di generazione, GET /v1/tasks/:id raccoglie il risultato — quindi il passo di "azione" nel ciclo è una funzione a due chiamate che scrivi una volta e riutilizzi su tutti i modelli. In concreto, puoi costruire un agente di produzione video il cui ciclo sia così:

1. L'agente riceve un brief: "Crea una ripresa prodotto di 6 secondi, con un orologio su un marmo."
2. Assembla il prompt e crea un'attività seedance-2-0 tramite POST /v1/tasks, poi interroga l'ID attività fino al completamento (a 2026-06, sulla piattaforma hiapi il 480P è prezzato a $0,15 al secondo di video, il 720P con un coefficiente di 2,2x — la clip di 6 secondi sopra costa $0,90 a 480P).
3. Scarica il video generato, esegue un rapido passo di revisione — "Il quadrante è davvero visibile? L'illuminazione è coerente con il brief?" — e poi o accetta l'output, o modifica il prompt.
4. Se la revisione fallisce N volte di fila, l'agente passa la palla all'utente, allegando il miglior risultato finora e una descrizione del problema.

La stessa forma vale per gli agenti di generazione di immagini: brief → chiamata text-to-image (ad esempio gpt-image-2 a $0,03 per immagine a 1K, o Nano-Banana-2 a $0,085 a 1K) → ispezione visiva → modifica → nuovo tentativo. Lo schema di Codex "cacha stabilmente il prompt di sistema e lascia che gli output delle chiamate agli strumenti si accumulino nella conversazione" si applica direttamente: metti le definizioni del ruolo e le linee guida del brand nel prompt di sistema, e lascia che il ciclo accumuli ogni tentativo di generazione e revisione come turni nello stesso thread.

Alcune conversioni pratiche per trasferire le lezioni di Codex agli agenti media:

• AGENTS.md diventa il file delle linee guida del brand. Stabile, caricato una sola volta, mai modificato a metà sessione. È esattamente ciò che il caching dei prefissi premia.
• Le funzionalità di esempio diventano output di riferimento. Immagini curate a mano di "come appare un buon risultato", da confrontare nel passo di revisione.
• La sandbox diventa un limite di velocità e di spesa. Un agente media che non ha imparato quando fermarsi può accumulare una grande quantità di generazioni. Imposta un limite di spesa per turno, come Codex limita di default le scritture sul filesystem.
• Il segnale di terminazione è identico. Il ciclo finisce quando il passo di revisione restituisce "accetta" invece di un'altra richiesta di generazione.

Se vuoi provare prima i modelli di base dietro questo tipo di ciclo, senza scrivere subito la logica di orchestrazione, la pagina dei prezzi di hiapi elenca i prezzi attuali per immagine e per secondo di video, e le pagine di dettaglio di ogni modello hanno un Playground dove puoi eseguire un prompt prima di decidere cosa collegare all'agente.

FAQ

Cos'è il ciclo dell'agente Codex?

È il flusso di controllo interno a Codex CLI, che orchestra l'interazione tra te, il modello e gli strumenti che il modello è autorizzato a chiamare. Ogni "turno" può contenere al suo interno più cicli di ragionamento del modello → chiamata a uno strumento, e termina quando il modello emette un normale messaggio dell'assistente invece di un'altra chiamata a uno strumento.

Perché il caching dei prefissi è così importante per gli agenti?

Perché ogni turno reinvia un lungo prefisso — prompt di sistema, istruzioni di progetto, cronologia della conversazione. Senza cache, il modello ricodificherebbe tutti questi contenuti a ogni richiesta, lento e costoso. Con la cache, il prefisso condiviso viene calcolato una volta e riutilizzato nei turni successivi della stessa sessione. Il significato pratico è: non modificare le istruzioni di progetto (ad esempio AGENTS.md) a metà sessione, perché questo invalida la cache per il resto della sessione.

Quanti ingegneri servono per consegnare qualcosa come Sora per Android?

Il numero pubblicato da OpenAI è quattro ingegneri, 28 giorni, con Codex che secondo quanto riportato ha generato quasi l'85% della base di codice, e il progetto complessivo che ha consumato circa 5 miliardi di token. Il team ha scelto esplicitamente di restare piccolo — citando il "aggiungere persone a un progetto in ritardo lo rende solo più in ritardo" di Brooks — e di affidarsi all'agente per l'implementazione.

Cosa ha effettivamente catturato Codex nella valutazione di Datadog?

Nel metodo di "replay dei guasti" del team, hanno rieseguito tramite Codex le PR che storicamente avevano causato guasti, e hanno chiesto agli ingegneri di turno se il feedback avrebbe cambiato l'esito. Codex ha fornito feedback azionabile su circa il 22% dei guasti — ad esempio regressioni tra servizi e cambiamenti di prestazioni che i revisori umani si erano lasciati sfuggire quando la PR era stata originariamente integrata.

Posso usare lo stesso schema di ciclo dell'agente per la generazione di immagini o video?

Sì. Lo schema architetturale — prepara il prompt, chiama il modello, esegui gli strumenti, aggiungi i risultati, cicla fino alla terminazione — è indipendente dal modello. Puoi collegarlo agli endpoint di generazione media di hiapi (modelli di immagini come gpt-image-2 o nano-banana-2, modelli video come seedance-2-0), e seguire le stesse lezioni: prompt di sistema stabili per favorire il caching dei prefissi, esempi per garantire la qualità, limiti di spesa sandbox per la sicurezza, e un passo di revisione per decidere la terminazione.

Cosa dovrei mettere in AGENTS.md?

Specificamente per Codex: convenzioni del progetto, comandi di build/test/lint, regole di stile del codice, e qualsiasi confine "da non toccare". I team pubblicati di Sora e Datadog lo trattavano come il documento di onboarding dell'agente — le cose che diresti a un ingegnere senior il primo giorno. Mantienilo stabile durante la sessione, così resta nella cache dei prefissi.

Punti chiave

• Il ciclo dell'agente Codex è un semplice flusso di controllo: prepara il prompt → ragionamento del modello → chiamata opzionale a uno strumento → aggiungi il risultato → ripeti, finché il modello emette un normale messaggio dell'assistente.
• Tre dettagli implementativi lo portano a livello di produzione: il caching dei prefissi, i risultati delle chiamate agli strumenti che restano nella conversazione, e il rilevamento della terminazione guidato dalla forma dell'output del modello.
• Datadog usa questo ciclo per la revisione del codice a livello di sistema per oltre 1.000 ingegneri; il suo framework di test per il replay dei guasti mostra che Codex cattura circa il 22% dei problemi legati ai guasti storici che i revisori umani si erano lasciati sfuggire.
• OpenAI ha consegnato l'app Sora Android con quattro ingegneri in 28 giorni, con circa l'85% del codice generato da Codex e un tasso di crash-free al rilascio del 99,9% — grazie a una pesante impalcatura fatta di esempi e AGENTS.md, non al prompt "vai e costruiscilo".
• La stessa architettura del ciclo dell'agente si trasferisce in modo pulito alle pipeline di generazione media che puoi costruire su hiapi: ogni modello text-to-image e text-to-video usa la stessa forma asincrona /v1/tasks, e le mosse di Codex su caching dei prefissi, sandbox ed esempi si mappano una a una sugli agenti di immagini e video.