Agent Engine のステートフル データ サイエンス エージェント

1. 概要

この Codelab では、BigQuery 一般公開データセットから実際のデータをクエリし、セッション間でユーザー設定を記憶するデータ サイエンス エージェントを構築します。次に、インフラストラクチャ、スケーリング、セッション管理を処理するフルマネージドの Google Cloud サービスである Agent Engine にデプロイします。

エージェントは、段階的に有効になる 3 つのコア機能を使用します。

  • BigQuery ツールセット: エージェントはスキーマを探索し、実際の BigQuery データセットに対して SQL クエリを実行します。これはローカルでもデプロイ時でも機能します。
  • メモリバンク: デプロイすると、エージェントは切断されたセッション間でユーザー設定とコンテキストを記憶します。
  • オブザーバビリティ: Cloud Trace は、OpenTelemetry 計測を使用して、エージェントの推論ステップ、ツール呼び出し、レイテンシをキャプチャします。

学習内容

  • 実際のデータにアクセスするための BigQueryToolset を使用して ADK エージェントを作成する方法
  • セッション間の永続化のためにメモリバンクを構成する方法
  • adk deploy を使用してエージェントを Agent Engine にデプロイする方法
  • デプロイされたエージェントのサービス アカウントに IAM 権限を付与する方法
  • メモリの永続性とオブザーバビリティをテストする方法

必要なもの

  • 課金を有効にした Google Cloud プロジェクト
  • Google Cloud SDK（gcloud CLI）
  • ウェブブラウザ（Chrome など）
  • uv（Python パッケージ マネージャー）
  • Python 3.12 以降（必要に応じて uv によって自動的にインストールされます）

ADK（Agent Development Kit）は、AI エージェントを構築するための Google のフレームワークです。この Codelab では、ADK を使用してエージェントを作成し、Agent Engine にデプロイします。

この Codelab は、Python と Google Cloud にある程度精通している中級レベルのデベロッパーを対象としています。

この Codelab を完了するには、約 30 分かかります（デプロイに 5 ～ 10 分かかります）。

この Codelab で作成するリソースの費用は 5 ドル未満です。

2. 環境を設定する

Google Cloud プロジェクトの作成

  1. Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
  2. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

環境変数の設定

作成した GCP プロジェクトで Cloud Shell エディタ を開きます。

次に、[ターミナル] > [新しいターミナル] を選択してターミナルを開き、次のコマンドを実行します。

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

API を有効にする

ターミナルで、次のコマンドを実行します。

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT
  • AI Platform API （aiplatform.googleapis.com） - Agent Engine ホスティング
  • BigQuery API （bigquery.googleapis.com） - 一般公開データセットと非公開データセットに対する SQL クエリ
  • Telemetry API （telemetry.googleapis.com） - エージェントのオブザーバビリティのための OpenTelemetry トレース

仮想環境を作成して ADK をインストールする

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

google-adk パッケージには、エージェントのテストとデプロイに使用する adk CLI ツールが含まれています。

3. エージェントを作成する

新しいエージェント プロジェクト ディレクトリを作成します。以降のコマンドはすべて、この作業ディレクトリ（data_science_agent/ の親）から実行する必要があります。

mkdir data_science_agent

最終的なディレクトリ構造は次のようになります。

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

ここで __init__.py と agent.py を作成し、デプロイ ステップで requirements.txt と .env を追加します。

data_science_agent/__init__.py を作成します。このファイルは、ADK がエージェントを検出して読み込むために必要です。

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

data_science_agent/agent.py を作成します。

このエージェントは、データ抽出のために BigQuery に接続し、セッションをメモリバンクに永続化します。

Memory はデプロイ時に自動的に有効になります。GOOGLE_CLOUD_AGENT_ENGINE_ID 環境変数は Agent Engine ランタイムによって設定され、ローカルで実行する場合は存在しません。

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

このコードの動作を見ていきましょう。

  1. BigQueryToolset は、エージェントに execute_sql、list_table_ids、get_table_info などのツールを提供します。これにより、スキーマを探索し、呼び出し元がアクセスできるデータセットに対してクエリを実行できます。
  2. PreloadMemoryTool は、メモリバンクでユーザーのメッセージに関連するコンテンツを検索して、各 LLM 呼び出しの前に関連するメモリを自動的に取得します。_save_memory コールバックは、エージェントの実行後にセッションをメモリバンクに永続化するため、エージェントは今後のセッションでコンテキストを呼び出すことができます。
  3. App は、ルート エージェントを Agent Engine が提供できるデプロイ可能なアプリケーションにラップします。name はディレクトリ名（data_science_agent）と一致する必要があります。adk web はこれを使用してエージェントを検索して読み込みます。
  4. instruction は、SQL クエリに課金プロジェクトを使用し、ユーザー設定を記憶するようにエージェントに指示します。

4. Agent Engine にデプロイする

data_science_agent ディレクトリに 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 と google-genai - ADK フレームワークと Gemini クライアント
  • google-auth - Google Cloud 認証
  • python-dotenv - 起動時に .env ファイルを読み込む
  • 4 つの opentelemetry-instrumentation-* パッケージを使用すると、後で説明するオブザーバビリティ機能を使用できます。FastAPI HTTP リクエスト、Gemini モデル呼び出し、内部 gRPC/HTTP 通信を計測して、トレースが Agent Engine の [トレース] タブに表示されるようにします。

data_science_agent ディレクトリに .env ファイルを作成して、デプロイされたエージェントでテレメトリーを有効にします。

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY - Agent Engine ランタイムで OpenTelemetry パイプラインを有効にします。
  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - プロンプト入力とエージェントのレスポンスを完全に記録します。デバッグに役立ちます。

エージェントをデプロイします。最後の引数 data_science_agent は、エージェント コードを含むディレクトリです。

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

フラグ

目的

--project / --region

ターゲットの Google Cloud プロジェクトとリージョン

--display_name

Cloud Console に表示される人間が読める名前

--trace_to_cloud

エージェント スパンの Cloud Trace エクスポータを有効にする

--otel_to_cloud

OpenTelemetry 計測パイプラインを有効にする

Agent Engine にデプロイすると、次の 2 つの機能が自動的に有効になります。

  • メモリバンク: PreloadMemoryTool は Agent Engine メモリバンクに接続し、_save_memory はセッションを自動的に永続化します。
  • オブザーバビリティ: Cloud Trace は、エージェントの推論ステップ、ツール呼び出し、レイテンシをキャプチャします。

5. BigQuery の権限を付与する

Agent Engine サービス アカウントに BigQuery へのアクセス権を付与する必要があります。デプロイすると、エージェントは Google マネージド サービス アカウント（個人の認証情報ではない）として実行されるため、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"

コマンドが成功すると、Updated IAM policy for project [...] と出力されます。

6. デプロイしたエージェントをテストする

Google Cloud コンソールで Agent Engine ページ を開きます。デプロイしたエージェントをクリックして、Agent Engine Playground を開きます。

BigQuery の機能をテストします。

  1. 「bigquery-public-data.hacker_news のテーブルを一覧表示する」
    • 想定される結果: エージェントは list_table_ids を呼び出し、full などのテーブル名を返します。
  2. 「bigquery-public-data.hacker_news.full の投稿数を年ごとに確認する」
    • 想定される結果: エージェントは SQL クエリで execute_sql を呼び出し、年と投稿数のテーブルを返します。
  3. 「投稿数の前年比変化率は？」
    • 想定される結果: エージェントは、変化率を計算する SQL クエリで execute_sql を呼び出し、結果を返します。

7. メモリの永続性をテストする

Playground で、エージェントに設定を教えます。

  1. 「好きなデータセットは bigquery-public-data.hacker_news であることを覚えておいて」
  2. 「どんなテーブルがある？」

メモリが永続化されるまで数秒待ちます（エージェントが応答した後に _save_memory コールバックが実行されます）。

Playground サイドバーの [+ 新しいセッション] ボタンをクリックして新しいセッションを開始 し、次の質問をします。

  1. 「好きなデータセットは？」

エージェントは、会話履歴のない新しいセッションであっても、bigquery-public-data.hacker_news を呼び出す必要があります。その理由は次のとおりです。

  • _save_memory は、callback_context.add_session_to_memory() を介して各セッションをメモリバンクに永続化します。
  • PreloadMemoryTool は、各 LLM 呼び出しの前に関連するメモリを取得します。
  • メモリバンクは、キーワードだけでなく、コンテンツをセマンティックに照合します。

8. オブザーバビリティを確認する

Cloud Console で、デプロイしたエージェントに移動し、[トレース] タブをクリックします。

セッション テーブルを示す [トレース] タブ

前のステップで実行したテストクエリのセッションが一覧表示されたセッション テーブル が表示されます。このテーブルには、各セッションの概要指標（平均時間、モデル呼び出し、ツール呼び出し、トークンの使用量、エラー）が表示されます。

セッション をクリックすると、次のトレースの詳細を確認できます。

  • スパンの有向非巡回グラフ（DAG） - エージェントの推論、ツール呼び出し（BigQuery クエリ）、レイテンシの詳細な内訳を示します。
  • 各スパンの入力と出力 （.env の OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 環境変数で有効にします）
  • スパン ID、トレース ID、タイミングなどのメタデータ属性

[スパンビュー]（上部の切り替え）に切り替えて、すべてのセッションの個々のスパンを表示することもできます。

トレースの仕組み

--trace_to_cloud と --otel_to_cloud を使用してデプロイすると、Agent Engine ランタイムは次の OpenTelemetry パイプラインを初期化します。

  1. スパンを telemetry.googleapis.com に送信する OTLP エクスポータを使用してTracerProvider を作成します。
  2. requirements.txt の 4 つの計測パッケージ を使用して、主要なライブラリ（FastAPI、Gemini、httpx、gRPC）からスパンをキャプチャします。google-genai はランタイムによって明示的に計測されますが、他のライブラリは OpenTelemetry 自動検出を介して貢献します。
  3. スパンをバッチ処理して Telemetry API にエクスポートします。この API で [トレース] タブにスパンが表示されます。

Agent Engine ベースイメージには OpenTelemetry SDK とエクスポータが用意されていますが、計測パッケージは含まれていません 。そのため、requirements.txt に 4 つすべてをリストする必要があります。これがないと、スパンが作成されず、トレースが表示されません。

トラブルシューティング

数分経ってもトレースが表示されない場合:

  1. Telemetry API が有効になっていることを確認します 。これは設定ステップで有効にしました。gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry で確認します。
  2. Cloud Logging で警告を確認します 。[ロギング] > [ログ エクスプローラ] に移動し、"telemetry enabled but proceeding without" を検索します。GenAI 計測に関する警告が表示された場合は、opentelemetry-instrumentation-google-genai が requirements.txt にありません。
  3. requirements.txt に google-cloud-aiplatform[agent-engines] を追加しないでください 。ADK deploy CLI は自動的に追加します。別のバージョンで再宣言すると、OpenTelemetry パッケージの競合が発生し、計測がサイレントに中断される可能性があります。

9. クリーンアップ

継続的な課金を避けるため、この Codelab で作成したリソースを削除します。

Cloud Console の Agent Engine ページからデプロイしたエージェントを削除 します。エージェントを選択して [削除] をクリックします。

この Codelab 専用のプロジェクトを作成した場合は、プロジェクト全体を削除できます。

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

必要に応じて、ローカル環境をクリーンアップします。

deactivate
rm -rf .venv data_science_agent

10. 完了

ステートフル データ サイエンス エージェントを構築し、Agent Engine にデプロイしました。

学習した内容

  • 実際のデータにアクセスするための BigQueryToolset を使用して ADK エージェントを作成する方法
  • PreloadMemoryTool と after_agent_callback を使用してメモリバンクで永続メモリを有効にする方法
  • デプロイされたエージェントのサービス アカウントに IAM 権限を付与する方法
  • Agent Engine にデプロイし、Cloud Trace でオブザーバビリティを有効にする方法

次のステップ

  • Agent Engine サービス アカウントにデータへのアクセス権を付与して、独自の非公開 BigQuery データセットにクエリを実行する
  • コード実行を追加して、安全なサンドボックスで Python 分析を実行する
  • Cloud Trace オブザーバビリティ ダッシュボードを設定して、本番環境のエージェントをモニタリングする
  • MCP ツールを使用して結果を Google Workspace に公開する

リファレンス ドキュメント