ADK: dalle nozioni di base agli agenti multi-strumento

1. Introduzione

Partendo dalle nozioni di base e passando allo sviluppo di agenti multi-strumento, 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 strumenti per mettere in pratica questi consigli.

LLM e agenti

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

Le mani (strumenti): si tratta delle API, degli SDK e delle 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 di 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 multi-strumento è un orchestratore che può 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 "Suggerimenti per la salute", un consulente nutrizionale intelligente che passa da un semplice ragionamento testuale a un potente strumento multifunzione. Inizierai creando un agente conversazionale di base che comprenda i concetti di nutrizione, per poi dotarlo 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 funzionante in grado di prendere una foto caricata di un'etichetta alimentare, archiviarla in un bucket cloud per la tenuta dei registri e fornire immediatamente "Suggerimenti per la salute" 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 nel tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Attiva Cloud Shell

Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione nella console Google Cloud che viene precaricato con le lingue richieste installate. 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 di ADK

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 fai clic su Get API Key nel menu in basso a sinistra.

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

Vedrai un 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. Si aprirà una finestra laterale che elenca tutti i tuoi progetti Google Cloud. Seleziona quello che vuoi utilizzare.

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 appena creata. Nel menu all'estrema sinistra, fai clic sull'icona , poi su File -> Apri cartella. Seleziona la cartella healthy_hints appena creata, che in genere si trova nella cartella /home/<username>.
La struttura delle cartelle healthy_hints in genere è simile alla seguente:

Vedrai un file .env che contiene la tua 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 nostro file dell'agente principale. È qui che viene creato un agente principale di esempio. Esaminiamo attentamente i contenuti di questo file. Per prima cosa, importiamo llm_agent da ADK. Utilizziamo quindi il DSL dell'ADK per creare l'agente principale. Specifichiamo il nome del modello come Gemini-2.5-flash, diamo un nome all'agente e forniamo una descrizione dettagliata. L'istruzione è la cosa più importante qui, è qui che diciamo all'agente cosa deve fare in linguaggio naturale.
Questo agente di esempio è piuttosto generico e risponde a qualsiasi domanda di un utente.
Ora eseguiamo questo agente localmente. 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 ciascuno, è la natura dell'IA generativa.

Web: esegui questo comando dalla directory principale di healthy_hints :

adk web

6. Agente multiutensile

Uno strumento è un componente di codice modulare, in genere una funzione o un'API, che consente a un agente di interagire con il mondo al di là delle sue conoscenze interne.

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 dall'ADK, come la Ricerca Google, Code Interpreter o Google RAG Engine.
Agents-as-Tools::nei sistemi avanzati "Multi-tool" o "Multi-agent", un agente specializzato può fungere da strumento per un altro. Ad esempio, un "agente di ricerca" può essere uno strumento utilizzato da un "agente responsabile della ricerca".

In questo codelab, esamineremo gli strumenti per le funzioni. Ora facciamo un passo avanti e rendiamo il nostro agente multi-tool.

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 il file 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 il nostro agente per richiamare 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. Vediamo alcuni esempi reali. Creiamo l'agente Suggerimenti per la salute. Il nostro obiettivo è caricare qualsiasi immagine che contenga un elenco di ingredienti sul 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:

Si aprirà 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 inseriremo come healthy-hints-bucket-kolkata . Lascia invariato tutto il resto e fai clic sul pulsante Create.

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

Innanzitutto, installa le dipendenze:

pip install -r requirements.txt

Potresti dover prima abilitare l'API Storage. Per farlo, 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 aggiungeremo un altro strumento per leggere gli ingredienti dell'immagine. Aggiungiamo google-cloud-vision in requirements.txt e installiamo la nuova dipendenza.

pip install -r requirements.txt

Anche in questo caso, potrebbe essere necessario abilitare prima l'API Vision. Per farlo, 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 per utilizzare 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 Suggerimenti per la salute. Hai trasformato correttamente un'AI standard da generatore di testo in un agente multi-strumento proattivo. Utilizzando l'ADK per integrare l'API Vision e l'SDK Cloud Storage, 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 per la 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 nucleo 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 ampliare l'impatto del tuo agente.