Harness dell'agente: cos'è e di cosa si compone

Definizione

L'harness di un agente AI (agent harness) è l'impalcatura software attorno al modello linguistico: tutto ciò che non è il modello stesso, ma che influenza il modo in cui l'agente lavora. La formula è: Agente = Modello + Harness. Il modello sa ragionare e scrivere codice, ma l'harness decide che cosa vede, con cosa può agire, dove vengono eseguiti i comandi, che cosa sopravvive tra una sessione e l'altra e come l'agente scopre i propri errori.

I cinque componenti dell'harness

• Istruzioni — il prompt di sistema e i file di progetto come CLAUDE.md e AGENTS.md, i documenti tematici e le skills.
• Strumenti — esecuzione di comandi nella shell, modifica dei file, browser, connessioni tramite MCP.
• Ambiente — sandbox o container in cui l'agente esegue il codice senza mettere a rischio la produzione.
• Stato — file di piano e di avanzamento, cronologia git: la memoria che sopravvive alla chiusura della sessione.
• Feedback — test, linter, controllo dei tipi, hook che restituiscono all'agente il segnale di errore.

L'harness non è un singolo file di prompt. Un AGENTS.md molto lungo non aiuta se l'agente non ha accesso ai test o se l'ambiente non si avvia. L'affidabilità la determina il componente più debole dei cinque.

Esempio

L'agente sta cercando di correggere lo stesso bug per la terza sessione di fila: a ogni riavvio non ricorda che cosa aveva già provato. Sembra un problema del modello. In realtà a rompersi è il componente di stato. La soluzione è un file PROGRESS.md in cui l'agente annota, alla fine della sessione, le ipotesi che non hanno funzionato e il passo successivo:

## Bug: addebito doppio con richiesta ripetuta
Verificato e scartato:
- timeout del client HTTP — nessun effetto
- race condition nel gestore del webhook — non riprodotta
Passo successivo: controllare la idempotency key in payments/service.py

La nuova sessione legge il file e riprende esattamente da dove si era fermata. Il modello non è cambiato: è cambiato l'harness.

Sintesi

L'harness di un agente AI è l'insieme di istruzioni, strumenti, ambiente, stato e feedback attorno al modello. È ciò che determina se lo stesso agente lavorerà in modo affidabile o si romperà. Come costruire ciascun componente è spiegato in un corso pratico su un progetto reale.