DeepSeek Harness (dsh) è un agent harness open source sviluppato da DeepSeek AI, pensato per costruire ed eseguire agenti basati su modelli linguistici. Il progetto si colloca tra l’LLM e l’ambiente sul quale l’agente deve operare: coordina il loop agentico, espone strumenti al modello, gestisce sessioni e autorizzazioni e permette di integrare provider, filesystem, shell e ulteriori capacità.
In questo momento lo strumento è indicato come Developer Preview. DeepSeek mette in evidenza che si tratta di un progetto che si evolve rapidamente e che sono previste modifiche spesso incompatibili tra una versione e l’altra. Quando si lavora su configurazioni, plugin o API interne bisogna quindi verificare sempre la versione di dsh a cui fa riferimento la documentazione.
Per uno sviluppatore, un elemento centrale è la separazione tra il runtime agentico e il modello che lo utilizza. Molti elementi che in altri prodotti rimangono integrati nell’applicazione possono essere sostituiti o ricomposti attraverso la configurazione.
Che cos’è DeepSeek Harness
Un LLM può generare testo o codice, mentre un agente deve anche interagire con un ambiente operativo: leggere un repository, richiamare strumenti, eseguire comandi, modificare file, conservare lo stato di una sessione e rispettare i vincoli stabiliti dall’utente o dall’infrastruttura.
DeepSeek Harness fornisce questo livello intermedio.
In termini architetturali, dsh mette a disposizione servizi per modelli, tool, agenti, sessioni, filesystem, shell, sandbox e altre funzionalità. Il modello rappresenta quindi una dipendenza del sistema agentico anziché coincidere con l’intera architettura.
DeepSeek Harness occupa quindi un livello diverso rispetto ad una semplice chat AI. Può essere utilizzato per sviluppare un coding agent, un agente di ricerca, un sistema che automatizza workflow tecnici oppure un runtime personalizzato nel quale modello, strumenti e policy vengono selezionati in funzione del progetto.
Come funziona l’architettura “everything is a plugin”
Alla base di Harness si trova Cordis, il framework attraverso il quale vengono composti i diversi elementi del runtime.
Il principio dichiarato dal progetto è “everything is a plugin”: model adapter, tool registry, session log e persino agent loop sono componenti inseriti nel runtime tramite plugin e possono essere sostituiti attraverso la composizione. Non esiste quindi un core privilegiato che debba essere modificato ogni volta che si vuole aggiungere una nuova capacità.
Cordis mette a disposizione un contesto condiviso sul quale i plugin pubblicano servizi e registrano effetti. Un componente che necessita di una funzionalità dichiara la relativa dipendenza; il consumer può così dipendere dal contratto del servizio anziché dalla specifica implementazione che lo fornisce.
La stessa logica compare in diverse componenti dell’architettura di dsh. Per una capability sufficientemente articolata è utile distinguere tra service definition, service provider e consumer.
Nel caso dell’esecuzione di comandi, per esempio, un componente può definire il contratto del servizio, un provider occuparsi concretamente dell’esecuzione e un consumer esporre quella capacità al modello come tool.
Un provider può quindi essere sostituito senza dover riscrivere i componenti che consumano quel servizio.
Standard, PTC, Minimal e Creator
Oltre ai profili esistono gli agent preset, che descrivono le capacità assegnate all’agente all’interno di una determinata composizione. Profilo e preset intervengono su livelli diversi: il primo definisce la struttura del runtime, il secondo le capacità disponibili per l’agente.
Tra le configurazioni disponibili si trovano Standard, PTC, Minimal e Creator.
Standard rappresenta la configurazione più completa per l’uso generale dell’agente e può combinare strumenti per modifica dei file, shell, ricerca, skill, pianificazione, subagenti e altre funzionalità disponibili nella composizione.
Con PTC, acronimo di Programmatic Tool Calling, parte dell’orchestrazione può essere espressa direttamente tramite codice. Invece di affidare l’intera sequenza operativa a una successione di tool call indipendenti, consente di coordinare più operazioni attraverso codice, rendendo più esplicita la logica con cui vengono utilizzati gli strumenti.
Minimal riduce intenzionalmente la superficie dell’agente. Nella composizione corrente mette a disposizione un ambiente essenziale basato su shell persistente e str_replace_editor.
Questo preset non deve però essere confuso con il profilo sdk-minimal. Quest’ultimo è ancora più essenziale: nella configurazione predefinita omette str_replace_editor, che può comunque essere aggiunto tramite patch insieme al relativo filesystem provider.
Poiché preset e profili possono cambiare durante la Developer Preview, quando si documentano capacità specifiche conviene indicare la versione di Harness utilizzata.
Creator, infine, è rivolto soprattutto alla configurazione e allo sviluppo delle estensioni del runtime.
Cosa si può fare con DeepSeek Harness
La modularità di Harness permette di utilizzare lo stesso runtime per agenti molto diversi. Il perimetro operativo dipende dal modello selezionato, dagli strumenti registrati e dalle policy applicate alla sessione.
Utilizzare agenti per il coding
Uno degli impieghi più comuni è la costruzione di coding agent.
Con gli strumenti appropriati, un agente può analizzare la struttura di un repository, cercare file e simboli, modificare codice, eseguire test e utilizzare il terminale. La Web UI permette inoltre di lavorare direttamente su un workspace locale.
Il comportamento può ricordare quello di strumenti come Claude Code o Codex, ma Harness opera a un livello differente dello stack.
A differenza di un coding assistant pronto all’uso, Harness permette di intervenire sul runtime: servizi disponibili, strumenti esposti al modello, modalità di esecuzione e gestione dello stato possono essere configurati separatamente.
Usare strumenti, shell e browser
I tool vengono registrati nel runtime e resi disponibili al modello attraverso schemi che ne descrivono input e comportamento.
La composizione può comprendere shell, filesystem, ricerca, MCP, subagenti e altre funzionalità. Il tool layer può inoltre esporre API aziendali, pipeline CI, database e altri servizi interni senza trasferirne la logica nell’agent loop.
Harness dispone inoltre di un sottosistema dedicato al browser use. I provider pubblicamente documentati includono integrazioni basate su Playwright MCP, Chrome DevTools MCP e Stagehand. Questi provider sono attualmente indicati come sperimentali e richiedono un’attivazione esplicita; non bisogna quindi considerare il controllo del browser come una funzionalità automaticamente presente in qualsiasi profilo.
Per i terminali persistenti il runtime prevede inoltre servizi specifici. I terminali persistenti servono, per esempio, quando un processo o una sessione CLI devono restare attivi tra operazioni successive.
Automatizzare attività tecniche ripetitive
Una volta collegati strumenti e workspace, Harness può gestire task composti da più operazioni: individuare file, applicare trasformazioni, eseguire verifiche e raccogliere il risultato finale.
In questi workflow, PTC permette di esprimere parte dell’orchestrazione tramite codice, anziché affidare ogni passaggio a una tool call indipendente.
Per workflow deterministici o semi-deterministici questo approccio può ridurre il numero di round trip tra modello e strumenti e rendere più leggibile la sequenza operativa.
Coordinare subagenti
La delega costituisce una funzionalità autonoma di Harness e non una funzione incorporata necessariamente nell’agent loop.
Il progetto comprende provider per agenti in-process, ACP, Claude Code, Codex e altri runtime Harness eseguiti tramite SDK. In particolare, subagent-codex utilizza il protocollo app-server ufficiale di Codex, mentre subagent-claude-code utilizza l’Agent SDK di Claude Code.
L’agente principale può così delegare parti del workflow a subagenti distinti.
Un subagente potrebbe, per esempio, esplorare un repository mentre un altro esegue una revisione indipendente del codice. La composizione determina quali backend di delega sono effettivamente disponibili.
Costruire agenti personalizzati
Harness offre maggiore libertà quando serve costruire un runtime agentico su misura.
L’architettura Cordis permette infatti di registrare servizi, aggiungere strumenti, intercettare eventi e sostituire provider. Poiché anche l’agent loop rientra nella composizione a plugin, il runtime espone un livello di controllo molto più profondo rispetto a un prodotto nel quale queste decisioni rimangono interne.
Un team può quindi adattare modello, strumenti, policy, persistenza e interfaccia allo specifico workload.
Utilizzare modelli e strumenti di fornitori diversi
DeepSeek Harness separa l’adapter del modello dal resto del runtime.
Cambiare provider LLM non richiede necessariamente di modificare tool layer, session management e le altre componenti del runtime. Per le integrazioni non previste direttamente dalla composizione è inoltre possibile implementare adapter specifici.
Nei benchmark, per esempio, si possono confrontare modelli differenti mantenendo invariata la restante infrastruttura agentica.
Bisogna comunque considerare le caratteristiche del provider. Tool calling, multimodalità, context window, streaming e formati delle API non sono necessariamente uniformi tra modelli diversi.
Come creare un primo agente
Costruire un agente con Harness significa anzitutto decidere quali servizi, strumenti e policy devono far parte della sua composizione.
Definire obiettivo e contesto operativo
Il perimetro dell’agente determina le funzionalità necessarie. Un coding agent che opera su una sola repository, per esempio, avrà probabilmente bisogno di filesystem, shell, ricerca e strumenti di test. Un agente destinato alla consultazione documentale può richiedere soprattutto retrieval, browser o servizi interni. Un’automazione che interviene su sistemi aziendali richiede invece policy più restrittive e un controllo accurato delle autorizzazioni.
Conviene quindi partire dalle funzionalità richieste dal task. Ogni funzionalità inutilizzata amplia la superficie operativa senza portare necessariamente un beneficio.
Scegliere il modello
Il modello viene collegato attraverso il relativo provider.
Poiché l’adapter LLM rimane separato dal resto del runtime, è possibile confrontare modelli differenti mantenendo più stabile la composizione dell’agente.
Nei benchmark questa separazione consente di distinguere meglio la qualità del modello dagli effetti prodotti da harness, tool e prompt operativo.
Aggiungere strumenti e skill
Gli strumenti model-facing e i servizi sottostanti appartengono a livelli differenti.
Un tool rappresenta normalmente un’azione che il modello può richiamare, mentre i servizi offrono funzionalità condivise ai plugin del runtime. Le skill permettono invece di rendere disponibili istruzioni operative e conoscenze contestuali senza trasformare necessariamente ciascuna competenza in una nuova azione.
In questo modo il tool layer rimane riservato alle azioni che il modello deve effettivamente richiamare.
Configurare sessione, memoria e storage
Le sessioni di Harness vengono rappresentate attraverso eventi persistenti dai quali possono essere derivate viste differenti.
La cronologia della singola sessione non deve però essere confusa con una memoria persistente cross-session.
La memoria cross-session può essere affidata, per esempio, a un servizio esterno collegato tramite MCP. In questo scenario Harness scopre gli strumenti messi a disposizione dal server e li registra nel runtime, mentre storage, embedding, identity e retrieval continuano a essere responsabilità del sistema di memoria esterno.
Harness può quindi utilizzare una memoria esterna senza incorporarne storage, embedding e retrieval nel proprio runtime.
Testare il comportamento dell’agente
La risposta finale rappresenta solo una parte del comportamento dell’agente.
Per comprenderne realmente il comportamento occorre osservare quali strumenti ha utilizzato, quali file ha consultato, quali comandi ha eseguito, quali autorizzazioni ha richiesto e in quale passaggio si è verificato un eventuale errore.
La Web UI espone una rappresentazione della Trajectory separata dalla semplice conversazione. Turn, step, tool call, risultati e operazioni intermedie possono così essere utilizzati per ricostruire ciò che l’agente ha fatto.
La Trajectory può essere usata come strumento di debugging del comportamento agentico, oltre che come cronologia delle operazioni.
DeepSeek Harness a confronto con Claude Code e Codex
DeepSeek Harness, Claude Code e Codex possono comparire nello stesso processo di valutazione tecnica, ma non occupano esattamente lo stesso livello dello stack.
Claude Code e Codex sono prodotti agentici progettati per fornire direttamente un ambiente operativo per lo sviluppo software. DeepSeek Harness espone invece in maniera più esplicita la composizione interna del runtime.
| Aspetto | DeepSeek Harness | Claude Code | Codex |
|---|---|---|---|
| approccio | harness open source componibile | coding agent dell’ecosistema Anthropic | coding agent dell’ecosistema OpenAI |
| runtime | composto attraverso plugin e profili | configurabile attraverso le estensioni previste dal prodotto | configurabile attraverso le estensioni previste dal prodotto |
| agent loop | parte della composizione e sostituibile tramite plugin | parte del prodotto | parte del prodotto |
| model layer | provider configurabili e adapter estendibili | centrato sull’ecosistema Claude | centrato sull’ecosistema OpenAI |
| tool layer | registry e plugin Cordis | tool nativi, MCP e integrazioni | tool e integrazioni Codex |
| sandbox e policy | componenti espliciti della composizione | integrate nel prodotto | integrate nel prodotto |
| scenario tipico | sviluppo e ricerca su runtime agentici personalizzati | coding agentico con Claude | coding agentico con Codex |
Se l’obiettivo è aprire un repository e iniziare rapidamente a delegare attività di sviluppo, un coding agent maturo può risultare più immediato.
Dsh è più adatto quando serve intervenire sul runtime stesso: tool registry, provider, capability e composizione rimangono direttamente accessibili.
I tre strumenti possono anche convivere nella stessa architettura. Harness può utilizzare Claude Code e Codex come backend per i propri subagenti, diventando in determinate architetture un livello di orchestrazione sopra altri sistemi agentici.
Dsh mette inoltre a disposizione bridge capaci di riutilizzare command hook già configurati per Claude Code e Codex. La compatibilità non è totale: i bridge supportano il subset documentato dei command hook, mentre handler di altro tipo possono essere ignorati. Per integrazioni specifiche che vanno oltre questo perimetro rimane preferibile sviluppare un plugin Cordis nativo.
Per approfondire l’utilizzo operativo dell’ambiente Anthropic, Data Masters propone anche un Corso su Claude Code dedicato all’impiego dello strumento nei workflow di sviluppo.
Sicurezza e limiti del progetto
Concedere a un LLM accesso a filesystem, shell, browser o sistemi esterni introduce rischi molto differenti rispetto a una normale conversazione.
La sandbox governa gli effetti sul filesystem prodotti dai processi che passano attraverso i relativi executor, mentre il sistema di approval determina quando sia necessario un intervento dell’utente per aumentare i privilegi.
L’enforcement non va comunque interpretato come una garanzia universale di isolamento. Le stesse specifiche distinguono tra enforcement completo e parziale e chiariscono che networking e process visibility appartengono a problemi separati rispetto ai SandboxMode.
La sicurezza dei server MCP va valutata separatamente da quella di Harness.
Un server MCP è infatti un processo o un servizio esterno con proprie dipendenze, credenziali e privilegi. Harness può collegarne gli strumenti al proprio runtime, ma la sicurezza del software upstream e delle risorse alle quali questo accede rimane un problema distinto.
Infine bisogna considerare la maturità del progetto. DeepSeek Harness è ancora in Developer Preview e le API sono pre-stabili. Per applicazioni sensibili conviene quindi bloccare le versioni utilizzate, verificare le release notes e testare gli aggiornamenti prima di introdurli negli ambienti operativi.
A chi è utile DeepSeek Harness
DeepSeek Harness si rivolge soprattutto a chi deve progettare o personalizzare l’infrastruttura di un coding agent.
È particolarmente interessante per sviluppatori di agenti, AI engineer, team che lavorano su infrastrutture agentiche e organizzazioni che vogliono integrare LLM con strumenti interni mantenendo un maggiore controllo sulla composizione del runtime.
È utile anche per confrontare modelli sullo stesso runtime o sviluppare capability riutilizzabili tra più configurazioni.
Rispetto a strumenti agentici più generalisti come OpenClaw, DeepSeek Harness si rivolge maggiormente a chi vuole intervenire sulla composizione del runtime, sui servizi disponibili e sulle policy operative. Per la sola assistenza alla programmazione, Claude Code, Codex o Cursor richiedono meno configurazione. Harness diventa invece interessante quando occorre controllare come l’agente opera, un po’ come abbiamo scritto per Pi Agent: quali servizi riceve, quali strumenti vede, dove vengono eseguiti i comandi, quali policy vengono applicate e quali componenti possono essere sostituiti.
AUTORE:Simone Truglia Apri profilo LinkedIn
Simone è un Ingegnere Informatico con specializzazione nei sistemi automatici e con una grande passione per la matematica, la programmazione e l’intelligenza artificiale. Ha lavorato con diverse aziende europee, aiutandole ad acquisire e ad estrarre il massimo valore dai principali dati a loro disposizione.
