Analizowanie działania agenta ADK za pomocą wtyczki BigQuery Agent Analytics

1. Wprowadzenie

W tym laboratorium nauczysz się tworzyć system z wieloma agentami za pomocą pakietu Agent Development Kit (ADK) i włączać widoczność agenta za pomocą wtyczki BigQuery Agent Analytics.Zadasz agentowi serię pytań, a potem użyjesz BigQuery do analizowania śladów konwersacji i użycia narzędzi agenta.

c8d3754ee87af43f.png

Co musisz zrobić

  • Tworzenie wieloagentowego asystenta sprzedaży detalicznej za pomocą ADK
  • Zainicjuj wtyczkę BigQuery Agent Analytics, aby rejestrować i przechowywać w BigQuery dane śledzenia dotyczące wykonywania tego agenta.
  • Analizowanie danych z dziennika agenta w BigQuery

Czego potrzebujesz

  • przeglądarka, np. Chrome;
  • projekt Google Cloud z włączonymi płatnościami,
  • konto Gmail, W następnej sekcji dowiesz się, jak wykorzystać bezpłatne środki w wysokości 5 USD na potrzeby tego laboratorium i skonfigurować nowy projekt.

Te warsztaty są przeznaczone dla deweloperów na wszystkich poziomach zaawansowania, w tym dla początkujących. Do tworzenia ADK będziesz używać interfejsu wiersza poleceń w Google Cloud Shell i kodu w języku Python. Nie musisz być ekspertem w Pythonie, ale podstawowa wiedza o tym, jak czytać kod, pomoże Ci zrozumieć te koncepcje.

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

  1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt Google Cloud.

c745d833b0ed52b0.png

  1. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Uruchamianie Cloud Shell

Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia.

  1. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell:

404e4cce0f23e5c5.png

  1. Po połączeniu z Cloud Shell uruchom to polecenie, aby sprawdzić uwierzytelnianie w Cloud Shell:
gcloud auth list
  1. Aby sprawdzić, czy projekt jest skonfigurowany do używania z gcloud, uruchom to polecenie:
gcloud config get project
  1. Jeśli projekt nie jest skonfigurowany zgodnie z oczekiwaniami, użyj tego polecenia, aby go ustawić:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Włącz interfejsy API

  1. Aby włączyć wszystkie wymagane interfejsy API i usługi, uruchom to polecenie:
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. Po pomyślnym wykonaniu polecenia powinien wyświetlić się komunikat podobny do tego poniżej:

Operacja „operations/…” została ukończona.

3. Instalacja i konfiguracja

Wróć do Cloud Shell i upewnij się, że jesteś w katalogu domowym.

Aby utworzyć w BigQuery nowy zbiór danych o nazwie adk_logs, uruchom w Cloud Shell to polecenie:

bq mk --dataset --location=US adk_logs

Teraz utwórzmy wirtualne środowisko Pythona i zainstalujmy wymagane pakiety.

  1. Otwórz nową kartę terminala w Cloud Shell i uruchom to polecenie, aby utworzyć folder o nazwie adk-agent-observability i przejść do niego:
mkdir adk-agent-observability
cd adk-agent-observability
  1. Utwórz wirtualne środowisko Pythona:
python -m venv .venv
  1. Aktywuj środowisko wirtualne:
source .venv/bin/activate
  1. Zainstaluj ADK:
pip install --upgrade google-adk

4. Tworzenie aplikacji ADK

Teraz utwórzmy agenta, który będzie pełnił rolę asystenta w sklepie. Ten agent będzie zaprojektowany tak, aby ...

  1. Uruchom polecenie narzędzia adk create, aby utworzyć szkielet nowej aplikacji agenta z niezbędnymi folderami i plikami:
adk create retail_assistant_app

Postępuj zgodnie z wyświetlanymi instrukcjami:

  1. Wybierz model gemini-2.5-flash.
  2. Wybierz Vertex AI jako backend.
  3. Potwierdź domyślny identyfikator projektu Google Cloud i region.

Przykładowa interakcja jest pokazana poniżej:

acc9c6bb436f7025.png

  1. Kliknij przycisk Otwórz edytor w Cloud Shell, aby otworzyć edytor Cloud Shell i wyświetlić nowo utworzone foldery i pliki:

a940b7eaf3c9f4b3.png

Zwróć uwagę na wygenerowane pliki:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py: oznacza folder jako moduł Pythona.
  • agent.py: zawiera początkową definicję agenta.
  • .env: aby wyświetlić ten plik, może być konieczne kliknięcie kolejno View (Widok) > Toggle Hidden Files (Przełącz ukryte pliki).

16a1a92b33f78e6b.png

  • Plik .env zawiera zmienne środowiskowe projektu. Zaktualizuj wszystkie zmienne, które nie zostały prawidłowo ustawione w odpowiedzi na monity:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Zdefiniuj agenta

Zdefiniujmy teraz hierarchiczny system wieloagentowy.

  1. Real Time Trend Agent: korzysta z wyszukiwarki Google, aby znajdować aktualne trendy w modzie.
  2. Agent danych o asortymencie: używa zestawu narzędzi BigQuery do wysyłania zapytań do publicznego zbioru danych thelook_ecommerce o dostępne produkty.
  3. Agent asystujący w sprzedaży detalicznej (główny): koordynuje przepływ pracy, prosząc agenta ds. trendów o poradę, a agenta ds. asortymentu o pasujące produkty.

Zastąp całą zawartość pliku retail_assistant_app/agent.py tym kodem.

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. Generowanie logów za pomocą wtyczki BigQuery Agent Analytics

Teraz skonfiguruj wtyczkę BigQuery Agent Analytics, aby rejestrować dane o wykonaniu.

Aby to zrobić, utworzysz instancję klasy App. Ta klasa służy jako kontener środowiska wykonawczego dla Twojego agenta. Zarządza pętlą rozmowy, stanem użytkownika i wszystkimi dołączonymi wtyczkami (np. rejestratorem statystyk agenta).

Kod poniżej:

  • Inicjuje wtyczkę rejestrowania: tworzy obiekt BigQueryAgentAnalyticsPlugin z wymaganymi szczegółami połączenia.
  • Integruje wtyczkę: przekazuje zainicjowaną wtyczkę BigQuery do konstruktora App, dzięki czemu zdarzenia wykonania agenta są automatycznie rejestrowane i zapisywane w dzienniku.
  • Uruchamia i rejestruje wykonanie agenta: wykonuje przepływ konwersacyjny za pomocą runner.run_async, a wtyczka jednocześnie zbiera i wysyła całą sekwencję zdarzeń do BigQuery przed zamknięciem zasobów.

Skopiuj ten kod i wklej go pod definicjami agentów w pliku 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.")

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())

Po skonfigurowaniu instrumentacji możesz zobaczyć agenta w akcji. Uruchom skrypt, aby wywołać przepływ pracy rozmowy.

python retail_assistant_app/agent.py

Powinien być widoczny asystent sprzedaży detalicznej, który koordynuje przepływ pracy:

  1. Prosi agenta trendów w czasie rzeczywistym (real_time_agent) o określenie pogody w Londynie i wyszukanie odpowiednich trendów w modzie.
  2. Następnie przekazuje to zadanie do agenta danych o asortymencie (inventory_data_agent), aby wysłać zapytanie do zbioru danych BigQuerythelook_ecommerce o konkretne produkty pasujące do tych trendów.
  3. Na koniec główny koordynator łączy wyniki w ostateczną rekomendację.

W tym czasie wtyczka przesyła ślad wykonania agenta do BigQuery.

7. Analizowanie logów agenta

Korzystanie z narzędzia

Możemy teraz zobaczyć, co nasz agent robił w tle. Dane zostały przesłane strumieniowo do BigQuery i są gotowe do analizy:

  1. W konsoli Google Cloud wyszukaj BigQuery.
  2. W panelu Eksplorator znajdź projekt.
  3. Rozwiń zbiór danych adk_logs.
  4. Otwórz tabelę retail_assitant_agent_logs i kliknij Zapytanie.

a2de3b52da21855f.png

Aby sprawdzić, jakie wywołania narzędzi wykonał agent, i wychwycić błędy narzędzi, uruchom w edytorze BigQuery to zapytanie:

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;

Kliknij Wizualizacja, aby wyświetlić wyniki w formie wykresu (Twoje wyniki mogą się różnić):

2e8d009e3e0459ed.png

Wykorzystanie tokenów

Aby oszacować koszt agentów, możesz zsumować tokeny promptów i tokeny kandydatów wykorzystane przez każdego agenta:

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;

Kliknij Wizualizacja, aby wyświetlić wyniki w formie wykresu (Twoje wyniki mogą się różnić):

134dc090ba55372d.png

8. [Bonus] Analizowanie opinii użytkowników

Teraz przeanalizujmy nastawienie użytkownika, które wynika z danych wejściowych przekazanych agentowi.

  1. W Cloud Shell utwórz połączenie z zasobem w chmurze, aby umożliwić BigQuery interakcję z usługami Vertex AI:
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Powinna pojawić się odpowiedź podobna do tej:

Połączenie 517325854360.us.test_connection zostało utworzone

  1. Utwórz połączenie z zasobem Cloud:
export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)
  1. Aby sprawdzić, czy konto usługi zostało utworzone, uruchom to polecenie:
echo $SERVICE_ACCOUNT_EMAIL

Powinno się wyświetlić Twoje konto usługi:

c4a155d9d005e3d8.jpeg

  1. Przyznaj kontu usługi połączenia z zasobami uprawnienia na poziomie projektu wymagane do interakcji z 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'

Zaczekaj kilka minut na rozpowszechnienie uprawnień. Następnie wróć do BigQuery i uruchom to zapytanie zawierające funkcję AI.SCORE, aby przeanalizować nastawienie użytkowników:

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;

Funkcja AI.SCORE przypisze każdemu wpisowi użytkownika wartość nastroju z zakresu od 1 do 5. Powinny pojawić się wyniki podobne do tych:

4e345b703b86cde8.jpeg

9. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tych warsztatów.

Usuń zbiór danych logowania utworzony przez skrypt:

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

Usuń połączenie z zasobem Cloud:

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

Aby usunąć katalog bigquery-adk-codelab i jego zawartość:

cd .. 
rm -rf adk-agent-observability

10. Gratulacje

Gratulacje! Udało Ci się utworzyć system z wieloma agentami za pomocą pakietu Agent Development Kit (ADK) i zintegrować wtyczkę BigQuery Agent Analytics, aby śledzić i kontrolować zachowanie agenta.

Dokumentacja