Agent nativo (ds4-agent): conversazioni persistenti e bassa latenza

Oltre al CLI classico (ds4) e al server API (ds4-server), ds4 offre un agente nativo chiamato ds4-agent. Non è un semplice client: è un’esperienza integrata in cui l’inferenza è controllata direttamente dall’agente, senza socket HTTP, senza conversioni di formato, con la sessione che è il file su disco. Il risultato è una latenza minima e la possibilità di passare da una conversazione all’altra in modo istantaneo.

Perché un agente nativo?

La maggior parte degli agenti di coding (es. Codex CLI, Aider) parlano con un server API via HTTP. Ogni interazione richiede:

• Serializzazione/deserializzazione JSON
• Gestione dei tool call in formati diversi (OpenAI, Anthropic, ecc.)
• Overhead di rete
• Rischio di mismatch della KV cache (se il prompt renderizzato cambia anche di un byte)

ds4-agent elimina tutto questo: l’inferenza avviene nello stesso processo che gestisce l’interfaccia utente. Non c’è rete, non c’è conversione di formato, e la sessione è rappresentata direttamente dal file di cache KV su disco.

Vantaggi concreti:

• Latenza ridottissima: la generazione inizia non appena il modello ha finito il prefill.
• Tool calling nativo: il modello genera DSML, l’agente lo interpreta senza trasformazioni.
• Sessioni istantanee: puoi salvare una conversazione, passare a un’altra con /switch, e tornare indietro senza alcuna ricomputazione.
• Progress bar durante il prefill: sai esattamente quanto manca.

Stato del progetto (alpha)

ds4-agent è stato aggiunto dopo il resto del progetto ed è attualmente alpha quality. Funziona, ma ci sono ancora bordi da limare e feature mancanti. È comunque già usabile per attività di coding e chat quotidiane.

Avviare ds4-agent

La compilazione di ds4 produce già il binario ds4-agent. Non serve alcuna configurazione aggiuntiva.

./ds4-agent

Se sei partito da una directory diversa dal root del progetto (ad esempio se hai installato il binario in ~/bin/), devi passare --chdir per far sì che i file .metal vengano trovati:

./ds4-agent --chdir /percorso/della/clonazione/ds4

All’avvio, l’agente carica il modello predefinito (./ds4flash.gguf). Se vuoi un modello diverso, usa -m:

./ds4-agent -m gguf/DeepSeek-V4-Flash-Q4K...-imatrix.gguf

Una volta avviato, ti troverai di fronte a un prompt ds4-agent>. Puoi iniziare a scrivere messaggi come in una chat normale.

Comandi interni dell’agente

L’agente riconosce comandi che iniziano con /. Ecco i principali:

Comando	Descrizione	Esempio
/help	Mostra l’elenco dei comandi	/help
/save	Salva la sessione corrente su disco	/save
/list	Elenca tutte le sessioni salvate, ordinate per ultimo aggiornamento	/list
/switch <sha>	Passa a un’altra sessione salvata (si ripristina la KV cache)	/switch abc123
/strip <sha>	Rimuove i tensori KV pesanti da una sessione, mantenendo solo il testo	/strip abc123
/del <sha>	Elimina definitivamente una sessione	/del abc123
/think	Attiva la modalità di ragionamento	/think
/nothink	Disattiva la modalità di ragionamento	/nothink
/ctx N	Imposta la lunghezza massima del contesto	/ctx 100000
/quit	Esce dall’agente	/quit

Persistenza delle sessioni: come funziona

Tutte le sessioni vengono salvate in ~/.ds4/kvcache/. Ogni sessione è un file .kv nello stesso formato descritto nel capitolo 6, ma con alcune differenze:

• Il nome del file non è l’SHA1 del prompt, ma un ID stabile derivato dal primo prompt dell’utente e dalla data/ora di creazione.
• La sessione contiene l’intera conversazione (tutti i token, i logits, i tensori KV), non solo un prefisso.
• Quando fai /save, il file viene sovrascritto con lo stato più recente.
• Perché l’ID è stabile? Perché puoi usare /switch con lo stesso identificatore anche dopo giorni, e l’agente ritrova la conversazione esatta.

Comando /strip: quando la KV cache pesa troppo

Le sessioni possono diventare molto grandi, specialmente se hai conversazioni lunghe con molti tool call. Il comando /strip <sha> rimuove i tensori KV pesanti dal file, lasciando solo il testo renderizzato della conversazione.

Cosa succede se poi fai /switch su una sessione strippata? L’agente ripristina la KV cache eseguendo nuovamente il prefill dell’intero testo salvato. Ci vuole tempo (come una nuova conversazione), ma è più veloce che ricominciare da zero perché non devi ridigitare il prompt. Inoltre, il testo è già lì, pronto per essere ripassato al modello.

Quando usare /strip:

• Se hai bisogno di liberare spazio su disco.
• Se vuoi archiviare una conversazione ma non pensi di riprenderla presto (la ricostruzione sarà lenta, ma possibile).
• Se la sessione è corrotta (raro) e vuoi rigenerare la cache.

Esperienza d’uso tipica

Ecco una sessione di esempio:

$ ./ds4-agent
Loading model from ./ds4flash.gguf... done.
ds4-agent> Ciao, chi sei?
[Sono DeepSeek V4, un assistente AI...]

ds4-agent> /save
Session saved with ID: a3f5c2

ds4-agent> /list
Sessions:
  a3f5c2  2026-06-10 14:32:15  "Ciao, chi sei?" (128 tokens)
  (no other sessions)

ds4-agent> /nothink
ds4-agent> Spiega Redis in 10 parole.
Database in-memory veloce, strutture dati, persistente.

ds4-agent> /switch a3f5c2
Switched to session a3f5c2. Restored 128 tokens.
ds4-agent> (ora sei tornato alla prima conversazione, con thinking mode attivo)

L’agente mantiene la modalità di ragionamento, la lunghezza del contesto e tutti i parametri di campionamento specifici della sessione.

Differenze tra ds4-agent e ds4-server

Caratteristica	ds4-agent	ds4-server
Protocollo	Nessuno (in-process)	HTTP (OpenAI/Anthropic)
Persistenza sessioni	Manuale (/save)	Automatica (cache su disco)
Tool calling	DSML nativo	Traduzione da/a JSON
Client supportati	Solo il terminale	Codex CLI, Claude Code, Pi, ecc.
Multi-utente	No	Sì (via rete)
Stato	Alpha	Beta

Limitazioni attuali (alpha)

• L’interfaccia è solo testuale (nessuna integrazione con IDE, nessuna API remota).
• La gestione dei tool call è ancora acerba: a volte il parsing dei DSML può fallire.
• Nessuna modalità “server” – non puoi esporre l’agente in rete.
• Alpha significa bug: alcune sessioni potrebbero corrompersi, specialmente con tool call annidati.
• Salvataggio solo manuale: non c’è autosave periodico (usa /save spesso).

Debugging di ds4-agent

Puoi lanciare l’agente con --trace per vedere esattamente cosa sta facendo:

./ds4-agent --trace /tmp/agent-trace.txt

Il trace contiene:

• La cronologia dei token generati
• Le chiamate a tool (DSML grezzo)
• Le operazioni di salvataggio/caricamento delle sessioni
• Eventuali errori di parsing

Se incontri un comportamento strano, includi il trace in una issue su GitHub.

Prossimi sviluppi (secondo antirez)

L’autore del progetto ha dichiarato che, quando l’agente raggiungerà una forma più stabile, verrà splittato in un protocollo client-server stateful. In pratica, l’agente diventerebbe un server che espone un’API specifica per la gestione delle sessioni, mantenendo la persistenza su disco e la bassa latenza, ma accessibile da altri client (es. estensioni IDE).

Per ora, però, l’agente è pensato per l’uso diretto da terminale.

Conclusione

ds4-agent è lo strumento ideale se vuoi chattare con DeepSeek V4 in modo snello e reattivo, senza preoccuparti della gestione della cache o delle conversioni di tool call. La possibilità di salvare e riprendere conversazioni con /switch lo rende adatto a chi lavora su più progetti contemporaneamente e vuole mantenere separati i contesti.

Consiglio: Usalo per conversazioni lunghe o per attività di coding dove la latenza conta. Per integrazioni con IDE o agenti esistenti, invece, preferisci ds4-server (capitolo 9).

⚠️ Alpha quality – aspettati qualche imperfezione
L’agente è ancora in fase iniziale. Alcune funzionalità (es. il parsing dei tool call complessi) potrebbero non funzionare sempre. Salva frequentemente le sessioni con /save e tieni un backup delle conversazioni importanti.

💡 Combinare agente e server?
Puoi lanciare ds4-server in un terminale per esporre l’API, e ds4-agent in un altro per l’uso interattivo. Condividono la stessa directory dei modelli, ma le sessioni dell’agente sono indipendenti dalla cache del server.