Skip to content
Chatta con un agente AI
Fondamenti

Architettura dell'agent harness: le sei parti che la tua azienda dovrebbe possedere

Orange ITS — Team di ingegneria AI 12 min di lettura

Il tuo pilota con un agente funziona. Poi esce un aggiornamento del modello, un collega modifica un prompt, e i risultati dell’abbinamento delle fatture del mese scorso cambiano senza che nessuno se ne accorga. Nessuno sa dire quale dei pezzi attorno al modello sia la causa, perché nessuno ha mai messo per iscritto quali siano.

È la situazione in cui si trova il responsabile tecnico quando la proprietà chiede: “cosa abbiamo pagato esattamente, e possiamo tenerlo?” Il modello è in affitto. Tutto ciò che lo circonda è dove vive il tuo investimento, e una buona parte dovrebbe essere tua.

Per i team che vogliono questo involucro costruito attorno ai propri sistemi, è il lavoro che svolgiamo con il nostro servizio di forward-deployed AI engineering.

Un agent harness si compone di sei parti, e l’azienda dovrebbe possedere e documentare ciascuna di esse, perché insieme determinano la verificabilità, la facilità di cambiare modello e quanto rework ricade sul personale. Questo articolo le passa in rassegna, indica cosa può andare storto in ognuna e in quale ordine costruirle.

Nota di perimetro: per il lato buy-versus-build di questa questione, leggi harness AI su misura o copilot SaaS.


Che cos’è un agent harness

Il team di ingegneria di Anthropic (Demystifying evals for AI agents) definisce l’agent harness (chiamato anche scaffold) come il sistema che permette a un modello di agire da agente: elabora gli input, orchestra le chiamate agli strumenti e restituisce i risultati. Ne ricava una conseguenza: valutare un agente significa valutare l’harness e il modello che lavorano insieme. Cambiando uno dei due, il risultato può cambiare.

I fornitori usano vocabolari diversi, ma i pezzi coincidono. Contesto, strumenti, memoria, guardrail, eval e orchestrazione coprono ciò che descrivono le fonti, e la tabella qui sotto è la versione che usiamo con i clienti.

ParteCosa faCosa dovresti possedereGuasto tipico
ContestoDecide cosa vede il modello a ogni passaggioFile di istruzioni e regole di retrieval in testo sempliceIstruzioni gonfie o obsolete che fanno salire il costo senza migliorare l’accuratezza
StrumentiPermette all’agente di leggere e modificare sistemi realiDefinizioni degli strumenti, permessi e codice di integrazioneDescrizioni vaghe degli strumenti, con scelta dell’azione sbagliata
MemoriaPorta lo stato da una sessione all’altraI file archiviati, in un formato esportabileNote obsolete trattate come verità, o dati sensibili scritti nell’archivio
GuardrailLimita ciò che l’agente può raggiungere o approvarePolicy, sandbox e regole di approvazioneRegole scritte senza alcun controllo tecnico a sostenerle
EvalValuta se il lavoro era giustoCasi di test, grader e storico dei risultatiUn grader difettoso che riporta con sicurezza il punteggio sbagliato
OrchestrazioneOrdina passaggi, ripetizioni e passaggi di consegneLa definizione del workflow e i suoi logComplessità aggiunta prima di aver dimostrato che un solo agente fallisce

Nel resto dell’articolo le vediamo una alla volta.


Contesto: seleziona ciò che il modello legge

I modelli non leggono con la stessa efficacia una quantità illimitata di testo. La guida di Anthropic al context engineering parla di “context rot”: il recupero delle informazioni peggiora con la crescita dei token nella finestra, quindi l’obiettivo è il più piccolo insieme di informazioni che basti a svolgere il compito. Tra le tecniche ci sono il recupero del materiale al momento del bisogno, la compattazione delle cronologie lunghe, le note strutturate e la delega di sottocompiti. La guida ne dichiara anche i costi: l’esplorazione a runtime è più lenta del retrieval precalcolato, e una compattazione troppo aggressiva può perdere contesto sottile ma decisivo. Cosa tenere, cancellare e archiviare prima di tagliare lo spieghiamo nell’articolo sul context engineering per gli agenti.

I file di istruzioni sono la forma più visibile di contesto. AGENTS.md è il formato aperto per scriverli, e il suo sito lo descrive come un README per agenti. Esistono limiti pratici: la documentazione di OpenAI Codex dice che, per impostazione predefinita, smette di aggiungere file di istruzioni quando la loro dimensione complessiva raggiunge 32 KiB.

Le prove su quanto scrivere sono contrastanti. In uno studio dell’ETH di Zurigo (arXiv 2602.11988) gli autori hanno rilevato che i file di contesto non miglioravano in generale il successo dei task e aumentavano in media di oltre il 20% il costo di inferenza. Gli agenti seguivano le istruzioni; a non servire erano le panoramiche del repository, che i fornitori di modelli raccomandano spesso. Gli autori hanno trovato i file utili per specificare pratiche non standard, e quelli scritti da sviluppatori hanno reso meglio di quelli generati da un modello.

Cosa significa per te: tieni il file breve, inseriscici solo ciò che l’agente non può dedurre dal tuo codice o dai tuoi documenti, e provalo sui tuoi compiti. Il valore per il business sta in una spesa di token più bassa e in meno risposte strane. Tieni il file nel tuo repository, in testo semplice, così ti segue.


Strumenti: tratta l’interfaccia come un prodotto

Uno strumento è qualsiasi azione che l’agente può compiere: interrogare l’ERP, leggere una casella di posta, creare un ticket. La guida di Anthropic “Building effective agents” afferma che le definizioni degli strumenti meritano la stessa attenzione di prompt engineering del prompt principale, e suggerisce di scrivere la descrizione di uno strumento come il docstring per uno sviluppatore junior. Raccomanda inoltre di rendere gli errori più difficili già in fase di progetto: nel suo esempio, richiedere percorsi di file assoluti ha fatto usare lo strumento in modo affidabile a un modello.

Il guasto, qui, è silenzioso. Uno strumento dal nome ambiguo o con funzioni sovrapposte non va in crash: in una parte delle esecuzioni l’agente ne sceglie semplicemente un altro. Come consiglia la guida, esegui molti input di esempio, leggi gli errori e correggi la definizione.

Quanto alla proprietà, le definizioni degli strumenti e il codice di integrazione devono essere tuoi. Se stanno dentro il builder visuale di un fornitore, chiedi un export prima di impegnarti. Il nostro articolo su MCP e strumenti degli agenti tratta il protocollo standard che rende gli strumenti portabili tra runtime di agenti diversi.


Memoria: file che puoi leggere e cancellare

La memoria è tutto ciò che sopravvive tra una sessione e l’altra. La documentazione di Anthropic sul suo memory tool precisa che lo strumento opera lato client: il modello richiede le operazioni sui file e la tua applicazione le esegue. Il lavoro di sicurezza ricade quindi su di te. La documentazione indica agli sviluppatori di validare ogni percorso per prevenire il directory traversal, di limitare la dimensione dei file, di far scadere i file a cui non si accede da molto tempo e di rimuovere i dati sensibili prima della scrittura.

Per un’azienda è per lo più una buona notizia. Una memoria tenuta come file nel tuo storage è ispezionabile, cancellabile ed esportabile, il che conta per le richieste in materia di protezione dei dati e per gli audit. Fallisce anche in modo prevedibile: una vecchia nota viene trattata come fatto attuale. Assegna ai file di memoria un responsabile e una regola di scadenza.

In un post di aprile 2026 Anthropic riporta che su BrowseComp-Plus una cartella di memoria ha portato Sonnet 4.5 dal 60,4% al 67,2%. È una singola esecuzione del fornitore, senza replica indipendente: leggila come un segnale incoraggiante, ancora da confermare. Il nostro articolo sulla memoria degli agenti AI approfondisce le scelte di progettazione.


Guardrail: le regole hanno bisogno di un controllo che le sostenga

I guardrail limitano ciò che l’agente può raggiungere e ciò che può fare senza l’approvazione di una persona. La documentazione di Claude Code è insolitamente schietta sui limiti delle proprie modalità di permesso. Afferma che la modalità più permissiva non offre alcuna protezione contro la prompt injection o le azioni indesiderate, e che l’auto mode riduce le richieste di permesso senza garantire la sicurezza. La documentazione distingue due questioni: le modalità di permesso decidono se l’agente chiede, mentre sandbox e isolamento esterno decidono che cosa un’azione può raggiungere una volta eseguita.

Il post di Anthropic sul sandboxing riferisce che il sandboxing ha ridotto dell’84% le richieste di permesso nell’uso interno, e che un sandboxing efficace richiede sia l’isolamento del filesystem sia quello della rete. La cifra è una misurazione di Anthropic stessa, e il runtime era stato rilasciato come research preview in beta.

Una regola scritta non è un controllo. Un preprint di Ting Yan (arXiv 2608.23550) ha esaminato 481 file CLAUDE.md pubblici e stimato che, con il criterio di corrispondenza più rigoroso, solo il 4,4% delle regole di sicurezza aveva un controllo integrato corrispondente. È uno studio di un solo autore su file pubblici, e non dimostra che chi li ha scritti volesse far rispettare ogni riga. La lezione resta valida: se la regola dice “mai toccare la produzione”, a garantirlo deve essere qualcosa di diverso dal prompt.

Cosa significa per te: dai all’agente credenziali proprie con diritti ristretti, registra ogni azione e richiedi l’approvazione per tutto ciò che è irreversibile. La verificabilità che il tuo responsabile compliance cerca nasce da quei log e da quei permessi.


Eval: la risorsa che sopravvive al modello

Le eval sono i test che dicono se l’agente ha fatto il suo lavoro. Il post di Anthropic sulle eval definisce un task, un trial, un grader e un esito, e insiste che l’esito è lo stato finale dell’ambiente (la prenotazione esiste nel database?), qualunque cosa l’agente dichiari di aver fatto. Il suo consiglio per iniziare è concreto: da 20 a 50 task semplici tratti da errori reali sono un ottimo inizio, e costruire le eval diventa più difficile quanto più si aspetta.

Due dettagli di quel post contano per chi dirige. Primo, la coerenza. Un tasso di successo del 75% per trial dà circa il 42% se servono tutti e tre i tentativi su tre. Un agente che gestisce correttamente una fattura tre volte su quattro non è pronto per lavorare senza supervisione. Secondo, i grader possono sbagliare. Il post dice che i punteggi possono trarre in inganno se i grader sono difettosi o i task ambigui, e descrive un benchmark in cui problemi di valutazione hanno abbassato il punteggio iniziale di un modello.

Le eval sono anche la parte più portabile dell’harness. Un set di casi reali con soglie di superamento concordate funziona con qualsiasi modello e qualsiasi runtime. Quando un fornitore rilascia un nuovo modello, rilanci il set e decidi in un pomeriggio. Senza, il cambio di modello diventa una questione di opinioni. La nostra guida a test ed eval per gli agenti AI mostra come costruire il primo set.


Orchestrazione: aggiungi struttura solo quando un agente non basta

L’orchestrazione decide come i passaggi vengono ordinati, ripetuti e consegnati. Anthropic distingue i workflow, in cui percorsi di codice predefiniti guidano il modello, dagli agenti, in cui è il modello a dirigere il proprio processo. Elenca cinque pattern comuni: prompt chaining, routing, parallelizzazione, orchestrator-workers ed evaluator-optimizer. Il suo consiglio è cercare la soluzione più semplice possibile, perché gli agenti comportano costi maggiori e il potenziale di errori che si accumulano.

I progetti multi-agente richiedono ancora più scetticismo. Nel suo post sugli agenti di lunga durata, Anthropic dice che resta incerto se funzioni meglio un singolo agente di programmazione generalista o un’architettura multi-agente. Il suo post di aprile 2026 riporta che, con Opus 4.6, l’avvio di subagenti ha migliorato i risultati di BrowseComp del 2,8% rispetto alle migliori esecuzioni a singolo agente, un risultato del fornitore su un compito ristretto. La posizione onesta è che i vantaggi di molti agenti che cooperano non sono dimostrati, e i ruoli in più aggiungono costi, log da leggere e più punti in cui qualcosa può rompersi.


I file che tengono in rotta gli agenti di lunga durata

Un compito che richiede ore attraversa molte sessioni, e ogni nuova sessione parte senza ricordo della precedente. Il post di Anthropic sugli harness di lunga durata descrive una risposta semplice costruita con file ordinari. Ne aggiungiamo un quinto, che è una nostra raccomandazione e non fa parte di quel post:

  • Un file mappa (nostra aggiunta) come AGENTS.md o CLAUDE.md, che dice a ogni nuova sessione dove si trovano le cose e quali sono le regole.
  • Uno script di inizializzazione, che il post descrive come un init.sh che avvia il server di sviluppo ed esegue un controllo end-to-end di base.
  • Un elenco di funzionalità in JSON in cui ogni funzionalità parte come fallita. Il post riporta che il modello ha meno probabilità di modificare il JSON in modo improprio, che gli agenti possono modificare solo il campo passes e che rimuovere o modificare i test è dichiarato inaccettabile. Nella demo conteneva oltre 200 funzionalità.
  • Un registro di avanzamento, un file di testo che annota cosa ha fatto ogni sessione, così la successiva può riprendere.
  • La cronologia Git con messaggi di commit descrittivi, per poter annullare le modifiche sbagliate.

Il lavoro procede una funzionalità alla volta. Gli autori precisano che la demo era tarata sullo sviluppo web full-stack e si limitano a ipotizzare che le lezioni valgano anche per altri ambiti.

Questi artefatti valgono per l’azienda più di quanto sembri. Sono la traccia di audit: cosa è stato tentato, cosa ha superato i test, chi ha cambiato cosa e quando. Sono anche la tua via d’uscita. Un nuovo modello, o un nuovo fornitore, può leggere gli stessi file e proseguire.


Ordine di costruzione e date di revisione

Cosa costruire per primo e cosa saltare

Conta più l’ordine che la completezza. Una sequenza che funziona per il primo workflow:

  1. Scegli un workflow circoscritto e scrivi che aspetto ha un risultato corretto.
  2. Costruisci il set di eval, partendo da 20 casi tratti da errori o correzioni reali del passato.
  3. Definisci gli strumenti di cui il workflow ha bisogno, con permessi ristretti e logging.
  4. Scrivi il file di istruzioni utile più breve possibile, poi verifica se ogni sezione migliora il punteggio delle eval.
  5. Aggiungi guardrail e approvazioni per tutto ciò che è irreversibile, sostenuti da controlli tecnici.
  6. Aggiungi la memoria quando le sessioni devono proseguire il lavoro l’una dell’altra.
  7. Aggiungi l’orchestrazione solo se il singolo agente ha dimostrabilmente fallito.

Salta tutto ciò che duplica quanto la tua piattaforma già offre. Salta i team multi-agente finché il passo 7 non pone la questione.

Le parti invecchiano: prevedi la revisione

L’argomento più forte contro un investimento pesante viene dai fornitori stessi. Lance Martin di Anthropic scrive in un post del 2026 che gli harness codificano ipotesi su ciò che il modello non sa fare da solo, e che queste ipotesi invecchiano con il miglioramento dei modelli. Cita reset del contesto pensati per una generazione di modelli che con la successiva sono diventati zavorra. LangChain, nello stesso spirito, scrive che con il miglioramento dei modelli i suoi guardrail diventeranno probabilmente superflui. Per capire quanto può valere un miglioramento ottenuto solo con il harness e come verificare quali regole eliminare, vedi harness engineering.

Il risultato di LangChain stessa è in tensione con questo. Nel suo post sull’harness engineering, le sole modifiche all’harness hanno portato un coding agent dal 52,8% al 66,5% su Terminal-Bench 2.0 a modello invariato. Si tratta di un solo fornitore, di un solo benchmark, con ottimizzazione su quel benchmark, e LangChain non separa il contributo di ciascuna modifica. Gli autori avvertono anche che le modifiche che si adattano troppo a un task possono causare regressioni su altri.

Entrambe le cose possono essere vere. Il lavoro sull’harness rende oggi, e una parte sarà obsoleta dopo il prossimo modello. Da qui il consiglio iniziale: possiedi le parti legate al tuo business (casi di test, accessi agli strumenti, log, standard scritti) e tratta lo scaffolding generico come usa e getta. Metti una data di revisione su ogni parte e rilancia il set di eval a ogni cambio di modello.

Se oggi non sai dire chi possiede ciascuna delle sei parti, è la prima evidenza di qualsiasi revisione dell’harness. Il passo successivo più economico è un inventario di una pagina: per ogni parte, dove vive, chi la mantiene e se potresti esportarla domani.

Domande frequenti

Che cos'è un agent harness?

Un agent harness è il codice e la configurazione attorno a un modello linguistico che lo trasforma in un agente. Anthropic lo descrive come il sistema che permette a un modello di agire da agente elaborando gli input, orchestrando le chiamate agli strumenti e restituendo i risultati. Nella nostra impostazione comprende contesto, strumenti, memoria, guardrail, eval e orchestrazione, mentre il modello mette il ragionamento.

Che cos'è AGENTS.md e ne abbiamo bisogno?

AGENTS.md è un formato aperto in Markdown semplice per dare istruzioni di progetto ai coding agent, spesso descritto come un README per agenti. Ti serve solo se usi coding agent sui tuoi repository. Tienilo breve, perché OpenAI Codex smette di leggere i file di istruzioni a un totale di 32 KiB per impostazione predefinita, e verifica se ogni riga serve davvero.

Quale parte dell''harness conviene costruire per prima?

Parti da un piccolo set di eval, poi da strumenti e contesto per un solo workflow circoscritto. Anthropic indica come buon inizio da 20 a 50 task semplici tratti da errori reali. Senza quel set non puoi sapere se una modifica successiva a contesto, memoria od orchestrazione ha aiutato, e tutto il resto viene costruito alla cieca.

Servono più agenti?

Di solito no, all'inizio. Anthropic consiglia di cercare la soluzione più semplice possibile e avverte che gli agenti comportano costi maggiori e il rischio di errori che si accumulano. Nel suo articolo sugli agenti di lunga durata ammette che resta aperto se funzioni meglio un agente generalista o un assetto multi-agente. Aggiungi ruoli solo quando un singolo agente dimostrabilmente fallisce.

Con modelli migliori l''harness diventerà superfluo?

In parte sì. LangChain afferma che i suoi guardrail diventeranno probabilmente superflui con il miglioramento dei modelli, e Anthropic sostiene che le ipotesi dell'harness invecchiano. Restano utili le parti legate al tuo business: casi di test, accessi agli strumenti, log di audit e la definizione scritta di un risultato corretto. Rivedi ogni parte a ogni cambio di modello.

Insights

Metti queste idee al lavoro

Bastano 30 minuti per capire se un agente AI si adatta al tuo flusso di lavoro — e quanto può rendere.