Cos'è un agent harness e come funziona
Scopri cos'è un agent harness: il ciclo che richiama il modello, gli strumenti, i permessi, lo stato della sessione e la directory di lavoro.
Che cos'è un agent harness
Un agent harness è il programma che esegue il ciclo intorno a un modello linguistico e lo trasforma in un agente. Contiene il ciclo che continua a richiamare il modello, le definizioni degli strumenti che il modello può usare, le regole di autorizzazione che stabiliscono quali chiamate vengono effettivamente eseguite, lo stato della sessione che persiste tra un turno e l'altro e la directory di lavoro in cui vengono eseguite le attività. Il modello può essere sostituito al suo interno.
È importante ricordare l'ultima frase. Un modello, da solo, risponde a una domanda e poi si dimentica di te. Un harness chiede al modello quale sia il passaggio successivo, esegue il comando richiesto dal modello, restituisce il risultato al modello e pone di nuovo la domanda. Questa ripetizione è ciò che si intende con "agente". Se la terminologia circostante non è ancora chiara, la differenza tra un agente AI, un LLM e un assistente chiarisce i termini prima di scegliere uno strumento.
Il harness non è il modello
La confusione nasce perché i vendor li distribuiscono con lo stesso marchio.
dsh e DeepSeek sono prodotti diversi. DeepSeek Harness, pubblicato su github.com/deepseek-ai/deepseek-harness il 13 August 2026 con licenza MIT, è un programma Node da installare su una macchina. I modelli DeepSeek sono pesi serviti tramite un'API (application programming interface). Se si configura dsh con un modello di un altro vendor, continua a funzionare, perché al harness serve soltanto un componente che accetti messaggi e restituisca chiamate agli strumenti.
Claude Code e Claude costituiscono la stessa coppia. Claude Code è un harness: un programma per terminale con un ciclo di esecuzione, un sistema di autorizzazioni e strumenti per i file e la shell. Claude è la famiglia di modelli che richiama per impostazione predefinita. Codex e Gemini CLI adottano la stessa separazione.
Ecco il test che chiarisce sempre la distinzione. Si installa un harness. Si richiama un modello. Se il componente ha una versione sul disco e un file di configurazione nella home directory, è un harness. Se è una stringa all'interno di quel file, ad esempio deepseek-flash, è il modello.
Cosa fa realmente il loop
Un'iterazione del loop dell'harness funziona in questo modo. Leggi con attenzione, perché quasi ogni differenza tra gli harness consiste in una differenza all'interno di questi cinque passaggi.
- L'harness invia al modello la conversazione corrente, insieme a un elenco di definizioni degli strumenti.
- Il modello risponde con del testo oppure chiede di chiamare uno di quegli strumenti.
- L'harness verifica la richiesta rispetto alle proprie regole di autorizzazione e la esegue oppure si ferma per chiederti conferma.
- L'harness esegue lo strumento, acquisisce l'output e il codice di uscita, quindi tronca l'output se è molto lungo.
- L'harness aggiunge il risultato alla conversazione e torna al passaggio 1.
Nell'uso quotidiano, il passaggio 3 è quello in cui gli harness differiscono maggiormente. Un harness che chiede conferma prima di ogni comando è sicuro, ma stancante. Un harness che non chiede mai conferma prima o poi eseguirà un comando distruttivo su un percorso interpretato in modo errato dal modello. Claude Code supporta una configurazione intermedia: un elenco di comandi autorizzati che vengono eseguiti senza chiedere conferma e una richiesta di conferma per gli altri comandi.
Il passaggio 1 contiene il resto delle differenze. L'harness scrive anche il prompt di sistema che accompagna ognuna di queste richieste. Claude Code ti consente di modificarlo direttamente, perché uno stile di output modifica il prompt di sistema che invia e quindi cambia ogni risposta restituita. La conversazione cresce a ogni iterazione e il modello dispone di una finestra di contesto fissa. Per questo l'harness deve decidere cosa eliminare, cosa riassumere e cosa scrivere in un file per leggerlo in seguito. Questa decisione spiega in gran parte perché due harness che usano lo stesso modello producono risultati di qualità diversa. Se questi cinque passaggi ti sembrano ancora astratti, puoi scrivere una volta un loop rudimentale, che è esattamente ciò che un percorso graduale per imparare a creare agenti AI ti fa costruire nelle prime fasi.
Oggi la maggior parte degli harness collega strumenti esterni tramite MCP (model context protocol), uno standard per esporre uno strumento a qualsiasi harness che lo supporti. In questo modo una sola integrazione può raggiungere più harness. Eseguire server MCP su un VPS tratta questo aspetto. La ricerca sul Web è di solito il primo strumento che le persone aggiungono. Indirizzare l'agente verso la propria istanza SearXNG mantiene le query al di fuori di un servizio di terze parti e chiarisce che ogni pagina letta successivamente dall'agente è un input non attendibile che arriva all'interno del loop.
Agent harness e framework per agent
Questa domanda ricorre ogni volta che viene rilasciato un nuovo harness e le risposte non concordano, in parte perché non concordano nemmeno i vendor. Ecco la distinzione che resta valida.
Un framework è una libreria che si importa. Si assembla l’agent nel codice, usando il loop del framework oppure scrivendone uno proprio. LangChain è l’esempio più noto: fornisce i blocchi fondamentali e l’agent viene assemblato nel codice.
Un harness è un programma che si esegue. Il loop è già scritto, gli strumenti esistono già e il modello delle autorizzazioni ha già una configurazione predefinita. Si ottiene un agent funzionante al primo comando e lo si configura in seguito.
Di solito è il test di installazione a stabilire la distinzione. Se dopo averlo installato si scrive codice, è un framework. Se dopo averlo installato si interagisce con esso, è un harness.
Il confine è realmente oggetto di discussione e la prova più chiara arriva dalla documentazione di LangChain. A ottobre 2026 definisce Deep Agents sia "un harness per agent" sia "una libreria standalone costruita sui blocchi fondamentali di LangChain per gli agent", mentre il repository langchain-ai/deepagents si definisce "l’harness per agent completo di tutto il necessario". Entrambe le descrizioni sono corrette. Deep Agents è un SDK Python (software development kit) che si importa, quindi il test di installazione lo identifica come una libreria, ma distribuisce una quantità sufficiente di comportamento predefinito da essere usato come un harness. Microsoft ha annunciato la disponibilità generale di Hosted Agents in Foundry Agent Service il 9 luglio 2026 e il suo post del 22 luglio 2026 annuncia il rilascio di Microsoft Agent Framework Harness. Questo dimostra che il termine è ormai una categoria di prodotto, non solo gergo tecnico.
È quindi più utile porsi la domanda che consente di prevedere il carico di lavoro. Se si scrive il loop, si diventa responsabili del loop: dei retry, della riduzione del contesto, delle richieste di autorizzazione e della registrazione di ciò che è accaduto. Se il loop viene fornito dal prodotto, si eredita la soluzione di qualcun altro per tutti questi aspetti. Si inizia molto più rapidamente, ma in seguito è più difficile modificarla.
Differenze tra un harness e una finestra di chat
Una finestra di chat e un harness mostrano entrambi l'output del modello. La differenza riguarda il computer su cui viene eseguito il lavoro. In una finestra di chat, qualsiasi codice eseguito dal modello viene eseguito nella sandbox del fornitore e opera sui file caricati. Un harness esegue gli strumenti sul computer da cui lo hai avviato, con l'account dell'utente che lo ha avviato, sui file reali e con le credenziali reali disponibili nel relativo ambiente.
Questi sono, in due frasi, tutti i vantaggi e tutti i rischi. L'agent può finalmente eseguire il lavoro. Ma può anche eliminare il lavoro.
Gli harness che vengono effettivamente utilizzati
Questo elenco è datato 19 agosto 2026 intenzionalmente. La categoria cambia ogni settimana e qualsiasi panoramica diventa rapidamente obsoleta.
- Claude Code e Codex sono harness dei rispettivi vendor. Sono orientati innanzitutto al terminale, associati per impostazione predefinita ai modelli del proprio vendor e offrono la gestione delle autorizzazioni più curata. Confronto tra Claude Code, Cursor, Codex e Copilot li analizza in dettaglio.
- DeepSeek Harness (
dsh) è distribuito con licenza MIT e si basa su un unico principio: tutto è un plugin. Modelli, strumenti, sessioni, sandbox e interfaccia utente sono quindi componenti sostituibili. Ogni plugin installato viene eseguito con le autorizzazioni dell'agente, quindi verificare a cosa può accedere un plugin dsh prima di aggiungerlo è più importante che con un harness dotato di un set di strumenti fisso. - Hermes, di Nous Research, è un agente autonomo generalista, non uno strumento per la programmazione. È stato rilasciato con licenza MIT a febbraio 2026 e utilizza uno storage locale integrato: memorie e competenze sono file in
~/.hermes, mentre la cronologia delle sessioni è archiviata in un database SQLite locale. Questo non rappresenta più l'intero quadro quando abiliti uno dei provider di memoria esterni opzionali, come Mem0 o Hindsight. A ottobre 2026 la documentazione di Hermes indica che un provider attivo riceve ogni turno della conversazione dopo ciascuna risposta e una copia di ogni scrittura nella memoria integrata. I dati risiedono quindi anche presso quel provider. Confronto tra Hindsight e Mem0 è utile prima di abilitarne uno, mentre Self-hosting di Hermes su un VPS illustra i passaggi restanti. - Omnigent è un meta-harness: gestisce altri harness, tra cui Claude Code e Codex, tramite un'unica API con sessioni condivise, limiti di spesa e una sandbox a livello di sistema operativo. Omnigent come harness multi-agente spiega quali vantaggi offre.
- OneCLI è un harness con sandbox, pensato per i team e basato su un gateway che inserisce le credenziali nelle richieste in uscita dell'agente. L'agente stesso non vede mai le chiavi reali.
Tre di questi finiscono abbastanza spesso nella stessa selezione ristretta da rendere utile leggere DeepSeek Harness, Claude Code e Omnigent a confronto diretto per esaminare accoppiamento ai modelli, licenza, maturità e requisiti per l'esecuzione su un server.
Il quick start di dsh consiste in un singolo comando e basta eseguirlo una volta per capire rapidamente che cos'è un harness. Sul computer deve essere installato Node.js.
npx @deepseek-ai/dsh webIl comando avvia l'interfaccia web su http://127.0.0.1:3080. Leggi il README prima di farvi affidamento, perché dsh si definisce una developer preview e dichiara esplicitamente che saranno introdotte modifiche incompatibili. Se il primo comando fallisce direttamente o scarica una build diversa da quella prevista, fissare una versione esatta di dsh e svuotare la cache di npx è in genere sufficiente per riprendere l'installazione. Eseguire DeepSeek Harness su un VPS illustra l'installazione sul server, mentre perché quell'indirizzo inizia con 127.0.0.1 spiega l'impostazione predefinita sul loopback.
I router si collocano sopra l’harness
Un model router è un proxy locale tra l’harness e l’API del provider. Claude Code Router è l’esempio più comune: per impostazione predefinita si mette in ascolto su 127.0.0.1:3456, accetta le richieste che Claude Code avrebbe inviato al proprio vendor e le inoltra al provider configurato. L’harness non rileva alcuna modifica.
I router esistono perché il modello è sostituibile, quindi dimostrano bene il punto principale di questo articolo. Concentrano inoltre i rischi, perché il proxy vede ogni prompt e conserva ogni chiave dei provider. Trattalo come un componente dell’infrastruttura, non come una semplice comodità. Dove un harness conserva le chiavi API e le impostazioni dei modelli è lo stesso problema a un livello inferiore.
Cosa cambia quando l’harness viene eseguito su un VPS
Quando l’harness viene spostato dal laptop a un server preso in affitto, cambiano quattro aspetti.
Continua a funzionare quando chiudi il coperchio. Un’attività lunga continua durante il tragitto e non dipende dalla batteria. Avviala all’interno di tmux e scollegati dalla sessione:
tmux new -s agent
# start the harness, then press Ctrl-b and then d to detach
tmux attach -t agentPer tutto ciò che deve ripartire dopo un riavvio, un servizio utente è preferibile a una sessione del terminale:
loginctl enable-linger $USER
systemctl --user status my-agent.serviceloginctl enable-linger è l’aspetto che spesso viene trascurato. Senza questa impostazione, il comportamento predefinito di systemd è arrestare il service manager dell’utente 10 secondi dopo la chiusura dell’ultima sessione. Di conseguenza, un servizio utente non mantiene l’agent in esecuzione dopo il logout. Eseguire dsh senza interfaccia tramite systemd contiene il file dell’unità. Quando una sessione è già attiva su quel server, puoi avviarne una seconda. Inoltre, due sessioni di Claude Code sullo stesso host possono inviarsi messaggi, quindi quella avviata questa mattina può assegnare un’attività all’altra senza che tu debba inoltrarla manualmente.
Conserva le tue chiavi. La chiave del provider ora si trova in un file di configurazione su quel server. Verifica chi può leggerlo:
ls -l ~/.configQualsiasi processo eseguito con il tuo account può leggere quel file. Questo include l’agent e tutto ciò che l’agent decide di eseguire.
Può raggiungere gli altri computer. Un VPS sulla stessa rete privata degli altri host fornisce all’agent un percorso per raggiungerli. Questo è esattamente lo scopo, ma rappresenta anche l’ampiezza del potenziale impatto.
È raggiungibile ovunque ti trovi. La maggior parte degli harness espone un’interfaccia web e, per un motivo preciso, la maggior parte la associa all’interfaccia di loopback. Controlla la tua:
ss -tlnp | grep 3080127.0.0.1:3080 significa che solo il server stesso può connettersi. 0.0.0.0:3080 significa che l’interfaccia web è in ascolto su tutte le interfacce. Di conseguenza, chiunque possa raggiungere l’indirizzo pubblico del server può connettersi, a meno che un firewall a monte non blocchi la porta. A ottobre 2026 dsh rifiuta all’avvio un indirizzo wildcard di questo tipo, ma molte altre interfacce web lo accettano. Raggiungi un’interfaccia associata a loopback tramite un tunnel SSH invece di modificare l’indirizzo di binding:
ssh -N -L 3080:127.0.0.1:3080 you@your-serverApri quindi http://127.0.0.1:3080 nel browser del laptop. Il traffico passa all’interno della sessione SSH, quindi non viene esposto nulla di nuovo a Internet.
Tutte queste proprietà costituiscono anche la motivazione di sicurezza
Rileggete le quattro proprietà dal punto di vista di un attaccante.
Il sistema viene eseguito senza supervisione, quindi nessuno controlla il momento in cui il modello interpreta erroneamente un percorso. Contiene le vostre chiavi, quindi un solo file di configurazione leggibile equivale all'accesso all'intero account del provider. Può raggiungere le altre macchine, quindi una prompt injection, cioè istruzioni nascoste in una pagina web o in un file letto dall'agente, ora dispone di un percorso verso il server del database. È raggiungibile da qualsiasi rete, quindi un'interfaccia web in ascolto su un indirizzo pubblico, senza un firewall davanti e senza una propria autenticazione, offre una shell a chiunque la trovi. dsh inserisce un token di processo nell'URL che stampa all'avvio. Questo aiuta, ma quell'URL è ora una credenziale, quindi condividetelo con la stessa cautela riservata a una password.
In ogni caso la correzione è semplice e sempre la stessa. Assegnate all'agente un proprio account utente senza privilegi, invece di usare il vostro:
sudo adduser --disabled-password --gecos "" agentMantenete l'interfaccia web sull'interfaccia di loopback e raggiungetela tramite SSH. Assegnate all'agente le credenziali con l'ambito più ristretto possibile, purché siano sufficienti a completare il lavoro. L'approccio mantenere i secret fuori dagli agenti AI viene illustrato in dettaglio nella relativa guida. Per tutto ciò che viene eseguito mentre non state controllando il sistema, una macchina usa e getta è preferibile a una macchina configurata con attenzione: sia eseguire agenti di coding in una VM usa e getta sia eseguire Claude Code in sicurezza su un VPS seguono questo approccio.
Ti serve un harness per agenti?
Se il tuo lavoro consiste in una domanda alla volta, una finestra di chat è sufficiente; un harness aggiunge solo un ciclo che dovresti supervisionare. Un harness inizia a essere utile quando un'attività richiede molti passaggi su file reali, o quando deve continuare a lavorare mentre dormi.
La maggior parte di questa categoria è ancora acerba. dsh riporta la dicitura "developer preview" nel proprio README a ottobre 2026, e gli altri progetti evolvono abbastanza rapidamente da rendere possibile che un file di configurazione scritto oggi richieda modifiche già il mese prossimo. Questo è un motivo per mantenere la propria configurazione piccola e riproducibile, e un motivo per annotare ogni modifica effettuata. La stessa moderazione aiuta all'interno del ciclo, dove una competenza che spinge l'agente verso la modifica minima funzionante ti lascia un diff che puoi effettivamente leggere al termine di un'esecuzione non presidiata. Inizia con un solo harness su un singolo server, assegnagli un solo compito e una chiave con permessi limitati, ed estendi il suo accesso solo dopo che quel primo compito è diventato banale per una settimana. Gli agenti self-hosted che vale la pena eseguire oggi è un punto di partenza ragionevole per scegliere il primo.
FAQ
Che cos'è un agent harness in termini semplici?
È il programma che circonda il modello. Il modello produce testo e richieste di utilizzo degli strumenti. L'harness esegue il ciclo che continua a inviare richieste, esegue gli strumenti richiesti dal modello, applica le regole sugli strumenti che possono essere eseguiti senza autorizzazione e conserva lo stato della sessione e i file tra un turno e l'altro. Se si sostituisce il modello, l'harness continua a funzionare. Questo dimostra nel modo più chiaro che sono componenti distinti.
Claude Code è un modello o un harness?
Claude Code è un harness. È un programma per terminale con un ciclo di esecuzione, un sistema di autorizzazioni e strumenti integrati per i file e la shell. Claude è la famiglia di modelli che richiama per impostazione predefinita. La stessa distinzione vale per DeepSeek Harness (dsh), un programma Node da installare, e per i modelli DeepSeek, disponibili tramite API. Si installa un harness su una macchina. Si richiama un modello tramite la rete.
Qual è la differenza tra un agent harness e un agent framework?
Un framework è una libreria che si importa e sulla quale si scrive codice, usando il suo ciclo di esecuzione oppure implementandone uno proprio. Un harness è un programma che si esegue. Il ciclo, i tentativi ripetuti e la gestione del contesto sono quindi inclusi con impostazioni predefinite da configurare, invece di doverli implementare. Nella pratica, il confine non è netto: a ottobre 2026, il repository di LangChain's Deep Agents lo definisce un agent harness completo e pronto all'uso, anche se si tratta di un SDK importabile. Chiedersi se si dovrà scrivere personalmente il ciclo di esecuzione. La risposta determina quale termine descrive meglio la situazione.
Serve un VPS per eseguire un agent harness?
No. Tutti gli harness citati qui possono essere eseguiti su un laptop. Un server cambia quattro aspetti: l'agente continua a funzionare quando si chiude il coperchio, conserva le chiavi su una macchina sempre accesa, può raggiungere gli altri server e consente di tornare alla stessa sessione da qualsiasi dispositivo. Ognuno di questi aspetti comporta anche considerazioni di sicurezza. È quindi opportuno assegnare all'agente un account utente dedicato e mantenere ogni interfaccia web in ascolto su 127.0.0.1.
Posso usare un modello diverso nello stesso harness?
Di norma sì, ed è questa la caratteristica distintiva di un harness. La maggior parte degli harness accetta nella configurazione il nome del modello e un base URL. Per usare un altro provider è quindi sufficiente modificare la configurazione, senza riscrivere il programma. Quando un harness non lo consente direttamente, un router locale come Claude Code Router si interpone tra l'harness e il provider e traduce le richieste; per impostazione predefinita, è in ascolto su 127.0.0.1:3456. Prestare attenzione a questo proxy, perché può vedere ogni prompt e conserva ogni chiave.