La maggior parte delle persone cerca di sistemare gli agenti AI al livello sbagliato.
Quando un agente fallisce, riscrivono il prompt. Quando fallisce di nuovo, aggiungono altre istruzioni, cambiano modello, aumentano la finestra di contesto o collegano un altro strumento.
Poi gli stessi problemi si ripresentano.
L'agente dimentica una decisione importante. Usa lo strumento sbagliato. Perde il filo di ciò che è successo tre passaggi prima. Dichiara che il task è completato senza verificare il risultato. Riprova la stessa azione fallita finché non esaurisce il budget.
Il problema non è sempre il modello.
Il problema è l'ambiente che lo circonda.
Quell'ambiente è l'harness.
L'Harness Engineering è la pratica di costruire il sistema attorno a un modello, decidendo cosa può vedere, cosa può fare, cosa ricorda, cosa conta come successo e cosa succede quando qualcosa va storto.
Un prompt migliore può migliorare una singola risposta.
Un harness migliore migliora ogni esecuzione.
Segui il mio Substack per altre analisi pratiche su agenti AI, automazione e sistemi in produzione:
1. Il modello non è l'agente
Un modello può ragionare, generare, confrontare e scegliere.
Questo non lo rende un agente affidabile.
Un vero agente deve anche trovare il contesto giusto, usare gli strumenti, preservare lo stato, rispettare i permessi, verificare il proprio lavoro e riprendersi quando l'ambiente si comporta diversamente da quanto previsto.
Il modello è solo il motore di ragionamento.
L'harness è tutto ciò che trasforma quel ragionamento in esecuzione reale.
1RICHIESTA UTENTE2 |3 v4+-----------------------------+5| HARNESS |6| |7| contratto contesto |8| strumenti stato |9| policy verifica |10| tracce ripristino |11+-----------------------------+12 |13 v14 MODELLO15 |16 v17AMBIENTE REALE
Metti lo stesso modello dentro una chat e risponderà alle domande.
Mettilo dentro un repository con accesso al terminale, test, strumenti browser, memoria del progetto, permessi controllati e un ciclo di revisione, e potrà completare del lavoro reale.
Il modello non è cambiato.
È cambiato l'harness.
2. Trasforma ogni richiesta in un contratto
Il linguaggio naturale è flessibile.
L'esecuzione autonoma non dovrebbe esserlo.
Una richiesta come:
Migliora il flusso di onboarding.
va benissimo se c'è un essere umano seduto accanto al modello.
È pessima come istruzione per la produzione.
Prima che l'agente agisca, trasforma la richiesta in un contratto di task ben delimitato.
1obiettivo: ridurre l'abbandono durante l'onboarding23input:4 - brief di prodotto5 - dati analitici6 - repository78vincoli:9 - mantenere l'autenticazione10 - non modificare lo schema del database11 - preservare il comportamento mobile attuale1213deliverable:14 - pull request revisionabile1516completato_quando:17 - i test passano18 - l'evento analytics viene tracciato correttamente19 - il flusso desktop supera la revisione20 - il flusso mobile supera la revisione2122approvazione_richiesta:23 - deploy in produzione
La parte fondamentale è completato_quando.
Senza di essa, l'agente potrebbe risolvere una versione leggermente più semplice del problema e dichiarare comunque con sicurezza che il task è completo.
Con questa clausola, il completamento diventa misurabile.
L'agente non dovrebbe chiedere:
Cosa devo fare adesso?
Dovrebbe chiedersi:
Quale azione avvicina l'ambiente attuale al risultato pattuito nel contratto?
Questo è un loop molto più solido.
3. Dai all'agente una mappa, non una finestra di contesto gigante
Una reazione comune agli errori degli agenti è dare al modello più contesto.
Più documentazione.
Più cronologia della conversazione.
Più file.
Più output dagli strumenti.
Alla fine l'agente riceve tutto e capisce meno.
Il contesto non è archiviazione.
È un budget di attenzione.
Invece di riversare l'intero progetto in ogni esecuzione, dai all'agente una piccola mappa che indichi dove si trovano le informazioni utili.
1MAPPA DEL PROGETTO23regole di prodotto -> docs/product/4architettura -> docs/architecture.md5frontend -> apps/web/6backend -> services/api/7test -> tests/8comandi -> docs/commands.md9sicurezza -> docs/security.md
Poi espandi solo quando serve.
1TASK2 |3 v4MAPPA DEL PROGETTO5 |6 v7SISTEMA RILEVANTE8 |9 v10FILE ESATTI11 |12 v13ISTRUZIONI LOCALI
Il materiale originale lo definisce "progressive disclosure" (divulgazione progressiva): l'harness dovrebbe caricare più informazioni perché il task ne ha bisogno, non semplicemente perché quelle informazioni esistono.
L'obiettivo non è il massimo del contesto.
L'obiettivo è il massimo del segnale utile.
4. Metti un gateway tra il modello e i suoi strumenti
Un modello con venti strumenti non è automaticamente venti volte più capace.
Potrebbe semplicemente avere venti modi in più per fallire.
Ogni strumento dovrebbe avere un contratto.
1STRUMENTO: edit_file23INPUT4percorso5patch67PRECONDIZIONI8il percorso esiste9il percorso è all'interno del workspace1011SUCCESSO12patch applicata13diff restituito1415FALLIMENTO16errore strutturato17nessuna sovrascrittura parziale1819RISCHIO20reversibile
A quel punto il percorso di esecuzione diventa:
1IL MODELLO PROPONE2 |3 v4IL GATEWAY VALIDA5 |6 v7LA POLICY AUTORIZZA8 |9 v10LO STRUMENTO ESEGUE11 |12 v13L'HARNESS REGISTRA IL RISULTATO
Il modello decide quale azione vuole compiere.
L'harness decide se quell'azione è valida, consentita e sicura.
Questa distinzione diventa critica quando gli strumenti possono inviare messaggi, modificare la produzione, spendere denaro o eliminare dati.
Un buon gateway per gli strumenti può anche aggiungere timeout, validare gli argomenti, limitare i percorsi dei file, normalizzare gli errori e rendere sicuri i tentativi ripetuti.
Strumenti ben progettati riducono il numero di cose che il modello deve indovinare.
5. Sposta la memoria fuori dalla conversazione
La conversazione non dovrebbe essere il sistema di riferimento.
Gli agenti che girano a lungo prima o poi raggiungono i limiti di contesto, vanno in crash, si riavviano o passano il lavoro a un'altra sessione.
Se ogni decisione importante esiste solo all'interno del transcript, il workflow è fragile.
Archivia lo stato persistente separatamente.
1{2 "task_id": "feature_042",3 "stato": "in_verifica",4 "passaggio_attuale": "controllo_mobile",56 "completati": [7 "implementazione",8 "unit_test",9 "controllo_desktop"10 ],1112 "decisioni": [13 "riutilizzare l'endpoint di esportazione esistente",14 "mantenere il formato data attuale"15 ],1617 "artefatti": [18 "export.csv",19 "desktop-after.png"20 ],2122 "rischi_aperti": [23 "la toolbar mobile potrebbe andare fuori dallo schermo"24 ],2526 "prossima_azione": "renderizzare la viewport mobile"27}
Un sistema efficace divide la memoria in quattro categorie:
1FATTI2conoscenze stabili34DECISIONI5cosa è stato scelto e perché67STATO8a che punto è l'esecuzione corrente910LEZIONI11fallimenti che dovrebbero influenzare le esecuzioni future
La sessione successiva dell'agente dovrebbe ereditare lo stato del lavoro, non un riassunto compresso della conversazione precedente.
6. Rendi le prove il requisito per il completamento
Un agente che dice "fatto" non è la prova che il lavoro sia finito.
È solo un altro output del modello.
L'harness ha bisogno di prove osservabili.
1DICHIARAZIONE PROVA23"il bug è risolto" il test che falliva ora passa45"la pagina funziona" il flusso nel browser è completato67"i dati sono corretti" i valori corrispondono alla fonte89"la migrazione è sicura" dry run + rollback superati1011"il task è completo" tutti i controlli di accettazione superati
Usa prima i controlli deterministici.
1sintassi2 |3 v4tipi5 |6 v7test mirati8 |9 v10test di integrazione11 |12 v13revisione visiva / semantica14 |15 v16approvazione umana
Non chiedere a un altro modello di rispondere a qualcosa che un compilatore, un test, uno schema o una query al database possono dimostrare.
Usa i modelli per le valutazioni.
Usa i sistemi deterministici per i fatti.
Il modello crea l'artefatto.
L'ambiente genera le prove sull'artefatto.
L'harness decide se le prove sono sufficienti.
7. Separa chi costruisce da chi verifica
C'è un altro problema con l'auto-revisione.
L'agente che ha commesso l'errore spesso porta le stesse assunzioni anche nella fase di revisione.
Un'architettura più solida separa l'esecutore dal verificatore.
1BUILDER2 |3 v4crea il candidato5 |6 v7VERIFICATORE8 |9 +-- controlla il contratto10 +-- cerca i casi mancanti11 +-- testa le affermazioni non supportate12 +-- cerca di far fallire il risultato13 |14 +------ SUPERATO ------> ACCETTA15 |16 +------ FALLITO ------> RESTITUISCI LE PROVE
Il verificatore non dovrebbe chiedersi:
Sembra fatto bene?
Dovrebbe chiedersi:
Cosa renderebbe questo risultato inaccettabile?
Questo trasforma la revisione da una conferma a un tentativo di confutazione.
Il materiale originale raccomanda esplicitamente di dare alla verifica criteri di rifiuto propri e un'indipendenza sufficiente per mettere in discussione le assunzioni che hanno prodotto il primo risultato.
8. Sposta i permessi fuori dal modello
Alcune regole non dovrebbero mai dipendere dal fatto che il modello se le ricordi.
1non pubblicare mai senza approvazione2non esporre mai i secret3non superare mai il limite di spesa4non scrivere mai fuori dal workspace5non dichiarare mai che i test sono passati se non sono stati eseguiti
Questi non sono suggerimenti per il prompt.
Sono policy.
Una semplice scala dei permessi:
1BASSO RISCHIO23lettura4ricerca5ispezione67-> automatico89REVERSIBILE1011modifica del workspace12esecuzione dei test13creazione di bozze1415-> automatico + tracciamento1617EFFETTO ESTERNO1819invio20deploy21acquisto2223-> approvazione richiesta2425IRREVERSIBILE / SENSIBILE2627eliminazione dati28rotazione credenziali29pubblicazione globale3031-> blocco rigido o vietato
Più gravi sono le conseguenze, più forte deve essere il controllo.
Il modello può raccomandare l'azione.
L'harness la autorizza.
Lo strumento la esegue.
L'autonomia non è assenza di controllo.
È libertà all'interno di un confine imposto.
9. Smetti di riprovare alla cieca
Una delle peggiori politiche di recupero è:
Qualcosa è andato storto. Riprova.
Se non cambia nulla, il sistema sta semplicemente pagando per riprodurre lo stesso errore.
I fallimenti andrebbero prima classificati.
1TIMEOUT DELLO STRUMENTO2-> riprova con backoff34ARGOMENTI NON VALIDI5-> correggi la chiamata allo strumento67CONTESTO MANCANTE8-> recupera la fonte mancante910TEST FALLITO11-> analizza il comportamento anomalo1213PERMESSO NEGATO14-> richiedi approvazione1516REQUISITI IN CONTRADDIZIONE17-> escala1819FALLIMENTO RIPETUTO INVARIATO20-> fermati
Un loop efficace per un agente funziona così:
1OSSERVA2 |3 v4DECIDI5 |6 v7AGISCI8 |9 v10MISURA11 |12 +---- ACCETTA13 |14 +---- CORREGGI15 |16 +---- ESCALA17 |18 +---- FERMATI
Ogni loop dovrebbe avere limiti sui tentativi, sul tempo, sulla spesa e sull'impatto distruttivo.
Un agente affidabile deve sapere come proseguire.
Ma deve anche sapere quando un ulteriore tentativo non vale più la pena.
10. Trasforma le istruzioni ricorrenti in infrastruttura
Immagina che il prompt contenga:
Esegui sempre il formatter.
Quella regola è molto più solida se il formatter parte in automatico.
Oppure che le istruzioni dicano:
Il codice UI non può accedere direttamente al database.
Diventa molto più efficace come test architetturale che fallisce quando la regola viene violata.
L'evoluzione segue questo schema:
1SPIEGAZIONE2 |3 v4CHECKLIST5 |6 v7TEMPLATE8 |9 v10CONTROLLO AUTOMATIZZATO11 |12 v13POLICY IMPOSTA
Il prompt dovrebbe spiegare come valutare.
L'harness dovrebbe imporre gli invarianti.
Ogni errore ricorrente dovrebbe scendere di un gradino in questa scala.
Alla fine il modello non avrà più bisogno di ricordare la lezione.
Sarà l'ambiente a ricordarla al posto suo.
11. Registra l'esecuzione
Un artefatto finale perfetto può nascondere un percorso di esecuzione disastroso.
Forse l'agente ha consultato la fonte sbagliata.
Forse ha ignorato un comando fallito.
Forse ha eseguito due volte un'azione esterna.
Forse ha speso dieci volte il budget previsto.
Forse ha dato la risposta giusta per il motivo sbagliato.
Registra abbastanza informazioni per ricostruire cosa è successo.
109:14 creato il contratto del task209:15 caricato architecture.md309:17 modificato checkout.ts409:18 test mirato fallito509:21 implementazione corretta609:22 test mirato superato709:24 test di integrazione superato809:25 deploy bloccato: approvazione richiesta
Tracce utili includono le fonti del contesto, le chiamate agli strumenti, i cambi di stato, i risultati delle verifiche, i motivi dei nuovi tentativi, le decisioni di approvazione, i costi e la latenza.
L'obiettivo non è raccogliere log per divertimento.
L'obiettivo è localizzare il fallimento.
Se il passaggio 18 si rompe, dovresti poter riparare il passaggio 18.
Non dovresti dover rieseguire l'intera sequenza.
12. Dai una ricevuta a ogni esecuzione
Non costringere un essere umano a rileggere un transcript di quaranta messaggi.
Compila il risultato in una breve ricevuta.
1OBIETTIVO23Correggere l'applicazione duplicata dei coupon.45MODIFICATO67validazione checkout8test di regressione910VERIFICATO1112lint superato13unit test superati14test di integrazione superato1516NON VERIFICATO1718provider di pagamento in produzione1920RISCHI2122client mobile legacy non disponibile2324APPROVAZIONE RICHIESTA2526deploy in staging
Questa non è una sintesi di ciò che il modello sostiene sia successo.
È una sintesi di ciò che l'harness può dimostrare sia successo.
Questa distinzione rende la ricevuta utile per le revisioni, i passaggi di consegne e le sessioni future dell'agente.
13. Fai in modo che ogni fallimento migliori l'harness
La maggior parte dei team corregge l'output fallito.
L'approccio migliore è correggere il sistema che ha permesso il fallimento.
1CONTESTO MANCANTE2-> migliora la mappa del progetto34STRUMENTO SBAGLIATO5-> migliora il routing o il contratto dello strumento67OUTPUT SCADENTE8-> aggiungi un validatore910LOOP INFINITO11-> aggiungi un limite ai tentativi1213AZIONE NON SICURA14-> aggiungi un gate di permessi1516DECISIONE PERSA17-> rendi lo stato persistente1819FALLIMENTO SCONOSCIUTO20-> migliora il tracciamento
È qui che l'Harness Engineering inizia a generare effetti composti.
Un output corretto aiuta una singola esecuzione.
Un harness corretto migliora tutte le esecuzioni successive.
I migliori sistemi di agenti diventano più affidabili perché gli errori lasciano dietro di sé nuova infrastruttura.
14. Inizia con l'harness utile più piccolo
Non ti serve un'enorme piattaforma di orchestrazione per partire.
Costruisci a strati.
1LIVELLO 023prompt4modello56LIVELLO 178contratto del task9mappa del progetto10strumenti1112LIVELLO 21314stato strutturato15verifica16loop delimitato1718LIVELLO 31920permessi21tracce22ripristino23gate umani
Un breve task di ricerca potrebbe aver bisogno solo di un prompt e di una revisione.
Un task di programmazione di sei ore con accesso ai file, alla rete e capacità di deploy richiede molto di più.
Aggiungi complessità solo quando la superficie di errore lo giustifica.
Non perché l'architettura degli agenti sembra figa.
La checklist dell'Harness Engineering
Prima di dare a un agente un'autonomia significativa, chiediti:
1[ ] Il successo è definito prima dell'esecuzione?23[ ] L'agente riesce a trovare il contesto giusto4 senza caricare tutto?56[ ] Ogni strumento ha uno scopo chiaro,7 uno schema e uno stato di fallimento?89[ ] Le decisioni importanti vengono archiviate10 fuori dalla conversazione?1112[ ] Il completamento richiede delle prove?1314[ ] Le azioni rischiose sono protette da policy?1516[ ] Ogni loop ha un limite di tentativi?1718[ ] L'esecuzione può riprendere dopo un'interruzione?1920[ ] Riesci a ricostruire ogni azione importante?2122[ ] Un fallimento migliora una regola, uno strumento,23 un test, una mappa o un permesso?2425[ ] La modifica finale può essere annullata?
Se diverse risposte sono "no", un modello più potente non renderà automaticamente l'agente affidabile.
Potrebbe semplicemente rendere il fallimento più veloce e più costoso.
Il vero cambio di paradigma
Il prompt engineering chiede:
Cosa devo dire al modello?
Il context engineering chiede:
Cosa dovrebbe sapere il modello in questo momento?
L'Harness Engineering chiede:
Quale sistema permette al modello di agire, verificare il proprio lavoro, riprendersi dai fallimenti e operare in sicurezza?
1PROMPT2-> istruzione34CONTESTO5-> vista operativa67HARNESS8-> ambiente operativo910LOOP11-> correzione locale1213GRAFO14-> coordinamento
I modelli continueranno a cambiare.
Il vantaggio duraturo vive intorno a loro.
I tuoi contratti migliorano.
I tuoi strumenti migliorano.
I tuoi test migliorano.
Il tuo stato diventa più pulito.
I tuoi permessi diventano più sicuri.
La tua logica di recupero diventa più intelligente.
I tuoi fallimenti si trasformano in infrastruttura.
È così che modelli capaci diventano agenti affidabili.
Questo è l'Harness Engineering.
Se sei arrivato fin qui
Salva questa guida nei preferiti.
Seguimi su X: x.com/0xjmori
Iscriviti al mio Substack: substack.com/@lunarresearcher
Invia questo articolo a qualcuno che sta ancora cercando di risolvere ogni fallimento degli agenti con un prompt più lungo.
![[Scuse] Non consiglio più il freelance per l'indipendenza.](/cdn-cgi/image/width=1920,quality=90,format=auto,metadata=none/https%3A%2F%2Fcms-assets.youmind.com%2Fmedia%2F1790615558140_ndvona_HTQ9s6laYAAX4J7.jpg)
