Harness Engineering: La guida completa per creare agenti AI che non falliscono

La maggior parte delle persone cerca di migliorare gli agenti AI al livello sbagliato.

Quando un agente fallisce, riscrivono il prompt.

Quando fallisce di nuovo, aggiungono altre istruzioni.

Prima di iniziare:

Segui il mio Substack per ricevere novità fresche sull'AI, flussi di lavoro per agenti e guide passo-passo prima che arrivino su X: [https://substack.com/@lunarresearcher

Poi cambiano modello, aggiungono più strumenti, aumentano la finestra di contesto e sperano che il prossimo esecuzione si comporti diversamente.

Ma molti fallimenti degli agenti non sono fallimenti di ragionamento.

Sono fallimenti dell'ambiente.

L'agente non sapeva quali file fossero importanti.

Ha usato lo strumento giusto nel posto sbagliato.

Ha perso le decisioni prese nella sessione precedente.

Ha dichiarato il successo senza eseguire i controlli.

Ha ripetuto un'azione dopo un fallimento parziale.

Aveva il permesso di fare qualcosa che avrebbe dovuto richiedere un'approvazione.

Il modello non era necessariamente il problema. Il sistema attorno al modello era incompleto.

Questo sistema è l'imbracatura.

E progettarla sta diventando una disciplina ingegneristica a sé stante.

L'Ingegneria dell'Imbracatura è la pratica di costruire l'ambiente che trasforma l'intelligenza del modello in lavoro affidabile.

Un prompt cambia un singolo tentativo.

Un'imbracatura cambia ogni tentativo.

Questa guida spiega come costruirne una.

1. Il Modello Non È l'Agente

Un modello può ragionare, generare, confrontare e scegliere.

Ma un agente deve anche interagire con un ambiente reale.

Deve:

• comprendere il compito
• trovare il contesto rilevante
• selezionare e usare strumenti
• preservare lo stato
• rispettare i permessi
• ispezionare il risultato
• riprendersi da un fallimento
• dimostrare che il lavoro è completo

Il modello è il motore di ragionamento all'interno di quel sistema.

L'imbracatura è tutto ciò che rende operativo il ragionamento.

1richiesta utente
2     |
3     v
4+-----------------------------+
5|         IMBRACATURA         |
6| contratto | contesto | policy|
7| strumenti | stato   | controlli|
8| tracce    | recupero          |
9+-----------------------------+
10     |
11     v
12    modello
13     |
14     v
15ambiente reale

Un modello potente all'interno di un'imbracatura debole è comunque un agente debole.

Può produrre risposte individuali impressionanti, ma si comporterà in modo incoerente in compiti lunghi, ambienti mutevoli e fallimenti parziali.

L'obiettivo dell'ingegneria dell'imbracatura non è rimuovere l'incertezza dal modello.

È contenere quell'incertezza all'interno di un sistema che può osservare, verificare e recuperare.

2. Inizia con un Contratto di Compito

La maggior parte dei compiti degli agenti inizia come un'intenzione vaga:

Migliora il flusso di onboarding.

Quella frase può bastare per una conversazione.

Non è sufficiente per un'esecuzione autonoma.

Prima che l'agente agisca, l'imbracatura dovrebbe convertire la richiesta in un contratto di compito.

Un contratto utile risponde a cinque domande:

1. Quale risultato deve esistere?
2. Cosa rientra nell'ambito?
3. Cosa non deve cambiare?
4. Quali prove dimostrano il completamento?
5. Quali azioni richiedono l'approvazione umana?

1obiettivo: ridurre l'abbandono dell'onboarding
2
3ambito:
4  - flusso di iscrizione
5  - analisi dell'onboarding
6
7vincoli:
8  - non modificare l'autenticazione
9  - preservare il comportamento mobile esistente
10
11accettazione:
12  - test superati
13  - evento di analytics emesso
14  - screenshot coprono desktop e mobile
15
16approvazione_richiesta:
17  - deploy in produzione
18  - migrazione del database

Questo cambia la domanda dell'agente da:

Cosa dovrei fare dopo?

a:

Quale azione muove l'ambiente verso il risultato contrattuale?

Senza un contratto, l'agente ottimizza per un'attività plausibile.

Con un contratto, può ottimizzare per un completamento verificato.

3. Dai all'Agente una Mappa, Non un Manuale

Scaricare l'intero repository, la documentazione e la cronologia della conversazione nel contesto non è una buona ingegneria del contesto.

È un'inondazione di contesto.

L'imbracatura dovrebbe fornire prima una piccola mappa, poi permettere all'agente di recuperare i dettagli quando diventano rilevanti.

1MAPPA DEL PROGETTO
2
3regole del prodotto   -> docs/prodotto/
4architettura          -> docs/architettura.md
5frontend              -> apps/web/
6backend               -> services/api/
7test                  -> tests/
8comandi               -> docs/comandi.md
9regole di rilascio    -> docs/rilascio.md

Questa è una divulgazione progressiva:

1compito
2  -> mappa del progetto
3      -> sottosistema rilevante
4          -> file esatti
5              -> istruzioni locali

Il contesto dovrebbe espandersi perché il compito lo richiede, non perché l'informazione esiste.

Un buon compilatore di contesto decide:

• cosa è sempre necessario
• cosa può essere recuperato dopo
• cosa è diventato obsoleto
• cosa può essere riassunto
• cosa deve rimanere testuale

L'obiettivo non è il contesto massimo.

È il massimo segnale per token.

4. Costruisci un Gateway per Strumenti, Non un Mucchio di Strumenti

Dare a un agente venti strumenti non lo rende capace.

Gli dà venti modi per commettere un errore.

Ogni strumento dovrebbe avere un contratto chiaro:

1STRUMENTO: modifica_file
2
3input:
4  percorso
5  patch
6
7precondizioni:
8  percorso esiste
9  percorso è all'interno dell'area di lavoro consentita
10
11prova di successo:
12  patch applicata
13  diff risultante restituito
14
15comportamento in caso di fallimento:
16  nessuna sovrascrittura parziale
17  errore strutturato restituito
18
19classe di rischio:
20  reversibile

L'imbracatura dovrebbe controllare come gli strumenti vengono esposti e utilizzati.

Può:

• nascondere strumenti irrilevanti
• validare argomenti
• limitare percorsi e domini
• allegare timeout
• rendere i tentativi idempotenti
• normalizzare gli output
• richiedere conferma per azioni rischiose
• restituire prove, non solo "successo"

Questo crea una separazione importante:

1il modello decide l'intento
2il gateway valida l'azione
3lo strumento modifica l'ambiente
4il sensore osserva il risultato

Il modello può proporre un'azione.

Il gateway degli strumenti decide se quell'azione è abbastanza valida per essere eseguita.

5. Separa il Cervello, le Mani e la Storia

Molti agenti fragili mescolano tutto in un'unica trascrizione in crescita.

Ragionamento, chiamate a strumenti, file, decisioni, errori e vecchie osservazioni competono tutte per la stessa finestra di contesto.

Un sistema più solido separa tre responsabilità:

1CERVELLO
2pianifica, ragiona, sceglie
3
4MANI
5esegue strumenti in un ambiente controllato
6
7STORIA
8memorizza fatti durevoli, decisioni e stato dell'esecuzione

Il modello non ha bisogno di ogni evento grezzo nel contesto attivo.

Ha bisogno del giusto stato corrente.

La sandbox non ha bisogno di comprendere l'intero obiettivo.

Deve eseguire in sicurezza un'azione limitata.

Il log della sessione non ha bisogno di ragionare.

Deve preservare ciò che è successo dopo che il contesto corrente scompare.

Questa separazione rende più facile riprendere, ispezionare e riparare gli agenti a lunga esecuzione.

Permette anche di sostituire una parte senza ricostruire l'intero sistema.

6. La Memoria Deve Diventare Stato Durevole

La cronologia della conversazione non è una memoria affidabile.

È un flusso di eventi.

La memoria utile dovrebbe essere convertita in stato esplicito.

Come minimo, preserva quattro categorie:

1FATTI
2informazioni stabili scoperte sull'ambiente
3
4DECISIONI
5scelte fatte e la ragione dietro di esse
6
7PROGRESSO
8lavoro completato, attivo, bloccato e rimanente
9
10LEZIONI
11fallimenti che dovrebbero cambiare il comportamento futuro

Per esempio:

1fatti:
2  - la validazione del checkout risiede in services/orders
3
4decisioni:
5  - riutilizzare la pipeline di validazione esistente
6  - motivo: evita una seconda fonte di verità
7
8progresso:
9  completato:
10    - aggiunta regola lato server
11  rimanente:
12    - aggiornare test di integrazione
13
14lezioni:
15  - il comando di test locale richiede TEST_DB_URL

Questo è molto più utile che riprodurre cinquanta pagine di trascrizione sperando che il modello noti la riga importante.

Conserva la cronologia grezza per la verificabilità.

Compila lo stato durevole per l'esecuzione.

7. Il Completamento Richiede Prove

Un agente che dice "fatto" non è una prova che il compito sia stato completato.

È solo un altro output del modello.

Il completamento deve essere deciso da cambiamenti osservabili nell'ambiente.

1affermazione                    prova
2--------------------------------------------------
3"il bug è stato risolto"        il test che falliva ora passa
4"la pagina funziona"            flusso del browser completato
5"la migrazione è sicura"        dry run e rollback superati
6"il report è corretto"          i valori corrispondono ai dati sorgente
7"il compito è completo"         ogni controllo di accettazione superato

L'imbracatura dovrebbe eseguire prima i controlli deterministici più economici.

1sintassi
2  -> tipi
3      -> test mirati
4          -> test di integrazione
5              -> revisione visiva o semantica
6                  -> approvazione umana

Non usare un altro modello dove un compilatore, uno schema, un checksum, una query o un test possono rispondere alla domanda.

Usa i modelli per l'ambiguità.

Usa il codice per la struttura.

Un modello può proporre che il compito sia completo.

Solo l'ambiente può dimostrarlo.

8. La Verifica Dovrebbe Attaccare il Risultato

Lavoratori e valutatori non dovrebbero condividere lo stesso obiettivo.

Il lavoratore cerca di creare la soluzione più forte.

Il valutatore cerca di trovare il motivo per cui dovrebbe essere respinta.

1lavoratore
2  -> produce candidato
3
4verificatore
5  -> controlla il contratto
6  -> cerca casi mancanti
7  -> testa affermazioni non supportate
8  -> tenta di rompere il risultato
9
10sopravvive
11  -> accetta
12
13fallisce
14  -> restituisce prove mirate

Questa asimmetria è importante.

Se chiedi allo stesso agente, nello stesso contesto, di "ricontrollare il suo lavoro", spesso preserva le ipotesi che hanno creato l'errore.

Una fase di verifica utile dovrebbe avere:

• una rubrica di rifiuto esplicita
• accesso all'artefatto prodotto
• accesso al contratto di accettazione
• strumenti indipendenti o contesto fresco quando necessario
• permesso di rifiutare senza riparare

La verifica non è una seconda opinione.

È un tentativo di confutazione.

9. Il Modello Propone, la Policy Autorizza

Alcune regole non dovrebbero mai dipendere dal fatto che il modello le ricordi.

1mai pubblicare senza approvazione
2mai esporre un segreto
3mai scrivere fuori dall'area di lavoro
4mai superare il limite di spesa
5mai segnare test come superati a meno che non siano stati eseguiti

Questi non sono suggerimenti di prompt.

Sono policy.

Il design più sicuro mantiene la policy al di fuori del ciclo di ragionamento.

1BASSO RISCHIO
2leggere file, cercare, ispezionare
3-> automatico
4
5MODIFICA REVERSIBILE
6modificare area di lavoro, eseguire test
7-> automatico con traccia
8
9EFFETTO ESTERNO
10inviare messaggio, fare deploy, acquistare
11-> approvazione esplicita
12
13IRREVERSIBILE O SENSIBILE
14cancellare dati, ruotare credenziali, pubblicare globalmente
15-> blocco rigido o vietato

Più forte è la conseguenza, più duro è il blocco.

L'autonomia non è l'assenza di controllo.

È la capacità di operare liberamente all'interno di un confine chiaramente imposto.

10. Il Recupero Dovrebbe Mirare alla Classe di Fallimento

La strategia di recupero più comune è:

Qualcosa è fallito. Riprova.

Questo non è recupero.

È ripetizione.

L'imbracatura dovrebbe classificare il fallimento prima di selezionare l'azione successiva.

1timeout dello strumento
2-> riprova con backoff
3
4argomenti non validi
5-> ripara la chiamata allo strumento
6
7contesto mancante
8-> recupera fonte specifica
9
10test fallito
11-> ispeziona il comportamento fallito
12
13permesso negato
14-> richiedi approvazione o scegli percorso sicuro
15
16requisiti contraddittori
17-> passa all'umano
18
19fallimento ripetuto invariato
20-> ferma il ciclo

Un tentativo dovrebbe cambiare almeno una condizione rilevante.

Altrimenti il sistema paga per riprodurre lo stesso fallimento.

Un ciclo di agente limitato assomiglia a questo:

1osserva
2  -> decidi
3      -> agisci
4          -> misura
5              -> accetta
6              -> ripara
7              -> passa all'umano
8              -> ferma

Ogni ciclo ha bisogno di un budget:

• tentativi massimi
• tempo massimo
• spesa massima
• portata distruttiva massima
• condizione di escalation

Gli agenti affidabili sanno come continuare.

Sanno anche quando continuare non è più razionale.

11. Le Istruzioni Dovrebbero Diventare Infrastruttura

Le istruzioni per gli agenti sono utili quando spiegano la realtà locale.

Ma le istruzioni da sole sono un'applicazione debole.

Se una regola è importante ripetutamente, spostala più in basso nello stack.

1"usa il formattatore"
2-> esegui il formattatore automaticamente
3
4"non importare tra i livelli"
5-> aggiungi test di architettura
6
7"includi un rollback della migrazione"
8-> richiedi file di rollback in CI
9
10"non modificare file generati"
11-> blocca scritture su percorsi generati
12
13"cita ogni affermazione esterna"
14-> valida la copertura delle citazioni

Questo crea una scala di istruzioni:

1spiegazione
2  -> checklist
3      -> modello
4          -> controllo automatizzato
5              -> policy applicata

Sposta la conoscenza importante il più in basso possibile su quella scala.

Il prompt dovrebbe spiegare il giudizio.

L'imbracatura dovrebbe applicare gli invarianti.

12. Osserva l'Esecuzione, Non Solo la Risposta Finale

Un artefatto finale pulito può nascondere un processo terribile.

L'agente potrebbe aver:

• acceduto ai dati sbagliati
• ignorato un comando fallito
• ritentato un'azione esterna due volte
• consumato dieci volte il budget previsto
• raggiunto la risposta giusta per il motivo sbagliato

Hai bisogno di tracce che rendano l'esecuzione ricostruibile.

109:14  contratto creato
209:15  fonte di contesto caricata: architettura.md
309:17  file modificato: checkout.ts
409:18  test mirato fallito: coupon duplicato
509:21  implementazione riparata
609:22  test mirato superato
709:24  test di integrazione superato
809:25  deploy esterno bloccato: approvazione richiesta

Una traccia utile registra:

• transizioni di stato
• fonti di contesto
• input e output degli strumenti
• cambiamenti dell'ambiente
• risultati della verifica
• motivi dei tentativi
• decisioni di approvazione
• costo e latenza

L'obiettivo non è la sorveglianza.

L'obiettivo è la riparazione locale.

Quando un'esecuzione fallisce al passaggio 18, dovresti essere in grado di ripartire da un checkpoint affidabile invece di riprodurre l'intero compito.

13. Ogni Esecuzione Ha Bisogno di una Ricevuta di Modifica

Le lunghe trascrizioni degli agenti sono difficili da revisionare.

Alla fine di un'esecuzione, l'imbracatura dovrebbe compilare una piccola ricevuta di modifica.

1OBIETTIVO
2Risolvere l'applicazione di coupon duplicati durante il checkout.
3
4MODIFICATO
5- logica di validazione del checkout
6- test di regressione mirato
7
8VERIFICATO
9- lint superato
10- test unitari superati
11- test di integrazione del checkout superato
12
13NON VERIFICATO
14- fornitore di pagamento in produzione
15
16DECISIONI
17- preservato l'ordine di priorità dei coupon esistente
18
19RISCHI
20- il client mobile legacy non era disponibile localmente
21
22APPROVAZIONE NECESSARIA
23- deploy in staging

La ricevuta non è un riassunto di ciò che il modello ha detto.

È un riassunto di ciò che il sistema può dimostrare.

Questo dà agli umani una superficie di revisione compatta e fornisce alla prossima sessione dell'agente un punto di partenza affidabile.

Il miglior passaggio di consegne non è "ecco la conversazione."

È "ecco lo stato, le prove e il rischio irrisolto."

14. Ogni Fallimento Dovrebbe Aggiornare l'Imbracatura

I team più deboli riparano l'output fallito.

I team più forti riparano anche il sistema che lo ha permesso.

Dopo un fallimento, chiedi:

1Il contratto di compito era ambiguo?
2Un contesto importante era invisibile?
3Lo strumento sbagliato era esposto?
4Mancava una precondizione?
5Il risultato non era verificabile?
6La policy era lasciata dentro il prompt?
7Il recupero era troppo ampio?
8La traccia era insufficiente?

Poi converti la lezione in un miglioramento riutilizzabile.

1fallimento
2  -> diagnosi
3      -> nuovo sensore, regola, mappa, test o contratto di strumento
4          -> le esecuzioni future migliorano automaticamente

Questo è il volano dell'imbracatura.

Il sistema diventa più affidabile perché i fallimenti lasciano dietro di sé infrastruttura.

Una risposta corretta aiuta un'esecuzione.

Un'imbracatura corretta aiuta ogni esecuzione futura.

15. Anche le Imbracature Degradano

Più imbracatura non è sempre meglio.

I modelli migliorano. Gli strumenti migliorano. I compiti cambiano. Le vecchie salvaguardie possono diventare attriti inutili.

Una soluzione alternativa creata per il modello di ieri potrebbe impedire al modello di oggi di usare una strategia migliore.

Questo crea il degrado dell'imbracatura:

1limitazione del vecchio modello
2  -> soluzione alternativa nell'imbracatura
3      -> il modello migliora
4          -> la soluzione alternativa rimane
5              -> il sistema diventa più lento o meno capace

Tratta i componenti dell'imbracatura come codice di produzione.

Misura se forniscono ancora un vantaggio.

Per ogni router, valutatore, livello di memoria e regola di tentativo, chiedi:

• Quale fallimento previene questo?
• Quanto spesso si verifica ancora quel fallimento?
• Quale latenza e complessità aggiunge questo?
• Lo stesso risultato può ora essere ottenuto più semplicemente?
• Cosa succede se lo rimuoviamo?

La migliore imbracatura non è la più grande.

È il sistema più piccolo che colma in modo affidabile il divario tra intento e prova.

Costruisci per eliminare.

16. L'Imbracatura Minima Funzionante

Non hai bisogno di una piattaforma di orchestrazione per iniziare.

Costruisci l'imbracatura a strati.

Livello 1: Un compito limitato

• obiettivo
• ambito
• vincoli
• controlli di accettazione

Livello 2: Un ambiente leggibile

• mappa del progetto
• comandi
• istruzioni locali
• dipendenze note

Livello 3: Azioni controllate

• strumenti tipizzati
• validazione degli argomenti
• limiti di percorso e permessi
• risultati strutturati

Livello 4: Esecuzione durevole

• stato di esecuzione esplicito
• checkpoint
• decisioni
• lezioni

Livello 5: Prove

• controlli deterministici
• verifica avversaria
• ricevuta di modifica

Livello 6: Recupero e apprendimento

• classificazione dei fallimenti
• tentativi limitati
• escalation
• aggiornamenti dell'imbracatura da fallimenti ricorrenti

Costruisci il livello più piccolo che elimina il fallimento che hai effettivamente.

Non iniziare con un'architettura multi-agente perché un singolo prompt occasionalmente ha bisogno di chiarimenti.

La complessità dovrebbe essere guadagnata da fallimenti osservati.

17. Una Specifica di Imbracatura Riutilizzabile

Prima di dare a un agente un'autonomia significativa, definisci questo:

1SPECIFICA IMBRACATURA AGENTE
2
31. CONTRATTO
4   obiettivo:
5   ambito:
6   vincoli:
7   prova di accettazione:
8
92. CONTESTO
10   mappa sempre caricata:
11   fonti di recupero:
12   istruzioni locali:
13   regole di freschezza:
14
153. STRUMENTI
16   strumenti consentiti:
17   precondizioni:
18   effetti collaterali:
19   prova di successo:
20   policy di timeout e tentativi:
21
224. STATO
23   fatti:
24   decisioni:
25   progresso:
26   lezioni:
27   formato checkpoint:
28
295. POLICY
30   azioni automatiche:
31   azioni che richiedono approvazione:
32   azioni vietate:
33   limiti di budget:
34
356. VERIFICA
36   controlli deterministici:
37   controlli avversari:
38   regola di accettazione:
39
407. RECUPERO
41   classi di fallimento:
42   limiti di tentativi:
43   condizioni di escalation:
44   rollback sicuro:
45
468. OSSERVABILITÀ
47   eventi di traccia:
48   metriche:
49   ricevuta di modifica finale:

Se questi campi non sono definiti, l'agente non è autonomo.

Sta improvvisando.

18. Misura il Sistema al Livello Giusto

Il conteggio dei token non è la metrica finale.

Nemmeno il numero di compiti tentati.

L'unità utile è il lavoro accettato.

Una metrica pratica è:

1output accettati
2------------------------------
3minuti di revisione umana + costo di esecuzione

Tieni traccia anche di:

• tasso di accettazione al primo passaggio
• tasso di recupero dopo un fallimento dello strumento
• tasso di fallimento ripetuto
• interventi umani per compito
• affermazioni di completamento non supportate
• tempo dalla richiesta al risultato verificato
• overhead dell'imbracatura per componente

Questo previene un'illusione comune:

Un agente può sembrare molto produttivo mentre crea costoso lavoro di revisione.

L'obiettivo non è più attività dell'agente.

Sono più risultati attendibili per unità di attenzione umana.

19. Quando Non Hai Bisogno di un'Imbracatura Pesante

Non ogni chiamata al modello ha bisogno di un sistema operativo.

Usa un prompt semplice quando:

• il compito è breve
• l'output è facile da ispezionare
• il fallimento è economico
• non si verifica alcun effetto collaterale esterno
• l'utente rimane nel ciclo

Aggiungi un'imbracatura quando:

• il lavoro si estende su più strumenti o sessioni
• l'ambiente può cambiare
• le azioni hanno conseguenze reali
• il completamento è difficile da giudicare manualmente
• lo stesso fallimento appare ripetutamente
• la revisione umana diventa il collo di bottiglia

Lo scopo di un'imbracatura non è rendere una demo sofisticata.

È rendere il lavoro reale affidabile.

Il Vero Cambiamento

La prima generazione di prodotti AI è stata costruita attorno ai prompt.

La prossima generazione viene costruita attorno agli ambienti.

La domanda non è più solo:

Come facciamo a far rispondere meglio il modello?

È:

Come costruiamo un sistema in cui le buone azioni sono facili, le azioni pericolose sono controllate, i fallimenti sono visibili e il completamento è dimostrabile?

Questo è il passaggio dall'ingegneria dei prompt all'ingegneria dell'imbracatura.

Il modello fornisce intelligenza.

L'imbracatura fornisce struttura.

Insieme producono un'esecuzione affidabile.

Se il tuo agente continua a cadere a pezzi, smetti di aggiungere aggettivi al prompt.

Costruisci l'ambiente di cui ha bisogno per avere successo.

Se Sei Arrivato Fin Qui

Aggiungi questa guida ai segnalibri.

Segui @LunarResearcher su X

Iscriviti al mio Substack

Invia questo articolo a qualcuno che sta ancora cercando di risolvere ogni fallimento dell'agente con un prompt più lungo.