Questa pagina è stata tradotta dall'API Cloud Translation.

Analizza l'esecuzione dell'agente ADK con il plug-in BigQuery Agent Analytics

1. Introduzione

In questo codelab, creerai un sistema multi-agente utilizzando l'Agent Development Kit (ADK) e abiliterai l'osservabilità degli agenti utilizzando il plug-in BigQuery Agent Analytics.Porrai all'agente una serie di domande, quindi utilizzerai BigQuery per analizzare le tracce delle conversazioni e l'utilizzo degli strumenti dell'agente.

Attività previste

Crea un assistente per la vendita al dettaglio multi-agente utilizzando ADK
Inizializza il plug-in BigQuery Agent Analytics per acquisire e archiviare i dati di traccia sull'esecuzione di questo agente in BigQuery
Analizzare i dati dei log dell'agente in BigQuery

Che cosa ti serve

Un browser web come Chrome
Un progetto Google Cloud con la fatturazione abilitata oppure
Un account Gmail. La sezione successiva ti mostrerà come riscattare un credito senza costi di 5 $per questo codelab e configurare un nuovo progetto.

Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti. Utilizzerai l'interfaccia a riga di comando in Google Cloud Shell e il codice Python per lo sviluppo dell'ADK. Non è necessario essere esperti di Python, ma una conoscenza di base di come leggere il codice ti aiuterà a comprendere i concetti.

2. Prima di iniziare

Crea un progetto Google Cloud

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.

Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari.

Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud:

Una volta connesso a Cloud Shell, esegui questo comando per verificare l'autenticazione in Cloud Shell:

gcloud auth list

Esegui questo comando per verificare che il tuo progetto sia configurato per l'utilizzo con gcloud:

gcloud config get project

Se il progetto non è configurato come previsto, utilizza il seguente comando per impostarlo:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Abilita API

Esegui questo comando per abilitare tutte le API e i servizi richiesti:

gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com

Se il comando viene eseguito correttamente, dovresti visualizzare un messaggio simile a quello mostrato di seguito:

Operation "operations/..." finished successfully.

3. Installazione e configurazione

Torna a Cloud Shell e assicurati di trovarti nella home directory.

Esegui questo comando in Cloud Shell per creare un nuovo set di dati denominato adk_logs in BigQuery:

bq mk --dataset --location=US adk_logs

Ora creiamo un ambiente virtuale Python e installiamo i pacchetti richiesti.

Apri una nuova scheda del terminale in Cloud Shell ed esegui questo comando per creare una cartella denominata adk-agent-observability e spostarti al suo interno:

mkdir adk-agent-observability
cd adk-agent-observability

Crea un ambiente virtuale Python:

python -m venv .venv

Attiva l'ambiente virtuale:

source .venv/bin/activate

Installa ADK:

pip install --upgrade google-adk

4. Crea un'applicazione ADK

Ora creiamo il nostro agente assistente per la vendita al dettaglio. Questo agente verrà progettato per…

Esegui il comando dell'utilità di creazione dell'ADK per creare una nuova applicazione agente con le cartelle e i file necessari:

adk create retail_assistant_app

Segui le istruzioni:

Scegli gemini-2.5-flash per il modello.
Scegli Vertex AI per il backend.
Conferma l'ID progetto Google Cloud e la regione predefiniti.

Di seguito è riportato un esempio di interazione:

Fai clic sul pulsante Apri editor in Cloud Shell per aprire l'editor di Cloud Shell e visualizzare le cartelle e i file appena creati:

Prendi nota dei file generati:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env

init.py::contrassegna la cartella come modulo Python.
agent.py: contiene la definizione iniziale dell'agente.
.env: per visualizzare questo file, potresti dover fare clic su Visualizza > Attiva/disattiva file nascosti

Il file .env contiene le variabili di ambiente per il tuo progetto. Aggiorna le variabili che non sono state impostate correttamente dai prompt:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Definisci l'agente

Definiamo ora un sistema multi-agente gerarchico.

Agente di tendenze in tempo reale: utilizza la Ricerca Google per trovare le tendenze della moda attuali.
Inventory Data Agent:utilizza il set di strumenti BigQuery per eseguire query sul set di dati pubblico thelook_ecommerce per i prodotti disponibili.
Agente assistente alla vendita al dettaglio (root):orchestra il flusso di lavoro chiedendo consiglio all'agente di tendenza e all'agente di inventario per i prodotti corrispondenti.

Sostituisci l'intero contenuto di retail_assistant_app/agent.py con il seguente codice.

import os
import uuid
import asyncio
import google.auth
import dotenv
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(
 credentials_config=credentials_config
)

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-2.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-2.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'
  
   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-2.5-flash",   
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.   
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. Genera log con il plug-in BigQuery Agent Analytics

Ora configuriamo il plug-in BigQuery Agent Analytics per acquisire i dati di esecuzione.

Per farlo, creerai un'istanza della classe App. Questa classe funge da contenitore di runtime per l'agente, gestisce il ciclo di conversazione, gestisce lo stato dell'utente e coordina tutti i plug-in collegati (come il nostro logger di analisi dell'agente).

Il codice riportato di seguito:

Inizializza il plug-in di logging:crea BigQueryAgentAnalyticsPlugin con i dettagli di connessione richiesti.
Integra il plug-in:passa il plug-in BigQuery inizializzato al costruttore App, assicurando che gli eventi di esecuzione dell'agente vengano acquisiti e registrati automaticamente.
Esecuzione di esecuzioni e log dell'agente:esegue il flusso conversazionale tramite runner.run_async, con il plug-in che raccoglie e invia simultaneamente l'intera sequenza di eventi a BigQuery prima di chiudere le risorse.

Copia e incolla questo codice sotto le definizioni dell'agente nel file agent.py:

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )
    app = App(name=APP_NAME, root_agent=root_agent, plugins=[bq_logger_plugin])
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        my_session = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

if __name__ == "__main__":
   prompts = [
       "what outfits do you have available that are suitable for the weather in london this week?",      
       "You are such a cool agent! I need a gift idea for my friend who likes yoga.",       
       "I'd like to complain - the products sold here are not very good quality!"
   ]
   for prompt, prompt in enumerate(prompts):
       asyncio.run(main(prompt))

Con la strumentazione in posizione, è il momento di vedere l'agente in azione. Esegui lo script per attivare il flusso di lavoro della conversazione.

python retail_assistant_app/agent.py

Dovresti vedere l'assistente retail orchestrare il flusso di lavoro:

Chiede all'agente per le tendenze in tempo reale (real_time_agent) di identificare il meteo a Londra e cercare tendenze di moda adatte.
Delega quindi l'agente per i dati di inventario (inventory_data_agent) a eseguire query sul set di dati BigQuery thelook_ecommerce per prodotti specifici che corrispondono a queste tendenze.
Infine, l'orchestratore principale sintetizza i risultati in un consiglio finale.

Nel frattempo, il plug-in trasmette in streaming la traccia di esecuzione dell'agente a BigQuery.

7. Analizzare i log dell'agente

Utilizzo dello strumento

Ora possiamo vedere cosa ha fatto il nostro agente dietro le quinte. I dati sono stati trasmessi in streaming a BigQuery e sono pronti per l'analisi:

Nella console Google Cloud, cerca BigQuery.
Nel riquadro Explorer, individua il progetto.
Espandi il set di dati adk_logs.
Apri la tabella retail_assitant_agent_logs e fai clic su Query.

Per vedere quali chiamate di strumenti ha effettuato il tuo agente e acquisire eventuali errori degli strumenti, esegui la seguente query nell'editor di BigQuery:

SELECT
   -- Extract text between "Tool Name: " and the next comma (or end of line)
   REGEXP_EXTRACT(content, r'Tool Name: ([^,]+)') AS tool_name,
   -- Count every time a tool finished (successfully or with an error)
   COUNT(*) AS total_finished_runs,
   -- Count it as a failure if it's an explicit system error OR contains "error" in the text
   COUNTIF(event_type = 'TOOL_ERROR' OR REGEXP_CONTAINS(content, r'(?i)\berror\b')) AS failure_count
FROM
   `.adk_logs.retail_assistant_agent_logs`
WHERE
   event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
   1

Fai clic su Visualizzazione per visualizzare i dati come grafico:

Utilizzo dei token

Per dedurre il costo degli agenti, puoi aggregare i token di prompt e i token candidati utilizzati da ogni agente distinto:

SELECT
     t.agent,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'prompt:\s*(\d+)') AS INT64)) AS prompt_tokens,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'candidates:\s*(\d+)') AS INT64)) AS candidate_tokens
   FROM
     `adk_logs.retail_assistant_agent_logs` AS t
   WHERE
     t.event_type = 'LLM_RESPONSE'
     AND t.content LIKE '%Token Usage: %'
   GROUP BY 1

Fai clic su Visualizzazione per visualizzare i dati come grafico:

8. [Bonus] Analizzare il sentiment degli utenti

Ora analizziamo il sentiment dell'input fornito all'agente dall'utente.

Crea una connessione alle risorse cloud per consentire a BigQuery di interagire con i servizi Vertex AI:

bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Dovresti visualizzare una risposta simile a questa:

Connessione 517325854360.us.test_connection creata correttamente

Crea una connessione risorsa cloud:

export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)

Esegui questo comando per verificare che il service account sia stato creato correttamente:

echo $SERVICE_ACCOUNT_EMAIL

Dovresti visualizzare il tuo service account:

Concedi all'account di servizio di connessione alle risorse le autorizzazioni a livello di progetto necessarie per interagire con Vertex AI:

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

Attendi qualche minuto, quindi esegui la funzione AI.SCORE di BigQuery per analizzare il sentiment degli utenti:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', content,
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

La funzione AI.SCORE assegnerà un valore di sentiment compreso tra 1 e 5 per ogni input dell'utente. Dovresti vedere risultati simili a quelli riportati di seguito:

9. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi, elimina le risorse create durante questo workshop.

Elimina il set di dati di logging creato dallo script:

bq rm -r -f -d $PROJECT_ID:adk_logs

Per rimuovere la directory bigquery-adk-codelab e i relativi contenuti:

cd .. 
rm -rf adk-agent-observability

10. Complimenti

Complimenti! Hai creato un sistema multi-agente con l'Agent Development Kit (ADK) e hai integrato correttamente il plug-in BigQuery Agent Analytics per monitorare e controllare il comportamento del tuo agente.