Creazione di agenti AI con ADK: potenziamento con gli strumenti

1. Prima di iniziare

Benvenuti alla seconda parte della serie "Creazione di agenti AI con ADK". In questo codelab pratico, doterai un agente AI di base di 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 il codice di base dell'agente necessario per iniziare.

Al termine di questo codelab, avrai potenziato il tuo agente assistente personale con 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).

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

Prerequisiti

Cosa imparerai a fare

  • Fornisci 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 sub-agenti specializzati per attività complesse.
  • Integra strumenti di framework 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 alla console Google Cloud
  • Una mente curiosa e la voglia di imparare

2. Introduzione

Un agente di base creato con l'ADK ha un potente cervello LLM, ma presenta 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 chiuso 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 capacità 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 competente. Iniziamo.

3. Guida introduttiva: l'agente di base

Prima di poter potenziare un agente con gli strumenti, devi disporre di 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 Creazione di agenti AI con ADK: le basi, non devi fare altro. Puoi continuare a lavorare nella directory del progetto ai-agents-adk esistente.

Se non vedi (ai-agents-adk) nel prompt di Cloud Shell, esegui questi comandi per attivare l'ambiente virtuale Python:

cd ~/ai-agents-adk
source .venv/bin/activate

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. Crea un agente
  4. Eseguire l'agente nell'interfaccia utente 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 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?"

7b3c502f88e8ab80.png

Vedrai che l'agente non può recuperare i tassi di cambio in tempo reale. Questo perché l'agente attualmente non ha accesso a internet e connettività al sistema esterno. Anche se l'agente risponde con un valore, è difficile fidarsi di questo valore, perché probabilmente si tratta 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 di funzione per l'agente.

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

Crea file custom_functions.py

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

cloudshell edit personal_assistant/custom_functions.py

Ecco come dovrebbe apparire ora 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.

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 .custom_functions import get_fx_rate

root_agent = Agent(
    model='gemini-3.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, avvia di nuovo l'agente digitando:

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

Quando l'agente è disponibile, poni di nuovo la stessa domanda: "Qual è il tasso di cambio dal dollaro di Singapore allo yen giapponese?"

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

76b1647fbfc0687a.png

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

5. Integrare lo strumento della Ricerca Google integrato

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

399f40c4ea3e0bb3.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 caso d'uso che richiede dati in tempo reale, l'aggiunta di un numero sempre maggiore di 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.

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

Crea file custom_agents.py

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

cloudshell edit 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 custom_agents.py conterrà il codice per google_search_agent specializzato. 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-3.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.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-3.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. Prendi nota della sua descrizione specifica e del fatto che il suo unico strumento è google_search. È un esperto 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 a sua disposizione.

L'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. 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: "Qual è la previsione meteo 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 fare una domanda su un cambio attuale. Ora l'agente dovrebbe essere in grado di utilizzare lo strumento giusto per la domanda in questione.

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 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, arresta il processo dell'agente in esecuzione (Ctrl + C) e installa librerie aggiuntive nell'ambiente virtuale Python corrente digitando i seguenti comandi in Terminale.

uv pip install langchain-community wikipedia

Crea 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 Cloud:

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

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.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-3.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, chiedigli: "Parlami della storia di Kyoto".

9098274a483dee32.png

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

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.

eb2cdb9806cd3734.png

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

119d55bfb0b36e17.png

7. Pulisci l'ambiente

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

Eliminare file e cartelle di progetto dell'agente

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

cd ~
rm -rf ai-agents-adk

Disattivare l'API Gemini Enterprise Agent Platform

Per disattivare l'API 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 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 appreso il pattern architetturale fondamentale per creare agenti capaci: utilizzare agenti specializzati come strumenti. Creando un google_search_agent dedicato e assegnandolo 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 flussi di lavoro. A presto!