Introduzione al nuovo Extension System di Agents CLI

Quando abbiamo lanciato Agents CLI al Google Cloud Next '26, lo abbiamo costruito attorno a un principio forte: passare da un'idea a un agente di produzione su Google Cloud dovrebbe richiedere un unico comando unificato. Per i team che utilizzano l’Agent Development Kit (ADK), questo percorso ha funzionato senza intoppi: basta eseguire agents-cli create, scrivere la logica dell’agente e distribuirlo su Cloud Run con osservabilità ed evals integrati, il tutto in circa trenta minuti.

Nei mesi successivi il panorama dei framework per agenti si è notevolmente ampliato. Oltre ad ADK, gli sviluppatori possono scegliere tra LangChain e LangGraph, nuovi arrivati specializzati come Deep Agents, o soluzioni interne costruite per specifici domini di business. Questa diversità porta a una realtà in cui il framework ideale per un prototipo non è sempre quello più adatto per una migrazione in produzione, e le politiche di governance aziendale – ad esempio scansioni di compliance, gateway SSO o controlli di Model Risk Management – devono poter essere applicate in modo uniforme a tutti i progetti.

La domanda chiave è: è possibile sfruttare le funzionalità di deployment, valutazione e osservabilità offerte da Agents CLI senza dover adottare obbligatoriamente ADK o accettare il comportamento predefinito di ogni comando? Con la versione 1.5.0 la risposta è sì. A partire dalla 1.8.0

Due percorsi di esempio: LangChain e policy personalizzate

1. Utilizzare LangChain con l’estensione ufficiale

Il primo viaggio mostra come l’ADLC (Agent Development Lifecycle) possa essere seguito con agenti LangChain. Grazie all’estensione, è possibile:

Scaffoldare un progetto LangChain con agents-cli scaffold usando il template fornito.
Eseguire l’agente in locale con agents-cli run, con le stesse opzioni di logging e tracciamento di ADK.
Distribuire su Cloud Run tramite agents-cli deploy, con osservabilità integrata.
Valutare le performance con agents-cli eval, senza dover configurare manualmente metriche o benchmark.

Il risultato è un agente LangChain completamente funzionante, integrato nella pipeline di sviluppo di Google Cloud, senza alcuna modifica al codice sorgente dell’estensione.

2. Creare un’estensione che aggiunge una scansione SBOM

Il secondo esempio dimostra come una squadra di piattaforma aziendale possa introdurre una policy di sicurezza: avvolgere ogni comando deploy in una scansione del Software Bill of Materials (SBOM). La procedura è la seguente:

Creare una directory Git contenente agents-cli-extension.yaml che dichiara la sovrascrittura del comando deploy.
Implementare lo script di wrapper (ad esempio in Bash o Python) che:
- Esegue la scansione SBOM con lo strumento interno.
- Se la scansione ha esito positivo, chiama il comando nativo agents-cli deploy.
- Altrimenti interrompe il processo e segnala l’errore.

Installare l’estensione a livello di progetto (o globale) usando agents-cli extension install <repo-url>.
Verificare con agents-cli info che il comando deploy ora punta al wrapper personalizzato.

Questa strategia consente di far rispettare le policy aziendali in modo centralizzato, senza forkare l’intero CLI o affidarsi a script ad hoc che gli sviluppatori potrebbero dimenticare.

Problemi comuni delle toolchain tradizionali

La maggior parte delle toolchain per lo sviluppo di agenti condivide una limitazione fondamentale: sono progettate per un singolo framework e le funzionalità di supporto (destinazione di deployment, pipeline CI/CD, harness di valutazione, osservabilità) presumono che lo sviluppatore abbia adottato quel framework. Quando il framework corrisponde all’assunzione, il percorso opinato funziona; altrimenti, si presentano tre soluzioni poco desiderabili.

La prima consiste nel forkare il CLI, mantenendo una copia divergente e sincronizzandola ad ogni rilascio upstream. Questo comporta un onere di manutenzione permanente e richiede di integrare manualmente ogni miglioramento.

La seconda è avvolgere il CLI con script personalizzati, creando una superficie di comando parallela. Il problema è che gli sviluppatori (e i loro assistenti di codifica) spesso dimenticano il wrapper e invocano direttamente il comando nativo, bypassando l’astrazione prevista.

La terza opzione è rinunciare al CLI e costruire tutto da zero, un’attività che può richiedere diversi mesi‑ingegnere e raramente produce uno strumento di qualità pari a quello originale.

Scenari tipici di frizione

Queste difficoltà emergono in due contesti principali.

Primo, i clienti enterprise in settori regolamentati: un team di piattaforma centrale richiede che ogni invocazione di deploy sia avvolta da un controllo di compliance, che l’autenticazione avvenga tramite SSO aziendale, o che le valutazioni passino attraverso una pipeline di Model Risk Management. Attualmente, implementare tali requisiti implica o forkare il CLI o costruire un layer di wrapper.

Secondo, i team che usano prevalentemente ADK ma devono occasionalmente lavorare con un framework diverso, ad esempio LangChain, per un progetto specifico. Nell’interfaccia di Agents CLI, sei comandi (playground, run e quattro sottocomandi di eval) assumono il runtime ADK, mentre gli altri ventiquattro (scaffold, infra, deploy, publish, login e simili) sono framework‑agnostici. Senza estensioni, scegliere un framework non‑ADK per un singolo progetto significherebbe perdere l’accesso a tutti questi comandi.

Come funziona il sistema di estensioni

Un’estensione per Agents CLI è una directory in un repository Git che contiene un unico file agents-cli-extension.yaml. Il file dichiara quali comandi built‑in vengono sovrascritti e quali nuovi comandi vengono aggiunti. Dalla documentazione ufficiale:

Le estensioni assumono due forme: un override di comando, che sostituisce il comportamento di un comando nativo (ad es. playground, deploy, eval generate), e un nuovo comando, che espone un workflow non previsto dal CLI (es. agents-cli my‑command). Entrambe le forme possono coesistere nella stessa estensione.

Le estensioni vengono distribuite tramite repository Git, senza un registro centralizzato. Questo modello si ispira al sistema di estensioni del progetto Gemini‑CLI: ogni directory all’interno di un repository può fungere da estensione, e Git gestisce versionamento, pinning e distribuzione.

Modalità di riferimento e ambiti di installazione

Le estensioni possono essere referenziate in diversi modi:

# consente a un singolo repository Git di contenere più estensioni, con l’identificatore di frammento che seleziona quella desiderata.
Le installazioni avvengono a livello di progetto (default) o a livello utente tramite il flag --global. L’ambito di progetto registra l’estensione e il relativo lockfile nel repository del progetto, rendendola disponibile a tutti i membri del team e ai pipeline CI. L’ambito utente la colloca nella directory di configurazione personale, rendendola valida per ogni progetto sul machine.
In caso di conflitto, l’estensione a livello di progetto prevale su quella utente, e il comando agents-cli info mostra la fonte di ciascun comando attivo.

Gestione della versione e ciclo di vita

Il sistema segue la disciplina dei package manager come uv o npm: al momento dell’installazione, il riferimento Git viene risolto a un commit SHA preciso, che viene registrato in un lockfile. In seguito, il comando agents-cli install ricostruisce la copia vendorizzata esattamente dallo SHA bloccato, garantendo che CI e sviluppo locale eseguano codice identico. Per aggiornare il pin a un nuovo commit, si utilizza agents-cli extension update, che risolve nuovamente il riferimento e richiede una conferma di trust per terze parti.

Il sistema di estensioni è contrassegnato come experimental nella versione 1.8.0; lo schema del manifest e la superficie dei comandi potrebbero subire cambiamenti breaking prima della stabilizzazione finale, pertanto è consigliato fissare la versione di Agents CLI nei progetti che dipendono da estensioni.

Estensione LangChain di prima parte

L’estensione ufficiale per LangChain è in realtà un project template. Un singolo comando agents-cli scaffold crea una struttura di progetto pronta all’uso, con:

Un file main.py che definisce un agente LangChain con tool di ricerca e LLM configurati.
Una configurazione agents.yaml che collega i comandi CLI (run, deploy, eval) alle API LangChain corrispondenti.
Script di test e di valutazione predefiniti, integrati con il framework di valutazione di Google Cloud.

Dopo lo scaffold, tutti i comandi standard di Agents CLI funzionano senza ulteriori modifiche: agents-cli run avvia l’agente in locale, agents-cli deploy lo pubblica su Cloud Run, agents-cli eval esegue benchmark di accuratezza e latenza, e agents-cli playground offre un’interfaccia web per test interattivi.

Costruire la propria estensione: passo passo

Per realizzare un’estensione personalizzata, ad esempio quella che aggiunge la scansione SBOM, seguire questi step:

Creare una cartella sbom-wrapper in un repository Git.

Aggiungere agents-cli-extension.yaml con contenuto simile a:

commands:

- name: deploy

type: override

script: sbom_deploy.sh

Scrivere sbom_deploy.sh che:
- Invoca lo scanner SBOM (ad es. cyclonedx-bom).
- Controlla il risultato; in caso di errori stampa un messaggio e termina con codice diverso da zero.
- Se OK, esegue agents-cli deploy "$@" passando gli argomenti originali.

Eseguire agents-cli extension install git+https://example.com/repo.git#sbom-wrapper a livello di progetto o globale.
Verificare con agents-cli info deploy che il comando punta allo script personalizzato.

Questa procedura garantisce che ogni deploy sia automaticamente verificato, senza richiedere interventi manuali né modifiche al flusso di lavoro esistente.

Vantaggi strategici per le organizzazioni

L’introduzione del sistema di estensioni porta diversi benefici:

Flessibilità: i team possono scegliere il framework più adatto al progetto (ADK, LangChain, Deep Agents, ecc.) mantenendo l’intera suite di strumenti di osservabilità, CI/CD e valutazione.
Governance centralizzata: le policy di sicurezza, compliance o autenticazione possono essere codificate in estensioni condivise e versionate tramite Git, riducendo il rischio di deviazioni.
Riduzione del debito tecnico: non è più necessario forkare o mantenere script wrapper sparsi; le modifiche sono tracciate e gestite come qualsiasi altro codice sorgente.
Coerenza ambientale: grazie al lockfile basato su SHA, tutti gli ambienti – locale, CI, produzione – eseguono esattamente lo stesso codice delle estensioni.

Conclusioni

Il nuovo Extension System di Agents CLI rappresenta una risposta concreta alla crescente diversità di framework per agenti e alle esigenze di governance delle grandi imprese. Grazie a un modello di distribuzione basato su Git, le estensioni sono facili da creare, versionare e condividere, sia a livello di progetto che a livello globale. L’estensione di prima parte per LangChain dimostra come sia possibile adottare un framework alternativo senza rinunciare a funzionalità chiave come deployment, valutazione e osservabilità. Allo stesso tempo, l’esempio della scansione SBOM mostra come le organizzazioni possano imporre policy di sicurezza in modo centralizzato e senza compromettere la produttività degli sviluppatori.

In sintesi, le squadre non devono più scegliere tra “usare il tool ufficiale e rinunciare al proprio framework” oppure “costruire da zero e perdere la qualità del tool”. Con le estensioni, è possibile avere il meglio di entrambi i mondi: flessibilità nella scelta del framework e coerenza operativa grazie a un ecosistema di CLI unificato e personalizzabile.