OrcaRouter ha rilasciato OrcaReplay, un motore open source di record-and-replay progettato per registrare l’intera esecuzione di un agente AI, riprodurla successivamente in modo deterministico e ripartire da un punto preciso cambiando il modello utilizzato. Il progetto nasce per affrontare un problema tipico degli agenti: quando una sessione fallisce, una semplice riesecuzione può produrre un comportamento diverso perché cambia l’output del modello, mentre i normali strumenti di observability mostrano soprattutto costi, token e chiamate effettuate senza ricostruire esattamente ciò che è successo. OrcaReplay salva invece richieste, risposte in streaming, tool call, risultati degli strumenti, comandi di shell, modifiche al filesystem, timing ed exit code, producendo una traccia che può essere riutilizzata anche dopo la chiusura della sessione originale.
Il funzionamento di base ruota attorno a tre operazioni. Con orca record viene registrata una sessione reale dell’agente, con orca replay la stessa esecuzione può essere riprodotta senza effettuare nuove chiamate al modello e con orca replay --from è possibile ripartire da uno specifico checkpoint utilizzando eventualmente un modello diverso. Il replay offline riutilizza quindi le risposte già catturate durante la sessione originale e non richiede rete, nuovi token o ulteriori costi di inferenza. La funzione di fork cambia invece il comportamento a partire dal checkpoint selezionato: file, cronologia della conversazione e stato precedente restano invariati, mentre dal punto scelto viene interrogato un altro modello. In questo modo il modello diventa la principale variabile dell’esperimento e diventa possibile verificare se un errore sarebbe stato risolto diversamente da Claude, GPT, Gemini, Grok, DeepSeek, Qwen o da un altro modello accessibile attraverso un endpoint compatibile.
OrcaReplay sfrutta una caratteristica strutturale delle API dei modelli conversazionali: poiché sono stateless, a ogni turno l’agente reinvia la conversazione precedente insieme ai risultati delle tool call già eseguite. Posizionando un proxy tra agente e modello, OrcaReplay può quindi osservare l’intero ciclo composto da richiesta, risposta del modello, chiamata allo strumento, risultato restituito dall’harness e turno successivo. Questa cattura avviene sotto il livello applicativo dell’agente e non richiede necessariamente modifiche al codice dell’agente stesso. Per gli strumenti che supportano un override dell’endpoint, OrcaReplay configura automaticamente il proxy locale tramite variabili d’ambiente; per gli agenti che non espongono un base URL configurabile può utilizzare invece tecniche di intercettazione a livello di processo e rete.
Il protocollo del modello non contiene però tutte le informazioni necessarie per ricostruire il comportamento reale di un agente. Una risposta API può indicare che deve essere eseguito un comando, ma non registra necessariamente l’exit code della shell, il tempo impiegato dal processo, la distinzione tra stdout e stderr o un file modificato direttamente dall’applicazione. Per questo OrcaReplay utilizza più livelli di cattura. Oltre al proxy delle API, può inserire shim nel PATH per registrare i processi avviati dalla shell, acquisire snapshot e differenze del filesystem e, quando necessario, intercettare il traffico TLS degli agenti che comunicano con endpoint che non possono essere reindirizzati attraverso una normale variabile di configurazione. Tutti questi eventi vengono poi combinati nella stessa timeline.
L’intercettazione TLS è opzionale e serve in particolare per gli agenti nei quali non esiste un endpoint API configurabile. Il comando orca record exec --tls-intercept avvia l’applicazione senza sostituirne direttamente credenziali o origin e intercetta soltanto gli host esplicitamente previsti. OrcaReplay crea per ogni sessione una propria autorità di certificazione temporanea, utilizzata esclusivamente dal processo avviato per decifrare il traffico selezionato, mentre gli altri host vengono inoltrati senza essere letti. Al termine della registrazione la chiave viene eliminata. Questa modalità permette di catturare anche agenti come Codex CLI autenticati tramite un abbonamento ChatGPT, che comunicano con un proprio backend e non dispongono necessariamente del classico parametro base_url utilizzato dalle API OpenAI-compatible.
Le tracce prodotte possono essere esplorate attraverso un’interfaccia HTML autonoma. Il comando orca replay last --ui oppure orca ui apre una timeline contenente i turni del modello, i token utilizzati, le chiamate agli strumenti con relativi argomenti e risultati, i comandi di shell con durata ed exit code e le modifiche apportate ai file. L’interfaccia non richiede un server attivo e può essere esportata in un singolo file HTML tramite orca export. Il file risultante non contiene dipendenze esterne, quindi può essere allegato a una segnalazione di bug, conservato come artefatto della CI o aperto successivamente anche senza connessione di rete.
Un’altra funzione centrale è orca compare, che prende una sessione già registrata e la esegue da uno stesso checkpoint attraverso più modelli. Ogni variante parte quindi dagli stessi file e dallo stesso prefisso della conversazione. Il risultato può essere valutato tramite un comando scelto dall’utente, per esempio una compilazione TypeScript con tsc --noEmit, una suite di test o un altro controllo automatico. In questo modo il confronto non si basa semplicemente sulla valutazione qualitativa di risposte diverse, ma sull’esecuzione dello stesso task partendo dallo stesso stato e applicando una metrica riproducibile. I modelli vengono identificati tramite namespace del provider e possono essere raggiunti attraverso OrcaRouter oppure tramite qualsiasi gateway che esponga endpoint compatibili con le API OpenAI.
L’integrazione con OrcaRouter non è obbligatoria per utilizzare OrcaReplay. Durante una normale registrazione, se non è stato configurato un gateway specifico, il proxy inoltra le chiamate verso il provider che l’agente stava già utilizzando e con le credenziali già configurate nell’agente. orca setup propone OrcaRouter come gateway predefinito per le funzioni che richiedono l’esecuzione di nuovi modelli, come compare o fork, ma l’indirizzo può essere sostituito con un endpoint differente. OrcaRouter fornisce a sua volta un unico endpoint per accedere a oltre 200 modelli appartenenti a provider differenti, tra cui OpenAI, Anthropic e Google, oltre a sistemi open source.
Le credenziali dei provider non vengono inserite nella traccia. OrcaReplay costruisce il record a partire dalla richiesta in ingresso eliminando le informazioni di autenticazione, mentre la chiave viene aggiunta soltanto quando il proxy inoltra la richiesta al provider effettivo. Questo comportamento è implementato nel percorso di registrazione in modo che il token non debba essere successivamente rimosso attraverso una procedura di pulizia manuale. Il progetto include comunque anche orca scrub, destinato alla rimozione postuma di informazioni che non si desidera mantenere all’interno di una registrazione.
OrcaReplay può acquisire anche chiamate MCP. La registrazione viene attivata indicando una configurazione MCP e le informazioni necessarie vengono conservate nella sessione, in modo che replay e fork possano ricostruire lo stesso livello di integrazione. Questa funzione permette di seguire non soltanto la conversazione tra agente e modello ma anche l’utilizzo di server e strumenti esterni esposti attraverso Model Context Protocol. Il progetto offre inoltre un proprio server MCP tramite orca mcp, che consente a un altro agente di interrogare direttamente l’archivio delle tracce, visualizzare run e checkpoint, generare grafi, eseguire replay e avviare confronti tra modelli.
Le funzioni sono disponibili anche in modalità JSON, pensata soprattutto per script, pipeline CI e strumenti automatici. Comandi come list, show, events, checkpoints, graph, record, replay, compare e doctor possono restituire un singolo documento JSON su stdout, mantenendo diagnostica e output del processo registrato su stderr. Un replay può quindi indicare programmaticamente il numero di divergenze, le richieste che non hanno trovato corrispondenza nella registrazione, eventuali chiamate live e l’exit code finale. L’API può essere utilizzata anche direttamente da codice TypeScript attraverso il package OrcaReplay, senza dover necessariamente invocare la CLI come processo esterno.
Il progetto supporta già la cattura dei formati Anthropic e OpenAI-compatible, la Responses API di OpenAI, snapshot e diff del filesystem, shell capture, traffico di rete non relativo ai modelli, MCP e replay a partire da checkpoint. È stata implementata anche la cattura di agenti Node e Bun che non leggono variabili relative al base URL, attraverso un preload capace di reindirizzare le chiamate fetch verso gli host dei provider supportati. Per una richiesta non interpretabile dal sistema, OrcaReplay può inoltrare comunque il traffico e registrarlo come normale richiesta e risposta di rete, conservando quindi l’evidenza dell’evento anche quando non è possibile trasformarlo in un turno completamente riproducibile.
Lo stato del progetto viene ancora definito iniziale dagli sviluppatori. La versione attuale utilizza il formato di traccia v0 e il repository dichiara oltre 1.300 test eseguiti su Node 20 e 22, insieme a controlli di conformità del formato e dell’API dei plugin. OrcaReplay è stato inoltre validato attraverso l’esecuzione di un task reale con Claude Code, registrando la correzione di un bug, riproducendo offline l’intero processo e successivamente effettuando un fork da un checkpoint. Il repository pubblico è stato aggiornato il 1° settembre 2026.
L’installazione avviene tramite npm con il pacchetto orcareplay e richiede Node.js 20 o successivo. Il progetto non utilizza dipendenze native da compilare e, su Windows, può generare shim .cmd per catturare l’esecuzione dei comandi; se è disponibile una shell POSIX come Git for Windows può inoltre intercettare sh.exe o bash.exe. Il codice del core, della CLI, del viewer, degli adapter e dell’interfaccia provider è distribuito con licenza Apache 2.0, mentre la specifica del formato di traccia è pubblicata con licenza CC BY 4.0, permettendo anche implementazioni indipendenti dello stesso formato.
La differenza tecnica rispetto a un normale sistema di observability consiste quindi nel fatto che la traccia non serve soltanto a consultare ciò che un agente ha fatto, ma diventa un ambiente riproducibile. Una sessione problematica può essere rieseguita senza rete e senza nuove chiamate ai modelli, ispezionata passaggio per passaggio e poi biforcata nel punto in cui è avvenuto l’errore per verificare il comportamento di un modello differente. Questo consente di separare più precisamente gli errori determinati dal modello da quelli prodotti dall’harness, dagli strumenti, dai comandi eseguiti o dallo stato del filesystem, mantenendo invariata la parte dell’esecuzione precedente al checkpoint selezionato.
Questo articolo è stato redatto con il supporto di strumenti di intelligenza artificiale (AI)