Introduzione agli harness agenti per modelli locali
Nel panorama in rapida evoluzione dell'intelligenza artificiale, la distinzione tra un modello e un harness è diventata sempre più critica, specialmente quando si lavora con modelli linguistici di grandi dimensioni distribuiti localmente. Un agente non è semplicemente un modello: è una combinazione di un modello e un harness. L'harness svolge un ruolo fondamentale: esegue gli strumenti, mantiene lo stato, gestisce i permessi e rimanda il contesto al modello. Con un modello locale, l'importanza dell'harness aumenta significativamente. Le finestre di contesto ridotte e la capacità di chiamata di funzione più debole espongono ogni difetto progettuale, rendendo la scelta del framework appropriato una decisione cruciale per il successo.
Questa guida completa classifica 11 harness open-source in base a quanto bene documentano l'inferenza locale. I dati sono stati raccolti direttamente dai repository GitHub il 18 settembre 2026. La classificazione pesa quattro criteri fondamentali: licenza approvata dall'OSI (Open Source Initiative), runtime locali documentati, stato di manutenzione e controlli di sicurezza. Comprendere questi fattori aiuta gli sviluppatori a scegliere la soluzione più adatta alle loro esigenze specifiche.
Le tre regole fondamentali per ogni harness
Prima di esplorare i singoli harness, è essenziale comprendere tre regole che si applicano universalmente a ogni framework agente quando si lavora con modelli locali. Queste regole non sono linee guida opzionali, ma principi fondamentali che determineranno il successo o il fallimento della vostra implementazione.
1. Aumentare prima la finestra di contesto
La finestra di contesto è il fattore limitante più critico quando si utilizzano modelli locali. Secondo la documentazione di Ollama sui parametri di lunghezza del contesto, i valori predefiniti dipendono dalla VRAM disponibile: 4.000 token con meno di 24 GB, 32.000 token da 24 a 48 GB, e 256.000 token con 48 GB o più. La stessa documentazione afferma esplicitamente che gli agenti e gli strumenti di codifica dovrebbero ricevere almeno 64.000 token di contesto. Il fix è sorprendentemente semplice e richiede una sola riga di codice:
OLLAMA_CONTEXT_LENGTH=64000 ollama serveQuesta modifica è non negoziabile. Un contesto insufficiente porterà a prompt di sistema troncati, perdita di informazioni critiche e comportamenti incoerenti dell'agente.
2. Scegliere un modello che supporti le chiamate di funzione
Non tutti i modelli sono uguali quando si tratta di tool calling. La documentazione del provider di Goose afferma chiaramente che i modelli senza supporto per le chiamate di funzione possono eseguire solo il completamento della chat, limitando drasticamente le loro capacità come agenti. Con llama.cpp, la documentazione di Pi nota che il flag --jinja abilita i template di chat compatibili e le chiamate di funzione. Questo è un aspetto tecnico spesso trascurato, ma che ha implicazioni profonde sulla praticità dell'agente.
3. Budgetare memoria onestamente
La memoria non è infinita e il budgeting onesto è essenziale. La guida locale di Cline fornisce una mappatura pratica: 16-32 GB di RAM per modelli quantizzati piccoli, 32-64 GB per modelli di codifica di medie dimensioni, e 64 GB o più per modelli più grandi. La pagina Hermes di Ollama elenca gemma4 a circa 16 GB di VRAM e qwen3.6 a circa 24 GB di VRAM. Comprendere questi requisiti evita frustrazione e cattive performance in seguito.
1. OpenCode: la scelta più documentata
OpenCode emerge come leader nella documentazione dei percorsi locali. Documenta tre percorsi locali distinti nella sua documentazione del provider: Ollama, LM Studio e il server llama-server di llama.cpp. Ogni percorso utilizza il pacchetto @ai-sdk/openai-compatible con un baseURL locale, permettendo una configurazione flessibile e coerente. La documentazione afferma il supporto per oltre 75 provider complessivi, rendendolo una soluzione straordinariamente versatile.
La configurazione può essere ridotta a un unico comando. La pagina di OpenCode su Ollama mostra: ollama launch opencode. Raccomandata una finestra di contesto di almeno 64.000 token. La documentazione stessa aggiunge un suggerimento pratico: se le chiamate di funzione falliscono, aumentare num_ctx a circa 16.000-32.000 token.
OpenCode spedisce due agenti integrati, ognuno con diversi livelli di accesso. L'agente build ha accesso completo ai sistemi. L'agente plan è di sola lettura e chiede conferma prima di eseguire comandi bash. Questa distinzione è importante per la sicurezza e il controllo.
Migliore per: sviluppatori che desiderano la configurazione locale documentata più ampia in uno strumento terminale.
2. Pi: la scelta minimalista
Pi rappresenta il design minimalista nel panorama degli harness agenti. Il suo README fornisce al modello esattamente quattro strumenti: read, write, edit e bash. Deliberatamente salta MCP, sub-agenti, modalità plan e popup di permesso. Queste caratteristiche arrivano invece attraverso estensioni TypeScript e pacchetti, mantenendo il core snello e efficiente.
Pi ha supporto nativo per il router server di llama.cpp. Il router scopre automaticamente più file GGUF e li carica su richiesta. Gestite i modelli all'interno di Pi con il comando /llama. Ollama lo supporta altrettanto bene: ollama launch pi installa Pi, configura il provider e apre una sessione.
Un avvertimento importante riguarda l'uso locale. Pi non ha un sistema di permessi integrato. Funziona con i permessi dell'utente corrente. Il README raccomanda Docker, un'estensione micro-VM, o una sandbox di policy per l'isolamento. Questo è un aspetto critico di sicurezza che non deve essere ignorato.
Un dettaglio storico importante: il vecchio URL badlogic/pi-mono ora reindirizza a earendil-works/pi. Earendil ha acquisito Pi nell'aprile 2026, e il creatore Mario Zechner si è unito all'azienda. The Pragmatic Engineer riporta che Pi è la base su cui è costruito OpenClaw.
Migliore per: piccoli modelli locali, dove una lista di strumenti breve lascia più contesto per il codice.
3. Goose: governo della Fondazione Linux
Goose documenta il maggior numero di runtime locali tra tutti gli harness presenti in questa guida. La sua documentazione del provider elenca Ollama, LM Studio, Docker Model Runner, Ramalama e Atomic Chat. vLLM e KServe funzionano attraverso il provider compatibile con OpenAI. I provider personalizzati possono saltare la chiave API per i server locali.
La governance è un differenziatore significativo. La Linux Foundation ha formato l'Agentic AI Foundation il 9 dicembre 2025, con Block che contribuisce goose. Il repository ora risiede in aaif-goose/goose. Goose è scritto in Rust e fornisce un'app desktop, una CLI e un'API. Il README cita oltre 70 estensioni MCP, offrendo un ecosistema ricco.
La configurazione con Ollama è brevissima. Eseguite goose configure, selezionate Ollama e inserite il nome del modello. Questo è tutto ciò che serve per iniziare.
Migliore per: automazione generale al di là del codice, sotto la governance della fondazione neutrale.
4. Cline: la scelta migliore basata su editor
Cline è l'opzione più forte basata su editor. La sua guida locale raccomanda una configurazione al di sopra di tutte le altre: abilitare "Use Compact Prompt" per l'inferenza locale. Consiglia inoltre attività focalizzate e sessioni fresche quando il contesto cresce.
Ogni modifica di file e comando richiede l'approvazione per impostazione predefinita. L'approvazione automatica è opzionale. Le modalità Plan e Act separano la strategia dall'esecuzione, offrendo flessibilità nel flusso di lavoro.
Un dettaglio di licenza merita attenzione. Il README di Cline afferma che i plugin JetBrains non sono open-source. L'estensione VS Code, la CLI e l'SDK sono nel repository Apache-2.0, limitando parzialmente la portabilità ma mantenendo il core completamente aperto.
Migliore per: utenti di VS Code che desiderano approvazioni human-in-the-loop con un modello locale.
5. OpenHands: la guida più specifica
OpenHands pubblica la guida più specifica per i modelli locali. La sua guida LLM locale raccomanda Qwen3.6-35B-A3B come primo modello locale da provare, aggiornata al 21 maggio 2026. I requisiti hardware sono dichiarati chiaramente. Le varianti quantizzate richiedono almeno 24 GB di VRAM, oppure un Mac Apple Silicon con 64 GB di memoria unificata.
Le linee guida sul contesto sono altrettanto dirette. Impostare la lunghezza del contesto ad almeno 22.000 token, con 32.768 consigliato. La guida avverte che il default di Ollama di 4.096 non può nemmeno contenere il prompt di sistema, un errore comune che causa frustrazione.
Gli utenti Linux affrontano una trappola particolare. LM Studio si associa a 127.0.0.1 per impostazione predefinita, quindi un OpenHands containerizzato non può raggiungerlo. Abilitare "Serve on Local Network" risolve il problema in una sola riga.
Migliore per: attività containerizzate di lunga durata su una workstation o server GPU.
6. Aider: gestione della capacità di chiamata di funzione debole
Aider gestisce la capacità di chiamata di funzione debole in modo completamente diverso. I suoi formati di modifica permettono al modello di restituire le modifiche come testo. Il formato whole restituisce file completi. Il formato diff restituisce blocchi di ricerca e sostituzione. Aider invia inoltre una mappa del repository dei simboli chiave con ogni richiesta, fornendo contesto arricchito.
La documentazione di Ollama segnala un pericolo reale. Ollama scarta silenziosamente il contesto oltre la finestra. Aider affronta questo dimensionando la finestra per richiesta, più 8.000 token per la risposta. Si noti che la pagina cita ancora un default di Ollama più vecchio di 2.000 token.
La manutenzione è la preoccupazione principale. PyPI mostra la versione 0.86.2 del 12 febbraio 2026. La release precedente era del 13 agosto 2025, indicando cicli di rilascio più lunghi.
Migliore per: pair programming nativo di Git con modelli che hanno difficoltà con le chiamate di funzione.
7. Codex CLI: sandbox dedicate per la sicurezza
Codex CLI è sotto licenza Apache-2.0 e fornisce due provider locali integrati. Il codice sorgente definisce ollama sulla porta 11434 e lmstudio sulla porta 1234. Secondo la pagina di Ollama per Codex, codex --oss è impostato di default su gpt-oss:20b. Il flag -m seleziona un altro modello.
C'è un vincolo difficile da ignorare. Codex ora parla solo l'API Responses all'endpoint /v1/responses. Il codice sorgente rifiuta wire_api = "chat" e indica questa discussione. Il vostro server locale deve esporre quell'endpoint, un requisito che potrà sorprendere chi si aspetta una compatibilità completa con OpenAI.
Il repository include crate sandbox dedicate per Linux e Windows, offrendo isolamento di sistema indispensabile per l'esecuzione di codice non attendibile.
Migliore per: team standardizzati su gpt-oss che desiderano sandboxing integrato.
8. Qwen Code: il framework sintonizzato dal laboratorio
Il README di Qwen Code elenca i protocolli OpenAI, Anthropic, Gemini e Qwen. Nomina Ollama e vLLM per i modelli locali. Il progetto ha avuto inizio dalla Gemini CLI v0.8.2 di Google. Ha smesso di sincronizzarsi a monte alla v0.1. L'npm install richiede Node.js 22 o più recente, un requisito moderno che garantisce l'accesso alle funzionalità JavaScript più recenti.
Migliore per: accoppiare modelli Qwen open-weight con un harness sintonizzato dallo stesso laboratorio.