Zustandsbehafteter Data Science Agent in der Agent Engine

1. Übersicht

In diesem Codelab erstellen Sie einen Data-Science-Agenten, der echte Daten aus öffentlichen BigQuery-Datasets abfragt und sich Ihre Einstellungen sitzungsübergreifend merkt. Anschließend stellen Sie ihn in der Agent Engine bereit, einem vollständig verwalteten Google Cloud-Dienst, der sich um die Infrastruktur, Skalierung und Sitzungsverwaltung kümmert.

Der Agent verwendet drei Kernfunktionen, die nach und nach aktiviert werden:

• BigQuery-Toolset: Der Agent untersucht Schemas und führt SQL-Abfragen für echte BigQuery-Datasets aus. Das funktioniert sowohl lokal als auch bei der Bereitstellung.
• Memory Bank: Bei der Bereitstellung merkt sich der Agent Nutzereinstellungen und den Kontext über getrennte Sitzungen hinweg.
• Beobachtbarkeit: Cloud Trace erfasst die Denkprozesse, Toolaufrufe und Latenzen des Agenten über die OpenTelemetry-Instrumentierung.

Lerninhalte

• Erstellen eines ADK-Agenten mit BigQueryToolset für den Zugriff auf echte Daten
• Konfigurieren von Memory Bank für die sitzungsübergreifende Persistenz
• Bereitstellen des Agenten in der Agent Engine mit adk deploy
• Gewähren von IAM-Berechtigungen für das Dienstkonto des bereitgestellten Agenten
• Testen der Speicherpersistenz und Beobachtbarkeit

Voraussetzungen

• Ein Google Cloud-Projekt mit aktivierter Abrechnung
• Google Cloud SDK (gcloud CLI)
• Ein Webbrowser wie Chrome
• uv (Python-Paketmanager)
• Python 3.12 oder höher (wird bei Bedarf automatisch von uv installiert)

Das ADK (Agent Development Kit) ist das Framework von Google zum Erstellen von KI-Agenten. In diesem Codelab wird das ADK verwendet, um einen Agenten zu erstellen und ihn in der Agent Engine bereitzustellen.

Dieses Codelab richtet sich an fortgeschrittene Entwickler, die mit Python und Google Cloud vertraut sind.

Für dieses Codelab benötigen Sie etwa 30 Minuten (einschließlich 5–10 Minuten für die Bereitstellung).

Die in diesem Codelab erstellten Ressourcen sollten weniger als 5 $kosten.

2. Umgebung einrichten

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Umgebungsvariablen festlegen

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

APIs aktivieren

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

• AI Platform API (aiplatform.googleapis.com) – Agent Engine-Hosting
• BigQuery API (bigquery.googleapis.com) – SQL-Abfragen für öffentliche und private Datasets
• Telemetry API (telemetry.googleapis.com) – OpenTelemetry-Traces für die Beobachtbarkeit des Agenten

Es kann bis zu einer Minute dauern, bis die API-Aktivierung wirksam wird. Wenn in späteren Schritten Fehler vom Typ „API nicht aktiviert“ angezeigt werden, warten Sie einen Moment und versuchen Sie es noch einmal.

Virtuelle Umgebung erstellen und ADK installieren

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

Das Paket google-adk enthält das adk-CLI-Tool, mit dem Sie den Agenten testen und bereitstellen.

3. Agent erstellen

Erstellen Sie ein neues Agent-Projektverzeichnis. Alle nachfolgenden Befehle sollten in diesem Arbeitsverzeichnis (dem übergeordneten Verzeichnis von data_science_agent/) ausgeführt werden:

mkdir data_science_agent

Die endgültige Verzeichnisstruktur sieht so aus:

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

Sie erstellen jetzt __init__.py und agent.py und fügen dann im Bereitstellungsschritt requirements.txt und .env hinzu.

Erstellen Sie data_science_agent/__init__.py. Diese Datei ist erforderlich, damit das ADK Ihren Agenten erkennen und laden kann:

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

Erstellen Sie data_science_agent/agent.py:

Dieser Agent stellt eine Verbindung zu BigQuery her, um Daten zu extrahieren, und speichert Sitzungen in Memory Bank.

Memory wird bei der Bereitstellung automatisch aktiviert. Die Umgebungsvariable GOOGLE_CLOUD_AGENT_ENGINE_ID wird von der Agent Engine-Laufzeit festgelegt und ist bei der lokalen Ausführung nicht vorhanden.

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

Sehen wir uns an, was dieser Code tut:

1. BigQueryToolset bietet dem Agenten Tools wie execute_sql, list_table_ids und get_table_info. Er kann Schemas untersuchen und jedes Dataset abfragen, auf das der Aufrufer Zugriff hat.
2. PreloadMemoryTool ruft vor jedem LLM-Aufruf automatisch relevante Informationen ab, indem es in Memory Bank nach Inhalten sucht, die sich auf die Nachricht des Nutzers beziehen. Der Callback _save_memory speichert die Sitzung nach jeder Ausführung des Agenten in Memory Bank, sodass sich der Agent in zukünftigen Sitzungen an den Kontext erinnern kann.
3. App verpackt den Root-Agenten in eine bereitstellbare Anwendung, die von der Agent Engine bereitgestellt werden kann. Der name muss mit dem Verzeichnisnamen (data_science_agent) übereinstimmen. adk web verwendet ihn, um den Agenten zu finden und zu laden.
4. Die Anweisung weist den Agenten an, das Abrechnungsprojekt für SQL-Abfragen zu verwenden und sich Nutzereinstellungen zu merken.

4. In der Agent Engine bereitstellen

Erstellen Sie im Verzeichnis data_science_agent eine Datei requirements.txt:

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 und google-genai – das ADK-Framework und der Gemini-Client
• google-auth – Google Cloud-Authentifizierung
• python-dotenv – lädt die Datei .env beim Start
• Die vier Pakete opentelemetry-instrumentation-* aktivieren die Beobachtbarkeitsfunktionen, die Sie später kennenlernen. Sie instrumentieren FastAPI-HTTP-Anfragen, Gemini-Modellaufrufe und die interne gRPC/HTTP-Kommunikation, sodass Traces auf dem Tab „Traces“ der Agent Engine angezeigt werden.

Fügen Sie google-cloud-aiplatform[agent-engines] nicht zu requirements.txt hinzu. Die ADK-CLI für die Bereitstellung fügt diese Abhängigkeit während der Bereitstellung automatisch hinzu. Wenn Sie sie mit einer anderen Version noch einmal deklarieren, kann das zu OpenTelemetry-Paketversionskonflikten führen, die die Instrumentierung unbemerkt unterbrechen, sodass keine Traces auf dem Tab „Traces“ angezeigt werden.

Erstellen Sie im Verzeichnis data_science_agent eine Datei .env, um die Telemetrie für den bereitgestellten Agenten zu aktivieren:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY – aktiviert die OpenTelemetry-Pipeline in der Agent Engine-Laufzeit.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT – protokolliert vollständige Prompt-Eingaben und Agentenantworten, was für das Debugging nützlich ist.

Die Einstellung OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT protokolliert den vollständigen Inhalt von Nutzer-Prompts und Agentenantworten in Cloud Logging. Das ist nützlich für das Debugging, kann aber sensible Daten oder personenidentifizierbare Informationen erfassen. Legen Sie in der Produktion für diese Einstellung false fest oder sorgen Sie für entsprechende Richtlinien zur Datenverarbeitung.

Stellen Sie den Agenten bereit. Das letzte Argument data_science_agent ist das Verzeichnis mit Ihrem Agentencode:

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

Flag	Zweck
--project / --region	Google Cloud-Zielprojekt und ‑region
--display_name	Für Menschen lesbarer Name, der in der Cloud Console angezeigt wird
--trace_to_cloud	Aktiviert den Cloud Trace-Exporter für Agent-Spans
--otel_to_cloud	Aktiviert die OpenTelemetry-Instrumentierungspipeline

Die Bereitstellung dauert in der Regel 5–10 Minuten. Wenn sie abgeschlossen ist, sehen Sie: Created agent engine: projects/.../reasoningEngines/

Während Sie warten, können Sie sich die Memory Bank-Dokumentation ansehen, um mehr über die sitzungsübergreifende Memory-Funktion zu erfahren.

Die von adk deploy ausgegebene URL ist möglicherweise falsch. Wenn der Link nicht funktioniert, rufen Sie in der Cloud Console die Seite „Agent Engine“ auf und klicken Sie stattdessen auf Ihren Agenten.

Bei der Bereitstellung in der Agent Engine werden zwei Funktionen automatisch aktiviert:

• Memory Bank: PreloadMemoryTool stellt eine Verbindung zu Memory Bank der Agent Engine her und _save_memory speichert Sitzungen automatisch.
• Beobachtbarkeit: Cloud Trace erfasst die Denkprozesse, Toolaufrufe und Latenzen des Agenten.

5. BigQuery-Berechtigungen gewähren

Sie müssen dem Agent Engine-Dienstkonto Zugriff auf BigQuery gewähren. Bei der Bereitstellung wird der Agent als von Google verwaltetes Dienstkonto ausgeführt (nicht mit Ihren persönlichen Anmeldedaten). Daher sind explizite Berechtigungen zum Ausführen von SQL-Abfragen erforderlich.

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"

Bei jedem erfolgreichen Befehl wird Updated IAM policy for project [...] ausgegeben.

Wenn Sie diesen Schritt überspringen, gibt der bereitgestellte Agent bei der Ausführung von SQL-Abfragen 403-Fehler zurück. Die Rolle bigquery.jobUser ist für das Abrechnungsprojekt (Ihr Projekt) erforderlich, nicht für das Datenprojekt.

Hinweis: bigquery.dataViewer gewährt Lesezugriff auf alle Datasets in Ihrem Projekt. Für die Produktion sollten Sie diese Rolle stattdessen auf Dataset-Ebene gewähren.

6. Bereitgestellten Agenten testen

Öffnen Sie in der Google Cloud Console die Seite „Agent Engine“. Klicken Sie auf Ihren bereitgestellten Agenten, um den Agent Engine-Playground zu öffnen.

Jede Abfrage kann 10–30 Sekunden dauern, da der Agent Denkprozesse durchführt, Tools aufruft und Ergebnisse zurückgibt.

Testen Sie die BigQuery-Funktionen:

1. „List the tables in bigquery-public-data.hacker_news“
   • Erwartet: Der Agent ruft list_table_ids auf und gibt Tabellennamen einschließlich full zurück.
2. „Find the number of posts per year in bigquery-public-data.hacker_news.full“
   • Erwartet: Der Agent ruft execute_sql mit einer SQL-Abfrage auf und gibt eine Tabelle mit Jahren und der Anzahl der Beiträge zurück.
3. „What was the year-over-year percentage change in posts?“
   • Erwartet: Der Agent ruft execute_sql mit einer SQL-Abfrage auf, die die prozentuale Änderung berechnet, und gibt die Ergebnisse zurück.

7. Speicherpersistenz testen

Weisen Sie dem Agenten im Playground eine Einstellung zu:

1. „Remember that my favorite dataset is bigquery-public-data.hacker_news“
2. „What tables does it have?“

Warten Sie einige Sekunden, bis der Speicher persistent ist. Der Callback _save_memory wird ausgeführt, nachdem der Agent geantwortet hat.

Starten Sie jetzt eine neue Sitzung , indem Sie in der Seitenleiste des Playground auf die Schaltfläche „+ Neue Sitzung“ klicken, und fragen Sie dann:

3. „What is my favorite dataset?“

Der Agent sollte sich an bigquery-public-data.hacker_news erinnern, obwohl dies eine brandneue Sitzung ohne Unterhaltungsverlauf ist. Das funktioniert so:

• _save_memory speichert jede Sitzung über callback_context.add_session_to_memory() in Memory Bank.
• PreloadMemoryTool ruft vor jedem LLM-Aufruf relevante Informationen ab.
• Memory Bank vergleicht Inhalte semantisch, nicht nur anhand von Schlüsselwörtern.

Wenn sich der Agent nicht an Ihre Einstellung erinnert, warten Sie 10 Sekunden und versuchen Sie es in einer anderen neuen Sitzung noch einmal. Die Speicherpersistenz ist asynchron und kann einige Zeit dauern.

8. Beobachtbarkeit kennenlernen

Rufen Sie in der Cloud Console Ihren bereitgestellten Agenten auf und klicken Sie auf den Tab Traces.

Sie sollten eine Sitzungstabelle mit den Sitzungen aus den Testabfragen sehen, die Sie in den vorherigen Schritten ausgeführt haben. Die Tabelle enthält zusammenfassende Messwerte für jede Sitzung: durchschnittliche Dauer, Modellaufrufe, Toolaufrufe, Tokennutzung und alle Fehler.

Klicken Sie auf eine Sitzung , um die Tracedetails zu prüfen, einschließlich:

• Ein gerichteter azyklischer Graph (DAG) der Spans, der die schrittweise Aufschlüsselung der Denkprozesse des Agenten, der Toolaufrufe (BigQuery-Abfragen) und der Latenzen zeigt
• Ein- und Ausgaben für jeden Span (aktiviert über die Umgebungsvariable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT in .env)
• Metadatenattribute wie Span-IDs, Trace-IDs und Timing

Sie können auch zur Span-Ansicht wechseln (oben umschalten), um einzelne Spans in allen Sitzungen zu sehen.

Es kann 1–2 Minuten dauern, bis Traces nach Abschluss einer Abfrage angezeigt werden. Wenn noch keine Traces angezeigt werden, warten Sie einen Moment und aktualisieren Sie die Seite.

Funktionsweise von Tracing

Wenn Sie mit --trace_to_cloud und --otel_to_cloud bereitstellen, initialisiert die Agent Engine-Laufzeit eine OpenTelemetry-Pipeline, die Folgendes tut:

1. Erstellt einen TracerProvider mit einem OTLP-Exporter, der Spans an telemetry.googleapis.com sendet
2. Verwendet die vier Instrumentierungspakete aus requirements.txt, um Spans aus wichtigen Bibliotheken (FastAPI, Gemini, httpx, gRPC) zu erfassen. google-genai wird explizit von der Laufzeit instrumentiert, während die anderen über die automatische OpenTelemetry-Erkennung beitragen.
3. Batcht und exportiert Spans an die Telemetry API, wo sie auf dem Tab „Traces“ gelesen werden

Das Basis-Image der Agent Engine enthält das OpenTelemetry SDK und den Exporter, aber nicht die Instrumentierungspakete. Daher müssen in requirements.txt alle vier aufgeführt sein. Andernfalls werden keine Spans erstellt und keine Traces angezeigt.

Fehlerbehebung

Wenn nach einigen Minuten keine Traces angezeigt werden, gehen Sie so vor:

1. Prüfen Sie, ob die Telemetry API aktiviert ist. Sie haben sie im Einrichtungsschritt aktiviert. Bestätigen Sie mit: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Prüfen Sie in Cloud Logging auf Warnungen. Rufen Sie Logging > Log-Explorer auf und suchen Sie nach "telemetry enabled but proceeding without". Wenn Sie eine Warnung zur GenAI-Instrumentierung sehen, fehlt opentelemetry-instrumentation-google-genai in requirements.txt.
3. Fügen Sie google-cloud-aiplatform[agent-engines] nicht zu requirements.txt hinzu. Die ADK-CLI für die Bereitstellung fügt sie automatisch hinzu. Wenn Sie sie mit einer anderen Version noch einmal deklarieren, kann das zu OpenTelemetry-Paketkonflikten führen und die Instrumentierung unbemerkt unterbrechen.

9. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Kosten zu vermeiden.

Löschen Sie den bereitgestellten Agenten auf der Seite „Agent Engine“ in der Cloud Console. Wählen Sie Ihren Agenten aus und klicken Sie auf Löschen.

Für die BigQuery-Abfragen in diesem Codelab wurden öffentliche Datasets verwendet, für die keine Speicherkosten anfallen. Die von Ihnen gewährten IAM-Rollen bleiben im Projekt, haben aber keine Auswirkungen auf die Kosten.

Wenn Sie ein Projekt speziell für dieses Codelab erstellt haben, können Sie stattdessen das gesamte Projekt löschen:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Optional können Sie Ihre lokale Umgebung bereinigen:

deactivate
rm -rf .venv data_science_agent

10. Glückwunsch

Sie haben einen zustandsbehafteten Data Science Agenten erstellt und ihn in der Agent Engine bereitgestellt.

Lerninhalte

• Erstellen eines ADK-Agenten mit BigQueryToolset für den Zugriff auf echte Daten
• Aktivieren des persistenten Speichers mit Memory Bank mithilfe von PreloadMemoryTool und after_agent_callback
• Gewähren von IAM-Berechtigungen für das Dienstkonto des bereitgestellten Agenten
• Bereitstellen in der Agent Engine und Aktivieren der Beobachtbarkeit mit Cloud Trace

Nächste Schritte

• Eigene private BigQuery-Datasets abfragen, indem Sie dem Agent Engine-Dienstkonto Zugriff auf Ihre Daten gewähren
• Codeausführung hinzufügen, um Python-Analysen in einer sicheren Sandbox auszuführen
• Richten Sie Cloud Trace-Dashboards für die Beobachtbarkeit ein, um Ihren Agenten in der Produktion zu überwachen
• Ergebnisse mit MCP-Tools in Google Workspace veröffentlichen

Referenzdokumente

• ADK-Dokumentation
• Agent Engine-Dokumentation
• Memory Bank-Dokumentation
• Bereitstellungsleitfaden für die Agent Engine