Ingegneria dell'imbracatura per agenti

Un agente di codifica è il modello più tutto ciò che è costruito attorno ad esso. L'ingegneria dell'harness tratta quell'impalcatura come un artefatto vivente, stringendola ogni volta che l'agente commette un errore.

In parole povere: ogni volta che un agente fallisce, si progetta una soluzione permanente in modo che non commetta mai più lo stesso errore.

Negli ultimi due anni, l'industria ha dibattuto sui modelli: quale è il più intelligente, quale scrive il React più pulito, o quale allucina di meno. Sebbene questa conversazione sia importante, trascura l'altra metà del sistema.

Il modello è solo un input in un agente in esecuzione. Il resto è l'harness: i prompt, gli strumenti, le policy di contesto, gli hook, i sandbox, i subagenti, i cicli di feedback e i percorsi di recupero avvolti attorno al modello in modo che possa effettivamente completare i compiti.

Un modello decente con un grande harness batte costantemente un grande modello con un cattivo harness. Sempre più spesso, il lavoro di ingegneria più interessante non sta nella selezione del modello, ma nella progettazione dell'impalcatura attorno ad esso.

Quella disciplina ora ha un nome. @Vtrivedy10 ha coniato il termine harness engineering, fornendo una chiara suddivisione di cosa sia realmente un harness e perché ogni pezzo esista. Altre voci del settore come @dexhorthy che traccia pattern emergenti, HumanLayer che inquadra i fallimenti degli agenti come 'problemi di configurazione', il team di ingegneria di Anthropic che pubblica guide sulla progettazione di app a lunga esecuzione, e Birgitta Böckeler che esplora l'esperienza lato utente - stanno tutte convergendo sulla stessa idea.

Questo post unisce questi fili.

Cos'è realmente un Harness?

La definizione centrale di Trivedy fa la maggior parte del lavoro pesante:

Agente = Modello + Harness. Se non sei il modello, sei l'harness.

Un harness comprende ogni pezzo di codice, configurazione e logica di esecuzione che non è il modello stesso. Un modello grezzo non è un agente. Diventa tale solo quando un harness gli fornisce stato, esecuzione di strumenti, cicli di feedback e vincoli applicabili.

Concretamente, un harness include:

• Prompt di sistema, CLAUDE.md, AGENTS.md, file di skill e istruzioni per subagenti.
• Strumenti, skill, server MCP e le loro descrizioni tecniche.
• Infrastruttura integrata, come filesystem, sandbox e browser headless.
• Logica di orchestrazione per generare subagenti, gestire passaggi di consegne e instradare modelli.
• Hook e middleware per esecuzione deterministica, come controlli lint o compattazione del contesto.
• Strumenti di osservabilità per log, trace, misurazione dei costi e della latenza.

Al suo nucleo, un agente è un sistema che esegue strumenti in un ciclo per raggiungere un obiettivo. La vera abilità sta nel progettare sia gli strumenti che quel ciclo.

Sebbene ciò rappresenti un'enorme superficie, è la tua superficie, non quella del fornitore del modello. Claude Code, Cursor, Codex, Aider e Cline sono tutti harness. Il modello sottostante potrebbe essere identico tra le piattaforme, ma il comportamento che si sperimenta è dominato dall'harness.

Riformuliamo il 'problema di competenza'

È comune vedere ingegneri incolpare il modello quando un agente fa qualcosa di insensato, spesso archiviando il problema come qualcosa da 'aspettare la prossima versione' per risolverlo.

La mentalità dell'ingegneria dell'harness rifiuta questa impostazione predefinita. I fallimenti sono solitamente in qualche modo leggibili. Se l'agente ha ignorato una convenzione, aggiungila a AGENTS.md. Se ha eseguito un comando distruttivo, scrivi un hook per bloccarlo. Se si è perso in un compito di 40 passaggi, dividi l'architettura in un pianificatore e un esecutore. Se finisce costantemente con codice rotto, collega un segnale di back-pressure di type-checking nel ciclo.

Come dice HumanLayer: 'Non è un problema di modello. È un problema di configurazione.' Considera i benchmark delle prestazioni: un modello leader in esecuzione all'interno di un framework standard spesso ottiene punteggi drasticamente inferiori rispetto allo stesso identico modello in esecuzione in un harness personalizzato e altamente ottimizzato. Spostare un modello in un ambiente con strumenti di codebase migliori, prompt più stretti e back-pressure più affilata può sbloccare capacità che la configurazione originale aveva lasciato indietro.

Il divario tra ciò che i modelli odierni possono teoricamente fare e ciò che effettivamente si vede fare è in gran parte un divario di harness.

Il Ratchet: Ogni errore diventa una regola

L'abitudine più vitale nell'ingegneria dell'harness è trattare gli errori degli agenti come segnali permanenti - non come colpi di fortuna una tantum da riprovare e dimenticare.

Se un agente pubblica una PR con un test commentato che viene accidentalmente unito, questo è un input. La prossima iterazione di AGENTS.md deve affermare: 'Non commentare mai i test; cancellali o correggili.' Il prossimo hook pre-commit dovrebbe automaticamente segnalare .skip( nel diff. Il subagente revisore deve essere aggiornato per bloccare i test commentati.

I vincoli dovrebbero essere aggiunti solo quando si osserva un fallimento reale, e rimossi solo quando un modello capace li rende ridondanti. Ogni riga in un buon prompt di sistema dovrebbe risalire a un fallimento storico specifico.

Per questo motivo, l'ingegneria dell'harness è una disciplina piuttosto che un framework valido per tutti. L'harness giusto per un codebase specifico è interamente plasmato dalla sua storia unica di fallimenti.

Lavorare a ritroso dal comportamento

Il modo più efficace per progettare un harness è iniziare dal comportamento desiderato e costruire il componente che lo fornisce: Comportamento desiderato → Progettazione dell'harness per raggiungerlo.

Ogni pezzo dell'harness deve avere un compito distinto. Se non si riesce a nominare il comportamento specifico che un componente esiste per fornire, dovrebbe essere rimosso.

Filesystem e Git - stato durevole

Il filesystem è fondamentale. I modelli possono operare solo su ciò che rientra nella loro finestra di contesto. Un filesystem fornisce uno spazio di lavoro per leggere dati, un luogo per scaricare lavoro intermedio e una superficie per coordinare più agenti.

Aggiungere Git fornisce versioning gratuito, permettendo all'agente di tracciare i progressi, creare rami per esperimenti e annullare errori.

Bash ed Esecuzione di Codice: strumentazione generica

La maggior parte degli agenti opera su un ciclo ReAct: ragionare, agire tramite una chiamata a uno strumento, osservare, ripetere. Invece di pre-costruire uno strumento per ogni azione concepibile, dare all'agente accesso a bash gli permette di costruire ciò di cui ha bisogno al volo.

Gli agenti generalmente eccellono nei comandi shell, rendendo bash e l'esecuzione di codice la strategia predefinita per la risoluzione autonoma dei problemi.

Sandbox e Strumentazione Predefinita

Bash è utile solo se viene eseguito in sicurezza. I sandbox forniscono agli agenti un ambiente isolato per eseguire codice, ispezionare file e verificare il lavoro senza rischiare la macchina host.

Un buon sandbox viene fornito con impostazioni predefinite solide: runtime linguistici preinstallati, CLI di test e browser headless, permettendo all'agente di osservare il proprio lavoro e chiudere il ciclo di auto-verifica.

Memoria e Ricerca: Apprendimento Continuo

I modelli non hanno conoscenza al di là dei loro pesi di addestramento e del contesto attuale. Gli harness colmano questo divario utilizzando file di memoria (come AGENTS.md) che iniettano conoscenza in ogni sessione.

Per informazioni in tempo reale come nuove versioni di librerie o dati live, la ricerca web e gli strumenti MCP sono integrati direttamente nell'harness.

Combattere il Degrado del Contesto

I modelli degradano nel ragionamento man mano che le loro finestre di contesto si riempiono. Gli harness gestiscono questa scarsità utilizzando tre tecniche principali:

• Compattazione: Riassumere intelligentemente e scaricare il contesto più vecchio per prevenire errori API.
• Scaricamento delle chiamate agli strumenti: Memorizzare output massicci degli strumenti (come log di 2.000 righe) nel filesystem mantenendo solo le intestazioni e i piè di pagina essenziali nel contesto.
• Divulgazione progressiva: Rivelare istruzioni e strumenti solo quando un compito li richiede esplicitamente, invece di caricare tutto all'avvio.

Esecuzione a Lungo Termine

Il lavoro autonomo a lunga esecuzione soffre di arresto precoce e scarsa scomposizione dei problemi. Gli harness contrastano questo attraverso la progettazione strutturale:

• Cicli: Intercettare il tentativo di un modello di uscire e costringerlo a continuare verso un obiettivo di completamento in una nuova finestra di contesto.
• Pianificazione: Costringere il modello a scomporre gli obiettivi in un file di piano passo-passo, verificando il suo lavoro tramite hook di auto-verifica dopo ogni passo.
• Divisioni: Separare generazione e valutazione in agenti distinti, prevenendo il bias positivo intrinseco che i modelli hanno quando valutano il proprio lavoro.

Gli Hook sono il tuo Livello di Applicazione

Gli hook colmano il divario tra la richiesta di un'azione e la sua applicazione. Vengono eseguiti in cicli di vita specifici: prima di una chiamata a uno strumento, dopo una modifica di un file, o prima di un commit. Gli hook bloccano comandi distruttivi, impongono la formattazione automatica per risparmiare token ed eseguono suite di test.

Idealmente, il successo è silenzioso e i fallimenti sono verbosi. Se un typecheck passa, l'agente non sente nulla; se fallisce, l'errore viene iniettato direttamente nel ciclo per l'autocorrezione.

Ecco il regolamento e la scelta degli strumenti

Un file markdown piatto alla radice di un repository è ancora il punto di configurazione con la massima leva. Tuttavia, deve essere trattato come una checklist di un pilota, non come una guida di stile. Mantienilo breve e assicurati che ogni regola sia guadagnata attraverso un fallimento passato.

La stessa disciplina si applica agli strumenti. Dieci strumenti altamente focalizzati supereranno sempre cinquanta strumenti sovrapposti.

Inoltre, poiché le descrizioni degli strumenti popolano il prompt, integrazioni esterne dannose o sciatte (come server MCP non verificati) possono iniettare prompt errati nell'agente prima ancora che inizi a lavorare.

Come appare in produzione

L'immagine pubblica più chiara che abbia visto di un harness maturo è la suddivisione (stimata) di Fareed Khan dell'architettura di Claude Code.

Quasi ogni concetto della sezione precedente appare in questo diagramma come componente nominato. L'iniezione di contesto è il livello di conoscenza. Lo stato del ciclo risiede nel memory store e nell'isolatore del worktree. Gli hook per azioni distruttive si trovano dietro il permission gate. I firewall di contesto dei subagenti sono l'intero livello multi-agente. Il registro di dispatch degli strumenti è dove si collegano sia i server MCP che bash. La traiettoria di Claude Code riguarda l'harness almeno quanto il modello sottostante.

Gli Harness Non Si Restringono, Si Spostano

Man mano che i modelli migliorano, la necessità di un harness non scompare - si sposta.

È tentante presumere che modelli migliori rendano obsoleta l'impalcatura. Ad esempio, recenti aggiornamenti dei modelli hanno drasticamente ridotto la necessità di mitigazioni dell'ansia da contesto. Ma man mano che il pavimento si alza, anche il soffitto si alza. Compiti che prima erano irraggiungibili sono ora in gioco, portando modalità di fallimento completamente nuove.

Ogni componente in un harness codifica un'ipotesi su ciò che il modello non può fare da solo. Quando il modello migliora, l'impalcatura obsoleta dovrebbe essere rimossa e una nuova impalcatura deve essere costruita per raggiungere il prossimo orizzonte.

E il Ciclo di Addestramento?

C'è un ciclo di feedback attivo tra la progettazione dell'harness e l'addestramento del modello.

I modelli odierni sono spesso post-addestrati con harness specifici nel ciclo, creando un certo grado di overfitting. Il modello diventa eccezionalmente bravo nelle azioni specifiche che i progettisti dell'harness hanno prioritizzato (ad esempio, operazioni sul filesystem, bash, dispatch di subagenti).

Questo rende l'harness un sistema vivente, non un file di configurazione statico, e dimostra che il 'miglior' harness è quello ottimizzato specificamente per i tuoi compiti e flussi di lavoro distinti.

Harness-as-a-Service (HaaS)

L'industria si sta spostando dalla costruzione su API LLM (che forniscono completamenti) alla costruzione su API Harness (che forniscono un runtime). Gli SDK ora offrono il ciclo, gli strumenti, la gestione del contesto, gli hook e i sandbox pronti all'uso.

Invece di costruire l'orchestrazione da zero, l'impostazione predefinita moderna è selezionare un framework di harness, configurare i suoi pilastri principali e concentrarsi puramente sulla progettazione di prompt e strumenti specifici del dominio.

Questo è ciò che rende la risoluzione dei problemi scalabile: si sta ottimizzando una superficie di configurazione ben strutturata piuttosto che reinventare l'intera architettura dell'agente.

Dove Sta Andando

Se si guardano i migliori agenti di codifica oggi, si assomigliano più tra loro di quanto non facciano i loro modelli sottostanti. I modelli differiscono, ma i pattern degli harness stanno convergendo. L'industria sta rapidamente identificando l'impalcatura portante necessaria per trasformare il testo generativo in software distribuibile.

I problemi aperti più entusiasmanti vanno oltre i singoli agenti: orchestrare più agenti in parallelo, consentire agli agenti di analizzare le proprie tracce per risolvere fallimenti a livello di harness e costruire ambienti che assemblano dinamicamente strumenti just-in-time.

In definitiva, questa è la fase in cui gli harness smettono di essere file di configurazione statici e iniziano ad agire molto più come compilatori.

Se stai cercando un grande framework di harness per agenti, @FredKSchott ha scritto Flue. È solido e apparentemente è stato ispirato da una versione precedente di questo post!