Cos'è un agent harness e come funziona

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.

L’harness non è il modello

I due concetti vengono confusi perché i fornitori li distribuiscono con un unico nome commerciale.

dsh e DeepSeek sono prodotti diversi. DeepSeek Harness, pubblicato all’indirizzo 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 a cui si accede tramite un’API (application programming interface). Se si configura dsh per usare un modello di un altro fornitore, continua a funzionare, perché all’harness serve soltanto un componente che accetti messaggi e restituisca chiamate agli strumenti.

Claude Code e Claude sono la stessa coppia di componenti. Claude Code è un harness: un programma per il terminale con un ciclo di esecuzione, un sistema di autorizzazioni e strumenti per i file e la shell. Claude è la famiglia di modelli che chiama per impostazione predefinita. Codex e Gemini CLI adottano la stessa separazione.

Ecco il test che chiarisce sempre la distinzione. Si installa un harness. Si chiama un modello. Se il componente ha una versione sul disco e un file di configurazione nella home directory, è un harness. Se invece è una stringa contenuta in quel file di configurazione, come deepseek-chat, è il modello.

Cosa fa effettivamente il loop

Un'iterazione di un loop di orchestrazione funziona così. Leggila con attenzione, perché quasi tutte le differenze tra i vari sistemi dipendono da questi cinque passaggi.

1. Il sistema invia al modello la conversazione fino a quel momento, insieme a un elenco delle definizioni degli strumenti.
2. Il modello risponde con del testo oppure richiede l'esecuzione di uno di questi strumenti.
3. Il sistema verifica la richiesta in base alle proprie regole di autorizzazione e la esegue oppure si ferma per chiederti conferma.
4. Il sistema esegue lo strumento, acquisisce l'output e il codice di uscita, quindi tronca l'output se è molto lungo.
5. Il sistema aggiunge il risultato alla conversazione e torna al passaggio 1.

Nell'uso quotidiano, il passaggio 3 è quello in cui i sistemi differiscono maggiormente. Un sistema che chiede conferma prima di ogni comando è sicuro ma faticoso. Un sistema che non chiede mai conferma prima o poi eseguirà un comando distruttivo su un percorso interpretato erroneamente dal modello. Oggi ogni sistema serio offre una modalità intermedia: un elenco di comandi autorizzati che vengono eseguiti senza chiedere conferma e una richiesta di conferma per tutto il resto.

Il passaggio 1 è all'origine delle altre differenze. Il sistema inserisce inoltre il prompt di sistema in ogni richiesta, e Claude Code ti permette di controllare direttamente questo aspetto, perché uno stile di output modifica il prompt di sistema che invia e quindi cambia ogni risposta restituita. La conversazione cresce a ogni iterazione, mentre il modello dispone di una finestra di contesto fissa. Il sistema deve quindi decidere cosa eliminare, cosa riassumere e cosa scrivere in un file per leggerlo in seguito. Questa decisione spiega in gran parte perché due sistemi che usano lo stesso modello producano risultati di qualità diversa. Se questi cinque passaggi ti sembrano ancora astratti, il modo migliore per capirli è scrivere una volta un loop elementare, che è esattamente ciò che un percorso graduale per imparare a creare agenti AI ti porta a costruire nelle prime fasi.

Oggi la maggior parte dei sistemi collega anche strumenti esterni tramite MCP (model context protocol), uno standard per esporre uno strumento a qualsiasi sistema compatibile, così una sola integrazione può essere utilizzata da più sistemi. Eseguire server MCP su un VPS tratta questo aspetto. La ricerca sul web è solitamente il primo strumento che si aggiunge, e indirizzare l'agente verso la propria istanza SearXNG mantiene le query al di fuori di servizi di terze parti e chiarisce che ogni pagina letta successivamente dall'agente è un input non attendibile che entra nel loop.

Harness di agent e framework di agent

Questa domanda ricorre ogni volta che viene rilasciato un nuovo harness e le risposte non coincidono, in parte perché anche i vendor non concordano. Ecco la distinzione più solida.

Un framework è una libreria che si importa. Si scrive il loop, si decide quando chiamare il modello e si gestiscono autonomamente i risultati degli strumenti. LangChain è l'esempio più noto: fornisce blocchi di base che vengono assemblati nel codice per creare l'agent.

Un harness è un programma che si esegue. Il loop è già implementato, gli strumenti sono già disponibili e il modello delle autorizzazioni ha già una configurazione predefinita. Si ottiene un agent funzionante già dal primo comando e poi lo si configura.

In genere è il test dell'installazione a chiarire la distinzione. Se dopo l'installazione si scrive codice, è un framework. Se dopo l'installazione si inizia a interagire con il programma, è un harness.

Il confine è realmente oggetto di dibattito, e la prova più chiara arriva dalla documentazione di LangChain. Ad agosto 2026 descrive Deep Agents come un framework "opinionated, batteries-included" basato su LangGraph, mentre il repository langchain-ai/deepagents si definisce "the batteries-included agent harness". Entrambe le descrizioni sono corrette. Deep Agents è un Python SDK (software development kit) che si importa, quindi il test dell'installazione lo classifica come libreria, ma include un comportamento predefinito sufficiente perché venga utilizzato come un harness. Microsoft ha reso disponibile un harness e gli agent ospitati per la disponibilità generale ad agosto 2026. Questo dimostra che il termine è ormai una categoria di prodotto, non solo gergo tecnico.

Conviene quindi porre la domanda che consente di prevedere il carico di lavoro. Se si scrive il loop, se ne assume la responsabilità: retry, riduzione del contesto, richieste di autorizzazione e registrazione delle attività eseguite. Se il loop è già incluso nel prodotto, si eredita la soluzione di qualcun altro per tutti questi aspetti. Si parte molto più rapidamente, ma in seguito è più difficile modificare il comportamento.

Come differisce un harness da una finestra di chat

Una finestra di chat e un harness mostrano entrambi l'output del modello. La differenza riguarda il computer sul quale viene eseguito il lavoro. In una finestra di chat, qualsiasi codice eseguito dal modello viene eseguito nella sandbox del fornitore, sui file caricati dall'utente, e scompare al termine della sessione. Un harness esegue gli strumenti sul computer dal quale è stato avviato, con l'account dell'utente che lo ha avviato, sui file reali dell'utente e con le sue credenziali effettive disponibili nell'ambiente.

Questo riassume in due frasi sia il vantaggio sia il rischio. L'agente può finalmente eseguire il lavoro. Ma può anche eliminarlo.

Gli harness utilizzati concretamente

Questo elenco è aggiornato al 19 August 2026 appositamente. La categoria cambia ogni settimana e qualsiasi panoramica diventa rapidamente obsoleta.

• Claude Code e Codex sono harness del fornitore. Sono orientati innanzitutto al terminale, per impostazione predefinita sono collegati ai modelli del rispettivo fornitore 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'idea precisa: tutto è un plugin, quindi modelli, strumenti, sessioni, sandbox e interfaccia utente sono 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. Il 19 August 2026, sei giorni dopo la pubblicazione, contava circa 166,800 stelle su GitHub.
• Hermes, di Nous Research, è un agente autonomo generalista e non uno strumento per la programmazione. È stato rilasciato con licenza MIT nel February 2026 e conserva memorie e competenze in un database SQLite locale sul computer dell'utente. Eseguire Hermes in self-hosting su un VPS illustra la procedura.
• Omnigent è un meta-harness: controlla 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 i vantaggi di questo approccio.
• OneCLI è un harness con sandbox destinato ai team. Si basa su un gateway che inserisce credenziali reali nelle richieste in uscita, così l'agente vede soltanto chiavi segnaposto.

Tre di questi finiscono abbastanza spesso nella stessa lista ristretta da rendere utile la lettura di DeepSeek Harness, Claude Code e Omnigent a confronto per analizzare accoppiamento al modello, licenza, maturità e requisiti di esecuzione su un server.

La guida rapida dsh consiste in un singolo comando e la sua esecuzione una volta è il modo più rapido per capire che cos'è un harness. Sulla macchina deve essere installato Node.js.

npx @deepseek-ai/dsh web

Il comando avvia l'interfaccia web su http://127.0.0.1:3080. Leggere il README prima di farvi affidamento, perché dsh si descrive come un'anteprima per sviluppatori e dichiara esplicitamente che saranno introdotte modifiche incompatibili. Se il primo comando fallisce completamente o scarica una build inattesa, bloccare una versione esatta di dsh e svuotare la cache di npx consente di riprendere normalmente. Eseguire DeepSeek Harness su un VPS illustra l'installazione sul server, mentre perché quell'indirizzo inizia con 127.0.0.1 spiega il valore predefinito per il 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 sposti l'harness dal laptop a un server che noleggi, 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 agent

Per 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.service

loginctl enable-linger è il dettaglio che spesso viene trascurato. Senza questa impostazione, systemd arresta i servizi dell'utente non appena si chiude l'ultima sessione SSH (secure shell). L'agente termina quando esci e non viene visualizzato alcun errore. Eseguire dsh senza interfaccia sotto systemd contiene il file dell'unità. Quando una sessione è già attiva su quel server, una seconda sessione non comporta costi aggiuntivi. Inoltre, due sessioni di Claude Code sullo stesso sistema 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 si trova ora in un file di configurazione su quel server. Verifica chi può leggerla:

ls -l ~/.config

Qualsiasi processo eseguito con il tuo utente può leggere quel file. Tra questi rientrano l'agente e tutto ciò che l'agente decide di eseguire.

Può raggiungere le altre macchine. Un VPS nella stessa rete privata degli altri sistemi consente all'agente di raggiungerli. Questo è esattamente lo scopo, ma costituisce anche il raggio d'azione di un eventuale compromissione.

È raggiungibile da qualsiasi luogo. La maggior parte degli harness espone un'interfaccia web e, per un motivo preciso, la maggior parte la associa all'interfaccia di loopback. Verifica la configurazione:

ss -tlnp | grep 3080

127.0.0.1:3080 significa che può connettersi soltanto il server stesso. 0.0.0.0:3080 significa che può connettersi chiunque trovi l'indirizzo. Raggiungi un'interfaccia associata al loopback tramite un tunnel SSH invece di modificare l'indirizzo di ascolto:

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Quindi apri 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 su Internet.

Tutte queste proprietà costituiscono anche l’argomento principale per la sicurezza

Rileggete le quattro proprietà dal punto di vista di un attaccante.

Il sistema funziona senza supervisione, quindi nessuno controlla il momento in cui il modello interpreta male un percorso. Contiene le vostre chiavi, quindi un solo file di configurazione leggibile espone l’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 può raggiungere il server del database. È raggiungibile da qualsiasi luogo, quindi una web UI associata a 0.0.0.0 senza password equivale a una shell pubblica su Internet.

In tutti i casi, la correzione è semplice e sempre la stessa. Assegnate all’agente un account utente non privilegiato dedicato, invece di usare il vostro:

sudo adduser --disabled-password --gecos "" agent

Mantenete la web UI sull’interfaccia di loopback e accedetevi tramite SSH. Assegnate all’agente le credenziali con l’ambito più ristretto possibile, sufficienti per completare il lavoro; l’articolo mantenere i secret fuori dagli agenti AI approfondisce questo aspetto. Per tutto ciò che viene eseguito senza supervisione, una macchina usa e getta è preferibile a una configurata con attenzione: eseguire gli agenti di coding in una VM usa e getta e eseguire Claude Code in sicurezza su un VPS seguono entrambi questo approccio.

Ti serve un agent harness?

Se lavori su una domanda alla volta, una finestra di chat è sufficiente e un harness aggiunge soltanto un ciclo che devi supervisionare. Un harness diventa utile quando un'attività richiede molti passaggi su file reali oppure deve continuare a lavorare mentre dormi.

La maggior parte di questa categoria è recente. dsh nel proprio README indica lo stato di developer preview ad agosto 2026 e gli altri progetti evolvono abbastanza rapidamente da rendere necessario modificare il mese prossimo un file di configurazione scritto oggi. Per questo è opportuno mantenere la configurazione ridotta e riproducibile e annotare le modifiche apportate. La stessa prudenza è utile anche all'interno del ciclo, dove una skill che indirizza l'agent verso la modifica minima funzionante lascia al termine di un'esecuzione non supervisionata un diff che puoi leggere effettivamente. Inizia con un harness su un solo server, assegnagli un'attività e una chiave con autorizzazioni limitate, quindi amplia l'accesso soltanto dopo che quella prima attività è rimasta priva di problemi per una settimana. Gli agent 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 genera 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 che stabiliscono quali strumenti 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 è il segnale più chiaro che si tratta di due 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 la gestione dei file e della shell. Claude è la famiglia di modelli che il programma utilizza per impostazione predefinita. La stessa separazione vale per DeepSeek Harness (dsh), che è un programma Node da installare, e per i modelli DeepSeek, esposti tramite un'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 con cui si scrive codice. Il ciclo di esecuzione, i tentativi ripetuti e la gestione del contesto restano a carico dell'utente. Un harness è un programma che si esegue. Tutti questi componenti sono già inclusi con valori predefiniti da configurare, invece di doverli implementare. Nella pratica il confine non è netto: ad agosto 2026, il repository di LangChain definisce Deep Agents, un SDK importabile, un agent harness completo. Chiedersi se si dovrà scrivere personalmente il ciclo di esecuzione aiuta a scegliere il termine corretto per il proprio caso.

È necessario un VPS per eseguire un agent harness?

No. Tutti gli harness menzionati qui possono essere eseguiti su un laptop. Un server modifica 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 riprendere la stessa sessione da qualsiasi dispositivo. Ognuno di questi aspetti comporta anche considerazioni di sicurezza. È quindi consigliabile assegnare all'agente un account utente dedicato e mantenere qualsiasi interfaccia Web in ascolto solo su 127.0.0.1.

Posso usare un modello diverso all'interno dello stesso harness?

Di solito sì, ed è questa la caratteristica distintiva di un harness. Nella configurazione, la maggior parte di questi programmi accetta il nome del modello e un URL di base. Per usare un altro provider è quindi sufficiente modificare la configurazione, senza riscrivere il programma. Quando un harness non supporta facilmente questa modifica, un router locale come Claude Code Router può essere interposto tra l'harness e il provider per tradurre le richieste, con binding predefinito su 127.0.0.1:3456. Prestare attenzione a questo proxy, perché vede ogni prompt e conserva ogni chiave.