Creazione di agenti AI con ADK: potenziamento con gli strumenti

1. Prima di iniziare

Benvenuto alla seconda parte della serie "Creazione di agenti AI con 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 "Creazione di agenti AI con ADK: le basi" e un altro per chi inizia da zero. Entrambi i percorsi ti garantiranno di avere il codice dell'agente di base necessario per iniziare.

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

Puoi accedere a questo codelab anche tramite questo URL abbreviato: goo.gle/adk-using-tools.

Prerequisiti

Cosa imparerai a fare

  • Fornire al tuo agente nuove competenze creando funzioni Python personalizzate come strumenti.
  • Collegare l'agente a informazioni in tempo reale utilizzando strumenti integrati come la Ricerca Google.
  • Strutturare un agente multi-strumento creando sotto-agenti specializzati per attività complesse.
  • Integrare strumenti di framework AI diffusi 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 alla console Google Cloud
  • Una mente curiosa e la voglia di imparare

2. Introduzione

Un agente di base creato con 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 intelligente, ma bloccato in una libreria senza telefono né internet. Per rendere un agente davvero utile, dobbiamo fornirgli degli strumenti.

Pensa agli strumenti come se dessi 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 frammento 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 degli strumenti estende le sue funzionalità ben oltre la semplice conversazione.

ADK offre tre categorie di strumenti:

  1. Strumenti 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 comuni come Serper e strumenti di LangChain e CrewAI.

Per saperne 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 competente. Iniziamo.

3. Inizia: il tuo 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 sulle basi

Se hai appena completato il codelab "Creazione di agenti AI con ADK: le basi", non devi fare altro. Puoi continuare a lavorare nella directory del progetto ai-agents-adk esistente.

Percorso B: iniziare da zero

Se stai iniziando questo codelab direttamente, completa questi 4 passaggi per configurare l'ambiente e creare l'agente di avvio necessario.

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

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

4. Creare uno strumento personalizzato per il cambio valuta

A questo punto, dovresti già sapere come creare un semplice agente AI utilizzando ADK ed eseguirlo nell'UI 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?"

7b3c502f88e8ab80.png

Vedrai che l'agente non è in grado di recuperare i tassi di cambio in tempo reale. Questo perché al momento l'agente non ha accesso a internet e non è connesso a sistemi esterni. Anche se l'agente risponde con un valore, è difficile fidarsi di questo valore perché è 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.

Interrompi il processo dell'agente in esecuzione utilizzando la scorciatoia da tastiera CTRL + C nella finestra del terminale.

Creare il file custom_functions.py

Esegui questo comando nel terminale per creare un file Python denominato custom_functions.py nella cartella personal_assistant e aprilo nell'editor di codice.

cloudshell edit 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

Questo file custom_functions.py conterrà la funzione Python responsabile del recupero dei dati del tasso di cambio da un'API esterna. Copia e incolla il seguente codice nel file:

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.

Aggiornare il file agent.py

Copia questo blocco di codice e sostituisci il contenuto esistente 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:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

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

76b1647fbfc0687a.png

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

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

Ora che l'agente è in grado di fornire i tassi di cambio, la prossima attività consiste nell'ottenere le previsioni del tempo per il mese prossimo. Poni questa domanda all'agente: "Quali sono le previsioni del tempo a Tokyo, in Giappone, per il mese prossimo?"

399f40c4ea3e0bb3.png

Come potresti immaginare, le previsioni del tempo richiedono informazioni in tempo reale che il nostro agente non ha. Anche se potremmo codificare nuove funzioni Python per ogni caso d'uso che richiede dati in tempo reale, 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, inclusa la Ricerca Google, pronti all'uso, semplificando il modo in cui il nostro agente interagisce con il mondo esterno.

Per dotare l'agente dello strumento Ricerca Google, devi implementare un pattern multi-agente. Innanzitutto, crea un agente specializzato il cui unico compito è eseguire ricerche su Google. Poi, assegna questo nuovo agente di Ricerca Google al nostro personal_assistant principale come strumento. Procedi nel modo seguente:

Creare il file custom_agents.py

Esegui questo comando nel terminale per creare un file Python denominato custom_agents.py nella cartella personal_assistant e aprilo nell'editor di codice:

cloudshell edit personal_assistant/custom_agents.py

Ecco come dovrebbe apparire la struttura delle cartelle:

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

Questo file custom_agents.py conterrà il codice per l'agente specializzato google_search_agent. Copia il seguente codice nel file custom_agents.py:

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.

Aggiornare il file agent.py

Copia questo blocco di codice e sostituisci il contenuto esistente del file agent.py:

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

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), 
        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. Nota la descrizione specifica e che il suo unico strumento è google_search. È uno specialista di ricerca.
  • agent_tool.AgentTool: si tratta di un wrapper speciale dell'ADK. Prende un intero agente (il nostro google_search_agent) e lo confeziona in modo che appaia e si comporti come uno strumento standard.
  • Un **root_agent più intelligente**: il nostro root_agent ora ha un nuovo strumento: 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 disponibili.

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

Ora digita questo comando nel terminale per avviare l'istanza:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Una volta che l'agente è in esecuzione, poni di nuovo questa domanda: "Quali sono le previsioni del tempo a Tokyo, in Giappone, per il mese prossimo?"

8a2a6d9532b54301.png

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

Puoi anche provare a porre una domanda sul cambio attuale. L'agente dovrebbe ora essere in grado di utilizzare lo strumento giusto per la rispettiva domanda.

ff3739a0b5ede6c2.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 sta diventando un ottimo assistente di viaggio. Può gestire il cambio valuta con lo strumento get_fx_rate e gestire la logistica con lo strumento google_search_agent. Ma un ottimo viaggio non riguarda solo la logistica, ma anche la comprensione della cultura e della storia della tua 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, sfrutteremo gli strumenti di Wikipedia di LangChain.

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

uv pip install langchain-community wikipedia

Creare il file third_party_tools.py

Il seguente comando crea un file Python denominato third_party_tools.py nella cartella personal_assistant e lo apre nell'editor di codice:

cloudshell edit personal_assistant/third_party_tools.py

Ecco come dovrebbe apparire 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 Wikipedia di LangChain. Copia il seguente codice nel file third_party_tools.py**:**

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."
)

Aggiornare il 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.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

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), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Ora digita questo comando nel terminale per avviare l'istanza:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Quando l'agente è pronto, poni questa domanda: "Parlami della storia di Kyoto".

9098274a483dee32.png

L'agente identifica correttamente questa query come storica e utilizza il suo 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 la pianificazione dei viaggi.

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

eb2cdb9806cd3734.png

L'inspector mostra un elenco di tutti gli strumenti disponibili ed evidenzia il codice dello strumento per quello eseguito dall'agente.

119d55bfb0b36e17.png

7. Pulizia (facoltativo)

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

Eliminare file e cartelle del progetto dell'agente

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

cd ~
rm -rf ai-agents-adk

Disattivare l'API Vertex AI

Per disattivare l'API Vertex AI che hai attivato in precedenza, esegui questo comando:

gcloud services disable aiplatform.googleapis.com

Arrestare l'intero progetto Google Cloud

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

8. Conclusione

Complimenti! Hai potenziato con successo l'agente 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 competenti: 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 (in arrivo) della serie, in cui approfondiremo l'orchestrazione di più agenti e workflow. A presto!