Crea ed esegui il deployment di un agente ADK su Cloud Run

1. Introduzione

Questo lab è incentrato sull'implementazione e sul deployment di un servizio di agent client. Utilizzerai Agent Development Kit (ADK) per creare un agente AI che utilizza strumenti.

In questo lab, creeremo un agente per lo zoo che utilizza Wikipedia per rispondere a domande sugli animali.

Da sinistra a destra, un leone, due pinguini, una persona con un cappello da safari, un elefante e un orso sono in piedi di spalle allo spettatore, mentre guardano un grande razzo rosso e bianco che viene lanciato in un cielo blu con nuvole bianche. In lontananza sono visibili anche due razzi più piccoli in fase di lancio. La scena è ambientata all'interno di un recinto dello zoo con una recinzione in legno e scogliere rocciose.

Infine, eseguiremo il deployment dell'agente guida turistica in Google Cloud Run, anziché eseguirlo solo localmente.

Prerequisiti

  • Un progetto Google Cloud con la fatturazione abilitata.

Obiettivi didattici

  • Come strutturare un progetto Python per il deployment dell'ADK.
  • Come implementare un agente che utilizza strumenti con google-adk.
  • Come eseguire il deployment di un'applicazione Python come container serverless in Cloud Run.
  • Come configurare l'autenticazione sicura tra servizi utilizzando i ruoli IAM.
  • Come eliminare le risorse cloud per evitare costi futuri.

Che cosa ti serve

  • Un account Google Cloud e un progetto Google Cloud
  • Un browser web come Chrome

2. Perché eseguire il deployment in Cloud Run?

Cloud Run è un'ottima scelta per l'hosting degli agenti ADK perché è una piattaforma serverless, il che significa che puoi concentrarti sul codice e non sulla gestione dell'infrastruttura sottostante. Ci occupiamo noi del lavoro operativo.

È come un negozio pop-up: si apre e utilizza le risorse solo quando arrivano i clienti (richieste). Quando non ci sono clienti, chiude completamente e non paghi per un negozio vuoto.

Funzionalità principali

Esegue Containers Anywhere:

  • Porti un container (immagine Docker) che contiene la tua app.
  • Cloud Run lo esegue sull'infrastruttura di Google.
  • Nessun problema di applicazione di patch del sistema operativo, configurazione della VM o scalabilità.

Scalabilità automatica:

  • Se nessuno utilizza la tua app → vengono eseguite 0 istanze (viene ridimensionata a zero istanze, il che è conveniente).
  • Se riceve 1000 richieste, crea tutte le copie necessarie.

Stateless by Default:

  • Ogni richiesta potrebbe essere inviata a un'istanza diversa.
  • Se devi archiviare lo stato, utilizza un servizio esterno come Cloud SQL, Firestore o Memorystore.

Supporta qualsiasi lingua o framework:

  • Finché viene eseguito in un container Linux, Cloud Run non si preoccupa se si tratta di Python, Go, Node.js, Java o .NET.

Pagamento a consumo:

3. Configurazione del progetto

Account Google

Se non hai ancora un Account Google personale, devi crearne uno.

Utilizza un account personale anziché un account di lavoro o della scuola.

Accedi alla console Google Cloud

Accedi a Google Cloud Console utilizzando un Account Google personale.

Abilita fatturazione

Configurare un account di fatturazione personale

Se hai configurato la fatturazione utilizzando i crediti Google Cloud, puoi saltare questo passaggio.

Per configurare un account di fatturazione personale, vai qui per abilitare la fatturazione in Cloud Console.

Alcune note:

  • Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
  • Per evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab per eliminare le risorse.
  • I nuovi utenti hanno diritto alla prova senza costi di 300$.

Crea un progetto (facoltativo)

Se non hai un progetto attuale che vuoi utilizzare per questo lab, creane uno nuovo qui.

4. Apri editor di Cloud Shell

  1. Fai clic su questo link per andare direttamente all'editor di Cloud Shell.
  2. Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento della giornata, fai clic su Autorizza per continuare.Fai clic per autorizzare Cloud Shell
  3. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
    • Fai clic su Visualizza.
    • Fai clic su TerminaleApri un nuovo terminale nell'editor di Cloud Shell.

5. Abilita API

Per utilizzare Cloud Run, Artifact Registry, Cloud Build, Vertex AI e Compute Engine, devi abilitare le rispettive API nel tuo progetto Google Cloud.

  • Nel terminale, abilita le API:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    Al termine dell'esecuzione, dovresti vedere un output simile al seguente:
    Operation "operations/acat.p2-[GUID]" finished successfully.

Presentazione delle API

  • L'API Cloud Run Admin (run.googleapis.com) ti consente di eseguire servizi di frontend e backend, batch o siti web in un ambiente completamente gestito. Gestisce l'infrastruttura per il deployment e la scalabilità delle tue applicazioni containerizzate.
  • L'API Artifact Registry (artifactregistry.googleapis.com) fornisce un repository sicuro e privato per archiviare le immagini container. È l'evoluzione di Container Registry e si integra perfettamente con Cloud Run e Cloud Build.
  • L'API Cloud Build (cloudbuild.googleapis.com) è una piattaforma CI/CD serverless che esegue le build sull'infrastruttura Google Cloud. Viene utilizzato per creare l'immagine container nel cloud dal Dockerfile.
  • L'API Vertex AI (aiplatform.googleapis.com) consente all'applicazione di cui è stato eseguito il deployment di comunicare con i modelli Gemini per eseguire attività di AI di base. Fornisce l'API unificata per tutti i servizi AI di Google Cloud.
  • L'API Compute Engine (compute.googleapis.com) fornisce macchine virtuali sicure e personalizzabili che vengono eseguite sull'infrastruttura di Google. Sebbene Cloud Run sia gestito, l'API Compute Engine è spesso necessaria come dipendenza di base per varie risorse di networking e di calcolo.

6. Prepara l'ambiente di sviluppo

Crea la directory

  1. Nel terminale, crea la directory del progetto e le sottodirectory necessarie:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. Nel terminale, esegui questo comando per aprire la directory zoo_guide_agent in Esplora dell'editor di Cloud Shell:
    cloudshell open-workspace ~/zoo_guide_agent
  3. Il riquadro di esplorazione a sinistra verrà aggiornato. Ora dovresti vedere la directory che hai creato.
    Screenshot della nuova directory nel riquadro laterale di Explorer

Impostare il progetto

  1. Nel terminale, imposta il progetto con questo comando:
    gcloud config set project [PROJECT_ID]
    Esempio: gcloud config set project lab-project-id-example Imposta l'ID progetto nel terminale dell'editor di Cloud Shell
  2. Dovresti visualizzare questo messaggio:
    Updated property [core/project].

Requisiti di installazione

  1. Esegui questo comando nel terminale per creare il file requirements.txt.
    cloudshell edit requirements.txt
  2. Aggiungi quanto segue al file requirements.txt appena creato
    google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. Nel terminale, crea e attiva un ambiente virtuale utilizzando uv. In questo modo, le dipendenze del progetto non entrano in conflitto con Python di sistema.
    uv venv
source .venv/bin/activate
  4. Installa i pacchetti richiesti nell'ambiente virtuale nel terminale.
    uv pip install -r requirements.txt

Imposta le variabili di ambiente

  • Utilizza il seguente comando nel terminale per creare il file .env.
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-2.5-flash"
EOF

7. Creazione flusso di lavoro agente

Crea file __init__.py

  1. Crea il file init.py eseguendo il seguente comando nel terminale:
    cloudshell edit __init__.py
    Questo file indica a Python che la directory zoo_guide_agent è un pacchetto.
  2. Aggiungi il codice seguente al nuovo file __init__.py:
    from . import agent

Creare il file agent.py

  1. Crea il file agent.py principale incollando il seguente comando nel terminale.
    cloudshell edit agent.py
  2. Importazioni e configurazione iniziale: aggiungi il seguente codice al file agent.py attualmente vuoto:
    import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
    Questo primo blocco del file agent.py importa tutte le librerie necessarie dall'ADK e da Google Cloud. Configura anche la registrazione e carica le variabili di ambiente dal file .env, che è fondamentale per accedere all'URL del modello e del server.
  3. Definisci gli strumenti: un agente è efficace solo quanto gli strumenti che può utilizzare. Aggiungi il seguente codice alla fine di agent.py per definire gli strumenti:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    The Tools Explained
    • add_prompt_to_state 📝: questo strumento ricorda le domande di un visitatore dello zoo. Quando un visitatore chiede: "Dove sono i leoni?", questo strumento salva la domanda specifica nella memoria dell'agente, in modo che gli altri agenti del flusso di lavoro sappiano cosa cercare.
      Come: è una funzione Python che scrive il prompt del visitatore nel dizionario tool_context.state condiviso. Il contesto dello strumento rappresenta la memoria a breve termine dell'agente per una singola conversazione. I dati salvati nello stato da un agente possono essere letti dall'agente successivo nel flusso di lavoro.
    • LangchainTool 🌍: fornisce all'agente guida turistica conoscenze generali sul mondo. Quando un visitatore pone una domanda che non è presente nel database dello zoo, ad esempio "Cosa mangiano i leoni in natura?", questo strumento consente all'agente di cercare la risposta su Wikipedia.
      Come funziona:funge da adattatore, consentendo al nostro agente di utilizzare lo strumento predefinito WikipediaQueryRun della libreria LangChain.
      Il robot dall&#39;aspetto amichevole tiene in mano un blocco per appunti con disegni di animali e un fumetto con un leone, mentre parla con un uomo e un bambino con uno zaino. Giraffe e altri elementi dello zoo sullo sfondo, con palme che incorniciano l&#39;ingresso.
  4. Definisci gli agenti specializzati: aggiungi il seguente codice in fondo a agent.py per definire gli agenti comprehensive_researcher e response_formatter:
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • L'agente comprehensive_researcher è il "cervello" della nostra operazione. Prende il prompt dell'utente dal State condiviso, esamina lo strumento Wikipedia e decide quali utilizzare per trovare la risposta.
    • Il ruolo dell'agente response_formatter è la presentazione. Prende i dati non elaborati raccolti dall'agente Ricercatore (trasmessi tramite lo stato) e utilizza le competenze linguistiche del LLM per trasformarli in una risposta amichevole e colloquiale.
      Il robot, con occhi blu luminosi, è seduto davanti a un grande monitor curvo che mostra MCP ZOO SERVER a sinistra e una pagina di Wikipedia di ZOO a destra. Le icone degli animali sono visibili nell&#39;interfaccia del server. La scrivania ha più touchpad blu luminosi. Lo sfondo mostra lo skyline di una città attraverso grandi finestre.
  5. Definisci l'agente del workflow: aggiungi questo blocco di codice in fondo a agent.py per definire l'agente sequenziale tour_guide_workflow:
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    L'agente del flusso di lavoro funge da gestore di "back office" per il tour dello zoo. Prende la richiesta di ricerca e assicura che i due agenti che abbiamo definito sopra svolgano il loro lavoro nell'ordine corretto: prima la ricerca, poi la formattazione. In questo modo, la procedura per rispondere alla domanda di un visitatore è prevedibile e affidabile.
    Come: è un SequentialAgent, un tipo speciale di agente che non pensa in modo autonomo. Il suo unico compito è eseguire un elenco di sub_agents (il ricercatore e il formattatore) in una sequenza fissa, passando automaticamente la memoria condivisa da uno all'altro.
  6. Assembla il flusso di lavoro principale: aggiungi questo blocco di codice finale alla fine di agent.py per definire root_agent:
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
    Il framework ADK utilizza root_agent come punto di partenza per tutte le nuove conversazioni. Il suo ruolo principale è quello di orchestrare l'intero processo. Funge da controller iniziale, gestendo il primo turno della conversazione.
    Sono raffigurati tre robot: un robot di accoglienza a sinistra scrive su un blocco note con una bolla di pensiero di un leone, un robot ricercatore al centro è seduto a una scrivania con un computer che mostra dati e una freccia di query che punta verso di lui e un robot presentatore a destra sorride mentre tiene in mano un grafico con l&#39;etichetta Dati analizzati, con una freccia che punta verso di lui dal robot ricercatore. Sullo sfondo si vedono giraffe ed elefanti, mentre palme incorniciano la scena.

Il file agent.py completo

Il tuo file agent.py è stato completato. In questo modo, puoi vedere come ogni componente (strumenti, agenti worker e agenti manager) abbia un ruolo specifico nella creazione del sistema intelligente finale.

Il file completo dovrebbe avere il seguente aspetto:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Il prossimo passo è il deployment.

8. Preparare l'applicazione per il deployment

Controlla la struttura finale

Prima del deployment, verifica che la directory del progetto contenga i file corretti.

  • Assicurati che la cartella zoo_guide_agent abbia il seguente aspetto:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

Configurare le autorizzazioni IAM

Con il codice locale pronto, il passaggio successivo consiste nel configurare l'identità che l'agente utilizzerà nel cloud.

  1. Nel terminale, carica le variabili nella sessione della shell.
    source .env
  2. Crea un service account dedicato per il tuo servizio Cloud Run in modo che disponga di un'autorizzazione specifica. Incolla il seguente codice nel terminale:
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    Creando un'identità dedicata per questa applicazione specifica, ti assicuri che l'agente disponga solo delle autorizzazioni esatte di cui ha bisogno, anziché utilizzare un account predefinito con un accesso eccessivamente ampio.
  3. Concedi al service account il ruolo Utente Vertex AI, che gli consente di chiamare i modelli di Google.
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

9. Esegui il deployment dell'agente utilizzando ADK CLI

Con il codice locale pronto e il progetto Google Cloud preparato, è il momento di eseguire il deployment dell'agente. Utilizzerai il comando adk deploy cloud_run, uno strumento pratico che automatizza l'intero flusso di lavoro di deployment. Questo singolo comando comprime il codice, crea un'immagine container, la invia ad Artifact Registry e avvia il servizio su Cloud Run, rendendolo accessibile sul web.

  1. Esegui questo comando nel terminale per eseguire il deployment dell'agente.
    # Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    Il comando uvx ti consente di eseguire strumenti a riga di comando pubblicati come pacchetti Python senza richiedere un'installazione globale di questi strumenti.
  2. Se viene visualizzato il seguente messaggio:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    In questo caso, digita Y e premi Invio.
  3. Se viene visualizzato il seguente messaggio:
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    Digita y e premi INVIO. Ciò consente chiamate non autenticate per questo lab per facilitare i test. Se l'esecuzione va a buon fine, il comando fornirà l'URL del servizio Cloud Run di cui è stato eseguito il deployment. (Avrà un aspetto simile a https://zoo-tour-guide-123456789.europe-west1.run.app).
  4. Copia l'URL del servizio Cloud Run di cui è stato eseguito il deployment per l'attività successiva.

10. Testa l'agente di cui è stato eseguito il deployment

Ora che l'agente è attivo su Cloud Run, esegui un test per verificare che il deployment sia stato eseguito correttamente e che l'agente funzioni come previsto. Utilizzerai l'URL del servizio pubblico (ad esempio https://zoo-tour-guide-123456789.europe-west1.run.app/) per accedere all'interfaccia web dell'ADK e interagire con l'agente.

  1. Apri l'URL del servizio Cloud Run pubblico nel browser web. Poiché hai utilizzato --with_ui flag, dovresti visualizzare la UI per sviluppatori dell'ADK.
  2. Attiva Token Streaming in alto a destra.
    Ora puoi interagire con l'agente dello zoo.
  3. Digita hello e premi Invio per iniziare una nuova conversazione.
  4. Osserva il risultato. L'agente deve rispondere rapidamente con il suo saluto, che sarà simile a questo:
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Poni all'agente domande come:
    Where can I find the polar bears in the zoo and what is their diet?
    Screenshot dell&#39;agente ADK che esegue una sequenza di azioni: add_prompt_to_state, transfer_to_agent, wikipedia e get_animals_by_species. La prima risposta dice: &quot;Non posso dirti dove trovare gli orsi polari in questo zoo specifico, ma posso parlarti della loro dieta&quot;. La seconda risposta dice: &quot;Gli orsi polari si trovano nella mostra artica sul sentiero polare. Non riesco a recuperare informazioni sulla sua dieta con gli strumenti disponibili.&#39; La terza risposta, la più completa, recita: &quot;Sarei felice di parlarti dei nostri orsi polari. Puoi trovare i nostri orsi polari nella mostra sull&#39;Artico sul sentiero polare. Qui abbiamo tre orsi polari: Fiocco di Neve, che ha 7 anni. Blizzard, che ha 5 anni. Iceberg, che ha 9 anni. Per quanto riguarda la dieta, gli orsi polari sono principalmente carnivori. Sono specializzati nella caccia alle foche, in particolare alle foche dagli anelli. Mangiano anche trichechi, balene beluga e alcuni animali terrestri.&#39;

Spiegazione del flusso degli agenti

Il sistema funziona come un team multi-agente intelligente. La procedura è gestita da una sequenza chiara per garantire un flusso fluido ed efficiente dalla domanda di un utente alla risposta finale e dettagliata.

1. L'addetto all'accoglienza dello zoo (il banco di accoglienza)

L'intero processo inizia con l'agente di accoglienza.

  • Il suo compito: avviare la conversazione. La sua istruzione è di salutare l'utente e chiedergli di quale animale vorrebbe saperne di più.
  • Il suo strumento:quando l'utente risponde, il Greeter utilizza lo strumento add_prompt_to_state per acquisire le sue parole esatte (ad es. "tell me about the lions" (dimmi qualcosa sui leoni) e salvarli nella memoria del sistema.
  • Il trasferimento: dopo aver salvato il prompt, il controllo passa immediatamente al relativo subagente, tour_guide_workflow.

2. Il ricercatore completo (il super-ricercatore)

Questo è il primo passaggio del flusso di lavoro principale e il "cervello" dell'operazione. Invece di un team numeroso, ora hai un unico agente altamente qualificato che può accedere a tutte le informazioni disponibili.

  • Il suo compito: analizzare la domanda dell'utente e formulare un piano intelligente. Utilizza la funzionalità di utilizzo degli strumenti del modello linguistico per decidere se ha bisogno di:
    • Conoscenze generali dal web (tramite l'API Wikipedia).
    • Oppure, per domande complesse, entrambe.

3. The Response Formatter (The Presenter)

Una volta che il ricercatore completo ha raccolto tutti i fatti, questo è l'ultimo agente da eseguire.

  • Il suo lavoro: fare da voce amichevole della guida del tour dello zoo. Prende i dati non elaborati (che potrebbero provenire da una o entrambe le origini) e li perfeziona.
  • Azione:sintetizza tutte le informazioni in un'unica risposta coerente e coinvolgente. Seguendo le istruzioni, prima presenta le informazioni specifiche sullo zoo e poi aggiunge i fatti generali interessanti.
  • Il risultato finale:il testo generato da questo agente è la risposta completa e dettagliata che l'utente vede nella finestra della chat.

Se ti interessa saperne di più sulla creazione di agenti, consulta le seguenti risorse:

  1. Documentazione dell'ADK
  2. Creazione di strumenti personalizzati per gli agenti ADK

11. Pulizia dell'ambiente

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina i servizi e le immagini Cloud Run

Se vuoi conservare il progetto Google Cloud, ma rimuovere le risorse specifiche create in questo lab, devi eliminare sia il servizio in esecuzione sia l'immagine container archiviata nel registro.

  • Esegui questi comandi nel terminale:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

(Facoltativo) Elimina il progetto

Se hai creato un nuovo progetto appositamente per questo lab e non prevedi di utilizzarlo di nuovo, il modo più semplice per eseguire la pulizia è eliminare l'intero progetto. In questo modo, tutte le risorse (inclusi il service account e gli artefatti di build nascosti) vengono rimosse completamente.

  • Nel terminale, esegui il comando seguente (sostituisci [YOUR_PROJECT_ID] con l'ID progetto effettivo)
    gcloud projects delete $PROJECT_ID

12. Complimenti

Hai creato ed eseguito correttamente il deployment di un'applicazione AI multi-agente su Google Cloud.

Riepilogo

In questo lab, sei passato da una directory vuota a un servizio di AI live e accessibile pubblicamente. Ecco un riepilogo di ciò che hai creato:

  • Hai creato un team specializzato: anziché un'AI generica, hai creato un "Ricercatore" per trovare i fatti e un "Formattatore" per perfezionare la risposta.
  • Hai fornito loro gli strumenti: hai connesso i tuoi agenti al mondo esterno utilizzando l'API Wikipedia.
  • Hai eseguito la spedizione: hai preso il tuo codice Python locale e l'hai sottoposto a deployment come container serverless su Cloud Run, proteggendolo con un service account dedicato.

Argomenti trattati

  • Come strutturare un progetto Python per il deployment con l'ADK.
  • Come implementare un workflow multi-agente utilizzando [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/).
  • Come integrare strumenti esterni come l'API Wikipedia.
  • Come eseguire il deployment di un agente in Cloud Run utilizzando il comando adk deploy.

13. Sondaggio

Output:

Come utilizzerai questo tutorial?

Solo leggere Leggere e completare gli esercizi