Tutorial DeepSeek Harness: primi passi con l’agente AI open source più popolare

Perché DeepSeek Harness è popolare?

DeepSeek Harness ha attirato attenzione molto rapidamente, superando 160.000 stelle su GitHub e 18.000 fork al momento della pubblicazione di questo articolo.

Un motivo importante è che gli sviluppatori lo trovano capace di ottenere ottimi risultati con modelli diversi, non solo con DeepSeek. Su Reddit si legge spesso di utilizzi riusciti con modelli come Qwen3.8-27b, soprattutto per il coding e per compiti agentici più lunghi.

Un altro motivo è la sua autonomia e flessibilità. Gli utenti riportano che Harness riesce a portare avanti task multi-step, recuperare dagli errori, gestire contesti lunghi e continuare senza richiedere interventi costanti. Il design a plugin rende anche facile sostituire i modelli, aggiungere strumenti e personalizzare il workflow dell’agente invece di restare bloccati in una configurazione fissa.

Se stai confrontando Harness con gli strumenti a cui fa concorrenza, la nostra guida alle alternative a Claude Code confronta sette delle principali opzioni fianco a fianco.

Funzionalità principali di DeepSeek Harness

Ecco alcune delle funzionalità principali:

• Architettura basata su plugin: gran parte dei componenti dell’agente può essere estesa o sostituita tramite plugin, semplificando la personalizzazione dell’ambiente.

• Web UI locale: eseguendo dsh web ottieni un’interfaccia browser da cui gestire modelli, sessioni, workspace, impostazioni e agenti.

• SDK Python: il deepseek-harness-sdk permette di eseguire agenti Harness direttamente da applicazioni Python, script, test e workflow di automazione.

• Più provider di modelli: non sei limitato ai modelli DeepSeek. Puoi usare provider come OpenAI e Anthropic o collegare un endpoint compatibile tuo.

• Tool calling: gli agenti possono chiamare strumenti per eseguire azioni invece di generare solo testo.

• Strumenti per file e terminale: Harness include strumenti per leggere, cercare e modificare file, oltre a Bash su Linux e macOS e PowerShell su Windows.

• Ricerca web integrata: il provider di ricerca web di DeepSeek è incluso nella configurazione predefinita e usa la stessa chiave API DeepSeek del modello.

• Code Mode: Harness può esporre strumenti tramite una modalità di esecuzione basata su codice, dando all’agente più controllo su come combinare ed eseguire le chiamate agli strumenti.

• Trajectory: la vista Trajectory ti consente di ispezionare passo dopo passo cosa sta facendo l’agente, comprese risposte del modello, chiamate agli strumenti, attività annidate, tempi e uso di token.

• Preset di agenti: puoi creare diverse configurazioni di agenti con i loro strumenti e prompt, quindi riutilizzarle in sessioni diverse.

• Statistiche di sessione: Harness traccia informazioni utili come turni, step, tempo del modello, tempo degli strumenti, time to first token e tempo di decodifica.

• Sottoagenti: un agente principale può delegare parti di un task ad agenti figli, utile per workflow più complessi.

• Plugin della community: plugin di terze parti possono aggiungere capacità extra non disponibili nel modello base. In questa guida abbiamo usato ModLens per aggiungere la visione.

• Licenza MIT: DeepSeek Harness è open source e rilasciato sotto la permissiva licenza MIT.

Il vantaggio principale è che non sei legato a un solo modello, a un solo set di strumenti o a un solo tipo di agente. Puoi iniziare con la configurazione predefinita e aggiungere o sostituire gradualmente componenti mentre sperimenti workflow diversi.

Come si configura DeepSeek Harness?

Iniziamo installando DeepSeek Harness e predisponendo tutto ciò che ci servirà per il resto della guida. Installeremo Node.js, DeepSeek Harness e pnpm, quindi aggiungeremo le nostre chiavi API.

Installa Node.js

DeepSeek Harness gira su Node.js. Dato che più avanti useremo anche ModLens per la visione, ti consiglio di usare Node.js 22.19 o successivo.

Se usi Ubuntu o Debian, puoi installare Node.js con:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

Una volta installato, verifica che Node.js e npm funzionino entrambi:

node --version
npm --version

Nel mio setup ho ottenuto:

v24.19.0
11.17.0

Non serve avere esattamente le stesse versioni. Finché usi una versione di Node.js sufficientemente recente, sei a posto.

Installa DeepSeek Harness

Ora installiamo DeepSeek Harness vero e proprio.

Il quick start ufficiale usa npx, ma preferisco installarlo globalmente così possiamo usare semplicemente il comando dsh per tutta la guida.

Esegui:

npm install -g @deepseek-ai/dsh

Poi verifica che l’installazione sia andata a buon fine:

dsh --version

Quando ho testato questa guida, stavo usando:

0.1.0-rc.7

Installa pnpm

Ci serve anche pnpm. DeepSeek Harness lo usa quando aggiungiamo o rimuoviamo plugin. Installalo globalmente:

npm install -g pnpm

Configura le chiavi API

Per questo tutorial servono solo due chiavi API:

• Chiave API DeepSeek: usata per il modello DeepSeek e per la sua ricerca web integrata.
• Chiave API Gemini: usata da ModLens per la comprensione delle immagini.

Imposteremo subito la chiave DeepSeek, dato che è tutto ciò che serve per coding e ricerca web, e aggiungeremo la chiave Gemini più avanti quando abiliteremo la visione con ModLens.

Per DeepSeek, devi creare un account DeepSeek, generare una chiave API e aggiungere credito al tuo account. Per questa guida, consiglio di aggiungere almeno 2 $ di credito: dovrebbero bastare per testare gli esempi senza dover versare molto in anticipo.

Una volta ottenuta la chiave API, aggiungila al tuo ambiente.

Su Linux o macOS:

export DEEPSEEK_API_KEY="your_deepseek_api_key"

Su Windows PowerShell:

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

Un aspetto comodo di questa configurazione è che non serve una chiave API separata per la ricerca web. DeepSeek Harness include già il provider di ricerca web di DeepSeek e usa la stessa DEEPSEEK_API_KEY.

Puoi anche aggiungere la chiave API DeepSeek in seguito da Settings → Models all’interno della Web UI.

Come avvio DeepSeek Harness?

Ora che è tutto configurato, possiamo avviare DeepSeek Harness e aprire la Web UI. Esegui semplicemente dsh web, che avvia l’interfaccia nel browser sulla porta 3080 per impostazione predefinita.

Puoi vedere la UI aprendo l’indirizzo http://127.0.0.1:3080 nel browser.

Da lì, crea un nuovo workspace o selezionane uno esistente, avvia una nuova sessione e scegli il modello DeepSeek che vuoi utilizzare.

Una volta pronta la sessione, possiamo iniziare a testare supporto al coding, ricerca web, visione e modelli di terze parti.

Come usare DeepSeek Harness per il coding

Ora che DeepSeek Harness è in esecuzione, possiamo testare le principali capacità della nostra configurazione. Iniziamo con un semplice task di coding:

Create a simple Python calculator with a command-line interface.

DeepSeek Harness può lavorare direttamente con file e terminale, quindi può creare il file Python, modificare il codice ed eseguire comandi all’interno del workspace.

Al termine del task, dovresti vedere il file generato e le istruzioni per eseguirlo.

Per ottenere di più dai modelli DeepSeek che alimentano Harness, il nostro tutorial sull’API DeepSeek V4 illustra le modalità di reasoning V4 e i parametri API in Python.

Come usare DeepSeek Harness per la ricerca web

Ora testiamo la ricerca web. Non serve alcuna configurazione aggiuntiva perché DeepSeek Harness include già il provider di ricerca web di DeepSeek.

Prova un prompt come:

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

L’agente dovrebbe cercare sul web e restituire un riepilogo con le fonti.

Mentre lavora, apri la scheda Trajectory. Dovresti vedere chiamate a strumenti come SUBTOOL: web_search.

Questo mostra che l’agente sta effettivamente usando lo strumento di ricerca web invece di fare affidamento solo sulla conoscenza esistente del modello. Per impostazione predefinita, la ricerca è gestita dal provider deepseek-official e usa la stessa DEEPSEEK_API_KEY che abbiamo configurato prima.

Come usare DeepSeek per task di visione

Il modello di chat di DeepSeek in Harness è solo testuale, quindi non può comprendere immagini caricate da solo. Per aggiungere il supporto alla visione useremo ModLens, che fa da ponte tra DeepSeek e un modello con capacità visive.

Installa il plugin ModLens

Quando carichi un’immagine, ModLens la elabora con un modello di visione, estrae le informazioni visive utili e le restituisce a DeepSeek, che può così ragionare sull’immagine.

Inizia installando il plugin ModLens nel profilo web:

dsh plugin --profile web add @liustack/modlens@3.20.0

Una volta installato, ModLens aggiunge lo strumento modlens_read_image e crea opzioni di modello come ``DeepSeek-V4-Flash (modlens vision)`.

Queste varianti di modello ti permettono di caricare immagini usando comunque DeepSeek come modello di reasoning principale.

Registra il backend di visione

Per questa guida useremo la Gemini API come backend di visione, quindi ci serve una chiave API Gemini. Puoi iniziare con il Free Tier della Gemini API. Google fornisce accesso gratuito ai modelli Gemini supportati entro i limiti del Free Tier, quindi non devi aggiungere i dati di pagamento solo per testare la configurazione di visione in questa guida.

Una volta ottenuta la chiave, aggiungila al tuo ambiente.

Su Linux o macOS:

export GEMINI_API_KEY="your_gemini_api_key"

Su Windows PowerShell:

$env:GEMINI_API_KEY="your_gemini_api_key"

Installa e configura la CLI di ModLens

Poi installa la CLI di ModLens:

npm install -g @liustack/modlens

Quindi configurala usando la chiave API Gemini.

Su Linux o macOS:

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

Su Windows PowerShell:

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

Infine, verifica che tutto funzioni:

modlens doctor

Dovresti vedere gemini-api selezionato come provider e segnalato come pronto.

Test di DeepSeek Harness con ModLens

Ora testiamo la comprensione delle immagini.

Dal selettore dei modelli, scegli uno dei modelli con (modlens vision) nel nome, ad esempio DeepSeek-V4-Flash (modlens vision).

Incolla o carica un’immagine, quindi chiedi: Explain what is shown in this image.

Come mostrato nell’esempio sopra, DeepSeek ora può descrivere e ragionare sull’immagine caricata.

Dietro le quinte, ModLens invia l’immagine a Gemini per la comprensione visiva e passa le informazioni estratte a DeepSeek. In questo modo possiamo mantenere DeepSeek come modello di reasoning principale usando Gemini solo per la parte di visione.

Come usare DeepSeek Harness con un modello di terze parti

Infine, proviamo un modello di un altro provider. Apri Settings → Models.

Da qui puoi aggiungere provider come OpenAI e Anthropic, o configurare un altro provider supportato usando le tue credenziali API.

Puoi anche aggiungere un provider personalizzato se vuoi collegare un modello self-hosted o un altro endpoint compatibile. Questo ti consente di configurare dettagli come ID del provider, base URL, tipo di API, credenziali e nome del modello.

Una volta aggiunto il provider, torna alla tua sessione e seleziona il nuovo modello dal selettore dei modelli.

Ad esempio, prova il seguente prompt:

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

Nell’esempio sopra, un modello di terze parti Kimi-K3 completa il task di coding, mostrando che DeepSeek Harness non è limitato ai modelli DeepSeek.

Puoi passare tra i modelli configurati direttamente dal selettore: le modifiche si applicano alla richiesta successiva senza riavviare il server di Harness.

Considerazioni finali

Dopo aver testato DeepSeek Harness, per i miei workflow preferisco ancora Pi Coding Agent e OpenCode.

DeepSeek Harness mi ricorda molto Pi Coding Agent perché entrambi sono costruiti attorno a un ecosistema di plugin. Puoi installare diverse estensioni e dare al tuo agente di coding capacità extra a seconda di ciò di cui hai bisogno. Questa flessibilità è utile, ma nei miei test non ho davvero capito il clamore intorno a DeepSeek Harness. L’esperienza complessiva mi è sembrata piuttosto normale rispetto ad altri agenti di coding che ho già usato.

Mi sono anche imbattuto in alcuni problemi frustranti. A volte l’agente si fermava a metà di un task senza spiegare il perché, e dovevo digitare continue per farlo ripartire. Installare e configurare i plugin è stato un altro punto dolente. Può essere piuttosto difficile a meno che tu non sappia già esattamente cosa stai facendo, e la documentazione al momento non aiuta molto.

Detto questo, DeepSeek Harness è ancora un prodotto molto nuovo, quindi questi problemi sono comprensibili. Mi aspetto che esperienza, documentazione ed ecosistema di plugin migliorino parecchio col tempo. È anche possibile che DeepSeek stia costruendo un harness che funziona particolarmente bene con i propri modelli, e questo potrebbe spiegare in parte l’entusiasmo.