Stanowy agent Data Science Agent w Agent Engine

1. Przegląd

W tym module dowiesz się, jak utworzyć agenta Data Science, który wysyła zapytania do rzeczywistych danych z publicznych zbiorów danych BigQuery i zapamiętuje Twoje preferencje w różnych sesjach. Następnie wdrożysz go w Agent Engine, w pełni zarządzanej usłudze Google Cloud, która obsługuje infrastrukturę, skalowanie i zarządzanie sesjami.

Agent korzysta z 3 podstawowych funkcji, które są aktywowane kolejno:

• Zestaw narzędzi BigQuery: agent eksploruje schematy i uruchamia zapytania SQL w prawdziwych zbiorach danych BigQuery. Działa to zarówno lokalnie, jak i po wdrożeniu.
• Bank zapamiętanych informacji: po wdrożeniu agent zapamiętuje preferencje użytkownika i kontekst w różnych sesjach.
• Dostrzegalność: Cloud Trace rejestruje kroki rozumowania agenta, wywołania narzędzi i opóźnienia za pomocą instrumentacji OpenTelemetry.

Czego się nauczysz

• Jak utworzyć agenta ADK z BigQueryToolset, który ma dostęp do rzeczywistych danych
• Jak skonfigurować bank zapamiętanych informacji pod kątem trwałości między sesjami
• Jak wdrożyć agenta w Agent Engine za pomocą adk deploy
• Jak przyznać uprawnienia IAM do konta usługi wdrożonego agenta
• Testowanie trwałości pamięci i obserwowalności

Czego potrzebujesz

• projekt Google Cloud z włączonymi płatnościami;
• Google Cloud SDK (gcloud CLI)
• przeglądarka, np. Chrome;
• uv (system zarządzania pakietami Pythona)
• Python 3.12 lub nowszy (w razie potrzeby instalowany automatycznie przez uv)

ADK (pakiet Agent Development Kit) to platforma Google do tworzenia agentów AI. W tym ćwiczeniu używamy pakietu ADK do utworzenia agenta i wdrożenia go w Agent Engine.

To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy znają już Pythona i Google Cloud.

Wykonanie tego laboratorium zajmuje około 30 minut (w tym 5–10 minut na wdrożenie).

Zasoby utworzone w tym laboratorium powinny kosztować mniej niż 5 USD.

2. Konfigurowanie środowiska

Tworzenie projektu Google Cloud

1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google.
2. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Ustawianie zmiennych środowiskowych

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Włącz interfejsy API

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

• AI Platform API (aiplatform.googleapis.com) – hosting Agent Engine
• BigQuery API (bigquery.googleapis.com) – zapytania SQL dotyczące publicznych i prywatnych zbiorów danych.
• Telemetry API (telemetry.googleapis.com) – ślady OpenTelemetry na potrzeby obserwacji agenta.

Włączenie interfejsu API może potrwać do minuty. Jeśli w późniejszych krokach pojawią się błędy „API not enabled” (Interfejs API nie jest włączony), poczekaj chwilę i spróbuj ponownie.

Tworzenie środowiska wirtualnego i instalowanie pakietu ADK

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

Pakiet google-adk zawiera narzędzie CLI adk, którego będziesz używać do testowania i wdrażania agenta.

3. Tworzenie agenta

Utwórz nowy katalog projektu agenta. Wszystkie kolejne polecenia należy uruchamiać z tego katalogu roboczego (katalogu nadrzędnego data_science_agent/):

mkdir data_science_agent

Ostateczna struktura katalogu będzie wyglądać tak:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

Teraz utworzysz __init__.py i agent.py, a w kroku wdrażania dodasz requirements.txt i .env.

Utwórz plik data_science_agent/__init__.py – jest on wymagany, aby ADK mógł wykryć i wczytać Twojego agenta:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Utwórz data_science_agent/agent.py:

Ten agent łączy się z BigQuery w celu wyodrębniania danych i zapisuje sesje w Banku zapamiętanych informacji.

Pamięć aktywuje się automatycznie po wdrożeniu – zmienna środowiskowa GOOGLE_CLOUD_AGENT_ENGINE_ID jest ustawiana przez środowisko wykonawcze silnika agenta i nie występuje podczas uruchamiania lokalnego.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

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

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by the Agent Engine runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Engine where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model="gemini-2.5-pro",
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Zobaczmy, co robi ten kod:

1. BigQueryToolset udostępnia agentowi narzędzia takie jak execute_sql, list_table_ids i get_table_info. Może on przeglądać schematy i wysyłać zapytania do dowolnego zbioru danych, do którego dzwoniący ma dostęp.
2. PreloadMemoryTool automatycznie pobiera odpowiednie wspomnienia przed każdym wywołaniem LLM, przeszukując Bank zapamiętanych informacji pod kątem treści związanych z wiadomością użytkownika. Funkcja _save_memory wywołania zwrotnego zapisuje sesję w Banku zapamiętanych informacji po każdym uruchomieniu agenta, dzięki czemu agent może przywoływać kontekst w przyszłych sesjach.
3. Aplikacja opakowuje agenta głównego w aplikację, którą można wdrożyć i która może być obsługiwana przez Agent Engine. name musi być zgodny z nazwą katalogu (data_science_agent) – adk web używa go do lokalizowania i wczytywania agenta.
4. Instrukcja informuje agenta, że w przypadku zapytań SQL ma używać projektu rozliczeniowego i zapamiętywać preferencje użytkownika.

4. Wdrażanie w Agent Engine

Utwórz plik requirements.txt w katalogu data_science_agent:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk i google-genai – platforma ADK i klient Gemini
• google-auth – uwierzytelnianie Google Cloud
• python-dotenv – wczytuje plik .env podczas uruchamiania.
• Cztery pakiety opentelemetry-instrumentation-* umożliwiają korzystanie z funkcji obserwacji, które poznasz później. Instrumentują żądania HTTP FastAPI, wywołania modelu Gemini i wewnętrzną komunikację gRPC/HTTP, dzięki czemu ślady pojawiają się na karcie Ślady silnika agenta.

Nie dodawaj google-cloud-aiplatform[agent-engines] do requirements.txt. Interfejs ADK Deploy CLI automatycznie dodaje tę zależność podczas wdrażania. Ponowne zadeklarowanie go w innej wersji może spowodować konflikty wersji pakietu OpenTelemetry, które po cichu przerywają instrumentację, przez co ślady nie pojawiają się na karcie Ślady.

Aby włączyć telemetrię w przypadku wdrożonego agenta, utwórz plik .env w katalogu data_science_agent:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY – aktywuje potok OpenTelemetry w środowisku wykonawczym Agent Engine.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT – loguje pełne dane wejściowe promptów i odpowiedzi agenta, co jest przydatne do debugowania.

Ustawienie OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT loguje pełną treść promptów użytkowników i odpowiedzi agenta w Cloud Logging. Jest to przydatne do debugowania, ale może rejestrować dane wrażliwe lub informacje umożliwiające identyfikację. W środowisku produkcyjnym ustaw tę wartość na false lub zadbaj o to, aby wdrożone były odpowiednie zasady obsługi danych.

Wdróż agenta. Ostatni argument data_science_agent to katalog zawierający kod agenta:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

Flaga	Cel
--project/--region	Docelowy projekt w chmurze i region Google Cloud
--display_name	Czytelna nazwa wyświetlana w konsoli Cloud
--trace_to_cloud	Włącza eksporter Cloud Trace dla zakresów agenta.
--otel_to_cloud	Włącza potok instrumentacji OpenTelemetry

Wdrożenie zwykle zajmuje 5–10 minut. Po zakończeniu zobaczysz: Created agent engine: projects/.../reasoningEngines/

W tym czasie zapoznaj się z dokumentacją Banku zapamiętanych informacji, aby dowiedzieć się więcej o tym, jak działa pamięć między sesjami.

Adres URL wydrukowany przez adk deploy może być nieprawidłowy. Jeśli link nie działa, otwórz stronę Agent Engine w Cloud Console i kliknij swojego agenta.

Po wdrożeniu w Agent Engine automatycznie aktywują się 2 funkcje:

• Bank zapamiętanych informacji: PreloadMemoryTool łączy się z bankiem zapamiętanych informacji silnika agenta i _save_memory automatycznie zapisuje sesje.
• Obserwowalność: Cloud Trace rejestruje kroki rozumowania agenta, wywołania narzędzi i opóźnienia.

5. Przyznawanie uprawnień BigQuery

Musisz przyznać BigQuery dostęp do konta usługi Agent Engine. Po wdrożeniu agent działa jako konto usługi zarządzane przez Google (a nie przy użyciu Twoich osobistych danych logowania), więc potrzebuje wyraźnych uprawnień do wykonywania zapytań SQL.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Każde polecenie wyświetla znak Updated IAM policy for project [...], jeśli zakończy się powodzeniem.

Jeśli pominiesz ten krok, wdrożony agent będzie zwracać błędy 403 podczas wykonywania zapytań SQL. Rola bigquery.jobUser jest potrzebna w projekcie rozliczeniowym (Twoim projekcie), a nie w projekcie danych.

Uwaga: bigquery.dataViewer przyznaje dostęp w trybie odczytu do wszystkich zbiorów danych w projekcie. W przypadku użycia w środowisku produkcyjnym rozważ przyznanie tej roli na poziomie zbioru danych.

6. Testowanie wdrożonego agenta

Otwórz stronę Agent Engine w konsoli Google Cloud. Kliknij wdrożonego agenta, aby otworzyć środowisko testowe Agent Engine.

Każde zapytanie może potrwać od 10 do 30 sekund, ponieważ agent analizuje, wywołuje narzędzia i zwraca wyniki.

Sprawdź możliwości BigQuery:

1. „Wyświetl listę tabel w bigquery-public-data.hacker_news”
   • Oczekiwane: agent wywołuje funkcję list_table_ids i zwraca nazwy tabel, w tym full.
2. „Znajdź liczbę postów rocznie w bigquery-public-data.hacker_news.full”
   • Oczekiwane działanie: agent wywołuje funkcję execute_sql z zapytaniem SQL i zwraca tabelę z latami i liczbą postów.
3. „Jaka była procentowa zmiana liczby postów w porównaniu z rokiem poprzednim?”
   • Oczekiwane działanie: agent wywołuje funkcję execute_sql z zapytaniem SQL, które oblicza zmianę procentową i zwraca wyniki.

7. Testowanie trwałości pamięci

Na placu zabaw naucz agenta preferencji:

1. „Zapamiętaj, że moim ulubionym zbiorem danych jest bigquery-public-data.hacker_news”.
2. „Jakie tabele zawiera?”

Poczekaj kilka sekund, aż pamięć zostanie utrwalona (wywołanie zwrotne _save_memory zostanie uruchomione po odpowiedzi agenta).

Teraz rozpocznij nową sesję, klikając przycisk „+ Nowa sesja” na pasku bocznym Playground, a następnie zadaj pytanie:

3. „What is my favorite dataset?” (Jaki jest mój ulubiony zbiór danych?)

Agent powinien przypomnieć sobie bigquery-public-data.hacker_news, mimo że jest to zupełnie nowa sesja bez historii rozmów. Działa to w ten sposób:

• _save_memory zapisuje każdą sesję w Banku zapamiętanych informacji za pomocą callback_context.add_session_to_memory().
• PreloadMemoryTool pobiera odpowiednie wspomnienia przed każdym wywołaniem LLM,
• Bank zapamiętanych informacji dopasowuje treści semantycznie, a nie tylko na podstawie słów kluczowych.

Jeśli agent nie pamięta Twoich preferencji, poczekaj 10 sekund i spróbuj ponownie w nowej sesji. Zapisywanie pamięci jest asynchroniczne i może chwilę potrwać.

8. Poznaj usługę dostrzegalności

W konsoli Cloud otwórz wdrożonego agenta i kliknij kartę Ślady.

Powinna się wyświetlić tabela sesji z sesjami z zapytań testowych uruchomionych w poprzednich krokach. Tabela zawiera podsumowanie danych dotyczących każdej sesji – średni czas trwania, wywołania modelu, wywołania narzędzia, wykorzystanie tokenów i wszelkie błędy.

Kliknij sesję, aby zbadać szczegóły logu czasu, w tym:

• Skierowany graf acykliczny (DAG) obejmujący jego zakresy, który pokazuje szczegółowy rozkład rozumowania agenta, wywołań narzędzi (zapytań BigQuery) i opóźnień.
• Dane wejściowe i wyjściowe każdego zakresu (włączone za pomocą zmiennej środowiskowej OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT w .env).
• Atrybuty metadanych, takie jak identyfikatory zakresów, identyfikatory śledzenia i czas

Możesz też przełączyć się na widok zakresu (przełącznik u góry), aby zobaczyć poszczególne zakresy we wszystkich sesjach.

Wyświetlenie śladów po zakończeniu zapytania może potrwać 1–2 minuty. Jeśli nie widzisz jeszcze żadnych śladów, poczekaj chwilę i odśwież stronę.

Jak działa śledzenie

Gdy wdrożysz agenta za pomocą --trace_to_cloud i --otel_to_cloud, środowisko wykonawcze Agent Engine zainicjuje potok OpenTelemetry, który:

1. Tworzy obiekt TracerProvider z eksporterem OTLP, który wysyła zakresy do telemetry.googleapis.com
2. Korzysta z 4 pakietów instrumentacji z requirements.txt, aby rejestrować zakresy z kluczowych bibliotek (FastAPI, Gemini, httpx, gRPC) – google-genai jest jawnie instrumentowany przez środowisko wykonawcze, a pozostałe biblioteki są instrumentowane za pomocą automatycznego wykrywania OpenTelemetry.
3. Partie i eksporty zakresów do interfejsu Telemetry API, z którego odczytuje je karta Ślady

Obraz bazowy Agent Engine udostępnia pakiet SDK OpenTelemetry i eksporter, ale nie zawiera pakietów instrumentacji. Dlatego w requirements.txt muszą być wymienione wszystkie 4 elementy – bez nich nie zostaną utworzone żadne zakresy ani ślady.

Rozwiązywanie problemów

Jeśli po kilku minutach nie pojawią się żadne ślady:

1. Sprawdź, czy interfejs Telemetry API jest włączony – został on włączony w kroku konfiguracji. Weryfikacja za pomocą: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Sprawdź, czy w Cloud Logging nie ma ostrzeżeń – otwórz Logging > Eksplorator logów i wyszukaj "telemetry enabled but proceeding without". Jeśli zobaczysz ostrzeżenie dotyczące instrumentacji generatywnej AI, oznacza to, że w requirements.txt brakuje opentelemetry-instrumentation-google-genai.
3. Nie dodawajgoogle-cloud-aiplatform[agent-engines] do requirements.txt. Interfejs ADK deploy CLI dodaje go automatycznie. Ponowne zadeklarowanie go w innej wersji może spowodować konflikty pakietów OpenTelemetry i ciche przerwanie instrumentacji.

9. Czyszczenie

Aby uniknąć bieżących opłat, usuń zasoby utworzone podczas tego laboratorium.

Usuń wdrożonego agenta ze strony Agent Engine w konsoli Cloud. Wybierz agenta i kliknij Usuń.

Zapytania BigQuery w tym samouczku korzystały z publicznych zbiorów danych, za które nie są naliczane opłaty za przechowywanie. Przyznane role uprawnień pozostaną w projekcie, ale nie będą miały wpływu na koszty.

Jeśli Twój projekt został utworzony specjalnie na potrzeby tego ćwiczenia, możesz go usunąć w całości:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Opcjonalnie zwalniaj miejsce w środowisku lokalnym:

deactivate
rm -rf .venv data_science_agent

10. Gratulacje

Udało Ci się utworzyć agenta badania danych z zachowywaniem stanu i wdrożyć go w Agent Engine.

Czego się dowiedziałeś(-aś)

• Jak utworzyć agenta ADK z BigQueryToolset, który ma dostęp do rzeczywistych danych
• Jak włączyć pamięć trwałą w Banku zapamiętanych informacji za pomocą PreloadMemoryTool i after_agent_callback
• Jak przyznać uprawnienia IAM do konta usługi wdrożonego agenta
• Jak wdrożyć w Agent Engine i włączyć dostrzegalność za pomocą Cloud Trace

Dalsze kroki

• Wysyłaj zapytania do własnych prywatnych zbiorów danych BigQuery, przyznając kontu usługi Agent Engine dostęp do swoich danych.
• Dodaj wykonywanie kodu, aby uruchamiać analizę w Pythonie w bezpiecznej piaskownicy.
• Skonfiguruj panele dostrzegalności Cloud Trace, aby monitorować agenta w środowisku produkcyjnym.
• Publikowanie wyników w Google Workspace za pomocą narzędzi MCP

Dokumentacja

• Dokumentacja pakietu ADK
• Dokumentacja Agent Engine
• Dokumentacja Banku zapamiętanych informacji
• Przewodnik wdrażania Agent Engine