Stanowy agent Data Science Agent w środowisku wykonawczym Agent Runtime

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 Runtime, w pełni zarządzanej usłudze Google Cloud, która obsługuje infrastrukturę, skalowanie i zarządzanie sesjami.

Agent korzysta z 3 głównych funkcji, które są aktywowane kolejno:

• Zestaw narzędzi BigQuery: agent eksploruje schematy i wykonuje 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.
• Obserwacja: 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 Runtime za pomocą adk deploy
• Jak przyznać uprawnienia 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
• przeglądarka, np. Chrome;
• Jeśli kod jest uruchamiany na własnym komputerze zamiast w Cloud Shell: pakiet SDK Google Cloud (gcloud CLI), uv (menedżer pakietów Pythona) i Python 3.12 lub nowszy (instalowany automatycznie przez uv w razie potrzeby).

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 środowisku Agent Runtime.

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

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

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

2. Konfigurowanie środowiska

Tworzenie projektu Google Cloud

1. W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt w chmurze Google Cloud.
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 projektu

Otwórz edytor Cloud Shell w utworzonym projekcie GCP.

Następnie utwórz Terminal > Nowy terminal i uruchom to polecenie, aby ustawić projekt. Późniejsze polecenia odczytują identyfikator projektu z tego ustawienia.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Włącz interfejsy API

W terminalu uruchom to polecenie.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: hostuje agenta w Agent Runtime, w tym sesje Gemini Enterprise i Bank zapamiętanych informacji, oraz udostępnia model Gemini.
• 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 dalszych krokach pojawią się błędy „API not enabled” (Interfejs API nie jest włączony), poczekaj chwilę i spróbuj ponownie.

Instalowanie pakietu ADK

Aby utworzyć folder na potrzeby tego modułu i zainstalować ADK oraz jego zależności, uruchom w terminalu te polecenia:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv tworzy izolowane środowisko Pythona na potrzeby tego ćwiczenia, więc nie musisz niczego aktywować. Polecenia Pythona poprzedzaj znakiem uv run.

Pakiet google-adk zawiera narzędzie adk CLI, którego będziesz używać do testowania i wdrażania agenta. adk deploy używa google-cloud-aiplatform do tworzenia agenta w środowisku Agent Runtime, a google-cloud-bigquery to biblioteka klienta, która obsługuje narzędzia BigQuery w pakiecie ADK.

3. Tworzenie agenta

W folderze ~/adk-deploy-scale utwórz katalog agenta. Uruchom wszystkie kolejne polecenia z katalogu ~/adk-deploy-scale (katalogu nadrzędnego katalogu data_science_agent/):

mkdir data_science_agent

Następnie uruchom to polecenie, aby utworzyć data_science_agent/.env z projektem, regionem, w którym wdrożysz agenta, i ustawieniami wdrożonego agenta. adk deploy odczytuje ten plik, więc te ustawienia nadal działają, gdy otworzysz nowy terminal.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT i GOOGLE_CLOUD_LOCATION: identyfikator projektu (wypełniony na podstawie gcloud) i region, w którym działa agent.
• GOOGLE_GENAI_USE_ENTERPRISE: wywołuje Gemini za pomocą ADK w Twoim projekcie Google Cloud.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: rejestruje pełne dane wejściowe promptów i odpowiedzi agenta, co jest przydatne do debugowania.

Ustawienie OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT rejestruje pełną treść promptów użytkowników i odpowiedzi agenta w Cloud Logging. Jest to przydatne do debugowania, ale może przechwytywać 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.

Ostateczna struktura katalogów będzie wyglądać tak:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

Teraz utworzysz __init__.py i agent.py, a potem w kroku Wdrażanie dodasz requirements.txt.

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. Agent Runtime ustawia zmienną środowiskową GOOGLE_CLOUD_AGENT_ENGINE_ID, która jest nieobecna 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.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: 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 Agent 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 Runtime, 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(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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 zapamiętane informacje przed każdym wywołaniem LLM, wyszukując w Banku zapamiętanych informacji treści powiązane z wiadomością użytkownika. Funkcja _save_memory callback zapisuje sesję w Banku zapamiętanych informacji po każdym uruchomieniu agenta, dzięki czemu agent może przywołać kontekst w przyszłych sesjach.
3. Aplikacja opakowuje agenta głównego w aplikację, którą można wdrożyć i którą może obsługiwać środowisko wykonawcze agentów. 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 ma używać projektu rozliczeniowego do zapytań SQL i zapamiętywać preferencje użytkownika.
5. Gemini z client_kwargs={"location": "global"} wysyła wywołania modelu do globalnego punktu końcowego, w którym dostępna jest usługa gemini-3.8-flash. Sam agent działa w us-central1: adk deploy ustawia GOOGLE_CLOUD_LOCATION na wdrożonym agencie na region, w którym go wdrażasz, więc lokalizacja modelu jest ustawiana w kodzie.

4. Wdrażanie w środowisku Agent Runtime

Utwórz plik requirements.txt w katalogu data_science_agent:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk i google-genai: pakiet ADK i klient Gemini
• google-auth: uwierzytelnianie w Google Cloud
• google-cloud-bigquery: biblioteka klienta BigQuery, z której korzysta BigQueryToolset. ADK nie instaluje go domyślnie.
• python-dotenv: wczytuje plik .env podczas uruchamiania.
• 3 pakiety opentelemetry-instrumentation-* umożliwiają korzystanie z funkcji dostrzegalności, które poznasz później. Instrumentują wywołania modelu Gemini i wewnętrzną komunikację gRPC/HTTP, dzięki czemu ślady pojawiają się na karcie Ślady agenta.

Nie dodawaj google-cloud-aiplatform do requirements.txt, nawet jeśli została zainstalowana lokalnie. adk deploy dodaje go za Ciebie (wraz z wersją ADK, którą wdrażasz), ale tylko wtedy, gdy requirements.txt nie zawiera go jeszcze na liście. Zadeklarowanie go samodzielnie może spowodować konflikty wersji pakietu OpenTelemetry, które po cichu przerywają instrumentację, przez co ślady nie pojawiają się na karcie Ślady.

adk deploy odczytuje też utworzony wcześniej plik data_science_agent/.env i stosuje jego ustawienia do wdrożonego agenta.

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

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

Na początku danych wyjściowych pojawiają się 2 żółte linie: Ignoring GOOGLE_CLOUD_PROJECT in .env ... i Ignoring GOOGLE_CLOUD_LOCATION in .env .... Są one oczekiwane: flagi --project i --region mają pierwszeństwo przed tymi samymi wartościami w .env.

Flaga	Cel
--project/--region	Docelowy projekt w chmurze i region Google Cloud
--display_name	Czytelna nazwa wyświetlana w konsoli Cloud
--otel_to_cloud	Eksportuje logi czasu i logi OpenTelemetry do Google Cloud oraz włącza telemetrię (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) na wdrożonym agencie.

Wdrożenie zwykle zajmuje 5–10 minut. Po zakończeniu w danych wyjściowych pojawi się nazwa zasobu agenta (projects/.../reasoningEngines/) i link do wyświetlenia go w konsoli Cloud.

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.

Jeśli link wydrukowany przez adk deploy nie działa, otwórz stronę wdrożeń w konsoli Cloud i kliknij agenta.

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

• Bank zapamiętanych informacji: adk deploy łączy agenta z sesjami i Bankiem zapamiętanych informacji w instancji Agent Runtime. PreloadMemoryTool odczytuje informacje z Banku zapamiętanych informacji, a _save_memory automatycznie zapisuje sesje.
• Dostrzegalność: Cloud Trace rejestruje etapy rozumowania agenta, wywołania narzędzi i opóźnienia.

5. Przyznawanie uprawnień BigQuery

Musisz przyznać BigQuery dostęp do agenta usługi Agent Runtime (agenta usługi silnika wnioskowania AI Platform). Po wdrożeniu agent działa jako to 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 $(gcloud config get 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 $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

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

Każde polecenie w przypadku powodzenia wyświetla znak Updated IAM policy for project [...].

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

Uwaga: bigquery.dataViewer przyznaje dostęp z możliwością odczytu do wszystkich zbiorów danych w projekcie. W przypadku użycia produkcyjnego rozważ przyznanie tej roli na poziomie zbioru danych.

6. Testowanie wdrożonego agenta

Otwórz stronę wdrożeń w konsoli Google Cloud. Kliknij wdrożonego agenta, a potem kartę Playground (Piaskownica).

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: 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. „Pamiętaj, że moim ulubionym zbiorem danych jest bigquery-public-data.hacker_news”
2. „Jakie tabele zawiera?”

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

Teraz rozpocznij nową sesję, klikając Nowa sesja w trybie placu zabaw, a potem zadaj pytanie:

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

Agent powinien zapamiętać 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 jest zapisywany w Banku zapamiętanych informacji w każdej sesji 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 wyświetlić się 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ędzi, wykorzystanie tokenów i wszelkie błędy.

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

• Skierowany graf acykliczny (DAG) obejmujący 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 dla każdego zakresu (włączone za pomocą zmiennej środowiskowej OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT w .env)
• Atrybuty metadanych, takie jak identyfikatory spanó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.

Ślady mogą pojawić się po 1–2 minutach od zakończenia zapytania. Jeśli nie widzisz jeszcze żadnych śladów, poczekaj chwilę i odśwież stronę.

Jak działa śledzenie

Gdy wdrażasz za pomocą --otel_to_cloud, adk deploy tworzy kontener, który uruchamia serwer interfejsu ADK API z włączoną funkcją OpenTelemetry. W środowisku wykonawczym agentów serwer inicjuje potok OpenTelemetry, który:

1. Tworzy TracerProvider z eksporterem OTLP, który wysyła zakresy do telemetry.googleapis.com
2. Rejestruje własne zakresy ADK dotyczące uruchomień agenta, wywołań modelu i wywołań narzędzi oraz używa 3 pakietów instrumentacji z usługi requirements.txt, aby dodawać zakresy z kluczowych bibliotek (Gemini, httpx, gRPC).
3. Partie i eksporty zakresów do interfejsu Telemetry API, z którego odczytuje je karta Ślady

Wdrożony kontener zawiera ADK oraz pakiet SDK i eksporter OpenTelemetry, ale nie zawiera pakietów instrumentacji. Dlatego na liście requirements.txt znajdują się wszystkie 3 rodzaje. Bez nich serwer interfejsu ADK API rejestruje ostrzeżenie i pomija te zakresy.

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=$(gcloud config get project) | grep telemetry
2. Sprawdź, czy w Cloud Logging nie ma ostrzeżeń: otwórz Logging > Eksplorator logów i wyszukaj "proceeding without" lub "GoogleGenAiSdkInstrumentor". Ostrzeżenie, które zawiera nazwę instrumentacji (GenAI, HTTPX lub gRPC), oznacza, że w requirements.txt brakuje odpowiedniego pakietu opentelemetry-instrumentation-*.
3. Nie dodawaj google-cloud-aiplatform do requirements.txt. adk deploy dodaje go automatycznie. Zadeklarowanie go samodzielnie może spowodować konflikty pakietów OpenTelemetry i ciche przerwanie instrumentacji.

9. Czyszczenie

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

Usuń wdrożonego agenta ze strony Wdrożenia w konsoli Cloud. Wybierz agenta i kliknij Usuń.

Zapytania BigQuery w tym ćwiczeniu 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 <YOUR_PROJECT_ID>

Opcjonalnie zwalniaj miejsce w środowisku lokalnym:

cd ~
rm -rf ~/adk-deploy-scale

10. Gratulacje

Udało Ci się utworzyć agenta Data Science z zachowywaniem stanu i wdrożyć go w środowisku wykonawczym Agent Runtime.

Czego się dowiesz

• Jak utworzyć agenta ADK z BigQueryToolset, który ma dostęp do rzeczywistych danych
• Jak włączyć pamięć trwałą za pomocą banku zapamiętanych informacji przy użyciu PreloadMemoryTool i after_agent_callback
• Jak przyznać uprawnienia do konta usługi wdrożonego agenta
• Jak wdrożyć środowisko wykonawcze agentów i włączyć obserwację za pomocą Cloud Trace

Dalsze kroki

• Wykonywanie zapytań dotyczących własnych prywatnych zbiorów danych BigQuery przez przyznanie agentowi usługi Agent Runtime dostępu do danych.
• Dodaj wykonywanie kodu, aby uruchamiać analizę w Pythonie w bezpiecznej piaskownicy.
• Skonfiguruj panele obserwacji 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 Runtime
• Dokumentacja Banku zapamiętanych informacji
• Przewodnik wdrażania Agent Runtime