Loop, Graph e Harness: i 3 pilastri dell'ingegneria degli agenti AI

I 3 Sistemi di Agenti AI che Ogni Costruttore Deve Conoscere

Fallimenti degli Agenti

La maggior parte dei sistemi di agenti non fallisce perché il modello è troppo debole

Falliscono perché il sistema attorno al modello non è mai stato progettato come un sistema

Gli strumenti sono inaffidabili

Lo stato scompare tra un'esecuzione e l'altra

L'agente riprova senza imparare nulla

Il flusso di lavoro si dirama in modi che nessuno può ispezionare

Poi ogni fallimento viene attribuito al modello

Questa è la diagnosi sbagliata

Ci sono tre diversi livelli ingegneristici alla base di un agente serio:

• l'harness fornisce al modello un posto dove lavorare
• il loop dà al lavoro un ciclo di feedback
• il graph dà al processo un percorso esplicito

Si sovrappongono

Possono contenersi l'un l'altro

Ma risolvono problemi diversi

Un modello decide. Un harness gli permette di agire. Un loop gli fa dimostrare il risultato. Un graph controlla cosa è permesso fare dopo.

La versione in 30 secondi

L'ingegneria dell'Harness costruisce l'ambiente operativo attorno al modello

Strumenti, memoria, file, permessi, sandbox, routing, checkpoint, tracce e approvazioni umane vivono qui

L'ingegneria del Loop progetta lavoro ripetuto e feedback

L'agente produce qualcosa, lo verifica rispetto alle evidenze, riceve un segnale di fallimento utile e riprova sotto una regola vincolata

L'ingegneria del Graph rende esplicito il controllo del flusso

Definisce i nodi, le diramazioni, le giunzioni, il lavoro parallelo, i cicli legali, le transizioni di stato e i percorsi di uscita

Il modo più semplice per ricordare la differenza è:

1HARNESS = ENVIRONMENT
2LOOP    = FEEDBACK
3GRAPH   = FLOW

Questa distinzione diventa importante non appena un agente esce da una demo e inizia a toccare file reali, API, clienti, denaro o codice di produzione

Perché le persone continuano a confonderli

Tutti e tre i livelli si trovano attorno allo stesso modello

Tutti e tre influenzano l'affidabilità

Tutti e tre possono includere qualcosa che assomiglia a un loop

E in un piccolo prototipo, tutti e tre sono di solito sepolti all'interno di un unico script

Questo li fa sembrare intercambiabili

Non lo sono

Considera un agente di base che usa strumenti

1chiedi al modello
2ricevi chiamata strumento
3esegui strumento
4restituisci osservazione
5chiedi di nuovo al modello
6fermati quando finito

Quel piccolo ciclo fa parte del runtime

Ma le definizioni degli strumenti, il filesystem e l'archivio di stato appartengono all'harness

La politica di test e riprova è una decisione di progettazione del loop

La scelta tra ricercatore, revisore e pubblicatore è una decisione di progettazione del graph

Un singolo pezzo di software può contenere tutti e tre i livelli contemporaneamente

L'architettura più pulita inizia nominandoli separatamente

Livello 1: Ingegneria dell'Harness

Un modello grezzo può trasformare input in output

Non può mantenere in modo indipendente lo stato del progetto, eseguire una suite di test, ispezionare un browser, scrivere file in sicurezza, applicare permessi o riprendere domani da dove si era fermato oggi

L'harness fornisce queste capacità

La definizione più semplice è:

Il modello è l'intelligenza. L'harness è la macchina che rende utile quell'intelligenza.

Rimuovi il modello dal tuo diagramma architetturale

Tutto ciò che è ancora visibile è probabilmente parte dell'harness

Questo è il passaggio alla produzione che Boris Cherny continua a sottolineare attraverso Claude Code: hook, esecuzioni programmate, worktree isolati, agenti personalizzati ed esecuzione parallela non sono trucchi di prompt

Sono primitive dell'harness

https://x.com/bcherny/status/2038454336355999749

Cosa appartiene a un harness serio

Contesto

• istruzioni di sistema
• conoscenza recuperata
• stato della conversazione
• politiche del compito
• competenze e procedure operative

Superfici d'azione

• API
• controllo del browser
• shell ed esecuzione di codice
• database
• strumenti MCP
• agenti specializzati

Persistenza

• file
• checkpoint
• stato della sessione
• registri di avanzamento
• cronologia git
• memoria a lungo termine

Controllo dell'esecuzione

• timeout
• limiti di riprova
• budget di token e costi
• routing del modello
• passaggi di consegne
• porte di approvazione

Sicurezza

• ambienti isolati
• permessi con privilegio minimo
• liste consentite
• gestione dei segreti
• autorizzazione umana

Osservabilità

• tracce
• input e output degli strumenti
• transizioni di stato
• costi e latenza
• risultati di valutazione

Dove l'ingegneria dell'Harness dà i suoi frutti

Il lavoro sull'harness diventa critico quando i compiti durano più di una finestra di contesto

Un agente di codifica che lavora per ore non può fare affidamento solo sulla cronologia della chat

Ha bisogno di artefatti durevoli che un'altra sessione possa comprendere

Un setup utile potrebbe includere:

• un inizializzatore che ispeziona l'area di lavoro
• un file di avanzamento che spiega cosa è stato fatto e cosa rimane
• commit git che preservano gli stati funzionanti
• checkpoint prima di azioni rischiose
• strumenti di verifica che producono prove chiare

Questo non è un prompt migliore

È un ambiente di lavoro migliore

Inizia con l'ingegneria dell'harness quando l'agente:

• non può accedere alla capacità giusta
• perde progressi tra le sessioni
• ha permessi troppo ampi
• si comporta diversamente tra ambienti
• non può essere messo in pausa, ispezionato o ripreso
• produce fallimenti che nessuno può ricostruire

Livello 2: Ingegneria del Loop

Ogni agente che usa strumenti ha già un piccolo loop interno

1model -> action -> observation -> model

L'ingegneria del Loop inizia quando progetti intenzionalmente i cicli attorno a quel comportamento

L'obiettivo non è far ripetere l'agente all'infinito

L'obiettivo è trasformare un tentativo singolo in un processo gestito

Il loop di verifica

Il loop esterno più utile è semplice

1COSTRUISCI
2  ↓
3VERIFICA CONTRO LE EVIDENZE
4  ↓
5PASS? ── sì ──> FERMATI
6  │
7  no
8  ↓
9RESTITUISCI FEEDBACK SPECIFICO
10  ↓
11RIPROVA CON UN LIMITE

La verifica può essere deterministica:

• test superati
• schema validato
• link risolti
• numeri riconciliati
• file compilati

Oppure può richiedere un revisore:

• l'argomento è completo
• il tono corrisponde al pubblico
• le prove supportano la conclusione
• la modifica è ben dimensionata

La regola è la stessa

Non fare loop sulla fiducia

Fai loop sulle evidenze

"L'agente dice di aver finito" non è una prova

"I test passano, le fonti si risolvono e il revisore ha approvato la modifica" è una prova

La leva sta nel costruire il ciclo una volta e lasciare che il sistema lo esegua per te

Le attività pianificate di Claude sono la versione di prodotto visibile dello stesso cambiamento: definisci il lavoro ricorrente una volta e lascia che il sistema lo riprenda senza un altro prompt manuale

La pianificazione è solo il trigger

I controlli, il feedback e la condizione di uscita sono ciò che trasforma il compito ricorrente in un loop ingegnerizzato

https://x.com/claudeai/status/2026720870631354429

L'anatomia di un loop utile

Ogni loop di produzione ha bisogno di sette cose

1. Trigger

Cosa avvia un altro ciclo: una richiesta, un programma, un webhook, un test fallito, un nuovo documento o il risultato di un valutatore

2. Obiettivo

Uno stato misurabile da raggiungere, non "continua a migliorare"

3. Stato

Cosa deve sapere il prossimo tentativo senza dover riprodurre l'intera cronologia

4. Politica d'azione

Cosa l'agente può modificare, chiamare, delegare o spendere

5. Evidenze

Test, citazioni, diff, metriche, schemi o revisione umana

6. Feedback

Una spiegazione compatta di cosa è fallito e cosa deve cambiare

7. Regola di arresto

Successo, tentativi massimi, esaurimento del budget, timeout, errore grave o escalation umana

I loop possono impilarsi

Il loop dell'agente esegue il lavoro

Il loop di verifica controlla il lavoro

Un loop di eventi sveglia il sistema quando arriva nuovo lavoro

Un loop di miglioramento studia le tracce di produzione e modifica l'harness stesso

1EVENT LOOP
2└── VERIFICATION LOOP
3    └── AGENT LOOP
4
5TRACE IMPROVEMENT LOOP
6└── aggiorna prompt, strumenti, politiche e valutatori

Ecco perché l'ingegneria del Loop è più grande dell'ingegneria dei prompt

Un prompt definisce cosa dovrebbe accadere durante una chiamata al modello

Un loop definisce cosa fa il sistema dopo quella chiamata

Il costo è ovvio

Ogni riprova, valutatore e revisore aggiunge latenza e spesa

Aggiungi un loop quando il costo previsto del fallimento è superiore al costo della verifica

Livello 3: Ingegneria del Graph

L'ingegneria del Graph pone una domanda diversa

Non "come dovrebbe funzionare l'agente"

Ma "cosa è permesso eseguire dopo"

Il lavoro diventa nodi

Le transizioni consentite diventano archi

Lo stato si muove attraverso il grafo

Quella struttura può rappresentare:

• sequenze fisse
• diramazioni condizionali
• espansione parallela
• giunzioni
• cicli limitati
• percorsi di recupero
• interruzioni umane

Cosa decidono realmente gli ingegneri del Graph

Confini dei nodi

Quale lavoro appartiene al codice normale, a una chiamata LLM, a un agente specializzato o a un passaggio di revisione umana

Schema di stato

Cosa ogni nodo può leggere o aggiornare e come vengono combinati i risultati paralleli

Condizioni di routing

Quali evidenze muovono il lavoro in avanti, indietro, lateralmente o verso l'escalation

Concorrenza

Cosa può essere eseguito in parallelo e cosa deve attendere una giunzione

Cicli e uscite

Dove sono legali le riprove, quanti tentativi sono consentiti e cosa rende il ciclo sicuro

Durabilità

Dove l'esecuzione viene checkpointata e come riprende dopo un'interruzione

Quando un graph vale la cerimonia

Usa un graph quando il processo contiene diramazioni significative, specialisti paralleli, approvazioni, percorsi di recupero o passaggi di consegne con stato

Non iniziare con un graph solo perché il flusso di lavoro ha più passaggi

Se un agente capace con tre strumenti può risolvere il compito, un graph può aggiungere struttura senza aggiungere valore

C'è un'altra modalità di fallimento

I team formalizzano il flusso di lavoro prima di comprendere il lavoro

Il risultato è un diagramma meraviglioso che codifica le ipotesi sbagliate

Inizia con un harness semplice

Studia le tracce reali

Formalizza i percorsi che rimangono stabili

Il passo successivo dopo i loop è rendere esplicita la topologia di esecuzione

OpenAI ha confezionato la stessa idea in Agent Builder: una tela del flusso di lavoro visibile per l'esecuzione multi-agente con guardrail e valutazioni attorno al graph

https://x.com/OpenAIDevs/status/1975269388195631492

Come tutti e tre i livelli lavorano in un sistema reale

Immagina un agente di ricerca e pubblicazione che produce un briefing informativo di settore

L'harness fornisce:

• strumenti per browser e ricerca
• archivio delle fonti
• un'area di lavoro per la scrittura
• controllo delle citazioni
• permessi e regole di approvazione
• checkpoint e tracce

Il graph controlla il percorso:

1RESEARCH
2   ↓
3DRAFT
4   ↓
5FACT CHECK ── fallimento ──> RESEARCH
6   │
7  superato
8   ↓
9EDITORIAL REVIEW ── fallimento ──> DRAFT
10   │
11  superato
12   ↓
13HUMAN APPROVAL
14   ↓
15PUBLISH

I loop vivono all'interno di quel percorso

Il nodo di ricerca può cercare fino a quando la copertura delle fonti è sufficiente

Il nodo di bozza può rivedere fino a quando il valutatore di stile passa

Il nodo di verifica dei fatti può restituire affermazioni non supportate esatte invece di un rifiuto vago

L'annidamento è la parte importante

Il graph viene eseguito all'interno dell'harness

I loop vengono eseguiti all'interno di parti del graph

L'harness fornisce gli strumenti, lo stato e le evidenze di cui quei loop hanno bisogno

I livelli si sovrappongono perché i livelli software reali si sovrappongono

Ti danno ancora tre leve diverse quando il sistema fallisce

Diagnostica il fallimento prima di cambiare l'architettura

Sintomo

Inizia con

Correzione probabile

L'agente non può accedere ai dati giusti in sicurezza

Harness

Miglior contratto degli strumenti, permessi, sandbox e iniezione di contesto

L'agente dimentica i progressi tra le sessioni

Harness

Stato durevole, checkpoint, artefatti di avanzamento e compattazione

Il primo tentativo è vicino ma inaffidabile

Loop

Valutatore esterno, test deterministici, feedback attuabile e riprova limitata

L'agente continua dopo il successo o si ferma prima della prova

Loop

Stati terminali basati su evidenze e regole di arresto consapevoli del budget

Gli specialisti devono essere eseguiti in un ordine controllato

Graph

Nodi espliciti, archi, condizioni di routing e giunzioni

Un fallimento multi-passaggio è impossibile da localizzare

Graph + harness

Tracce con stato allineate con nodi e transizioni

Il processo cambia troppo rapidamente per un diagramma fisso

Harness più semplice

Mantieni la pianificazione guidata dal modello e ritarda la formalizzazione del graph

Questa tabella è più utile che discutere sulla terminologia

Trova il livello che possiede il fallimento

Ripara quel livello per primo

Gli errori costosi dietro i sistemi di agenti deboli

Costruire il graph troppo presto

Non convertire un processo aziendale immaginato in quaranta nodi prima di vedere un agente forte eseguire il lavoro

Traccia prima

Formalizza dopo

Lasciare che il creatore si valuti da solo

L'autovalutazione è utile ma condivide gli stessi punti ciechi del tentativo originale

Preferisci controlli deterministici quando possibile

Usa un contesto di revisore isolato per controlli soggettivi

Richiedi approvazione umana per azioni ad alto impatto

Definire il loop come "continua a provare"

Una riprova illimitata non è affidabilità

È una perdita di costo

Ogni ciclo ha bisogno di nuove evidenze, un numero massimo di tentativi e un percorso di escalation nominato

Trasformare l'harness in un magazzino

Più strumenti non creano automaticamente un agente migliore

Un set di strumenti affollato aumenta gli errori di selezione

Un contesto rumoroso aumenta la confusione

Permessi ampi aumentano il rischio

Dai all'agente l'ambiente più piccolo che può completare il lavoro

Incolpare il modello per fallimenti di orchestrazione

Un modello più forte non può riparare in modo affidabile stato obsoleto, API rotte, schemi di strumenti ambigui o condizioni di uscita mancanti

Non aggiornare il modello prima di aver dimostrato che il modello è il problema

Una checklist pronta per la produzione

Harness

• gli strumenti sono stretti, documentati e osservabili
• lo stato è durevole tra le sessioni
• i permessi sono a privilegio minimo
• un operatore può mettere in pausa, ispezionare e riprendere l'esecuzione
• ogni azione importante può essere ricostruita dalle tracce

Loop

• quali evidenze provano il successo
• quale feedback viene restituito dopo il fallimento
• quante riprove sono consentite
• cosa succede quando il budget è esaurito
• dove è richiesto il giudizio umano

Graph

• quali percorsi devono essere deterministici
• dove il lavoro può essere eseguito in parallelo
• quale stato è condiviso
• dove sono le giunzioni, le approvazioni e i percorsi di recupero
• quali cicli sono legali e come terminano

Valutazione

• il team può riprodurre tracce reali
• le versioni possono essere confrontate sugli stessi compiti
• un miglioramento può essere attribuito a una modifica specifica

Operazioni

• costi e latenza sono monitorati
• il tasso di fallimento è visibile per nodo e strumento
• l'intervento umano è misurato
• il successo a livello di compito è misurato in produzione

Il modo più semplice per ricordare la differenza

L'ingegneria dell'Harness rende il modello operativo

L'ingegneria del Loop rende il lavoro iterativo e verificabile

L'ingegneria del Graph rende l'esecuzione complessa esplicita e controllabile

Nessuno sostituisce gli altri

Un graph perfetto non può salvare un agente che perde il suo stato

Un harness perfetto spreca comunque denaro se il loop non ha evidenze o regole di arresto

Un loop forte diventa difficile da gestire quando diramazioni, parallelismo e approvazioni sono nascosti in codice ad hoc

Gli agenti affidabili appaiono quando tutti e tre i livelli sono progettati insieme

E quando ogni livello ha un lavoro chiaro

1ENVIRONMENT -> HARNESS
2FEEDBACK    -> LOOP
3FLOW        -> GRAPH

Questo è tutto il framework

Fonti e ulteriori letture

• Attività pianificate di Claude
• OpenAI AgentKit
• OpenAI Agents SDK
• AutoGen GraphFlow
• Come costruire agenti AI efficaci

Se hai letto fin qui

Segna l'articolo e segui @0xwhrrari per altri articoli pratici sull'ingegneria degli agenti

Puoi anche leggere altri articoli:

• Come ho configurato Obsidian + Claude come mio secondo cervello
• Come ho configurato Claude per fare davvero lavoro
• Come ho configurato i progetti di Claude per farli funzionare davvero
• 30 prompt di sistema di Claude che uso davvero
• Loop Engineering: La competenza AI che ogni costruttore deve avere nel 2026
• 30 impostazioni, scorciatoie e flussi di lavoro di Claude Code che la maggior parte degli utenti perde
• Come uso Claude Cowork per operare come un'azienda di una persona sola