Questa pagina è stata tradotta dall'API Cloud Translation.

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 intelligenza artificiale 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.

Prerequisiti

Comprensione dei concetti di 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
Una mente curiosa e la voglia di imparare

Utilizzare un account di fatturazione di prova

Per completare questo codelab, devi anche disporre di un account di fatturazione Google Cloud attivo. Se non ne hai ancora uno, segui questi passaggi per riscattare un account di fatturazione di prova:

Apri una finestra di navigazione in incognito nel browser.
Vai a questo portale per la riscossione dei premi
Accedi utilizzando il tuo account Gmail personale.
Segui le istruzioni passo passo del portale

2. Introduzione

Il mondo dell'AI generativa (GenAI) è in rapida evoluzione e gli agenti AI sono attualmente un argomento molto discusso. Un agente AI è 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 un 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

Inizia creando un nuovo progetto Google Cloud in modo che le attività di questo codelab siano isolate solo all'interno di questo nuovo progetto.

Vai alla pagina console.cloud.google.com/projectcreate.
Inserisci le informazioni richieste:

Nome progetto: puoi inserire il nome che preferisci (ad es. genai-workshop)
Sede: lascia Nessuna organizzazione
Account di fatturazione: se vedi questa opzione, seleziona Account di fatturazione di prova di Google Cloud Platform. Non preoccuparti se non vedi questa opzione. Procedi al passaggio successivo.

Copia l'ID progetto generato, ti servirà in un secondo momento.

Se è tutto a posto, fai clic sul pulsante Crea.

Configurare Cloud Shell

Una volta creato il progetto, segui questi passaggi per configurare Cloud Shell.

1. Avvia Cloud Shell

Vai a shell.cloud.google.com e, se viene visualizzato un popup che ti chiede di autorizzare, fai clic su Autorizza.

2. Imposta ID progetto

Esegui questo comando nel terminale Cloud Shell per impostare l'ID progetto corretto. Sostituisci <your-project-id> con l'ID progetto effettivo copiato dal passaggio di creazione del progetto precedente.

gcloud config set project <your-project-id>

Ora dovresti vedere che nel terminale Cloud Shell è selezionato il progetto corretto. L'ID progetto selezionato è evidenziato in giallo.

3. Abilita le API richieste

Per utilizzare i servizi Google Cloud, devi prima attivare le rispettive API per il tuo progetto. Esegui i comandi riportati di seguito nel terminale Cloud Shell per abilitare i servizi 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.

1. Crea la directory del progetto e accedi alla directory:

mkdir ai-agents-adk
cd ai-agents-adk

2. Crea e attiva un ambiente virtuale:

uv venv --python 3.12
source .venv/bin/activate

Vedrai il prefisso (ai-agents-adk) davanti al prompt del terminale, a indicare che l'ambiente virtuale è attivo.

3. Pagina di installazione di ADK

uv pip install google-adk

5. Crea un agente

Con l'ambiente pronto, è il momento di creare le fondamenta del tuo agente AI. L'ADK richiede alcuni file per definire la logica e la configurazione dell'agente:

agent.py: contiene il codice Python principale dell'agente, che ne definisce il nome, il LLM utilizzato e le istruzioni di base.
__init__.py: contrassegna la directory come pacchetto Python, aiutando ADK a scoprire e caricare la definizione dell'agente.
.env: memorizza informazioni sensibili e variabili di configurazione come chiave API, ID progetto e posizione.

Questo comando creerà una nuova directory denominata personal_assistant contenente i tre file essenziali.

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

Dopodiché, devi verificare che l'ID progetto mostrato tra parentesi quadre [...] sia impostato correttamente. Se sì, premi Invio. In caso contrario, inserisci l'ID progetto corretto nel seguente prompt:

Enter Google Cloud project ID [your-project-id]:

Infine, premi Invio alla domanda successiva per utilizzare us-central1 come regione per questo codelab.

Enter Google Cloud region [us-central1]:

Dovresti vedere un output simile nel terminale.

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

6. Esplora i codici agente

Per visualizzare i file creati, apri la cartella ai-agents-adk nell'editor di Cloud Shell.

Fai clic su File > Apri cartella… nel menu in alto.
Trova e seleziona la cartella ai-agents-adk.
Fai clic su OK.

Se non visualizzi la barra dei menu in alto, puoi anche fare clic sull'icona delle cartelle e scegliere Apri cartella.

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

Il file .env è spesso nascosto per impostazione predefinita. Per renderlo visibile nell'editor di Cloud Shell:

vai alla barra dei menu in alto,
fai clic su Visualizza e
seleziona Attiva/Disattiva file nascosti.

Esplora 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="root_agent": 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ù 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.

7. Esegui l'agente nel terminale

Con tutti e tre i file a posto, puoi eseguire l'agente direttamente dal terminale. Per farlo, esegui questo comando adk run nel terminale:

adk run personal_assistant

Se tutto è configurato correttamente, vedrai un output simile nel terminale. Per ora non preoccuparti degli avvisi, se vedi [user]: puoi procedere.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Inizia a chattare con l'agente. Digita qualcosa come "ciao. Cosa puoi fare per me?" e dovresti ricevere una risposta.

...
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:
...

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.

Risoluzione dei problemi

Il metodo API richiede l'attivazione della fatturazione

Se ricevi un messaggio che indica {‘message': ‘This API method requires billing to be enabled'}, svolgi questi passaggi:

Verifica di utilizzare l'ID progetto corretto nel file .env
Vai alla pagina Account di fatturazione collegato e verifica se l'account di fatturazione è già collegato.
In caso contrario, scegli Account di fatturazione di prova di Google Cloud Platform dall'opzione

L'API Vertex AI non è stata utilizzata nel progetto

Se ricevi un messaggio di errore contenente {'message': 'Vertex AI API has not been used in project...'}, abilita l'API Vertex AI digitando questo comando nel terminale:

gcloud services enable aiplatform.googleapis.com

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

Altri errori

Se ricevi altri errori non menzionati sopra, prova a ricaricare la scheda Cloud Shell nel browser (e autorizza di nuovo se richiesto).

8. Esegui l'agente nell'interfaccia utente web 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 il terminale è ancora in esecuzione adk run, digita exit per chiuderlo prima di digitare questo comando:

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:

Apri tramite Terminale

Ctrl + clic o Cmd + clic sul link (ad es. http://localhost:8000) come mostrato nel terminale.

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!

9. Pulizia (facoltativo)

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

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.

10. Conclusione

Complimenti! Hai creato correttamente un semplice agente assistente personale utilizzando Agent Development Kit (ADK). Ora hai una solida base e una buona comprensione dei componenti principali di un agente ADK.

Come passaggio successivo, puoi ampliare in modo significativo le funzionalità del tuo agente fornendogli strumenti per accedere a informazioni in tempo reale e interagire con servizi esterni. Se vuoi continuare il tuo percorso, la prossima codelab di questa serie, Building AI Agents with ADK: Empowering with Tools, ti guiderà in questo processo.