ADK: dalle nozioni di base agli agenti multi-strumento

1. Introduzione

Partendo dalle nozioni di base e passando allo sviluppo di agenti multiutensile, questo codelab fornisce un'introduzione completa alla creazione di agenti con ADK.

Nella sua forma più semplice, un agente AI è un sistema software che utilizza un modello linguistico di grandi dimensioni (LLM) come "motore di ragionamento" per raggiungere un obiettivo eseguendo autonomamente una sequenza di attività.

Se un LLM è un consulente altamente competente che può darti consigli, un agente AI è un ingegnere proattivo che può utilizzare gli strumenti per mettere in pratica questi consigli.

LLM e agenti

Il cervello (LLM): fornisce ragionamento, pianificazione e comprensione del linguaggio naturale. Decide cosa deve essere fatto.

Le mani (strumenti): sono le API, gli SDK e le funzioni personalizzate che consentono all'agente di interagire con il mondo reale. Esegue il piano.

Agent Development Kit (ADK)

Agent Development Kit (ADK) è un framework specializzato progettato per semplificare la creazione, il deployment e l'orchestrazione degli agenti AI. Fornisce i blocchi predefiniti standardizzati necessari per trasformare un modello linguistico di grandi dimensioni statico in un agente dinamico in grado di eseguire codice, chiamare API e gestire workflow in più passaggi.

Un agente multiutensile è un orchestratore in grado di selezionare e sequenziare diverse funzioni specializzate, come un motore di ricerca, un database e una calcolatrice, per risolvere problemi complessi. Determina in modo intelligente quale strumento utilizzare per ogni passaggio e può passare l'output di un'azione come input per la successiva per raggiungere un obiettivo finale.

Cosa creerai

In questo codelab creerai un agente "Healthy Hints", un consulente nutrizionale intelligente che passa dal semplice ragionamento testuale a un potente strumento multiutensile. Inizierai creando un agente conversazionale di base che comprende i concetti di nutrizione, quindi lo doterai progressivamente di uno strumento Storage SDK per archiviare le immagini degli ingredienti e di uno strumento Vision per "leggere" e analizzare queste immagini. Al termine di questo lab, avrai un orchestratore completamente funzionale in grado di prendere una foto caricata di un'etichetta alimentare, archiviarla in un bucket cloud per la tenuta dei registri e fornire immediatamente "Healthy Hints" per ogni ingrediente.

2. Prerequisiti

Un progetto Google Cloud con la fatturazione abilitata
Un browser web

Creazione di un progetto

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Attivazione di Cloud Shell

Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione nella console Google Cloud che viene fornito con i linguaggi richiesti precaricati. Nella console Cloud, fai clic su Attiva Cloud Shell nell'angolo in alto a destra:

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è impostato sul tuo ID progetto. Esegui questo comando in Cloud Shell per verificare che l'account sia autenticato:

gcloud auth list

Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto:

gcloud config list project

Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

Consulta la documentazione per i comandi e l'utilizzo di gcloud.

Apri editor

Per questo codelab, utilizzeremo l'editor Cloud integrato. Nella finestra di Cloud Shell, fai clic sul pulsante Apri editor nell'angolo in alto a destra. Verrà aperto un editor VSCode.

3. Configurazione delle Credenziali predefinite dell'applicazione

Passiamo al terminale Cloud Shell che abbiamo attivato nella sezione precedente:

Crea e attiva l'ambiente virtuale (consigliato)

Dal terminale Cloud Shell, crea un ambiente virtuale:

python -m venv .venv

Attiva l'ambiente virtuale:

source .venv/bin/activate

Installa ADK

pip install google-adk

4. Chiave API di Google

Crea la chiave API di Google utilizzando AI Studio:

Visita la pagina https://aistudio.google.com/ e, dal menu in basso a sinistra, fai clic su Get API Key

Verrà visualizzata una finestra Chiavi API. Fai clic su Crea chiave API in questa finestra:

Verrà visualizzata una finestra popup per la creazione di una nuova chiave. Assegna alla chiave il nome: healthy-hints-key

Vai al menu a discesa "Scegli un progetto importato".

Fai clic su Import Project. Verrà visualizzata una finestra laterale che elenca tutti i tuoi progetti Google Cloud. Seleziona quello con cui vuoi lavorare.

Fai clic su Importa.

Il menu a discesa verrà aggiornato con il progetto appena importato. Seleziona il progetto dal menu a discesa. Fai clic su Crea chiave ora. Ora vedrai l'elenco delle chiavi API create. Fai clic sull'icona di copia della chiave API appena creata.

5. Agente di esempio

Dal terminale Cloud Shell, crea una directory principale per l'agente nella posizione del progetto che preferisci:

adk create healthy_hints

Puoi scegliere qualsiasi modello, ma per questo codelab utilizzeremo gemini-2.5-flash.

Per questo codelab, utilizzeremo Google AI. Incolla la chiave API che hai creato nel passaggio precedente.

Apriamo la cartella che abbiamo appena creato. Nel menu più a sinistra, fai clic sull'icona , quindi su File -> Apri cartella. Seleziona la cartella healthy_hints appena creata, che in genere si trova nella cartella /home/<username>.
La struttura della cartella healthy_hints in genere è la seguente:

Vedrai un file .env che contiene la chiave API di Google. Puoi utilizzare questo file per impostare qualsiasi variabile di ambiente.
Viene creato anche un altro file denominato agent.py, che è il file dell'agente principale. Qui viene creato un agente root di esempio. Esaminiamo attentamente i contenuti di questo file. Per prima cosa, importiamo llm_agent da ADK. Quindi utilizziamo ADK DSL per creare l'agente root. Specifichiamo il nome del modello come Gemini-2.5-flash, assegniamo un nome all'agente e forniamo una descrizione appropriata. Le istruzioni sono la cosa più importante qui, perché è qui che diciamo all'agente cosa deve fare in linguaggio naturale.
Questo agente di esempio è piuttosto generico e risponderà a qualsiasi domanda di un utente.
Ora eseguiamo questo agente in locale. Esistono due modi per interagire con questo agente : CLI e web.
CLI: esegui il seguente comando dall'esterno della directory healthy_hints

adk run healthy_hints

In alternativa, se ti trovi nella directory healthy_hints, esegui il seguente comando:

adk run .

Vedrai un output simile:

Scrivi "ciao" o qualsiasi domanda tu abbia. La risposta può variare per ogni persona, questa è la natura di GenAI.

Web: esegui il seguente comando dalla directory principale di healthy_hints :

adk web

6. Agente multiutensile

Uno strumento è un pezzo di codice modulare, in genere una funzione o un'API, che consente a un agente di interagire con il mondo al di là della sua conoscenza interna.

Tipi di strumenti in ADK

Strumenti di funzione: logica personalizzata che scrivi tu. Ad esempio, una funzione che si connette al tuo database specifico o un "analizzatore di log" personalizzato per il formato univoco della tua azienda.
Strumenti integrati: funzionalità pronte all'uso fornite da Google o ADK, come Ricerca Google, Interprete di codice o Motore RAG di Google.
Agents-as-Tools: nei sistemi avanzati "multiutensile" o "multiagente", un agente specializzato può fungere da strumento per un altro. Ad esempio, un "agente di ricerca" può essere uno strumento utilizzato da un "agente di gestione della ricerca".

In questo codelab parleremo degli strumenti di funzione. Ora, facciamo avanzare il nostro agente e rendiamolo multiutensile.

Aggiungiamo un nuovo metodo get_weather in agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Modifichiamo agent.py e cambiamo il nome, la descrizione e le istruzioni dell'agente:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Finora abbiamo creato un solo strumento. Ora creiamo più strumenti:

Creiamo un altro metodo chiamato get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Modifichiamo l'agente in modo che richiami anche questo strumento:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Abbiamo modificato di conseguenza la descrizione, le istruzioni e gli strumenti. Ora eseguiamo questo agente aggiornato. Questa volta, l'agente risponderà anche con l'ora e il meteo correnti.

7. Integrazione dell'SDK

Ora che sappiamo come utilizzare più strumenti. Lavoriamo con alcuni esempi reali. Creiamo un agente di suggerimenti per la salute. Il nostro obiettivo è caricare qualsiasi immagine contenente un elenco di ingredienti nel nostro agente, che ci dirà se ogni ingrediente è sano o meno.

Per prima cosa, creiamo un bucket in Google Cloud Storage per caricare l'immagine. Apri una nuova scheda e vai alla pagina https://console.cloud.google.com/. Nella barra di ricerca, digita cloud storage. Ora seleziona Cloud Storage in Prodotti e pagine:

Verrà visualizzata la pagina di riepilogo di Google Cloud Storage. Fai clic sul pulsante Create bucket. Nella pagina di creazione del bucket, inserisci il nome del bucket. Il nome può essere qualsiasi, ma per questo codelab lo chiameremo healthy-hints-bucket-kolkata . Lascia invariato tutto il resto e fai clic sul pulsante Create.

Creiamo un nuovo file denominato requirements.txt e aggiungiamo google-cloud-storage. Utilizzeremo Python Storage SDK per caricare l'immagine in Storage.

Per prima cosa, installiamo le dipendenze:

pip install -r requirements.txt

Potresti dover prima abilitare l'API Storage. Esegui questo comando nel terminale:

gcloud services enable storage.googleapis.com

Ora aggiungiamo un nuovo strumento per caricare l'immagine.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Ora aggiorniamo l'agente in modo che utilizzi il nuovo strumento:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Ora aggiungiamo un altro strumento per leggere gli ingredienti dall'immagine. Aggiungiamo google-cloud-vision in requirements.txt e installiamo la nuova dipendenza.

pip install -r requirements.txt

Anche in questo caso, potresti dover prima abilitare l'API Vision. Esegui questo comando nel terminale:

gcloud services enable vision.googleapis.com

Ora aggiungiamo un nuovo strumento read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Ora aggiorniamo l'agente in modo che utilizzi questo strumento.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Conclusione

Congratulazioni per aver completato il codelab Healthy Hints. Hai trasformato un'AI standard da generatore di testo in un agente multiutensile proattivo. Utilizzando ADK per integrare l'API Vision e Cloud Storage SDK, hai dato al tuo agente gli "occhi" per leggere le etichette e la "memoria" per archiviarle. Hai visto come l'agente decide autonomamente quando salvare un file e come interpretare i dati non elaborati per fornire consigli sulla salute nel mondo reale.

In futuro, questi principi fungeranno da modello per qualsiasi sistema automatizzato. Che tu stia gestendo l'infrastruttura cloud o creando assistenti personali, il principio di base rimane lo stesso: definisci strumenti specializzati e lascia che l'agente orchestri la logica. Come passaggio successivo, prova ad aggiungere altri strumenti come un "database nutrizionale" o uno "strumento email" per espandere l'impatto del tuo agente.