MCP と Cloud Run を使用してエンタープライズガバナンス対応エージェントをデプロイする

1. はじめに

この Codelab は、ガバナンス対応の生成 AI エージェントを構築する方法について説明する 2 部構成のシリーズの一部です。

（このシリーズの第 1 部では、Dataplex アスペクトを BigQuery テーブルに適用し、Gemini CLI を使用してルールをローカルでテストすることで、データ基盤を確立する方法について説明しています。👉 第 1 部を読む）

ただし、ローカル CLI でのテストは始まりにすぎません。これを会社全体に展開するには、一元化されたセキュリティ、標準化された AI ツール接続、エージェントのロジックをオーケストレートし、使い慣れたチャットインターフェースを提供する適切なアプリケーションフレームワークが必要です。

この第 2 部では、これらの課題を解決し、本番環境にスケーリングします。ガバナンスルールを Cloud Run でホストされている中央の MCP サーバー にデプロイします。次に、Google の Agent Development Kit（ADK） を使用して実際のエージェントアプリケーションを構築し、プロフェッショナルなウェブ UI を使用して MCP ツールに接続します。

前提条件

課金を有効にした Google Cloud プロジェクト
Cloud Run、IAM サービスアカウント、Python の基本を理解していること。
第 1 部で作成した BigQuery データセットと Dataplex アスペクト（削除してしまっても問題ありません。以下のクイックスタートスクリプトを使用して再作成できます）。

学習内容

Model Context Protocol（MCP）を使用して、AI エージェントが Google Cloud データとやり取りする方法を標準化する方法。
安全な MCP サーバーを Cloud Run にデプロイする方法。
Agent Development Kit（ADK）を使用して AI エージェントを構築し、MCP バックエンドに接続する方法。
ADK の組み込みデベロッパー UI を実行して、管理対象のエージェントを操作する方法。

必要なもの

Google Cloud Shell へのアクセス

主なコンセプト

Model Context Protocol（MCP）: MCP は、AI エージェントの「ユニバーサル USB-C ケーブル」のようなものです。すべての AI モデルにカスタム API 統合コードを記述する代わりに、MCP は AI がエンタープライズデータツール（Dataplex や BigQuery など）に安全に接続するための標準的な方法を提供します。
Agent Development Kit（ADK）: Google が設計した柔軟なオープンソースフレームワークで、AI エージェントのエンドツーエンドの開発を簡素化します。ソフトウェアエンジニアリングの原則をエージェントの作成に適用することで、複雑なツールのオーケストレーション、状態の管理、テストとデプロイのための組み込みデベロッパー UI の簡単な起動が可能になります。

2. 設定と要件

Cloud Shell の起動

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Google Cloud コンソールで、右上のツールバーにある Cloud Shell アイコンをクリックします。

Cloud Shell をアクティブにする

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

環境が接続されていることを示す Google Cloud Shell ターミナルのスクリーンショット

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホームディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

環境を初期化する

Cloud Shell を開き、プロジェクト変数を設定して、すべてのコマンドが正しいインフラストラクチャをターゲットにしていることを確認します。

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

チェックポイント: 再開または再構築

これは第 2 部なので、エージェントが機能するには第 1 部の管理対象データが必要です。パスを選択してください。

パス A: 第 1 部を完了したばかりで、リソースはまだ実行されています。

これで、作業ディレクトリに移動すると、続行できます。

cd ~/devrel-demos/data-analytics/governance-context

パス B: 第 1 部をスキップしたか、リソースを削除しました（クリーンアップ）。

対応します。以下の「クイックスタート」コマンドブロックを用意しました。これにより、BigQuery データレイクが自動的に再構築され、第 1 部と同じように Dataplex ガバナンスメタデータが適用されます。

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Dataplex Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. MCP でスケーリングする: データコントロールプレーンの構築

これまでのところ、Gemini CLI を使用してガバナンスロジックを正常にテストできました。これは迅速なプロトタイピングに最適ですが、個人のユーザー認証情報を使用してローカルで実行されます。

実際のエンタープライズ環境では、一元化されたデータコントロールプレーンが必要です。これを構築するには、Google の公式オープンソースプロジェクトであるデータベース向け GenAI ツールボックスを使用します。このツールボックスには、AI エージェントを Google Cloud データベースや Dataplex などのメタデータサービスに安全に接続するように設計された、事前構築済みの MCP サーバーが用意されています。

このツールボックスを Cloud Run の MCP サーバーとしてデプロイすることで、次のことが実現します。

一元化された ID: エージェントは、個人のユーザーアカウントではなく、制限付きサービスアカウントとして実行されます。
標準化: 標準の MCP プロトコルを使用して、任意のクライアント（ADK、Gemini、カスタムアプリ）をこのサーバーに「接続」できます。
スコープの制御（最小権限）: LLM に BigQuery へのオープンエンドアクセス権を付与しません。まず Dataplex メタデータカタログをナビゲートするように強制します。

ツール定義を構成する（`tools.yaml`）

GenAI ツールボックスには、宣言型構成ファイル tools.yaml が必要です。このファイルでは、sources（接続先）と tools（AI が実行できること）を定義します。

サーバーディレクトリに移動し、プロジェクト ID を構成ファイルに挿入します。

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

次のスニペットと同じになります。プロジェクトフィールドが実際の Google Cloud プロジェクト ID と一致していることを確認します。

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Dataplex Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Dataplex Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

🔍 詳細: ガバナンス推論ループ

YAML の tools セクションをよく見てください。3 つの特定の Dataplex ツールを明示的に公開しています。これはランダムではなく、ハルシネーションを防ぐ厳密な推論ループを形成します。

dataplex-search-aspect-types（ルールを理解する）: ユーザーが「取締役会承認済みのデータ」を要求しても、LLM はその意味を認識できません。このツールを使用して、Dataplex アスペクトタイプを検索します。「取締役会承認済み」は、GOLD_CRITICAL の階層を持つ official-data-product-spec というアスペクトに対応していることがわかります。
dataplex-search-entries（候補を検索）: LLM は検索対象を認識しているため、このツールを使用して Dataplex Catalog を検索します（たとえば、キーワード「revenue」でテーブルを検索します）。一致するリソースのリストを取得します。
dataplex-lookup-entry（事実を確認）: LLM は、SQL を記述する前に、このツールを使用して特定のテーブルの正確なメタデータを検査します。テーブルに GOLD_CRITICAL アスペクトがアタッチされていない場合、LLM はそれを拒否して検索を続けます。

これらの 3 つのツールを定義することで、AI を「読み取り専用」および「ガバナンス優先」にすることができます。

構成を保護する（Secret Manager）

エンタープライズアーキテクチャでは、構成ファイルをコンテナイメージに直接組み込むことは避ける必要があります。tools.yaml は Google Cloud Secret Manager に安全に保存します。

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

最小権限を実装する（IAM）

次に、GenAI ツールボックス MCP サーバー専用のサービスアカウントを作成します。この ID には、Dataplex カタログの読み取りと BigQuery データへのアクセスに必要な権限のみが付与されます。

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Dataplex MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Dataplex Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

MCP サーバーを Cloud Run にデプロイする

次に、GenAI ツールボックスをデプロイします。Google の事前構築済みコンテナイメージ（database-toolbox/toolbox）を使用し、Secret Manager（--set-secrets）から構成をランタイムにマウントします。

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

これで、管理対象の API が確立されました。GenAI フロントエンドにデータベースへの直接アクセス権を付与する代わりに、この Cloud Run URL に接続します。エージェントは、このツールボックスで許可されているもののみを表示できます。

4. ADK を使用してエージェントバックエンドを構築する

Cloud Run で実行される安全な管理対象データコントロールプレーン（MCP）を確立しました。AI エージェントには、ユーザー入力の処理、MCP サーバーを呼び出すタイミングの決定、出力のフォーマットなど、ロジックをオーケストレートするためのフレームワークが必要です。

このボイラープレートコードをすべてゼロから記述する代わりに、Google の Agent Development Kit（ADK）を使用します。ADK は、エージェントロジックを FastAPI バックエンドに自動的にラップするコードファーストフレームワークです。さらに、組み込みのデベロッパー UI が付属しているため、カスタムフロントエンドを最初に構築しなくても、エージェントの推論プロセスとツール呼び出しを即座に可視化できます。

エージェントロジックを検査する（agent.py）

インフラストラクチャを構成する前に、このアプリケーションのコアを見てみましょう。

ディレクトリに移動し、agent.py の内容を出力します。このファイルは、ADK デプロイの「頭脳」です。

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

コード構造を確認します。最小限のボイラープレートで次の 3 つの重要な機能を実行します。

MCPToolset の統合: Dataplex ツールとやり取りするためのカスタム HTTP クライアントを記述する代わりに、ADK は MCPToolset(server_url=mcp_url) を使用します。これにより、デプロイされた MCP サーバーから tools.yaml 定義が動的に取得され、LLM のネイティブ関数呼び出しに変換されます。
システム命令: instructions パラメータには、厳格なガバナンスルール（CLI GEMINI.md で使用したのと同じロジック）が含まれています。フェーズ 1（メタデータの検索）からフェーズ 2（データクエリ）の推論ループを実行するようにモデルに明示的に指示します。
エージェントのオーケストレーション: Agent(...) クラスは、Gemini モデル、システムプロンプト、MCP ツールをバインドします。デプロイすると、ADK はこのオブジェクトをスケーラブルな FastAPI エンドポイントに自動的に変換します。

職務の分離: フロントエンド ID を構成する

このコードを安全に実行するには、MCP サーバーの場所をエージェントに伝える必要があります。URL を動的に構築し、ADK がランタイムに読み取る .env ファイルに保存します。

また、このユーザー向けアプリケーション用に別の ID（dataplex-agent-sa）を作成します。このように職務を分離することで、フロントエンドエージェントとバックエンドガバナンスサーバーの権限が異なります。

次のコマンドを実行して、環境と ID を構成します。

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=dataplex-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Dataplex Agent "

ランタイム変数を構成する

ADK フレームワークは、環境変数を使用してコンテキストを理解します。プロジェクト ID とリージョンを明示的に設定し、Vertex AI の使用を有効にする必要があります。これらを同じ .env ファイルに追加します。

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

権限を付与する

エージェントはガバナンスチェックを MCP サーバーに委任しますが、動作するには基本的な権限が必要です。次の 2 つのロールを付与します。

Vertex AI ユーザー: 自然言語の回答を生成するために Gemini モデルを呼び出す。
Cloud Run 呼び出し元: MCP サーバー API を安全に呼び出す。BigQuery または Dataplex に直接アクセスすることはできません。

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

Cloud Run へのデプロイ

最後に、フルスタックを Cloud Run にデプロイします。

uvx を使用して、依存関係を手動でインストールせずに ADK ツールを実行します。次のコマンドは、agent.py ロジックをパッケージ化し、コンテナイメージをビルドして、サービスアカウントを挿入し、FastAPI サーバーを起動します。--with_ui フラグを追加すると、デバッグ用の ADK ウェブ Playground もバンドルされます。

このコマンドは、コンテナをビルドしてデプロイします。完了までに 1 ～ 3 分かかることがあります。

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=dataplex-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

このコマンドが完了すると、サービス URL （e.g., https://dataplex-agent-xyz.run.app）が出力されます。そのリンクをクリックして、完全に管理された GenAI チャットインターフェースを開きます。

エンドツーエンドのアーキテクチャフロー

これでシステムが完成しました。ユーザーが ADK UI を操作すると、次のシーケンスが発生します。

ユーザー が ADK エージェント（デベロッパー UI） にプロンプトを送信します。
ADK エージェント （agent.py）が入力を処理し、Gemini モデルを呼び出します。
Gemini はコンテキストが必要であると判断し、MCP サーバー に Dataplex ツールを実行するように指示します。
MCP サーバー は Dataplex ガバナンスルール を適用し、メタデータを返します。
Gemini はメタデータに基づいて信頼できる回答を合成し、ユーザーに返します。

5. エンタープライズエージェントをテストする

エージェントが公開されたので、CLI でテストしたガバナンスシナリオをもう一度見てみましょう。ロジックは変わりませんが、デプロイされた ADK ウェブ Playground を操作して、内部状態とツールの実行を可視化します。

オーケストレーション: ADK エージェント（Cloud Run で実行）がテキストを受信します。
ツールルーティング: Gemini は、質問にデータコンテキストが必要であることを認識し、リクエストを MCP サーバー に転送します。
ガバナンスチェック: MCP サーバー（別の Cloud Run インスタンスで実行）が Dataplex に特定のアスペクトタイプをクエリします。
合成: 関連するメタデータが Gemini に返され、最終的な回答が生成されます。

ガバナンスロジックを確認する

前の手順で生成したサービス URL （e.g., https://dataplex-agent-xyz.run.app）をブラウザで開きます。次のプロンプトを貼り付けます。

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

デベロッパー UI でエージェントの推論プロセスを確認します。

インテント認識: エージェントは「今すぐ」と「一晩待てない」を解析します。
メタデータの検索: MCP ツール search_aspect_types を呼び出します。update_frequency アスペクトが DAILY または MONTHLY ではなく REALTIME または STREAMING に設定されているデータアセットを探します。
選択: テーブル mkt_realtime_campaign_performance がこれらの条件を満たしていることを特定します。一方、fin_monthly_closing_internal は（高画質ですが）リクエストに対して遅すぎます。
レスポンス: エージェントはリアルタイムテーブルを推奨します。

メリット:

このガバナンスメタデータがない場合、LLM は「ad_spend」という名前の列があるという理由だけで fin_monthly_closing_internal テーブルを推奨する可能性があります。データが 24 時間前のデータであることは無視されます。メタデータコンテキストにより、ビジネスエラーを防ぐことができました。

また、「Board Meeting」プロンプトをテストして、データプロダクト階層アスペクトに基づいてエージェントが別のテーブルにピボットする方法を確認することもできます。

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. クリーンアップ

この Codelab で使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の手順に沿って、第 1 部と第 2 部で作成したすべてのインフラストラクチャを破棄します。

データレイクを破棄する（Terraform）

Terraform を使用して、BigQuery テーブル、データセット、Dataplex アスペクト定義を削除します。

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Cloud Run サービスを削除する

コンピューティングリソースを削除して、実行中のコンテナの有効な課金を停止します。

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete dataplex-agent --region=$REGION --quiet

ビルドアーティファクトとステージングストレージをクリーンアップする

uvx を使用して ADK エージェントをデプロイすると、コンテナイメージが自動的にビルドされ、ソースコードが一時的な Cloud Storage バケットにアップロードされます。これらのアーティファクトは、Cloud Run サービスが削除された後も保持され、継続的にストレージ費用が発生します。

Artifact Registry リポジトリと Cloud Storage ステージングバケットを削除します。

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

ID、権限、シークレットを削除する

最初に IAM ポリシーバインディングを削除して、プロジェクトの IAM ページに「墓石」エントリ（孤立したレコード）が残らないようにします。次に、サービスアカウントと構成シークレットを削除します。

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

ローカル構成を削除する

最後に、Cloud Shell でローカル構成ファイルと環境変数をクリーンアップします。

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. 完了

エンドツーエンドのガバナンス対応の生成 AI エージェントを正常にデプロイできました。

この 2 部構成の Codelab では、単純なプロンプトエンジニアリングから、堅牢で本番環境に対応したアーキテクチャの実装に進みました。データガバナンスを生成 AI の前提条件として扱うことで、モデルが認定されていないデータやハルシネーションデータを取得しないようにする体系的な方法を確立しました。

重要ポイント

メタデータによる決定論的 AI: LLM が列名に基づいて正しいテーブルを推測するのではなく、データベース向け GenAI ツールボックスを使用して厳密な推論ループを適用しました。3 つの Dataplex ツール（search_aspect_types、search_entries、lookup_entry）のみを明示的に公開することで、モデルが回答を合成する前にデータ認証を確認するように強制しました。
疎結合アーキテクチャ（MCP）: Cloud Run に Model Context Protocol（MCP）サーバーをデプロイすることで、データガバナンスルールを集中型で標準化された API に抽象化しました。フロントエンドエージェントにデータベースロジックを含める必要はありません。MCP 標準を介して通信するだけで済みます。つまり、今後リリースされる AI モデルやクライアントを同じ管理対象バックエンドに接続できます。
職務の分離: IAM ID を分離することで、最小権限の原則を適用しました。ユーザー向け ADK エージェントは、モデル呼び出しと API ルーティングに制限された権限で動作しますが、バックエンド MCP サーバーは Dataplex カタログのクエリと BigQuery データの取得を安全に処理します。
コードファーストエージェントのオーケストレーション: Google Agent Development Kit（ADK）を使用して、Python エージェントロジックをスケーラブルな FastAPI バックエンドに即座にラップし、組み込みのデベロッパー UI を使用してエージェントの内部ツール実行を可視化してデバッグしました。

次のステップ

Dataplex の基本的なガバナンス Codelab: AI レイヤを追加する前に、Dataplex のデータガバナンスの基本を習得します。
Dataplex ツールのドキュメント: このラボで使用されている事前構築済みの Dataplex ツールと拡張機能の公式ドキュメントをご覧ください。
Gemini CLI 拡張機能を使ってみる: 独自のカスタム拡張機能を構築して、生成 AI エージェントの機能をさらに強化する方法を学びます。
MCP の詳細: 公式の MCP 仕様を確認して、内部エンタープライズ API 用のカスタムサーバーを構築する方法を理解します。

MCP と Cloud Run を使用してエンタープライズ ガバナンス対応エージェントをデプロイする