Tutorial DeepSeek Harness: come iniziare con l'agente AI open source più popolare

Perché DeepSeek Harness è popolare?

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

Un motivo importante è che gli sviluppatori stanno ottenendo ottimi risultati con modelli diversi, non solo con DeepSeek. Su Reddit, gli utenti segnalano spesso un uso riuscito con modelli come Qwen3.8-27b, soprattutto per il coding e per compiti agentici più lunghi.

Un'altra ragione è la sua autonomia e flessibilità. Gli utenti riferiscono che Harness riesce a portare avanti attività multi-step, a riprendersi dagli errori, a gestire contesti lunghi e a proseguire senza bisogno di un intervento costante. Il design basato su plugin rende anche facile sostituire i modelli, aggiungere strumenti e personalizzare il workflow dell'agente invece di essere bloccati in una configurazione fissa.

Se stai confrontando Harness con gli strumenti che intende rivaleggiare, la nostra guida alle alternative a Claude Code confronta sette delle principali opzioni affiancate.

Funzionalità principali di DeepSeek Harness

Ecco alcune delle funzioni principali:

• Architettura basata su plugin: la maggior parte delle parti dell'agente può essere estesa o sostituita tramite plugin, il che semplifica la personalizzazione della configurazione.

• Web UI locale: eseguire dsh web fornisce un'interfaccia nel browser in cui gestire modelli, sessioni, workspace, impostazioni e agent.

• SDK Python: il deepseek-harness-sdk ti consente di eseguire agent 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 agent 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 combina ed esegue le chiamate agli strumenti.

• Trajectory: la vista Trajectory ti permette di ispezionare cosa fa l'agente passo dopo passo, incluse risposte del modello, chiamate agli strumenti, attività annidata degli strumenti, tempi e uso dei token.

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

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

• Sotto-agent: un agente principale può delegare parti di un compito ad agent figli, utile per workflow più complessi.

• Plugin della community: plugin di terze parti possono aggiungere funzionalità extra non disponibili nel modello base. In questa guida abbiamo usato ModLens per aggiungere il supporto alla 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 partire dalla configurazione predefinita e aggiungere o sostituire gradualmente i 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, poi aggiungeremo le nostre chiavi API.

Installa Node.js

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

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 sia Node.js che npm funzionino:

node --version
npm --version

Sulla mia macchina ho ottenuto:

v24.19.0
11.17.0

Non è necessario avere esattamente le stesse versioni. Finché esegui una versione abbastanza recente di Node.js, 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

Al momento in cui 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 ci 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 ora la chiave DeepSeek, dato che è tutto ciò che serve per coding e ricerca web, e aggiungeremo la chiave Gemini più avanti quando aggiungeremo la visione con ModLens.

Per DeepSeek, dovrai creare un account DeepSeek, generare una chiave API e aggiungere credito al tuo account. Per questa guida, consiglio di aggiungere almeno 2 $ di credito, più che sufficienti per testare gli esempi senza versare subito una somma elevata.

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 interessante di questa configurazione è che non serve una API separata per la ricerca web. DeepSeek Harness include già il provider di ricerca web di DeepSeek e usa lo stesso DEEPSEEK_API_KEY.

Puoi anche aggiungere la tua chiave API DeepSeek in un secondo momento 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 nel browser l'indirizzo http://127.0.0.1:3080.

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

Una volta pronta la sessione, possiamo iniziare a testare le funzioni di coding, ricerca web, visione e il supporto ai 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 i file e il terminale, quindi può creare il file Python, modificare il codice ed eseguire comandi all'interno del workspace.

Al termine dell'attività, dovresti vedere il file generato e le istruzioni per eseguirlo.

Per sfruttare al meglio i modelli DeepSeek che alimentano Harness, il nostro tutorial sull'API DeepSeek V4 illustra le modalità di ragionamento V4 e i parametri API in Python.

Come usare DeepSeek Harness per la ricerca web

Ora testiamo la ricerca web. Non è necessaria 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 agli strumenti come SUBTOOL: web_search.

Questo mostra che l'agente sta effettivamente usando lo strumento di ricerca web invece di affidarsi solo alle conoscenze pregresse del modello. Per impostazione predefinita, questa ricerca è gestita dal provider deepseek-official e usa lo stesso DEEPSEEK_API_KEY che abbiamo configurato in precedenza. 

Come usare DeepSeek per attività di visione

Il modello di chat di DeepSeek in Harness è solo testuale, quindi non può comprendere da solo le immagini caricate. Per aggiungere il supporto alla visione useremo ModLens, che funge da ponte tra DeepSeek e un modello in grado di elaborare immagini.

Installa il plugin ModLens

Quando carichi un'immagine, ModLens la elabora con un modello di visione, estrae le informazioni visive utili e le rimanda a DeepSeek così che possa 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 continuando a usare DeepSeek come modello principale di ragionamento.

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 metodi di pagamento solo per testare l'impostazione della 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 configúrala 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 indicato come pronto.

Test di DeepSeek Harness con ModLens

Ora testiamo la comprensione delle immagini.

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

Incolla o carica un'immagine, poi 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 rimanda a DeepSeek le informazioni estratte. Questo significa che possiamo mantenere DeepSeek come modello principale di ragionamento 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 permette di configurare dettagli come l'ID del provider, la base URL, il tipo di API, le credenziali e il 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.

L'esempio sopra usa un modello Kimi-K3 di terze parti per completare il task di coding, mostrando che DeepSeek Harness non è limitato ai modelli DeepSeek.

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

Considerazioni finali

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

DeepSeek Harness mi ricorda molto Pi Coding Agent perché entrambi si basano su un ecosistema di plugin. Puoi installare estensioni diverse e dare al tuo assistente di coding capacità extra a seconda delle esigenze. Questa flessibilità è utile, ma nei miei test non capisco ancora davvero l'hype intorno a DeepSeek Harness. L'esperienza complessiva mi è sembrata piuttosto normale rispetto ad altri agent di coding che ho già usato.

Ho anche incontrato alcuni problemi frustranti. A volte l'agente si fermava a metà di un'attività senza spiegare perché, e ho dovuto 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 fare, 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 l'esperienza, la documentazione e l'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 essere in parte il motivo dell'entusiasmo.