Agent Harnesses: l'infrastruttura dietro agenti IA affidabili

Molte demo di agenti IA sembrano simili all'inizio: colleghi un buon modello, aggiungi alcuni strumenti, scrivi un buon prompt e lasci che il sistema lavori su un compito. Questo puo bastare per una demo. Non basta per la produzione. Gli agenti di produzione devono ricordare il contesto rilevante, usare strumenti in modo sicuro, recuperare dagli errori, rispettare i permessi, verificare il proprio lavoro e continuare a operare quando un compito dura piu di una singola risposta pulita del modello. Il modello conta, ma il sistema attorno al modello decide se l'agente e davvero utile ogni giorno. Questo sistema viene spesso chiamato agent harness, agent runtime, orchestration layer, execution environment o agent scaffolding. In questo articolo usiamo "agent harness" per indicare il runtime e il livello di orchestrazione attorno al modello. Altri team possono chiamare lo stesso livello agent framework, orchestration layer, execution runtime o agent scaffolding.

Che cos'e un agent harness

Un agent harness e l'infrastruttura software che trasforma un modello linguistico senza stato in un agente operativo. Il modello predice, pianifica ed esegue un'inferenza simile al ragionamento. Il harness gli fornisce un ambiente controllato nel quale puo agire. Un harness di produzione include di solito:

loop di orchestrazione
registrazione ed esecuzione degli strumenti
gestione del contesto
memoria a breve e lungo termine
persistenza dello stato
controlli sui permessi
esecuzione in sandbox
retry e gestione degli errori
loop di verifica
tracing e osservabilita
instradamento dei modelli
delega a subagenti

Senza questo livello, un agente IA resta di solito piu vicino a un'interfaccia tipo chat o a un assistente a passaggio singolo. Con questo livello, puo diventare un motore di workflow. Se un utente chiede di correggere un bug nel checkout, un modello puo suggerire dove guardare. Un harness permette invece all'agente di ispezionare il repository, cercare file, modificare codice, eseguire test, leggere errori, sistemare la patch, controllare il diff e fermarsi solo dopo aver verificato il risultato. Questa differenza e il prodotto.

Perche il harness conta sempre di piu

I team AI stanno imparando che due prodotti che usano lo stesso modello possono ottenere risultati molto diversi. La ragione e l'infrastruttura. I modelli frontier stanno migliorando rapidamente. Man mano che capacita come tool use, structured output, long context, code generation e inferenza simile al ragionamento diventano disponibili presso piu provider, una parte maggiore del vantaggio competitivo si sposta nell'ambiente attorno al modello. Anche il lavoro sul harness si accumula. Ogni errore puo diventare un miglioramento permanente del sistema:

Argomenti errati verso gli strumenti portano a schemi e validazioni piu rigidi.
Decisioni dimenticate portano a migliorare contesto e memoria.
Modifiche rischiose portano ad aggiungere permission gate.
Chiusure premature portano ad aggiungere verifica.
Chiamate costose ripetute portano a migliorare cache o routing.
Prestazioni peggiori con contesto lungo portano a compaction e retrieval.

I fix di prompt aiutano, ma non bastano. Il comportamento robusto nasce dal design del runtime.

Prompt engineering, context engineering e harness engineering

Questi termini sono collegati, ma non sono la stessa cosa. Prompt engineering e il livello delle istruzioni. Dice al modello quale ruolo seguire, quali vincoli contano e come rispondere. Context engineering e il livello informativo. Decide cosa vede il modello, quando lo vede e quanta parte di quell'informazione appartiene alla finestra corrente. Harness engineering e il livello completo di esecuzione. Include prompt e contesto, ma anche strumenti, stato, sicurezza, memoria, verifica, code, osservabilita e gestione del ciclo di vita. Questa distinzione conta perche i prompt chiedono un comportamento, mentre gli harness lo impongono. Un prompt puo dire: "Non cancellare file senza permesso." Un harness puo bloccare i comandi distruttivi finche l'utente non li approva. Un prompt puo dire: "Controlla il tuo lavoro." Un harness puo eseguire la suite di test, ispezionare l'output e impedire la chiusura se la verifica fallisce.

Come funziona un agent harness

La maggior parte degli agent harness segue un loop. Per prima cosa, il harness compone l'input del modello. Questo input puo includere il prompt di sistema, le istruzioni dello sviluppatore, la richiesta dell'utente, le definizioni degli strumenti, la memoria, lo stato corrente del task e il contesto selezionato da file o database. Poi il modello risponde. Puo restituire testo, dati strutturati, tool call o una richiesta di delegare il lavoro a un altro agente. Il harness classifica quindi l'output. Se il modello ha prodotto una risposta finale, il loop puo fermarsi. Se ha richiesto uno strumento, il harness valida la chiamata. La validazione e critica. Il harness verifica se gli argomenti rispettano lo schema, se lo strumento e disponibile, se l'azione e sicura e se utente o sistema hanno concesso il permesso necessario. Dopo parte lo strumento. Puo leggere file, interrogare un database, cercare documenti, chiamare API, eseguire codice, aprire un browser o scrivere una patch. Il risultato torna al modello come osservazione. Se lo strumento fallisce, l'errore deve essere confezionato in modo abbastanza chiaro da permettere al modello di recuperare. Il loop continua finche l'agente non raggiunge un punto di arresto verificato, incontra un limite di budget, richiede input umano o viene interrotto. Sembra semplice. La qualita di produzione vive nei dettagli attorno a questo loop.

Parti centrali di un harness di produzione

1. Loop di orchestrazione

Il loop di orchestrazione controlla i turni dell'agente. Pattern comuni:

ReAct: ragiona, agisci, osserva, ripeti
plan and execute: crea un piano e poi eseguilo
generate, test, repair: produci output, verificalo, correggi i problemi
gather, act, verify: raccogli contesto, agisci, verifica il risultato

Il loop puo essere tecnicamente piccolo. La parte difficile e decidere quale contesto entra in ogni turno, quali azioni sono permesse, cosa significano gli errori e quando un compito e davvero finito.

2. Livello strumenti

Gli strumenti sono il modo in cui l'agente tocca il mondo. Buoni strumenti sono progettati per i modelli, non solo per gli umani. Un umano puo interpretare output CLI rumoroso, default nascosti, flag ambigui e fallimenti parziali. Un agente ha bisogno di confini piu chiari. Il livello strumenti dovrebbe gestire:

nomi e descrizioni
schemi degli argomenti
controlli dei permessi
sandboxing
esecuzione
formattazione dell'output
retry
audit log

Il design degli strumenti decide spesso la qualita dell'agente. Troppi strumenti confondono il modello. Parametri vaghi producono chiamate poco affidabili. Permessi troppo larghi creano rischio. Gli harness migliori espongono il set minimo di strumenti utile per il passo corrente.

3. Gestione del contesto

Il contesto non e storage. E una superficie di lavoro scarsa. Finestre di contesto grandi aiutano, ma non eliminano il bisogno di selezione. Quando log irrilevanti, output vecchi, piani obsoleti e contenuto ripetuto riempiono la finestra, il modello diventa meno affidabile. Gli harness di produzione usano strategie come:

caricare prima piccoli indici
recuperare file o record esatti on demand
riassumere turni precedenti
nascondere vecchi output degli strumenti
mantenere decisioni e problemi aperti eliminando il rumore
delegare l'esplorazione a subagenti che restituiscono riassunti compatti

L'obiettivo non e il massimo contesto. L'obiettivo e il piu piccolo contesto ad alto segnale che aiuti il modello a fare bene il passo successivo.

4. Memoria

La memoria consente a un agente di portare con se informazioni utili tra turni e sessioni. La memoria a breve termine copre il task attivo. La memoria a lungo termine conserva fatti duraturi, preferenze, regole di progetto e decisioni ricorrenti. La memoria di lavoro puo includere file di avanzamento, todo list o scratchpad strutturati. La memoria non va trattata come verita. Va trattata come un indizio. Se la memoria dice che un progetto usa un certo framework, l'agente dovrebbe comunque ispezionare il progetto prima di applicare modifiche specifiche per quel framework. Questo evita che memoria vecchia diventi falsa certezza. La memoria richiede anche isolamento e revisione, perche fatti cattivi o malevoli memorizzati possono influenzare esecuzioni future. Un sistema di produzione deve evitare fughe di memoria tra utenti, team, tenant o confini di permesso.

5. Persistenza dello stato

I task di produzione spesso sopravvivono a una singola risposta del modello. Il harness dovrebbe tracciare:

ID di sessione
ID di esecuzione
stato corrente
tool call in sospeso
file toccati
agenti figli
approvazioni concesse
costo e uso di token
risultato finale
stato di consegna

Lo stato consente di riprendere un task dopo un'interruzione. Fornisce anche auditabilita: cosa e successo, quando, perche e attraverso quale strumento.

6. Gestione degli errori

Gli errori sono normali nei workflow con agenti. Un harness solido separa i tipi di errore:

errori transitori dovrebbero essere ritentati con backoff
errori di argomenti dovrebbero restituire feedback chiaro al modello
errori di permesso dovrebbero richiedere approvazione o scegliere un percorso sicuro
errori imprevisti dovrebbero fermarsi con diagnostica utile

Questo conta perche i task multi-step accumulano errori. Anche un alto tasso di successo per step puo diventare debole su una sequenza lunga. La logica di recupero non e opzionale.

7. Guardrail e permessi

Il modello puo decidere cosa vuole fare. Il harness deve decidere cosa gli e permesso fare. Confini utili dei permessi:

accesso in sola lettura contro scrittura
scope del workspace
approvazione per comandi distruttivi
approvazione per mutazioni di database
limiti per API esterne
restrizioni di accesso alle credenziali
revisione umana prima di un'azione rivolta all'utente

Questo livello deve essere imposto dal codice, non solo descritto in un prompt. Per azioni ad alto rischio, l'approvazione dovrebbe arrivare prima dell'esecuzione dello strumento, non dopo.

8. Loop di verifica

La verifica e il punto in cui gli agenti diventano affidabili. Per i task software, la verifica puo includere test, type check, linters, build, screenshot, browser check e revisione del diff. Per i workflow di business, puo includere validazione di schemi, vincoli di database, revisione umana, soglie di confidenza, citazioni di documenti e ispezione delle trace. Una parte della verifica e deterministica. Un'altra usa un modello come giudice. I controlli deterministici dovrebbero essere preferiti quando esiste una ground truth oggettiva.

9. Osservabilita

I team devono vedere come si comportano gli agenti. Un harness di produzione dovrebbe tracciare:

prompt e output del modello
tool call
risultati degli strumenti
errori
retry
approvazioni
uso di token
latenza
risultati della verifica
risultati finali

Senza osservabilita, i team non possono migliorare il sistema. Possono solo indovinare perche ha fallito.

Subagenti e gestione del ciclo di vita multi-agente

Quando un agente puo creare altri agenti, il problema cambia. I subagenti sono utili quando il lavoro puo essere diviso. Un agente puo ispezionare documentazione mentre un altro fa review del codice. Uno puo testare la UI mentre un altro corregge la logica backend. Uno puo ricercare fonti mentre un altro scrive la bozza. Ma creare subagenti non equivale a gestirli. La gestione del ciclo di vita multi-agente inizia quando il runtime deve possedere molti agenti in esecuzione nel tempo. Un sistema multi-agente serio ha bisogno di:

ID durevoli per gli agenti figli
lineage padre-figlio
ID di esecuzione
ruoli e limiti di profondita
code
cancellazione
steering
eventi di completamento
policy di cleanup
recupero dopo riavvio

La domanda chiave diventa: dove vive l'agente figlio, chi lo possiede, come riporta indietro il risultato e cosa succede se il genitore e gia andato oltre. La delega semplice restituisce un riassunto al genitore. La gestione del ciclo di vita multi-agente tratta il completamento come un problema di instradamento. Un figlio puo finire mentre il genitore e attivo, inattivo, riavviato o assente. Il runtime deve consegnare quel risultato al posto giusto con provenienza intatta. Per questo i sistemi di agenti avanzati iniziano a somigliare a process manager. Hanno bisogno di identita, ciclo di vita, code, recupero e cleanup.

Managed agents contro harness personalizzati

Le piattaforme di managed agents stanno diventando piu comuni. Impacchettano harness e infrastruttura di produzione per permettere ai team di muoversi piu rapidamente. Questo puo essere utile quando un team vuole:

lanciare piu velocemente
un runtime ospitato
scaling integrato
esecuzione gestita degli strumenti
osservabilita standard
meno responsabilita infrastrutturale

Ma i managed agents restano anche una decisione architetturale. I team possono comunque aver bisogno di un harness personalizzato quando:

la qualita del workflow e valore centrale del prodotto
gli strumenti di dominio sono molto specifici
permessi e audit trail sono rigidi
conta il costo per task
agenti di lunga durata hanno bisogno di regole di ciclo di vita proprie
il vendor lock-in e un rischio rilevante
il comportamento dell'agente standard va male nelle eval interne

Per molti team, la strada pratica non e "costruire tutto da zero" o "usare solo un runtime gestito". E una strada graduale. Si parte con gli strumenti esistenti. Si costruiscono eval. Si trovano pattern di fallimento. Si personalizza il harness dove gli errori ripetuti o l'economia lo giustificano.

Quando il tuo team dovrebbe interessarsene

Dovresti prendere sul serio il design del harness quando un workflow AI va oltre il prototipo. Segnali chiari:

gli utenti dipendono dall'output
gli errori generano costo operativo
il workflow tocca dati privati o regolati
l'agente ha bisogno di strumenti con effetti collaterali
il compito richiede molti passaggi
l'output necessita verifica
la revisione umana richiede audit trail
il costo dei token diventa visibile
il comportamento dell'agente cambia in modo imprevedibile tra un run e l'altro

A quel punto il modello e solo una parte del sistema. L'affidabilita arriva dal harness.

Come affrontiamo questo tema in Lunover

In Lunover trattiamo gli agenti IA come sistemi software di produzione, non come esperimenti di prompt. Questo significa partire dal valore del workflow. Mappiamo processo reale, fonti dati, rischi, utenti e criteri di successo prima di costruire. Poi scegliamo il livello giusto di complessita del harness per il lavoro da svolgere. Per un assistente interno semplice, questo puo significare retrieval, tool use e monitoraggio di base. Per un workflow rivolto al cliente, puo richiedere permessi piu rigidi, eval, fallback, trace review e approvazione umana. Per automazioni di lunga durata, puo richiedere stato durevole, job queue, recupero e ownership chiara di ogni azione eseguita dall'agente. L'obiettivo non e far sembrare l'agente impressionante in demo. L'obiettivo e rendere il sistema utile dopo il lancio. Se il tuo team sta costruendo agenti IA, copilots, sistemi RAG o automazione di workflow, Lunover puo aiutare attraverso Sviluppo AI, Web app e Sistemi aziendali, con attenzione al livello di produzione attorno al tuo modello: strumenti, memoria, permessi, verifica, osservabilita e deployment.