Cos'è un harness per agenti AI?

Cos'è un harness per agenti

Un harness per agenti è il programma che esegue le operazioni intorno a un modello linguistico e lo trasforma in un agente. Contiene il ciclo che continua a chiamare 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 al suo interno può essere sostituito.

È importante ricordare quest'ultima frase. Un modello da solo risponde a una domanda e poi si dimentica di te. Un harness chiede al modello cosa fare, esegue il comando richiesto dal modello, gli restituisce il risultato e pone di nuovo la domanda. Questa ripetizione è ciò che si intende quando si parla di "agente". Se la terminologia 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 componenti vengono spesso confusi perché i fornitori li distribuiscono con lo stesso nome commerciale.

dsh e DeepSeek sono prodotti diversi. DeepSeek Harness, pubblicato all’indirizzo github.com/deepseek-ai/deepseek-harness il 13 agosto 2026 con licenza MIT, è un programma Node che si installa su una macchina. I modelli DeepSeek sono pesi serviti tramite un’API (application programming interface). Se si configura dsh per usare un modello di un altro fornitore, continua a funzionare, perché l’harness richiede soltanto un componente che accetti messaggi e restituisca chiamate agli strumenti.

Claude Code e Claude costituiscono la stessa coppia di componenti. Claude Code è un harness: un programma da 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 seguono 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 directory home, è un harness. Se invece è una stringa contenuta in quel file di configurazione, come deepseek-chat, è il modello.

Cosa fa effettivamente il loop

Un ciclo del harness funziona in questo modo. Leggete con attenzione, perché quasi tutte le differenze tra i harness dipendono da questi cinque passaggi.

1. Il harness 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 di chiamare uno di quegli strumenti.
3. Il harness verifica la richiesta rispetto alle proprie regole di autorizzazione ed esegue lo strumento oppure si ferma per chiedere conferma.
4. Il harness esegue lo strumento, acquisisce l'output e il codice di uscita e tronca l'output se è molto lungo.
5. Il harness aggiunge il risultato alla conversazione e torna al passaggio 1.

Nell'uso quotidiano, il passaggio 3 è quello in cui i harness differiscono maggiormente. Un harness che chiede conferma prima di ogni comando è sicuro, ma poco pratico. Un harness che non chiede mai conferma prima o poi eseguirà un comando distruttivo su un percorso interpretato in modo errato dal modello. Oggi ogni harness serio offre un'impostazione intermedia: un allowlist di comandi eseguiti senza chiedere conferma e una richiesta di autorizzazione per tutto il resto.

Il resto delle differenze riguarda il passaggio 1. La conversazione cresce a ogni ciclo, mentre il modello dispone di una finestra di contesto fissa. Il harness 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 harness che usano lo stesso modello producono risultati di qualità diversa.

Oggi la maggior parte dei harness collega strumenti esterni tramite MCP (model context protocol), un metodo standard per esporre uno strumento a qualsiasi harness che supporti il protocollo. In questo modo una singola integrazione può essere utilizzata da più harness. Eseguire server MCP su un VPS tratta questo aspetto.

Harness per agent e framework per agent

Questa domanda ricorre ogni volta che viene rilasciato un nuovo harness e le risposte non concordano, in parte perché anche i vendor usano definizioni diverse. Di seguito trovi la distinzione più solida.

Un framework è una libreria che importi. Scrivi tu il ciclo, decidi quando chiamare il modello e gestisci direttamente i risultati degli strumenti. LangChain è l'esempio più noto: fornisce blocchi di base che assembli nel codice per costruire l'agent.

Un harness è un programma che esegui. Il ciclo è già implementato, gli strumenti sono già disponibili e il modello delle autorizzazioni ha già una configurazione predefinita. Ottieni un agent funzionante già dal primo comando e lo configuri successivamente.

Di solito è il test dell'installazione a chiarire la distinzione. Se lo installi e poi scrivi codice, è un framework. Se lo installi e poi interagisci con esso, è un harness.

Il confine è realmente oggetto di discussione, e la documentazione di LangChain fornisce l'evidenza più chiara. 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 importi; secondo il test dell'installazione è quindi una libreria. Tuttavia include un comportamento predefinito sufficiente perché molti lo utilizzino come un harness. Microsoft ha rilasciato un harness e gli hosted agents per la disponibilità generale ad agosto 2026. Questo dimostra che il termine è ormai una categoria di prodotto, non semplice gergo.

Conviene quindi porsi la domanda che meglio anticipa il carico di lavoro. Se scrivi tu il ciclo, ne sei responsabile: devi gestire retry, riduzione del contesto, richieste di autorizzazione e registrazione delle operazioni eseguite. Se il ciclo è già incluso nel prodotto, erediti le scelte di qualcun altro su tutti questi aspetti. In questo modo inizi molto più rapidamente, ma in seguito è più difficile modificare il comportamento.

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 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'utente che lo ha avviato, sui file reali dell'utente e con le credenziali effettive disponibili nel relativo ambiente.

Questi due aspetti riassumono interamente sia il vantaggio sia il rischio. L'agente può finalmente eseguire il lavoro. L'agente può anche eliminare quel lavoro.

Gli harness utilizzati realmente

Questo elenco è aggiornato al 19 agosto 2026 intenzionalmente. La categoria cambia ogni settimana e qualsiasi riepilogo diventa rapidamente obsoleto.

• Claude Code e Codex sono harness dei rispettivi vendor. Sono progettati innanzitutto per il terminale, per impostazione predefinita sono collegati ai modelli del rispettivo vendor e offrono la gestione dei permessi più completa. Confronto tra Claude Code, Cursor, Codex e Copilot li analizza in dettaglio.
• DeepSeek Harness (dsh) è rilasciato con licenza MIT e si basa su un principio: tutto è un plugin. Modelli, strumenti, sessioni, sandbox e interfaccia utente sono quindi componenti sostituibili. Il 19 agosto 2026 contava circa 166,800 stelle su GitHub, sei giorni dopo la pubblicazione.
• Hermes, sviluppato da Nous Research, è un agente autonomo generalista, non uno strumento per la programmazione. È stato rilasciato con licenza MIT a febbraio 2026 e archivia memorie e competenze in un database SQLite locale sul proprio computer. Eseguire Hermes in self-hosting su un VPS illustra la procedura.
• Omnigent è un meta-harness: coordina altri harness, inclusi 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.

La guida rapida dsh consiste in un unico comando. Eseguirlo una volta è il modo più rapido per capire che cos'è un harness. Sul computer deve essere installato Node.js.

npx @deepseek-ai/dsh web

Il comando avvia l'interfaccia web su http://127.0.0.1:3080. Leggi il README prima di usarlo in un ambiente operativo, perché dsh si definisce un'anteprima per sviluppatori e dichiara esplicitamente che sono previste modifiche incompatibili. Eseguire DeepSeek Harness su un VPS descrive l'installazione sul server, mentre perché quell'indirizzo inizia con 127.0.0.1 spiega l'impostazione predefinita sull'interfaccia loopback.

I router si trovano sopra l’harness

Un model router è un proxy locale tra l’harness e l’API del provider. Claude Code Router è l’esempio più comune: si mette in ascolto su 127.0.0.1:3456 per impostazione predefinita, accetta le richieste che Claude Code avrebbe inviato al proprio vendor e le inoltra al provider configurato. L’harness non rileva alcun cambiamento.

I router esistono perché il modello è sostituibile, quindi dimostrano bene il punto principale di questo articolo. Concentrano però anche il rischio, 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 del modello è lo stesso problema osservato 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 non si interrompe durante il tragitto né quando si scarica la 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 qualsiasi attività che deve riprendere dopo un riavvio, un servizio utente è più affidabile di una sessione terminale:

loginctl enable-linger $USER
systemctl --user status my-agent.service

loginctl enable-linger è l'aspetto che spesso viene trascurato. Senza questa impostazione, systemd arresta i servizi del tuo utente appena si chiude l'ultima sessione SSH (secure shell), quindi l'agent si interrompe quando esegui il logout e non viene visualizzato alcun errore. Esecuzione headless di dsh con systemd contiene il file dell'unità. Quando una sessione è già attiva su quel server, avviarne una seconda non comporta costi aggiuntivi; inoltre, due sessioni di Claude Code sullo stesso host possono scambiarsi 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 sul server. Verifica chi può leggerlo:

ls -l ~/.config

Qualsiasi processo eseguito con il tuo utente può leggere quel file, inclusi l'agent e qualsiasi comando scelga di eseguire.

Può raggiungere le altre macchine. Un VPS sulla stessa rete privata degli altri host consente all'agent di raggiungerli. Questo è esattamente lo scopo, ma definisce anche l'ampiezza dell'impatto in caso di compromissione.

È 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 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. Per raggiungere un'interfaccia loopback usa un tunnel SSH invece di modificare l'indirizzo di ascolto:

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

Poi 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 a Internet.

Ognuna di queste proprietà rappresenta anche un problema di sicurezza

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

Il sistema opera senza supervisione, quindi nessuno controlla il momento in cui il modello interpreta erroneamente un percorso. Contiene le tue chiavi, quindi un solo file di configurazione leggibile espone l’intero account del tuo provider. Può raggiungere gli altri computer, quindi una prompt injection, cioè istruzioni nascoste in una pagina web o in un file letto dall’agente, crea un percorso verso il server del database. È raggiungibile da qualsiasi posizione, quindi un’interfaccia web in ascolto su 0.0.0.0 senza password equivale a una shell esposta su Internet.

In ogni caso, la soluzione è semplice e sempre la stessa. Assegna all’agente un proprio account utente senza privilegi, invece di usare il tuo:

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

Mantieni l’interfaccia web sull’interfaccia di loopback e accedi tramite SSH. Assegna all’agente le credenziali con l’ambito più ristretto possibile, sufficienti per completare il lavoro; mantenere i secret fuori dagli agenti AI spiega come procedere correttamente. Per tutto ciò che viene eseguito senza supervisione, una macchina usa e getta è preferibile a una macchina configurata con attenzione: eseguire agenti di coding in una VM usa e getta e eseguire Claude Code in sicurezza su un VPS seguono entrambe questo approccio.

Ti serve un harness per agent?

Se lavori su una domanda alla volta, è sufficiente una finestra di chat 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 avanzano abbastanza rapidamente da rendere necessario modificare il mese prossimo un file di configurazione scritto oggi. Per questo conviene 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 necessaria lascia al termine di un'esecuzione non supervisionata un diff effettivamente leggibile. 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 sono un punto di partenza ragionevole per scegliere il primo.

FAQ

Che cos'è un agent harness in termini semplici?

È il programma che sta attorno al 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 dimostra in modo chiaro che sono componenti separati.

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 separazione vale per DeepSeek Harness (dsh), che è un programma Node da installare, e per i modelli DeepSeek, che vengono forniti 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 contro la quale si scrive codice. In questo caso, il ciclo di esecuzione, i tentativi ripetuti e la gestione del contesto sono a carico dell'utente. Un harness è un programma che si esegue. Queste funzioni sono quindi già disponibili con valori predefiniti da configurare, invece di doverle implementare. Nella pratica, la distinzione non è netta: LangChain's Deep Agents è un SDK importabile che il relativo repository definisce un agent harness completo, ad agosto 2026. Chiedersi se si dovrà scrivere personalmente il ciclo di esecuzione aiuta a scegliere il termine corretto per il proprio caso.

Serve un VPS per eseguire un agent harness?

No. Tutti gli harness menzionati qui funzionano su un laptop. Un server cambia quattro aspetti: l'agent 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 consigliabile assegnare all'agent un account utente dedicato e mantenere qualsiasi interfaccia web in ascolto su 127.0.0.1.

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

Di solito sì, ed è proprio questa la caratteristica principale di un harness. Nella maggior parte dei casi, la configurazione 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 pone limitazioni, un router locale come Claude Code Router può essere eseguito tra l'harness e il provider e tradurre le richieste, rimanendo in ascolto su 127.0.0.1:3456 per impostazione predefinita. Prestare attenzione a questo proxy, perché vede ogni prompt e conserva ogni chiave.