Perché scegliere un agente AI in locale

Nel novembre 2026 l’interesse verso gli agenti AI che operano direttamente sulla macchina dell’utente è esploso. Tre ragioni principali ne spiegano la diffusione, ben più profonde della semplice moda.

1. Riservatezza del codice

Un agente che esplora un repository accede a tutto: chiavi segrete nei file di configurazione, nomi di clienti nei commenti e logiche di business non pubblicate. Inviare questi dati a un’API esterna richiede valutazioni GDPR, contratti con il fornitore e spesso un’analisi dei trasferimenti fuori dall’UE. Con un modello locale la valutazione si riduce a una sola domanda: chi ha accesso fisico al computer. Lo stesso ragionamento ha spinto molte banche europee a preferire modelli open‑weight per ridurre costi e dipendenze.

2. Costo marginale

Un agente che lavora su un bug può effettuare 20‑30 chiamate al modello, ciascuna con decine di migliaia di token di contesto, perché ogni passo ripete la conversazione precedente. Le API a pagamento fanno lievitare rapidamente il conto. In locale paghi solo la corrente elettrica e, se vuoi, il tempo di utilizzo della GPU. Puoi far girare l’agente per tutta la notte, provando dieci strategie diverse, senza temere di superare un budget.

3. Evoluzione tecnica

I modelli Mixture‑of‑Experts (MoE) con pochi parametri attivi hanno cambiato l’equazione dell’hardware. Un modello da 35 miliardi di parametri che ne attiva solo 3 per token occupa in memoria tanto quanto un modello grande, ma il costo computazionale è comparabile a quello di un modello piccolo. Per un agente che genera token brevi e attende l’esito dei test, la velocità di risposta è più importante dell’ultimo punto di benchmark.

È importante però riconoscere un limite: un modello locale da 35 miliardi non eguaglia i modelli di frontiera ospitati su cluster da migliaia di GPU. Funziona bene su compiti circoscritti – correzione di test, aggiunta di una funzione a un modulo o scrittura di test mancanti – ma fatica con refactoring che coinvolgono decine di file. Il tutorial è costruito attorno a questo limite: compiti piccoli, verifica automatica e revisione umana del diff finale.

Prerequisiti hardware e software

Prima di avviare il progetto “locoder” è fondamentale verificare di avere a disposizione le componenti elencate nella tabella seguente.

    • Python: versione 3.11 o successiva (testato con 3.12). Utilizzato per eseguire l’agente con la sola libreria standard.
    • Docker Engine o Docker Desktop: versione 24 o successiva. Fornisce l’isolamento dei comandi dell’agente.
    • llama.cpp (llama‑server): build recente con supporto a Clover. Serve il modello su un endpoint compatibile OpenAI.
    • huggingface_hub: ultima versione, per scaricare i pesi tramite il comando hf.
    • Git: versione 2.x, per mostrare le modifiche apportate dall’agente.
    • Memoria: 24 GB di VRAM consigliati, oppure 32 GB di RAM con offload su CPU. Necessaria per i pesi e la KV cache.
    • Spazio disco: circa 25 GB liberi per i file GGUF e l’immagine Docker.

Nota sull’hardware: i file GGUF ufficiali di Clover variano da 18,24 GiB a 35,26 GiB a seconda della quantizzazione (Q80, Q4KM, Q40). La variante a 4 bit sta in una scheda da 24 GB solo se il contesto rimane contenuto. Oltre ai pesi serve spazio per la KV cache, che cresce con la lunghezza della conversazione. Se la GPU non basta, llama.cpp può spostare parte degli esperti in RAM, sacrificando velocità.

Per quanto riguarda le licenze, Docker Desktop è gratuito per uso personale, istruzione, progetti open source non commerciali e piccole imprese con meno di 250 dipendenti e meno di 10 milioni di dollari di fatturato annuo. Oltre queste soglie è necessario un piano a pagamento. Su Linux è sufficiente installare il solo Docker Engine.

Scelta del modello: Clover‑35B‑A3B‑Preview vs Mistral Large 4

Nel panorama dei modelli open‑weight per agenti di programmazione, a novembre 2026 dominano due opzioni: Clover‑35B‑A3B‑Preview e Mistral Large 4. Ecco un confronto dettagliato.

CaratteristicaClover‑35B‑A3B‑PreviewMistral Large 4
Parametri totali35 miliardicirca 1 trilione
Parametri attivi per tokencirca 3 miliardicirca 49 miliardi
Contesto128 K token1 milione di token
LicenzaApache 2.0Mistral Ecosystem Open‑Weight (MIT modificata)
Formati per uso localeGGUF Q80, Q4KM, Q40 (18,24‑35,26 GiB)FP8 e NVFP4, con vLLM, SGLang o NVIDIA NIM
Benchmark dichiaratiSWE‑bench Verified 73,6; Terminal‑Bench 2.1 51,7; BFCL‑v4 67,9Coding Agent Index 48 % (Artificial Analysis)
Prezzo APINessun prezzo confermato0,70 USD input, 0,07 USD cache, 2,10 USD output per milione di token
Dove gira nel tutorialPC con GPU da 24 GB o piùServer multi‑GPU oppure API

La scelta per il tutorial è Clover, poiché è più adatto a una singola GPU da 24 GB e offre una licenza Apache 2.0 più permissiva per usi commerciali e sperimentali.

Struttura del progetto “locoder”

Il progetto “locoder” è costituito da circa 300 righe di Python, utilizza solo la libreria standard e si basa su tre componenti chiave:

    • Server OpenAI‑compatible (llama.cpp) che espone il modello Clover tramite API REST.
    • Sandbox Docker che esegue il codice del progetto in isolamento, senza rete.
    • Ciclo di tool calling che gestisce la logica dell’agente: lettura dei file, esecuzione dei test, modifica del codice e verifica dei risultati.

Se hai già sperimentato la creazione di agenti AI con n8n e Ollama, qui il bersaglio cambia: non automatizzi un flusso di lavoro, ma lasci che il modello corregga un bug e faccia affidamento sui test per decidere se la soluzione è valida.

Il ciclo operativo dell’agente

Il ciclo si articola in quattro fasi ricorrenti:

    • Analisi del repository: l’agente legge tutti i file sorgente, costruisce una mappa delle dipendenze e identifica i test falliti.
    • Generazione della proposta: tramite una chiamata al modello, l’agente suggerisce una modifica al codice, includendo il diff in formato git.
    • Esecuzione nella sandbox: il diff viene applicato in un container Docker isolato; i test vengono eseguiti nuovamente.
    • Verifica del risultato: se la suite di test è verde, l’agente termina; altrimenti ripete il ciclo, eventualmente con una nuova strategia.

Ogni passaggio è accompagnato da test unitari specifici inseriti nel tutorial, così da identificare subito eventuali problemi di configurazione o incompatibilità.

Passo 1 – Preparare l’ambiente

Installa le dipendenze richieste:

python -m venv .venv

source .venv/bin/activate


pip install huggingface_hub

Assicurati che Docker sia in esecuzione e che la GPU sia riconosciuta da nvidia-smi. Verifica la versione di llama.cpp con:

git clone https://github.com/ggerganov/llama.cpp

cd llama.cpp


git checkout main


make LLAMA_CUDA=1

Compila il server con il flag LLAMA_CUDA=1 per abilitare il supporto GPU.

Passo 2 – Scaricare i pesi di Clover

Usa huggingface_hub per scaricare il modello in formato GGUF. Scegli la quantizzazione più adatta alla tua GPU:

huggingface-cli download diffuspace/Clover-35B-A3B-Preview \

--filename clover-35b-a3b-q4_0.gguf \


--local-dir ./models

Il file risultante avrà una dimensione intorno a 18 GiB se usi Q40, oppure 35 GiB per Q80.

Passo 3 – Avviare il server OpenAI‑compatible

Avvia il server con i parametri consigliati per le MoE:

./llama-server --model ./models/clover-35b-a3b-q4_0.gguf \

--port 8080 \


--n-gpu-layers 32 \


--max-context 131072 \


--log-level info

Il server ascolterà sulla porta 8080 e risponderà a chiamate compatibili con le API di OpenAI, ad esempio /v1/chat/completions.

Passo 4 – Configurare la sandbox Docker

Crea un Dockerfile minimale per eseguire i test del progetto target:

FROM python:3.12-slim

WORKDIR /app


COPY . /app


RUN pip install -r requirements.txt


CMD ["/bin/bash"]

Costruisci l’immagine:

docker build -t locoder-sandbox .

Il container non avrà accesso a internet; tutti i comandi di rete saranno bloccati per garantire la privacy.

Passo 5 – Implementare l’agente in Python

Il cuore dell’agente è una classe LocoderAgent che gestisce le quattro fasi del ciclo. Ecco lo scheletro:

import json, subprocess, pathlib, sys, urllib.request


class LocoderAgent:


def _init(self, apiurl, repo_path):


self.apiurl = apiurl


self.repopath = pathlib.Path(repopath)



def read_repository(self):


# Scansiona tutti i file .py e costruisce una mappa dei contenuti


files = list(self.repo_path.rglob('*.py'))


return {f.relativeto(self.repopath): f.read_text() for f in files}



def run_tests(self):


# Avvia il container Docker e ritorna lo stato dei test


result = subprocess.run([


'docker', 'run', '--rm',


'-v', f'{self.repo_path}:/app',


'locoder-sandbox',


'pytest', '--maxfail=1', '--disable-warnings'


], capture_output=True, text=True)


return result.returncode == 0, result.stdout + result.stderr



def proposechange(self, context, failedtests):


payload = {


"model": "clover-35b-a3b",


"messages": [


{"role": "system", "content": "Sei un assistente di programmazione. Correggi il bug segnalato dai test."},


{"role": "user", "content": f"Context: {context}\\nFailed tests: {failed_tests}\\nProponi un diff git."}


],


"max_tokens": 1024,


"temperature": 0.2


}


req = urllib.request.Request(self.api_url, data=json.dumps(payload).encode(), headers={'Content-Type': 'application/json'})


with urllib.request.urlopen(req) as resp:


data = json.load(resp)


return data['choices'][0]['message']['content']



def applydiff(self, difftext):


# Usa git apply per applicare il diff nella sandbox


diffpath = self.repopath / 'temp.diff'


diffpath.writetext(diff_text)


subprocess.run(['git', 'apply', str(diffpath)], cwd=self.repopath)



def run(self):


while True:


files = self.read_repository()


ok, testoutput = self.runtests()


if ok:


print("✅ Tutti i test passano. Fine.")


break


print("❌ Test falliti, richiedo una correzione al modello...")


diff = self.proposechange(files, testoutput)


print("Diff proposto:", diff[:200], "...")


self.apply_diff(diff)


# Loop continua finché i test non passano

Questo script è auto‑contenuto, non richiede librerie esterne oltre a quelle della standard library.

Passo 6 – Eseguire il ciclo di correzione

Posiziona il repository di un progetto Python con test falliti nella cartella project/. Avvia l’agente:

python locoder.py --api-url http://localhost:8080/v1/chat/completions --repo-path ./project

L’agente leggerà i file, eseguirà i test nella sandbox, invierà il contesto al modello e applicherà il diff proposto. Il ciclo si ripeterà finché la suite di test non diventerà verde.

Consigli avanzati e ottimizzazioni

    • Offload della KV cache: se la GPU ha meno di 24 GB, aggiungi il flag --cpu-offload a llama-server per spostare parte della cache in RAM, accettando una leggera perdita di velocità.
    • Strategie di prompting: sperimenta con temperature più basse (0.1‑0.2) per ridurre la variabilità delle proposte; usa system messages per impostare linee guida sullo stile del codice.
    • Parallelismo dei test: se il progetto contiene molti test, avvia più container Docker in parallelo per ridurre il tempo di feedback.
    • Versionamento dei diff: prima di applicare un diff, salva lo stato corrente con git commit -am "pre‑diff" così puoi tornare indietro in caso di regressioni.

Conclusioni

L’approccio presentato dimostra come, nel 2026, sia possibile costruire un agente AI di programmazione completamente locale, rispettando la privacy, contenendo i costi e sfruttando le nuove architetture MoE. Il modello Clover‑35B‑A3B‑Preview, con licenza Apache 2.0, offre un compromesso ideale tra dimensioni, performance e libertà d’uso per chi vuole sperimentare su una singola GPU.

Il progetto “locoder” è volutamente semplice: 300 righe di Python, Docker per l’isolamento e llama.cpp per l’interfaccia OpenAI‑compatible. Con questi strumenti, gli sviluppatori possono automatizzare la correzione di bug, l’aggiunta di piccole funzionalità o la generazione di test, tutto senza inviare una singola riga di codice a servizi esterni.

Il futuro degli agenti AI in locale