Creazione di agenti AI con ADK: potenziamento con gli strumenti

1. Prima di iniziare

Ti diamo il benvenuto alla seconda parte della serie "Creare agenti AI con l'ADK". In questo codelab pratico, potenzierai un agente AI di base con una serie di strumenti.

Per iniziare, questa guida fornisce due percorsi: uno per chi continua dal codelab " Building AI Agents with ADK: The Foundation" e un altro per chi inizia da zero. Entrambi i percorsi ti garantiranno il codice dell'agente di base necessario per iniziare.

Al termine di questo codelab, avrai dotato il tuo agente assistente personale di strumenti per vari scopi, un passo avanti verso l'espansione nelle parti successive di questa serie, mentre lo trasformiamo in un sofisticato sistema multi-agente (MAS).

Prerequisiti

Cosa imparerai a fare

  • Dai al tuo agente nuove competenze creando funzioni Python personalizzate come strumenti.
  • Collega il tuo agente a informazioni in tempo reale utilizzando strumenti integrati come la Ricerca Google.
  • Struttura un agente multi-strumento creando subagenti specializzati per attività complesse.
  • Integra strumenti di framework di AI popolari come LangChain per espandere rapidamente le funzionalità.

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

Un agente di base creato con l'ADK ha un potente cervello LLM, ma anche dei limiti: non può accedere alle informazioni create dopo la data di addestramento e non può interagire con servizi esterni. È come un assistente brillante e colto rinchiuso in una biblioteca senza telefono o internet. Per rendere un agente davvero utile, dobbiamo fornirgli degli strumenti.

Pensa agli strumenti come a un modo per dare all'assistente AI l'accesso al mondo esterno: una calcolatrice, un browser web o l'accesso a un database aziendale specifico. In ADK, uno strumento è un pezzo di codice modulare che consente all'agente di eseguire azioni specifiche come la ricerca di dati in tempo reale o la chiamata di un'API esterna. L'utilizzo di strumenti estende le sue funzionalità ben oltre la semplice conversazione.

ADK offre tre categorie di strumenti:

  1. Strumenti di funzione:strumenti personalizzati che sviluppi per soddisfare i requisiti unici della tua applicazione, come funzioni e agenti predefiniti.
  2. Strumenti integrati:strumenti pronti all'uso forniti dal framework per operazioni comuni, come la Ricerca Google e l'esecuzione di codice.
  3. Strumenti di terze parti:librerie esterne popolari come Serper e strumenti di LangChain e CrewAI.

Per scoprire di più sull'utilizzo degli strumenti con gli agenti ADK, consulta la documentazione ufficiale. In questo codelab, aggiungeremo strumenti per trasformare il nostro semplice agente in un assistente di viaggio personale in grado di svolgere diverse attività. Iniziamo.

3. Guida introduttiva: l'agente di base

Prima di poter potenziare un agente con gli strumenti, devi avere un agente di base con cui lavorare. Scegli il percorso più adatto ai tuoi progressi.

Percorso A: continuare dal codelab di base

Se hai appena completato il codelab " Building AI Agents with ADK: The Foundation", non devi fare altro. Puoi continuare a lavorare nella directory del progetto ai-agents-adk esistente.

Percorso B: iniziare da zero

Se inizi questo codelab direttamente, completa questi quattro passaggi per configurare l'ambiente e creare l'agente iniziale necessario.

  1. Configurare i servizi Google Cloud
  2. Crea un ambiente virtuale Python
  3. Creare un agente
  4. Esegui l'agente nell'UI di sviluppo

Una volta completati i passaggi, puoi iniziare il tuo percorso di apprendimento.

4. Crea uno strumento personalizzato per il cambio di valuta

A questo punto, dovresti già sapere come creare un semplice agente AI utilizzando l'ADK e come eseguirlo nell'interfaccia utente di sviluppo.

Immagina di prepararti per un viaggio in Giappone il mese prossimo e di dover controllare il tasso di cambio attuale. Chiedi all'agente: "Qual è il tasso di cambio da dollari di Singapore a yen giapponesi?"

a8f38e3c404ada9c.png

Vedrai che l'agente non può recuperare i tassi di cambio in tempo reale. Ciò è dovuto al fatto che l'agente attualmente non dispone dell'accesso a internet e della connettività al sistema esterno. Anche se l'agente risponde con un valore, è difficile fidarsi di questo valore, in quanto è probabile che si tratti di un'allucinazione.

Per risolvere questo problema, implementeremo una funzione Python per recuperare i tassi di cambio tramite un'API REST e la integreremo come strumento funzione per l'agente.

Termina il processo dell'agente in esecuzione utilizzando la scorciatoia da tastiera Ctrl + C (per Windows/Linux) o Cmd + C (per macOS) nella finestra del terminale.

Crea il file custom_functions.py**:**

Crea un file Python denominato custom_functions.py nella cartella personal_assistant digitando questo comando nel terminale.

touch personal_assistant/custom_functions.py

Ecco come dovrebbe apparire la struttura delle cartelle:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Apri custom_functions.py nell'editor di codice. Questo file conterrà la funzione Python responsabile del recupero dei dati sul tasso di cambio da un'API esterna.

Copia e incolla il seguente codice all'interno:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

Ora modifica il file agent.py: importa la funzione get_fx_rate e assegnala come FunctionTool.

Aggiorna il file agent.py**:**

Copia questo blocco di codice e sostituisci i contenuti esistenti del file agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

Dopo le modifiche, riavvia l'agente digitando:

uv run adk web

Quando l'agente è disponibile, ripeti la stessa domanda: "Qual è il tasso di cambio da dollari di Singapore a yen giapponesi?"

Questa volta dovresti visualizzare il tasso di cambio effettivo fornito dallo strumento get_fx_rate.

4f671fe04f8421f5.png

Non esitare a porre tutte le domande che vuoi in merito al cambio valuta.

5. Eseguire l'integrazione con lo strumento di ricerca Google integrato

Ora che l'agente è in grado di fornire i tassi di cambio, il prossimo compito è ottenere le previsioni meteo del mese successivo. Poni questa domanda all'agente: "Quali sono le previsioni meteo a Tokyo, in Giappone, per il mese prossimo?"

96c175077957fdd0.png

Come puoi immaginare, le previsioni meteo richiedono informazioni in tempo reale che il nostro agente non ha. Anche se potremmo codificare nuove funzioni Python per ogni dato in tempo reale richiesto, l'aggiunta di sempre più strumenti personalizzati rende rapidamente l'agente troppo complicato e difficile da gestire.

Fortunatamente, l'Agent Development Kit (ADK) fornisce una suite di strumenti integrati, tra cui la Ricerca Google, pronti all'uso, semplificando il modo in cui il nostro agente interagisce con il mondo esterno. Aggiungiamo uno strumento di ricerca Google al nostro agente.

Per farlo, devi modificare il file agent.py come segue:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

from .custom_functions import get_fx_rate

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',
    tools=[
        FunctionTool(get_fx_rate), 
        google_search,
    ]
)

Dopo aver modificato il file, riavvia l'istanza adk web. Se dovessi dimenticarlo,

  1. Fai clic sul terminale, premi Ctrl + C o Cmd + C per arrestare l'istanza.
  2. uv run adk web per avviare l'istanza
  3. Prova a porre la stessa domanda: "Quali sono le previsioni meteo a Tokyo, in Giappone, per il mese prossimo?"

L'approccio consigliato è quello di adottare un pattern multi-agente: creare un agente specializzato il cui unico compito è eseguire ricerche su Google. Poi, assegniamo questo nuovo agente della Ricerca Google al nostro personal_assistant principale come strumento.

Crea file custom_agents.py

Ora, crea un file Python denominato custom_agents.py nella cartella personal_assistant.

touch personal_assistant/custom_agents.py

Ecco come dovrebbe apparire ora la struttura delle cartelle:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

Questo file conterrà il codice per google_search_agent specializzato. Copia il seguente codice nel file custom_agents.py utilizzando l'editor di codice.

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

Una volta creato il file, aggiorna il file agent.py come mostrato di seguito.

Aggiorna file agent.py

Copia questo blocco di codice e sostituisci i contenuti esistenti del file agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

Analizziamo il nuovo potente pattern nel codice:

  • Un nuovo agente specializzato: abbiamo definito un agente completamente nuovo, google_search_agent. Prendi nota della sua descrizione specifica e del fatto che il suo unico strumento è google_search. È uno specialista della ricerca.
  • agent_tool.AgentTool: questo è un wrapper speciale dell'ADK. Prende un intero agente (il nostro google_search_agent) e lo confeziona in modo che sembri e si comporti come uno strumento standard.
  • Un'esperienza più intelligente **root_agent**: il nostro root_agent ora ha un nuovo strumento: agent_tool.AgentTool(agent=google_search_agent). Non sa come cercare sul web, ma sa di avere uno strumento a cui può delegare le attività di ricerca.

Nota che il campo delle istruzioni non è più presente in root_agent. Le sue istruzioni sono ora definite implicitamente dagli strumenti a sua disposizione.

root_agent è diventato un orchestratore o un router, il cui compito principale è comprendere la richiesta di un utente e trasmetterla allo strumento corretto, ovvero la funzione get_fx_rate o google_search_agent. Questo design decentralizzato è fondamentale per creare sistemi di agenti complessi e gestibili.

Ora, riavvia

adk web

esempio e poni di nuovo la domanda all'agente: "Quali sono le previsioni meteo a Tokyo, in Giappone, per il mese prossimo?"

9771716f64132c54.png

L'agente ora utilizza google_search_agent per ottenere le informazioni più recenti

Puoi anche provare a porre una domanda sul tasso di cambio attuale. Ora l'agente dovrebbe essere in grado di utilizzare lo strumento giusto per la domanda in questione.

2a8e6525a9f5a4ee.png

Non esitare a porre all'agente altre domande che richiedono informazioni in tempo reale e osserva come gestisce le query utilizzando gli strumenti a sua disposizione.

6. Sfruttare lo strumento Wikipedia di LangChain

Il nostro agente si sta rivelando un ottimo assistente di viaggio. Può gestire il cambio di valuta con lo strumento get_fx_rate e la logistica con lo strumento google_search_agent. Ma un viaggio indimenticabile non riguarda solo la logistica, ma anche la comprensione della cultura e della storia della destinazione.

Sebbene google_search_agent possa trovare fatti culturali e storici, le informazioni provenienti da una fonte dedicata come Wikipedia sono spesso più strutturate e affidabili.

Fortunatamente, ADK è progettato per essere altamente estensibile, consentendoti di integrare facilmente strumenti di altri framework di agenti AI come CrewAI e LangChain. Questa interoperabilità è fondamentale perché consente di ridurre i tempi di sviluppo e di riutilizzare gli strumenti esistenti. Per questo caso d'uso, utilizzeremo gli strumenti di Wikipedia di LangChain.

Innanzitutto, interrompi il processo dell'agente in esecuzione (Ctrl + C o Cmd + C) e installa librerie aggiuntive nell'ambiente virtuale Python corrente digitando i seguenti comandi in Terminale.

uv add langchain-community
uv add wikipedia

Crea file third_party_tools.py

Ora, crea un file Python denominato third_party_tools.py nella cartella personal_assistant.

touch personal_assistant/third_party_tools.py

Ecco come dovrebbe apparire ora la struttura delle cartelle:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

Questo file conterrà l'implementazione dello strumento LangChain Wikipedia. Copia il seguente codice in third_party_tools.py utilizzando Cloud Editor:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

Aggiorna file agent.py

Ora aggiorna il file agent.py con i contenuti riportati di seguito:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool
from google.adk.tools import langchain_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

Ora riavvia l'istanza adk web e poni questa domanda all'agente: "Parlami della storia di Kyoto".

862ec3546a8fbb5f.png

L'agente identifica correttamente questa query come storica e utilizza il nuovo strumento Wikipedia. Integrando uno strumento di terze parti e assegnandogli un ruolo specifico, hai reso il tuo agente molto più intelligente e utile per lo scopo di pianificazione dei viaggi.

Per vedere esattamente come l'agente ha fatto questa scelta, puoi utilizzare lo strumento di controllo degli eventi nella adk web UI. Fai clic sulla scheda Eventi e poi sull'evento functionCall più recente.

e3f388b64d08e666.png

L'inspector mostra un elenco di tutti gli strumenti disponibili ed evidenzia il tool_code di quello eseguito dall'agente.

135c9a1068d6c58f.png

7. Pulizia (facoltativo)

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.

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

Chiudere l'intero progetto Google Cloud

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

8. Conclusione

Complimenti! Hai abilitato l'agente dell'assistente personale con funzioni personalizzate e accesso in tempo reale alla Ricerca Google. Leggi questa documentazione ufficiale sull'utilizzo degli strumenti con Google ADK.

Ancora più importante, hai imparato il pattern architetturale fondamentale per creare agenti capaci: utilizzare agenti specializzati come strumenti. Creando un google_search_agent dedicato e fornendolo al tuo root_agent, hai fatto il primo passo dalla creazione di un singolo agente all'orchestrazione di un sistema multi-agente semplice, ma potente.

Ora sei perfettamente preparato per il prossimo codelab della serie, in cui approfondiremo l'orchestrazione di più agenti e flussi di lavoro. A presto!