ADK-Agentenausführung mit dem BigQuery Agent Analytics-Plug-in analysieren

1. Einführung

In diesem Codelab erstellen Sie ein Multi-Agent-System mit dem Agent Development Kit (ADK) und aktivieren die Agent-Beobachtbarkeit mit dem BigQuery Agent Analytics-Plug-in.Sie stellen dem Agent eine Reihe von Fragen und analysieren dann mit BigQuery Konversationsverläufe und die Nutzung von Agent-Tools.

c8d3754ee87af43f.png

Aufgaben

  • Multi-Agent-Einzelhandelsassistent mit dem ADK erstellen
  • Initialisieren Sie das BigQuery Agent Analytics Plugin, um Ablaufverfolgungsdaten zur Ausführung dieses Agents in BigQuery zu erfassen und zu speichern.
  • Agent-Logdaten in BigQuery analysieren

Voraussetzungen

  • Ein Webbrowser wie Chrome
  • Ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion oder
  • Ein Gmail-Konto. Im nächsten Abschnitt erfahren Sie, wie Sie ein kostenloses Guthaben in Höhe von 5 $für dieses Codelab einlösen und ein neues Projekt einrichten.

Dieses Codelab richtet sich an Entwickler aller Erfahrungsstufen, auch an Anfänger. Sie verwenden die Befehlszeile in Google Cloud Shell und Python-Code für die ADK-Entwicklung. Sie müssen kein Python-Experte sein, aber ein grundlegendes Verständnis dafür, wie man Code liest, wird Ihnen helfen, die Konzepte zu verstehen.

2. Hinweis

Google Cloud-Projekt erstellen

  1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

c745d833b0ed52b0.png

  1. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.

  1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren:

404e4cce0f23e5c5.png

  1. Wenn Sie eine Verbindung zu Cloud Shell hergestellt haben, führen Sie diesen Befehl aus, um Ihre Authentifizierung in Cloud Shell zu überprüfen:
gcloud auth list
  1. Führen Sie den folgenden Befehl aus, um zu bestätigen, dass Ihr Projekt für die Verwendung mit gcloud konfiguriert ist:
gcloud config get project
  1. Wenn Ihr Projekt nicht wie erwartet konfiguriert ist, verwenden Sie den folgenden Befehl, um es festzulegen:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

APIs aktivieren

  1. Führen Sie den folgenden Befehl aus, um alle erforderlichen APIs und Dienste zu aktivieren:
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. Bei erfolgreicher Ausführung des Befehls sollte eine Meldung wie die unten gezeigte angezeigt werden:

Operation "operations/..." finished successfully.

3. Installation und Einrichtung

Kehren Sie zu Cloud Shell zurück und vergewissern Sie sich, dass Sie sich in Ihrem Basisverzeichnis befinden.

Führen Sie den folgenden Befehl in Cloud Shell aus, um ein neues Dataset mit dem Namen „adk_logs“ in BigQuery zu erstellen:

bq mk --dataset --location=US adk_logs

Erstellen wir nun eine virtuelle Python-Umgebung und installieren wir die erforderlichen Pakete.

  1. Öffnen Sie einen neuen Terminaltab in Cloud Shell und führen Sie diesen Befehl aus, um einen Ordner mit dem Namen adk-agent-observability zu erstellen und zu diesem Ordner zu wechseln:
mkdir adk-agent-observability
cd adk-agent-observability
  1. Erstellen Sie eine virtuelle Python-Umgebung:
python -m venv .venv
  1. Aktivieren Sie die virtuelle Umgebung:
source .venv/bin/activate
  1. ADK installieren:
pip install --upgrade google-adk

4. ADK-Anwendung erstellen

Erstellen wir nun unseren Einzelhandelsassistenten-Agent. Dieser Agent wird für Folgendes entwickelt:

  1. Führen Sie den adk create utility command aus, um eine neue Agent-Anwendung mit den erforderlichen Ordnern und Dateien zu erstellen:
adk create retail_assistant_app

Folgen Sie der Anleitung:

  1. Wählen Sie gemini-2.5-flash als Modell aus.
  2. Wählen Sie Vertex AI als Backend aus.
  3. Bestätigen Sie Ihre Standard-Google Cloud-Projekt-ID und -Region.

Hier ein Beispiel für eine Interaktion:

acc9c6bb436f7025.png

  1. Klicken Sie in Cloud Shell auf die Schaltfläche „Editor öffnen“, um den Cloud Shell-Editor zu öffnen und die neu erstellten Ordner und Dateien anzusehen:

a940b7eaf3c9f4b3.png

Sehen Sie sich die generierten Dateien an:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py::Kennzeichnet den Ordner als Python-Modul.
  • agent.py::Enthält die ursprüngliche Agent-Definition.
  • .env:Möglicherweise müssen Sie auf „Ansicht“ > „Versteckte Dateien einblenden“ klicken, um diese Datei zu sehen.

16a1a92b33f78e6b.png

  • Die Datei „.env“ enthält Umgebungsvariablen für Ihr Projekt. Aktualisieren Sie alle Variablen, die nicht korrekt über die Prompts festgelegt wurden:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Agent definieren

Definieren wir nun ein hierarchisches Multi-Agent-System.

  1. Real Time Trend Agent:Verwendet die Google Suche, um aktuelle Modetrends zu finden.
  2. Inventory Data Agent:Verwendet das BigQuery-Toolset, um das öffentliche Dataset „thelook_ecommerce“ nach verfügbaren Produkten abzufragen.
  3. Retail Assistant-Agent (Root): Orchestriert den Workflow, indem er den Trend-Agent nach Ratschlägen und den Inventory-Agent nach passenden Produkten fragt.

Ersetzen Sie den gesamten Inhalt von retail_assistant_app/agent.py durch den folgenden Code.

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. Logs mit dem BigQuery Agent Analytics-Plug-in generieren

Konfigurieren Sie nun das BigQuery Agent Analytics Plugin, um Ausführungsdaten zu erfassen.

Dazu erstellen Sie eine Instanz der Klasse App. Diese Klasse dient als Laufzeitcontainer für Ihren Agent. Sie verwaltet den Konversationszyklus, den Nutzerstatus und alle angehängten Plug-ins (z. B. unseren Agent-Analysen-Logger).

Der folgende Code:

  • Initialisiert das Logging-Plug-in:Erstellt das BigQueryAgentAnalyticsPlugin mit den erforderlichen Verbindungsdetails.
  • Plug-in einbinden:Das initialisierte BigQuery-Plug-in wird an den App-Konstruktor übergeben. So werden Ereignisse bei der Agent-Ausführung automatisch erfasst und protokolliert.
  • Agent-Ausführung ausführen und protokollieren:Der Konversationsablauf wird über runner.run_async ausgeführt. Gleichzeitig erfasst und sendet das Plug-in die gesamte Ereignissequenz an BigQuery, bevor die Ressourcen geschlossen werden.

Kopieren Sie diesen Code und fügen Sie ihn in der Datei agent.py unter den Agentendefinitionen ein:

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

async def run_all_prompts():
    """Runs all prompts in a single event loop."""
    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 in prompts:
        await main(prompt)

if __name__ == "__main__":
    asyncio.run(run_all_prompts())

Nachdem die Instrumentierung eingerichtet ist, können wir uns den Agent in Aktion ansehen. Führen Sie das Skript aus, um den Konversationsworkflow auszulösen.

python retail_assistant_app/agent.py

Sie sollten sehen, wie der Einzelhandelsassistent den Workflow orchestriert:

  1. Er bittet den Real Time Trend Agent (real_time_agent), das Wetter in London zu ermitteln und nach passenden Modetrends zu suchen.
  2. Anschließend wird der Inventory Data Agent (inventory_data_agent) aufgerufen, um das thelook_ecommerce-BigQuery-Dataset nach bestimmten Produkten abzufragen, die diesen Trends entsprechen.
  3. Schließlich fasst der Root Orchestrator die Ergebnisse in einer endgültigen Empfehlung zusammen.

Währenddessen streamt das Plug-in den Ausführungs-Trace des Agents zu BigQuery.

7. Agent-Logs analysieren

Tool-Nutzung

Wir können jetzt sehen, was unser Agent im Hintergrund gemacht hat. Die Daten wurden in BigQuery gestreamt und können jetzt analysiert werden:

  1. Suchen Sie in der Google Cloud Console nach BigQuery.
  2. Suchen Sie im Bereich Explorer nach Ihrem Projekt.
  3. Maximieren Sie das Dataset adk_logs.
  4. Öffnen Sie die Tabelle retail_assitant_agent_logs und klicken Sie auf Abfrage.

a2de3b52da21855f.png

Wenn Sie sehen möchten, welche Tool-Aufrufe Ihr Agent ausgeführt hat, und Tool-Fehler erfassen möchten, führen Sie die folgende Abfrage im BigQuery-Editor aus:

SELECT
  -- Extract the tool name directly from the JSON key "tool"
  JSON_VALUE(content, '$.tool') AS tool_name,
  -- Count every time a tool finished (successfully or with an error)
  COUNT(*) AS total_finished_runs,
  -- Count as a failure if  event_type is ERROR, result object contains a status of 'ERROR', or error_details exist
  COUNTIF(
    event_type = 'TOOL_ERROR' OR
    JSON_VALUE(content, '$.result.status') = 'ERROR' OR
    JSON_VALUE(content, '$.result.error_details') IS NOT NULL
  ) AS failure_count
FROM
  `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
  1;

Klicken Sie auf „Visualisierung“, um die Ergebnisse als Diagramm anzusehen (Ihre Ergebnisse können abweichen):

2e8d009e3e0459ed.png

Tokennutzung

Um die Kosten Ihrer Agents zu ermitteln, können Sie die von jedem einzelnen Agent verbrauchten Prompt-Tokens und Kandidaten-Tokens zusammenfassen:

SELECT
 t.agent,
 SUM(LAX_INT64(t.content.usage.prompt)) AS prompt_tokens,
 SUM(LAX_INT64(t.content.usage.completion)) AS completion_tokens
FROM
 `adk_logs.retail_assistant_agent_logs` AS t
WHERE
 t.event_type = 'LLM_RESPONSE'
 -- Filter for records that actually contain usage metadata
 AND t.content.usage IS NOT NULL
GROUP BY 1;

Klicken Sie auf „Visualisierung“, um die Ergebnisse als Diagramm anzusehen (Ihre Ergebnisse können abweichen):

134dc090ba55372d.png

8. [Bonus] Nutzerstimmung analysieren

Analysieren wir nun die Stimmung der Eingabe des Nutzers an den Agent.

  1. Erstellen Sie in Cloud Shell eine Cloud-Ressourcenverbindung, damit BigQuery mit Vertex AI-Diensten interagieren kann:
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Sie sollten eine Antwort wie die folgende sehen:

Verbindung 517325854360.us.test_connection wurde erstellt

  1. Cloud-Ressourcen-Verbindung erstellen:
export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)
  1. Führen Sie diesen Befehl aus, um zu prüfen, ob das Dienstkonto erfolgreich erstellt wurde:
echo $SERVICE_ACCOUNT_EMAIL

Ihr Dienstkonto sollte angezeigt werden:

c4a155d9d005e3d8.jpeg

  1. Erteilen Sie dem Dienstkonto der Ressourcenverbindung die Berechtigungen auf Projektebene, die für die Interaktion mit Vertex AI erforderlich sind:
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'

Es kann einige Minuten dauern, bis die Berechtigungen übernommen werden. Kehren Sie dann zu BigQuery zurück und führen Sie die folgende Abfrage mit der Funktion AI.SCORE aus, um die Nutzerstimmung zu analysieren:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', JSON_VALUE(content.text_summary),
   '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;

Mit der Funktion „AI.SCORE“ wird jeder Nutzereingabe ein Sentimentwert zwischen 1 und 5 zugewiesen. Die Ergebnisse sollten in etwa so aussehen:

4e345b703b86cde8.jpeg

9. Bereinigen

Löschen Sie die in diesem Workshop erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.

Löschen Sie das vom Skript erstellte Logging-Dataset:

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

Löschen Sie die Verbindung zur Cloud-Ressource:

bq rm --connection --project_id=$PROJECT_ID --location=us test_connection

So entfernen Sie das Verzeichnis „bigquery-adk-codelab“ und dessen Inhalt:

cd .. 
rm -rf adk-agent-observability

10. Glückwunsch

Glückwunsch! Sie haben mit dem Agent Development Kit (ADK) ein Multi-Agenten-System erstellt und das BigQuery Agent Analytics-Plug-in erfolgreich integriert, um das Verhalten Ihres Agenten zu verfolgen und zu prüfen.

Referenzdokumente