Agent Zero con Ollama: installazione Docker e limites
Sì, Agent Zero (progetto agent0ai) gira in un contenitore Docker e può chiamare un Ollama locale puntando verso http://host.docker.internal:11434, l'indirizzo predefinito previsto dal progetto per connettersi all'host dal contenitore. Il computer dell'agente (il contenitore, con il suo desktop Linux e il suo browser) rimane distinto dalla macchina di inferenza: ospitare tutto localmente non garantisce da solo che il browser integrato o le estensioni restino offline.
Agent Zero è un framework per agenti open source pubblicato da agent0ai che mette a disposizione dell'agente un vero desktop Linux in un container Docker, un browser controllabile e strumenti per lavorare insieme sui documenti. Questa guida tratta la sua installazione, il collegamento a un Ollama locale, la scelta del modello in base al ruolo (conversazione o modello di utilità) e i limiti reali di un piccolo modello locale di fronte a questo insieme di compiti.
#Cosa è Agent Zero
Agent Zero (repository agent0ai/agent-zero) si presenta come un framework che dà all'agente un computer Linux completo: desktop XFCE all'interno di un container Docker, browser con annotazione del DOM, collaborazione in tempo reale su file Markdown, fogli di calcolo e presentazioni, e un hub di oltre 100 plugin della comunità. Al 28 settembre 2026, il progetto contava oltre 19.000 stelle su GitHub, con l'ultima versione contrassegnata dal tag v2.13 pubblicata il 23 settembre 2026.
Non è un agente specializzato nella programmazione come OpenCode o Cline: Agent Zero punta a compiti trasversali (ricerca, controllo di applicazioni desktop, revisione di interfacce web, analisi), al prezzo di un'infrastruttura più pesante rispetto a un semplice eseguibile da terminale.
Il progetto mette anche in evidenza i «profili di agente» (specialisti creati al volo, ad esempio per un'analisi finanziaria prudente con risultati consegnati in fogli di calcolo), una gestione dei progetti che isola file, segreti, memorie e repository per contesto, e una cooperazione multi-agente in cui un agente principale delega ricerca, programmazione, analisi o revisione a sottoagenti dedicati. Ciascuna di queste funzionalità consuma contesto e capacità di seguire le istruzioni, il che incide direttamente sulla scelta del modello quando si va oltre la semplice chat.
#Installa il container Docker
Agenti che agiscono sulla tua macchina: Cline agentico, MCP, n8n + Ollama, automazioni locali.
- Spazio online a vita
- PDF + file
- Aggiornamenti a vita
Con Docker già installato, la via più diretta è un singolo comando che monta i dati dell'istanza in un volume persistente. Il progetto propone anche uno script di installazione (A0 Install) per i server e la modalità headless, nonché un launcher grafico (A0 Launcher) che gestisce Docker, le istanze e le porte al posto dell'utente.
Una volta avviato il container, l'interfaccia web si apre sulla porta scelta (80 per impostazione predefinita, oppure quella passata come parametro) per configurare il fornitore del modello prima della prima attività. Su un server senza interfaccia grafica, lo script di installazione supporta una modalità silenziosa che crea un'istanza e una porta specificate senza aprire un menu, utile per una distribuzione automatizzata o per un computer remoto accessibile solo tramite SSH.
#Collegare un'istanza locale di Ollama
La documentazione ufficiale di installazione descrive in dettaglio la procedura da seguire: nelle impostazioni del modello di conversazione, del modello ausiliario o del modello di embedding, scegliere Ollama come fornitore, scrivere il nome del modello atteso da Ollama (ad esempio llama3.2 o qwen2.5:7b), poi inserire l'URL dell'API se diverso dal valore predefinito.
Se il container non riesce a raggiungere Ollama, la documentazione ricorda che la porta 11434 deve essere raggiungibile dal container; il file Docker Compose fornito associa host.docker.internal al gateway dell'host su Docker per Linux e, se i due servizi condividono la stessa rete Docker, l'indirizzo può anche essere http://(nom du conteneur):11434.
#Quale modello scegliere, e per quale ruolo?
Agent Zero distingue tre ruoli per i modelli: chat (conversazione principale), di servizio (organizzazione della memoria, riassunto) ed embedding (ricerca nella memoria). Il formato del nome del modello dipende dal fornitore: con Ollama si usa solo il nome del modello (gpt-oss:20b), senza prefisso del fornitore, a differenza di OpenRouter.
| Ruolo | Requisito documentato |
|---|---|
| Chat (conversazione) | Deve seguire il formato di comunicazione dell'agente (JSON con tool_name/tool_args) |
| Ausiliario (memoria, riepilogo) | I modelli molto piccoli (4B) falliscono spesso; un modello 70B o un modello cloud «flash/mini» di qualità funziona meglio |
| Embedding | Meno sensibile alle dimensioni, serve esclusivamente a indicizzare la memoria per la ricerca per similarità |
Il punto più spesso trascurato: un modello che funziona discretamente nella conversazione può fallire nel ruolo di servizio se è troppo piccolo, degradando silenziosamente la qualità della memoria senza che l'utente capisca perché l'agente «dimentica» o confonde fatti da una sessione all'altra.
#Chiamata a strumenti con un piccolo modello locale
Agent Zero stesso documenta un problema diffuso nei modelli locali leggeri: il modello spiega il comando invece di chiamare lo strumento che lo eseguirebbe. Il progetto propone una correzione basata esclusivamente sul prompt, senza modificare il codice: il profilo «Tiny Local», che mantiene il formato standard di chiamata agli strumenti ma rimuove i campi di ragionamento visibili dal prompt di comunicazione, per richiedere soltanto un oggetto JSON eseguibile con tool_name e tool_args.
Un'alternativa senza cambiare profilo consiste nell'aggiungere un file di prompt dedicato (estensione .promptinclude.md) che ribadisca la disciplina richiesta: una risposta visibile costituita esattamente da un oggetto JSON con esattamente i campi tool_name e tool_args, senza formattazione markdown né testo prima o dopo. La documentazione è esplicita sui limiti di questa correzione: si tratta di un adeguamento del prompt e del profilo, non di una modifica al codice di esecuzione — se un modello specifico continua a fallire nonostante questa disciplina, il passo successivo è cambiare modello, non complicare ulteriormente il prompt.
#Che cosa cambia davvero grazie al desktop Linux
La particolarità di Agent Zero rispetto agli agenti che operano esclusivamente da terminale è questo desktop XFCE completo all'interno del contenitore: l'agente può aprire un vero programma con interfaccia grafica (Blender per modellare un oggetto, un gestore di file, un terminale visibile) e l'utente osserva ogni azione condividendo lo stesso mouse e la stessa tastiera virtuali, con la possibilità di intervenire in qualsiasi momento.
Il browser integrato va oltre il semplice controllo di una pagina: la modalità Annotate trasforma qualsiasi pagina web in un'area in cui impartire istruzioni tramite clic — modificare un elemento, ispezionarlo, riutilizzarlo per un altro progetto o lasciare un commento mirato che l'agente tratta poi come un'attività da svolgere.
#Collegare server MCP
Oltre agli strumenti integrati (browser, terminale, file), Agent Zero può connettersi a server MCP esterni per accedere ad altri servizi: la documentazione ufficiale descrive ogni connessione MCP come un ponte — uno può collegare Gmail, un altro un database, un altro ancora uno strumento di automazione. Un server MCP si configura o come un comando avviato localmente o come un URL remoto, il che cambia gli aspetti di rete da considerare: un comando eseguito localmente nel container è soggetto agli stessi vincoli dell'accesso a Ollama (host.docker.internal, rete Docker condivisa), mentre un URL remoto segue le normali regole di rete del container.
La documentazione invita a limitare ogni connessione allo stretto necessario anziché aggiungerne per precauzione: ogni server MCP collegato amplia la superficie che il modello può raggiungere, anche quando si usa un modello locale il cui comportamento nell'invocazione degli strumenti è meno prevedibile di quello di un modello cloud di fascia alta.
#Checklist di sicurezza prima di collegare modello e strumenti
Tre aree meritano una verifica esplicita prima di lasciare operare Agent Zero senza supervisione costante: l'isolamento del contenitore, i segreti e le chiavi API, e i server MCP collegati.
| Superficie di attacco | Punto da verificare |
|---|---|
| Sandbox / container | Restare in Docker anziché eseguire direttamente sull'host; non montare l'intera directory personale nel volume senza comprenderne il rischio |
| Segreti e chiavi API | Utilizzare i segreti globali o di progetto anziché incollare una chiave in chiaro in un prompt, uno screenshot o una segnalazione di bug |
| Ambito dei segreti | I segreti globali si applicano a tutte le discussioni e a tutti i progetti, salvo ridefinizioni; un progetto può definire i propri segreti isolati, che hanno la precedenza sui segreti globali |
| Server MCP connessi | Aggiungere solo le connessioni realmente utili; ogni ponte MCP aggiuntivo amplia ciò a cui il modello può accedere, senza un legame diretto con la scelta tra Ollama locale e cloud |
#A confronto con gli altri agenti locali
| Framework | Ciò che lo distingue |
|---|---|
| Agent Zero | Desktop Linux completo (XFCE) e browser controllabile in un container Docker; attività trasversali oltre il codice |
| Hermes Agent | Agente da terminale e di messaggistica (Telegram, Discord…) incentrato sulla memoria persistente, senza desktop grafico |
| OpenCode / Cline | Agenti di programmazione nel terminale o nell'editor, senza container dedicato né browser controllabile |
#Limiti da conoscere prima di iniziare
- Volume di ricerca ingannevole
- « Agent Zero » comprende anche contenuti di intrattenimento nei motori di ricerca; la domanda reale per il framework di sviluppo è più limitata di quanto suggerisca il volume grezzo della parola chiave.
- Spazio disco e RAM
- Il container include un desktop completo oltre al runtime dell'agente: prevedere maggiori risorse rispetto a un agente CLI minimale, anche se l'inferenza stessa avviene altrove tramite Ollama.
- Modello di servizio sottodimensionato
- Un modello di servizio troppo piccolo compromette la memoria senza un messaggio di errore esplicito; è la prima cosa da controllare se l'agente sembra «perdere il filo» tra una sessione e l'altra.
- Rete interna al contenitore
- host.docker.internal funziona per Docker Desktop e la configurazione Linux fornita, ma un deploy personalizzato (rete Docker personalizzata, hosting remoto) richiede di riscrivere manualmente l'URL dell'API.
- Mettere un LLM in produzione con Docker Compose
- Installa Ollama con Docker
- Agente IA: definizioni e limiti generali
- Fonte: repository GitHub ufficiale Agent Zero
- Fonte: guida ufficiale di installazione
- Fonte: guida ufficiale sull'invocazione degli strumenti localmente
Qual è l'indirizzo Ollama da utilizzare da Agent Zero in Docker?+
Agent Zero funziona senza una GPU dedicata?+
Perché il mio modello locale non chiama mai gli strumenti in Agent Zero?+
Il desktop Linux di Agent Zero rende l'agente più sicuro di un agente che usa solo il terminale?+
Agent Zero e Hermes Agent fanno la stessa cosa?+
Come proteggere i segreti e le chiavi API in Agent Zero?+
Serve aggiungere tutti i server MCP disponibili a Agent Zero?+
Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.