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 プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

環境変数の設定

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 トレース

API の有効化が反映されるまでに 1 分ほどかかることがあります。後の手順で「API が有効になっていない」というエラーが表示された場合は、しばらく待ってから再試行してください。

仮想環境を作成して 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 に接続し、セッションをメモリバンクに保持します。

メモリはデプロイ時に自動的に有効になります。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 呼び出しの前に、ユーザーのメッセージに関連するコンテンツを Memory Bank で検索して、関連するメモリを自動的に取得します。_save_memory コールバックは、各エージェントの実行後にセッションをメモリバンクに保持するため、エージェントは将来のセッションでコンテキストを呼び出すことができます。
3. App は、ルート エージェントを Agent Engine が提供できるデプロイ可能なアプリケーションにラップします。name はディレクトリ名（data_science_agent）と一致する必要があります。adk web はこれを使用してエージェントを検索して読み込みます。
4. 指示は、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 の [トレース] タブに表示されるようにします。

requirements.txt に google-cloud-aiplatform[agent-engines] を追加しないでください。ADK デプロイ CLI は、デプロイ時にこの依存関係を自動的に追加します。別のバージョンで再宣言すると、OpenTelemetry パッケージのバージョンの競合が発生し、計測がサイレントに中断され、[トレース] タブにトレースが表示されなくなる可能性があります。

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 - プロンプト入力とエージェントの回答をすべてログに記録します。デバッグに役立ちます。

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 設定では、ユーザー プロンプトとエージェント レスポンスの完全な内容が Cloud Logging に記録されます。これはデバッグに役立ちますが、センシティブ データや個人情報（PII）がキャプチャされる可能性があります。本番環境では、これを false に設定するか、適切なデータ処理ポリシーが設定されていることを確認します。

エージェントをデプロイします。最後の引数 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 コンソールに表示される人間が読める名前
--trace_to_cloud	エージェント スパンの Cloud Trace エクスポーターを有効にします
--otel_to_cloud	OpenTelemetry 計測パイプラインを有効にします

通常、デプロイには 5 ～ 10 分かかります。完了すると、Created agent engine: projects/.../reasoningEngines/ と表示されます。

その間、メモリバンクのドキュメントで、セッション間のメモリの仕組みについてご確認ください。

adk deploy で印刷された URL が正しくない場合があります。リンクが機能しない場合は、Cloud コンソールの Agent Engine ページに移動して、エージェントをクリックします。

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 [...] を出力します。

この手順を省略すると、デプロイされたエージェントは SQL クエリの実行時に 403 エラーを返します。bigquery.jobUser ロールは、データ プロジェクトではなく、課金プロジェクト（自分のプロジェクト）に必要です。

注: bigquery.dataViewer は、プロジェクト内のすべてのデータセットに対する読み取りアクセス権を付与します。本番環境で使用する場合は、代わりにデータセット レベルでこのロールを付与することを検討してください。

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

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

エージェントが推論し、ツールを呼び出し、結果を返すため、各クエリの完了に 10 ～ 30 秒かかることがあります。

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. メモリの永続性をテストする

プレイグラウンドで、エージェントに優先順位を教えます。

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

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

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

3. 「お気に入りのデータセットは何ですか？」

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

• _save_memory は、callback_context.add_session_to_memory() を介して各セッションをメモリバンクに保持します。
• PreloadMemoryTool は、各 LLM 呼び出しの前に関連するメモリを取得します。
• メモリバンクは、キーワードだけでなく、コンテンツの意味に基づいて一致させます

エージェントがお客様の設定を思い出せない場合は、10 秒待ってから別の新しいセッションで再度お試しください。メモリの永続性は非同期であり、完了までにしばらく時間がかかることがあります。

8. オブザーバビリティの詳細

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

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

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

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

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

クエリの完了後、トレースが表示されるまでに 1 ～ 2 分かかることがあります。トレースがまだ表示されない場合は、しばらく待ってからページを更新してください。

トレースの仕組み

--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 にバッチ処理してエクスポートします。ここで、[トレース] タブがスパンを読み取ります。

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

トラブルシューティング

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

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

9. クリーンアップ

継続的な課金が発生しないようにするには、この Codelab で作成したリソースを削除します。

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

この Codelab の BigQuery クエリでは、一般公開データセットを使用しました。このデータセットでは、ストレージ料金は発生しません。付与した IAM ロールはプロジェクトに残りますが、費用には影響しません。

この 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 に公開する

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

• ADK ドキュメント
• Agent Engine のドキュメント
• メモリバンクのドキュメント
• Agent Engine デプロイガイド