Creare agenti AI con ADK: le basi

1. Prima di iniziare

Ti diamo il benvenuto alla prima parte della serie "Building AI Agents with ADK". In questa serie di codelab pratici, intraprenderai un entusiasmante viaggio per creare il tuo agente di AI intelligente utilizzando l'Agent Development Kit (ADK) di Google.

Inizieremo con le nozioni di base, guidandoti nella configurazione dell'ambiente di sviluppo e nella creazione di un agente conversazionale di base. Al termine di questo codelab, avrai creato la tua prima AI interattiva, pronta per essere ampliata nelle parti successive di questa serie, mentre la trasformiamo in un sofisticato sistema multi-agente (MAS).

Puoi completare questo codelab nel tuo ambiente locale o su Google Cloud. Per un'esperienza più coerente, ti consigliamo di utilizzare Cloud Shell dall'ambiente Google Cloud. Cloud Shell fornisce anche 5 GB di spazio di archiviazione permanente nella directory $HOME. Questo è utile per archiviare script, file di configurazione o repository clonati.

Nota:se scegli di lavorare in locale, potresti dover eseguire passaggi aggiuntivi di configurazione, installazione e autenticazione, che non sono trattati nella sezione di configurazione dell'ambiente di questo lab.

Prerequisiti

• Una comprensione dei concetti dell'AI generativa
• Una conoscenza di base della programmazione in Python
• Familiarità con la riga di comando / il terminale

Cosa imparerai a fare

• Come configurare un ambiente Python
• Come creare un semplice agente assistente personale utilizzando ADK
• Come eseguire, testare ed eseguire il debug dell'agente

Che cosa ti serve

• Un computer funzionante e una connessione Wi-Fi affidabile
• Un browser, ad esempio Chrome, per accedere a Google Cloud Console
• Un progetto Google Cloud con la fatturazione abilitata
• Una mente curiosa e la voglia di imparare

2. Introduzione

Il mondo dell'AI generativa (GenAI) è in rapida evoluzione e gli agenti AI sono attualmente un argomento molto discusso. Un AI Agent è un programma informatico intelligente progettato per agire per tuo conto, proprio come un assistente personale. Può percepire il suo ambiente digitale, prendere decisioni e intraprendere azioni per raggiungere obiettivi specifici senza il controllo umano diretto. Considerala un'entità proattiva e autonoma in grado di imparare e adattarsi per svolgere le attività.

Nella sua essenza, un agente AI utilizza un modello linguistico di grandi dimensioni (LLM) come "cervello" per comprendere e ragionare. Ciò consente di elaborare informazioni provenienti da varie fonti, come testo, immagini e suoni. L'agente utilizza quindi questa comprensione per creare un piano ed eseguire una serie di attività per raggiungere un obiettivo predefinito.

Ora puoi creare facilmente i tuoi agenti AI, anche senza competenze approfondite, grazie a framework pronti all'uso come Agent Development Kit (ADK). Inizieremo questo percorso creando un agente assistente personale per aiutarti con le tue attività. Iniziamo.

3. Configurare i servizi Google Cloud

Crea un progetto Google Cloud

Questo Codelab presuppone che tu abbia già creato un progetto Google Cloud con la fatturazione abilitata. Se non hai ancora un progetto, segui questi passaggi per crearne uno:

Seleziona o crea un progetto Google Cloud

• Vai alla console Google Cloud.
• In alto, fai clic sul menu a discesa del selettore progetti (accanto al logo Google Cloud).
• Scegli un progetto esistente o creane uno nuovo.

Abilita fatturazione

• Assicurati che la fatturazione sia attivata per il progetto Google Cloud selezionato.
• Per scoprire come verificare se la fatturazione è attivata per un progetto, segui le istruzioni riportate nella documentazione relativa alla fatturazione di Google Cloud.

Nota:la fatturazione deve essere abilitata anche per i servizi del livello senza costi, in quanto è il meccanismo utilizzato da Google Cloud per monitorare l'utilizzo delle risorse. Ciò detto, ti verranno addebitati dei costi solo se l'utilizzo supera i limiti del livello senza costi o se utilizzi servizi a pagamento.

Configurare Cloud Shell

Ora assicuriamoci che la configurazione sia corretta in Cloud Shell, una pratica interfaccia a riga di comando direttamente nella console Google Cloud.

Avvia Cloud Shell

Nell'angolo in alto a destra della console Google Cloud, vedrai un'icona a forma di terminale (>_). Fai clic per attivare Cloud Shell.

Autorizza accesso

Se richiesto, fai clic su Autorizza per concedere a Cloud Shell le autorizzazioni necessarie per interagire con il tuo progetto Google Cloud.

Verifica il tuo account:

Una volta caricata Cloud Shell, verifichiamo che tu stia utilizzando l'account Google Cloud corretto. Esegui questo comando:

gcloud auth list

Dovresti vedere un output del comando simile nel terminale:

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Cambia account (se necessario):

Se l'account attivo non è quello che intendi utilizzare per questo Codelab, passa all'account corretto utilizzando questo comando, sostituendo <[e-mail]> con l'email che utilizzerai per questo lab:

gcloud config set account <[e-mail]

Conferma il progetto

Successivamente, verifichiamo che Cloud Shell sia configurato per utilizzare il progetto Google Cloud corretto. Esegui:

gcloud config list project

Vedrai un elenco di configurazioni. Cerca la sezione [core] e assicurati che il valore del progetto corrisponda all'ID del progetto Google Cloud che vuoi utilizzare per questo Codelab:

[core]
project = <current-project-id>

Impostare il progetto (se necessario)

Se il valore di project ID non è corretto, impostalo sul progetto che preferisci utilizzando il seguente comando:

gcloud config set project <your-desired-project-id>

Abilita le API richieste

Per utilizzare i servizi Google Cloud, devi prima attivare le rispettive API per il tuo progetto. L'esecuzione dei comandi riportati di seguito nel terminale Cloud Shell attiva tutti i servizi necessari per questo Codelab:

gcloud services enable aiplatform.googleapis.com

Se l'operazione è andata a buon fine, vedrai Operation/... finished successfully stampato sul terminale.

4. Crea un ambiente virtuale Python

Prima di iniziare qualsiasi progetto Python, è buona prassi creare un ambiente virtuale. In questo modo, le dipendenze del progetto vengono isolate, evitando conflitti con altri progetti o con i pacchetti Python globali del sistema. Poiché l'Agent Development Kit (ADK) richiede Python 3.9 o versioni successive, utilizzeremo uno strumento come uv per gestire sia l'ambiente virtuale sia per assicurarci che venga utilizzata la versione corretta di Python.

uv è uno strumento moderno, veloce ed efficiente per la gestione di progetti e ambienti Python, che combina funzionalità tradizionalmente presenti in strumenti come pip, venv, pip-tools e pipx. È scritto in Rust per la velocità.

Cloud Shell ha già uv disponibile, quindi possiamo iniziare subito.

Verifica che uv sia installato correttamente

uv --version

Creare una nuova cartella di progetto per l'agente AI

uv init ai-agents-adk
cd ai-agents-adk

Crea un ambiente virtuale con Python 3.12

uv venv --python 3.12

Installa la libreria Google ADK all'interno dell'ambiente virtuale

uv add google-adk

Controllare se il pacchetto google-adk è stato installato correttamente

uv pip list | grep google-adk

Se vedi una riga di output con google-adk e la relativa versione, puoi procedere al passaggio successivo.

5. Crea un agente

Ora che l'ambiente di sviluppo è configurato e pronto, è il momento di creare le basi per il tuo agente AI. Agent Development Kit (ADK) semplifica questo processo, richiedendo solo alcuni file essenziali per definire la logica e la configurazione di base dell'agente.

Questi tre file funzionano insieme per rendere l'agente rilevabile, eseguibile e configurabile:

• agent.py: è il cuore del tuo agente. Contiene il codice Python principale che definisce il comportamento dell'agente, inclusi il nome, il modello linguistico di grandi dimensioni (LLM) che utilizza come "cervello" e le istruzioni di base che guidano le sue risposte.
• __init__.py: in Python, il file __init__.py contrassegna una directory come pacchetto Python. Per l'ADK, è fondamentale perché aiuta il framework a scoprire e caricare la definizione dell'agente da agent.py. Nei progetti ADK semplici, spesso contiene una sola riga per importare il modulo agent, rendendo l'agente accessibile al runner ADK.
• .env: questo file (abbreviazione di "ambiente") viene utilizzato per archiviare informazioni sensibili e variabili di configurazione necessarie all'agente, come chiavi API, ID progetto e località geografiche. Conservare questi dettagli in un file .env separato è una best practice per la sicurezza e la portabilità, in quanto impedisce di codificare in modo permanente i dati sensibili direttamente nel codice. Inoltre, ti consente di modificare facilmente le configurazioni senza modificare la logica principale dell'agente.

Utilizza i comandi riportati di seguito per creare questi file all'interno di una cartella dedicata per l'agente assistente personale:

uv run adk create personal_assistant

Una volta eseguito il comando, ti verrà chiesto di scegliere alcune opzioni per configurare l'agente. Per il primo passaggio, scegli l'opzione 1 per utilizzare il modello gemini-2.5-flash, un modello veloce ed efficiente perfetto per le attività conversazionali.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

Per il secondo passaggio, scegli Vertex AI (opzione 2), la potente piattaforma AI gestita di Google Cloud, come fornitore di servizi di backend.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Infine, ti verrà chiesto di confermare l'ID progetto Google Cloud e la regione. Se i valori precompilati (current-project-id e current-region) sono quelli che intendi utilizzare, premi Invio per ogni domanda.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Dovresti vedere un output simile nel terminale.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Ora, fai clic sul pulsante Apri editor nella parte superiore della finestra di Cloud Shell. Se fai clic su questo pulsante, si apre la finestra Editor, che semplifica notevolmente l'esplorazione dei contenuti dei file. Il cambio potrebbe richiedere un po' di tempo. Se la schermata di caricamento rimane bloccata per più di qualche minuto, prova ad aggiornare il browser.

Nota:puoi utilizzare un editor della riga di comando come Vim, ma dovrai conoscere i comandi per aprire e chiudere Vim autonomamente.

Una volta caricata completamente la finestra dell'editor, vai alla cartella personal-assistant. Vedrai i file necessari menzionati in precedenza (agent.py, __init__.py e .env). Esploriamo i contenuti.

Se non vedi il file .env nella cartella, vai alla barra dei menu in alto, fai clic su Visualizza e poi seleziona Attiva/disattiva file nascosti. Questa è un'impostazione comune, in quanto i file .env sono spesso nascosti per impostazione predefinita per evitare l'esposizione accidentale.

Esploriamo i contenuti di ogni file.

agent.py

Questo file crea un'istanza dell'agente utilizzando la classe Agent della libreria google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: questa riga importa la classe Agent necessaria dalla libreria ADK.
• root_agent = Agent(...): qui stai creando un'istanza del tuo agente AI.
• name="personal_assistant": un identificatore univoco per l'agente. In questo modo, ADK riconoscerà e farà riferimento al tuo agente.
• model="gemini-2.5-flash": questo parametro cruciale specifica quale modello linguistico di grandi dimensioni (LLM) verrà utilizzato dall'agente come "cervello" sottostante per comprendere, ragionare e generare risposte. gemini-2.5-flash è un modello rapido ed efficiente adatto alle attività conversazionali.
• description="...": fornisce un riepilogo conciso dello scopo o delle funzionalità dell'agente. La descrizione serve più che altro per la comprensione umana o per consentire ad altri agenti in un sistema multi-agente di capire cosa fa questo agente specifico. Viene spesso utilizzato per la registrazione, il debug o la visualizzazione di informazioni sull'agente.
• instruction="...": questo è il prompt di sistema che guida il comportamento dell'agente e ne definisce la personalità. Indica al modello LLM come deve agire e qual è il suo scopo principale. In questo caso, definisce l'agente come "assistente utile". Questa istruzione è fondamentale per definire lo stile e le capacità conversazionali dell'agente.

init.py

Questo file è necessario per consentire a Python di riconoscere personal-assistant come pacchetto, in modo che ADK possa importare correttamente il file agent.py.

from . import agent

• from . import agent: questa riga esegue un'importazione relativa, indicando a Python di cercare un modulo denominato agent (che corrisponde a agent.py) all'interno del pacchetto corrente (personal-assistant). Questa semplice riga garantisce che quando ADK tenta di caricare l'agente personal-assistant, possa trovare e inizializzare root_agent definito in agent.py. Anche se è vuoto, la presenza di __init__.py è ciò che rende la directory un pacchetto Python.

.env

Questo file contiene configurazioni specifiche per l'ambiente e credenziali sensibili.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: indica all'ADK che intendi utilizzare il servizio Vertex AI di Google per le tue operazioni di AI generativa. Ciò è importante per sfruttare i servizi gestiti e i modelli avanzati di Google Cloud.
• GOOGLE_CLOUD_PROJECT: questa variabile conterrà l'identificatore univoco del tuo progetto Google Cloud. L'ADK ne ha bisogno per associare correttamente l'agente alle tue risorse cloud e per attivare la fatturazione.
• GOOGLE_CLOUD_LOCATION: specifica la regione Google Cloud in cui si trovano le risorse Vertex AI (ad es. us-central1). L'utilizzo della posizione corretta garantisce che l'agente possa comunicare in modo efficace con i servizi Vertex AI in quella regione.

6. Esegui l'agente nel terminale

Con tutti e tre i file a posto, puoi eseguire l'agente direttamente dal terminale. Per farlo, devi aprire la finestra del terminale. Fai clic su Terminale nella barra dei menu, quindi scegli Nuovo terminale.

Una volta che il terminale è disponibile, puoi avviare l'agente utilizzando il comando adk run. Poiché si tratta di una nuova finestra del terminale e utilizziamo uv, devi prima passare alla cartella ai-agent-adk e poi aggiungere il prefisso uv run al comando adk run.

Digita questi comandi nel terminale:

cd ai-agents-adk
uv run adk run personal_assistant

Se tutto è configurato correttamente, vedrai un output simile nel terminale.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

Continua a chattare con l'agente. Noterai che a volte l'output è formattato con Markdown, che può essere difficile da leggere nel terminale. Nel passaggio successivo, utilizzeremo l'interfaccia utente di sviluppo per un'esperienza molto più ricca, simile a un'applicazione di chat.

7. Esegui l'agente nell'interfaccia utente di sviluppo

Agent Development Kit offre anche un modo pratico per lanciare l'agente come applicazione di chat utilizzando la sua UI di sviluppo. Utilizza semplicemente il comando adk web anziché adk run..

Se sei ancora nella sessione precedente, digita exit nel terminale per chiuderla. Una volta chiusa la sessione precedente, digita questo comando nel terminale:

uv run adk web

Dovresti vedere un output simile nel terminale:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Hai due opzioni per accedere alla UI di sviluppo:

1. Apri tramite Terminale

• Ctrl + fai clic o Cmd + fai clic sugli URL (ad es. http://localhost:8000) dal terminale.

2. Apri tramite Anteprima web

• Fai clic sul pulsante Anteprima web.
• Seleziona Cambia porta.
• Inserisci il numero di porta (ad es. 8000)
• Fai clic su Cambia e visualizza anteprima.

A questo punto, nel browser verrà visualizzata l'interfaccia utente simile a un'applicazione di chat. Inizia a chattare con il tuo assistente personale tramite questa interfaccia. Noterai che la formattazione Markdown ora viene visualizzata correttamente e questa UI ti consente anche di eseguire il debug e analizzare ogni evento di messaggistica, lo stato dell'agente, le richieste degli utenti e molto altro ancora. Buona chat!

8. Esegui la pulizia

Poiché questo codelab non coinvolge prodotti a lunga esecuzione, è sufficiente interrompere le sessioni dell'agente attive (ad es. l'istanza adk web nel terminale) premendo Ctrl + C nel terminale.

Attenzione: NON procedere con questi passaggi se prevedi di continuare la serie di codelab, in quanto ti costringeranno a ripetere alcune azioni nel codelab successivo.

Elimina cartelle e file del progetto dell'agente

Se vuoi rimuovere solo il codice dall'ambiente Cloud Shell, utilizza i seguenti comandi:

cd ~
rm -rf ai-agents-adk

Disabilita l'API Vertex AI

Per disattivare l'API Vertex AI abilitata in precedenza, esegui questo comando:

gcloud services disable aiplatform.googleapis.com

Arrestare l'intero progetto Google Cloud

Se vuoi chiudere completamente il tuo progetto Google Cloud, consulta la guida ufficiale per istruzioni dettagliate.

9. Conclusione

Complimenti! Hai creato correttamente un semplice agente assistente personale utilizzando Agent Development Kit (ADK).

Come avrai notato, questo agente di assistenza personale non è ancora molto efficiente (ad esempio, non può accedere a internet per le informazioni più recenti). Nel prossimo codelab di questa serie "Building AI Agents with ADK", imparerai come potenziare il tuo agente assistente personale con funzioni e strumenti. A presto!