Introduzione a Docker Agent

Docker Agent è un plugin open‑source che consente di descrivere, eseguire e distribuire agenti intelligenti come se fossero semplici contenitori Docker. Grazie a una sintassi dichiarativa, le configurazioni di agente possono essere versionate, validate e condivise tramite registri OCI, riducendo la complessità tipica dello sviluppo di sistemi IA multi‑modello.

Validazione delle configurazioni

Il progetto fornisce un validatore Python basato su yaml, json e jsonschema, costruito direttamente sul file agent-schema.json presente nel repository docker/docker-agent. Il validatore verifica automaticamente la correttezza di ogni configurazione, fallendo in maniera esplicita quando, ad esempio, viene specificato un tipo di strumento inesistente. Questa robustezza è stata dimostrata con una configurazione intenzionalmente errata, che ha generato un errore di schema, confermando l’affidabilità del meccanismo.

Un caso d’uso tipico è la definizione di un server MCP DuckDuckGo tramite la notazione ref: docker:duckduckgo. Tale configurazione è stata validata con successo contro lo schema, garantendo che il riferimento sia corretto e pronto per l’esecuzione.

Esecuzione dei server MCP

Docker Agent raccomanda l’esecuzione dei server MCP (Model Control Plane) in contenitori dedicati, fornendo isolamento di default. Tuttavia, è possibile avviare i server:

    • localmente, per debugging veloce;
    • in remoto, su macchine esterne;
    • in contenitore, per ambienti di produzione.

Questa flessibilità consente di adattare l’infrastruttura alle esigenze di sicurezza e performance di ogni progetto.

Orchestrazione di team di agenti

Una delle funzionalità più innovative è la gestione di team di agenti tramite la direttiva subagents. Questa opzione trasforma agenti singoli in una squadra coordinata, attivando automaticamente lo strumento integrato transfertask senza richiedere configurazioni aggiuntive.

Quando transfertask viene invocato, esso:

    • Lancia una sotto‑sessione dedicata per l’agente di destinazione;
    • Attende il risultato dell’agente;
    • Restituisce il risultato al coordinatore.

Questa modalità si differenzia dall’opzione transfers, che trasferisce l’intera conversazione e il controllo, più adatta a scenari di pipeline continua.

Esempio pratico: un agente coordinatore delega la ricerca a un agente ricercatore, passa il risultato a un agente redattore e infine valida l’output finale. Ogni ruolo può utilizzare un modello diverso, ad esempio anthropic/claude per il coordinatore e il redattore, e openai/gpt‑5 per il ricercatore. La possibilità di scegliere il modello più adatto per ciascuna funzione è uno dei principi guida del design di Docker Agent.

Formati di dichiarazione: YAML e HCL

Gli agenti possono essere descritti sia in YAML che in HCL. Il campo obbligatorio model segue il formato fornitore/nome‑del‑modello, garantendo uniformità tra provider diversi.

Il runtime è compatibile con una vasta gamma di servizi, tra cui:

    • OpenAI
    • Anthropic
    • Google Gemini
    • AWS Bedrock
    • Mistral
    • xAI
    • Modelli locali tramite Docker Model Runner

Gli strumenti possono essere integrati direttamente o forniti da server MCP, lanciabili localmente, a distanza o in contenitori.

Distribuzione tramite registri OCI

Gli agenti pubblicati vengono distribuiti come immagini OCI, analogamente alle tradizionali immagini Docker. Questo approccio semplifica il sharing e la riutilizzazione in ambienti eterogenei, poiché le immagini possono essere tirate da registri privati o pubblici, garantendo coerenza tra sviluppo e produzione.

Installazione e prime operazioni

Per utilizzare Docker Agent è necessario avere Docker operativo e l’accesso ad almeno un modello. Le modalità di installazione più comuni sono:

    • Su Docker Desktop 4.63 o versioni successive, il plugin è pre‑installato e si invoca con docker agent;
    • Via Homebrew: brew install docker-agent, che crea l’eseguibile docker-agent e un link simbolico ~/.docker/cli-plugins/docker-agent per usarlo come sotto‑comando;
    • Download diretto da GitHub Releases, seguito dalla creazione di un link simbolico analogo.

Una verifica rapida consiste nell’eseguire docker agent --help, che deve mostrare l’elenco delle sotto‑comandi disponibili.

Struttura di un agente minimale

Un agente di base è descritto in un file agent.yaml con i seguenti requisiti:

    • Definizione di un punto d’ingresso chiamato esattamente root;
    • Campo instruction contenente il comportamento desiderato in linguaggio naturale;
    • Sezione toolsets che espone le capacità (ad esempio, accesso al file system o esecuzione di comandi);
    • Facoltativo campo think per strutturare il ragionamento prima dell’azione.

Un esempio di modello potrebbe essere anthropic/claude-sonnet-4-5. Per avviare l’agente, si usa docker agent run agent.yaml per una sessione interattiva, oppure docker agent run --exec "istruzione" agent.yaml per eseguire un’unica istruzione e terminare, utile in script CI/CD.

Gestione delle credenziali e della memoria

L’accesso ai modelli avviene tramite chiavi API impostate come variabili d’ambiente, ad esempio ANTHROPICAPIKEY, OPENAIAPIKEY o GOOGLEAPI_KEY. In alternativa, è possibile eseguire modelli localmente con Docker Model Runner, eliminando la dipendenza dal cloud.

Gli agenti possono mantenere una memoria persistente salvata in un file, ad esempio ./research.db, per conservare fatti e contesti tra più interazioni.

Integrazione di server MCP per l’esplorazione web

Per la navigazione web, Docker Agent supporta server MCP come DuckDuckGo, referenziati mediante la notazione docker:duckduckgo. Il server viene avviato in un contenitore isolato, garantendo sicurezza e separazione delle risorse.

Tutto l’ecosistema rimane compatibile con fornitori cloud, modelli locali e strumenti personalizzati, offrendo una soluzione flessibile per team di sviluppo IA.

Storia e maturità del progetto

Docker ha iniziato a gettare le basi nel 2025, ampliando Docker Compose per includere agenti e modelli IA e rilasciando Model Runner per l’esecuzione locale di modelli. Docker Agent raccoglie queste innovazioni in uno strumento dedicato, separato da una semplice estensione di Compose.

Il modulo Go di Docker Agent è stato taggato regolarmente a partire da marzo 2026. Il repository GitHub conta più di 3 300 stelle e quasi 10 000 commit, testimonianza di una community attiva e di un rapido sviluppo.

Conclusioni

Docker Agent rappresenta un passo significativo verso la standardizzazione della creazione, validazione e distribuzione di agenti IA. La combinazione di un linguaggio dichiarativo, validazione schema‑driven, orchestrazione di team, supporto multi‑fornitore e distribuzione via OCI rende l’intero workflow più coerente e replicabile. Con l’adozione crescente di modelli locali e cloud‑agnostici, Docker Agent si posiziona come strumento chiave per gli sviluppatori e le imprese che desiderano costruire sistemi IA complessi, modulari e facilmente condivisibili.