Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

1. はじめに

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

（このシリーズの第 1 部では、ナレッジカタログのアスペクトタイプを登録し、BigQuery テーブルにアスペクトを適用し、AGY CLI を介してルールをローカルでテストすることで、データ基盤を確立する方法について説明しています。👉 パート 1 を読む）

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

この第 2 部では、これらの課題を解決し、本番環境にスケーリングします。カスタム MCP サーバーをデプロイする代わりに、エージェントを Google が管理する Knowledge Catalog MCP サーバーに直接接続します。次に、Google の Agent Development Kit（ADK）を使用して実際のエージェントアプリケーションを構築し、ローカルエージェントスキルからガバナンスルールを読み込んで、プロフェッショナルなウェブ UI を備えた Cloud Run にデプロイします。

ユーザーが ADK UI を操作すると、次のシーケンスが発生します。

学習内容

Model Context Protocol（MCP）を使用して、AI エージェントが Google Cloud データとやり取りする方法を標準化する方法。
ADK エージェントが Google マネージド Knowledge Catalog MCP サーバーに接続する方法。
共有エージェントスキルからガバナンスルールを動的に読み込む方法。
エージェントを Cloud Run にデプロイし、ADK の組み込みウェブプレイグラウンドを実行する方法。

必要なもの

課金を有効にした Google Cloud プロジェクト
Google Cloud Shell へのアクセス。
Cloud Run、IAM サービスアカウント、Python の基本的な知識。
パート 1 で作成した BigQuery データセットと Knowledge Catalog アスペクト。（削除してしまっても問題ありません。以下に、再作成するための高速トラックスクリプトを用意しています）。

主なコンセプト

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

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"

必要な API の有効化

データ基盤の管理、Vertex AI モデルの実行、Cloud Run での ADK エージェントのホストに必要な最小限の Google Cloud APIs を有効にします。

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

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

これはパート 2 であるため、エージェントが機能するにはパート 1 のガバナンスデータが必要です。以下のいずれかを選択してください。

パス A: パート 1 を完了したばかりで、リソースがまだ実行されている

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

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

パス B: パート 1 をスキップした、またはリソースを削除した（クリーンアップ済み）

ご安心ください。以下に「Fast-Track」コマンドブロックを示します。これにより、BigQuery データレイクが自動的に再構築され、アスペクトタイプが登録され、パート 1 で行ったのとまったく同じようにガバナンスメタデータが適用されます。

# 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 BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. 一元化されたデータコントロールプレーン（マネージド MCP）

実際のエンタープライズ環境では、安全で一元化されたデータコントロールプレーンが必要です。カスタム MCP サーバーコンテナを構築して Cloud Run にデプロイするのではなく、エージェントを Google が管理する Knowledge Catalog MCP サーバーに直接接続します。

このマネージドエンドポイントを使用することで、次のことが実現します。

メンテナンス不要: MCP サーバーのコンテナ、スケーリング、パッチ適用を管理する必要はありません。
標準化: エージェントは、Model Context Protocol（SSE 転送）を使用して、標準の安全な Google API エンドポイントに接続します。
制御されたスコープ: MCP サーバーは必要なメタデータツール（search_entries、lookup_context、lookup_entry）のみを公開し、読み取り専用のガバナンス優先の推論ループを適用します。

Google が管理する Knowledge Catalog MCP サーバーには、次の安全な URL からアクセスできます。

https://dataplex.googleapis.com/mcp

これはファーストパーティの Google API であるため、エージェントは ID トークンではなく、標準の Google Cloud OAuth2 アクセストークンを使用して認証する必要があります。この認証は、アプリケーションコードで自動的に処理されます。

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

安全なマネージドデータコントロールプレーンがあります。AI エージェントには、ユーザー入力の処理、MCP サーバーを呼び出すタイミングの決定、出力のフォーマットなどのロジックをオーケストレートするフレームワークが必要です。

ここでは、Google の Agent Development Kit（ADK）を使用します。ADK は、エージェントロジックを FastAPI バックエンドに自動的にラップし、インスタントテスト用の組み込みウェブインターフェースを提供するコードファーストのフレームワークです。

Cloud Shell エディタでエージェントコードを開く

ファイル全体をターミナルに出力するのではなく、Cloud Shell エディタで開いて、コードを簡単に検査、編集、理解できるようにしましょう。

ターミナルで次のコマンドを実行し、エディタでコード構造を確認します。このアプリケーションは、Google の Agent Development Kit（ADK）を使用して構築されています。

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

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

（注: agent.py の上部には、Google Cloud OAuth2 認証とトークン更新を処理するためのボイラープレートコードが含まれています。これにより、エージェントは Google マネージド Knowledge Catalog API と安全に通信できます）。

1. ネイティブスキルの読み込み

高度に最適化されたエージェントを構築するために、ADK のネイティブ load_skill_from_dir を使用して、外部エージェントスキルディレクトリからガバナンス手順を読み込みます。このアプローチにより、プログレッシブディスクロージャーが可能になります。

L1 メタデータ: エージェントは起動時にスキルの名前と説明のみを読み込みます。この最小限のコンテキストにより、LLM は大量のトークンを事前に消費することなく、スキルを使用するタイミングを特定できます。
L2 指示: SKILL.md 内の完全な命令セットは、モデルが関連性があると判断した場合にのみ、実行時に動的に取得されます。

base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

2. エージェントのオーケストレーション

ADK を使用すると、複数のエージェントを連結して複雑なエージェントの動作をオーケストレートできます。2 つの専門エージェントで構成される SequentialAgent ワークフローを定義します。

governance_researcher: governance_skill_toolset と Knowledge Catalog MCP tools を搭載。クエリが Data Catalog とコンプライアンスのスコープ内にあるかどうかを確認し、システムインストラクションに挿入された環境変数を使用して Knowledge Catalog にクエリを実行します。
compliance_formatter: 未加工の JSON メタデータの検索結果をクリーンなレスポンスに変換します。リクエストが範囲外の場合は、範囲の境界を丁寧に説明します。

# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

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

エージェントを実行するには、マネージド MCP サーバーの場所を指定し、プロジェクトとリージョンを構成する必要があります。これらの変数は、ADK が実行時に読み取る .env ファイルに保存します。

次のコマンドを実行して .env ファイルを生成します。MCP_SERVER_URL は Google が管理する Knowledge Catalog API エンドポイントを直接指しています。

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

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

5. エージェントをローカルで実行してテストする

エージェントをクラウドにデプロイする前に、Cloud Shell でローカルに実行して、その動作を確認する必要があります。エージェントは複数の Python パッケージ（Google Cloud Logging ライブラリや ADK ライブラリなど）に依存しているため、これらの依存関係をインストールするローカル仮想環境を設定します。

Cloud Shell でローカルに実行する場合、エージェントはアクティブな Google Cloud ユーザー認証情報を自動的に使用するため、Vertex AI と Knowledge Catalog にアクセスするために必要な権限がすでに付与されています。

mcp_server ディレクトリに移動し、仮想環境を作成して依存関係をインストールします。

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

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt

ターミナルでインタラクティブチャットセッションを開始します。

adk run .

セッションが開始されると、プロンプトが表示されます。クエリを入力して、エージェントのガバナンスロジックをテストします。

I need the Q1 revenue summary for our internal board meeting.

エージェントはリクエストを処理し、マネージド MCP サーバーを介してナレッジカタログをクエリし、推奨事項と理由をターミナルに直接出力します。

対話型セッションを終了するには、exit または quit と入力します（または Ctrl+C を押します）。終了したら、仮想環境を無効にできます。

deactivate

6. エージェントを本番環境にデプロイする

エージェントをローカルで検証したので、本番環境で使用するために Google Cloud にデプロイします。

サービスアカウントを作成する

セキュリティのため、デプロイされたエージェントは個人の認証情報で実行しないでください。最小権限の原則に従って、エージェント用に個別の ID（knowledge-catalog-agent-sa）を作成します。

次のコマンドを実行して、サービスアカウントを作成します。

export AGENT_SA=knowledge-catalog-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 Knowledge Catalog Agent"

権限を付与する

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

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

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

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

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

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

Cloud Run へのデプロイ

最後に、エージェントを Cloud Run にデプロイします。次のコマンドは、現在のディレクトリの Dockerfile を使用してコンテナイメージをビルドし、Artifact Registry にアップロードして Cloud Run にデプロイします。完了するまでに 1 ～ 3 分ほどかかることがあります。

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

このコマンドが完了すると、サービス URL（例: https://knowledge-catalog-agent-xyz.run.app）が出力されます。このリンクをクリックして、完全に管理された GenAI Chat Interface を開きます。

7. ライブエージェントをテストする

エージェントが稼働したので、ガバナンスシナリオをテストしましょう。ロジックは変わりませんが、内部状態とツールの実行を可視化するデプロイされた ADK Web Playground を操作するようになります。

前の手順で生成したサービス URL（https://knowledge-catalog-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 でエージェントの推論プロセスを確認します。

インテント認識: エージェントが「今すぐ」と「一晩待てない」を解析します。
メタデータの検索: クエリ [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING を使用して MCP ツール search_entries を呼び出します。
選択: テーブル mkt_realtime_campaign_performance がこれらの条件を満たしていることを示します。
回答: エージェントがリアルタイムテーブルを推奨します。

この機能が重要な理由:

このガバナンスメタデータがないと、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?"

8. クリーンアップ

Google Cloud アカウントに課金されないようにするには、次の手順でこの Codelab で作成したすべてのインフラストラクチャを破棄します。

データレイクを破棄する

クリーンアップスクリプトを使用して、BigQuery テーブル、データセット、Knowledge Catalog のアスペクト定義を削除します。

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

Cloud Run サービスの削除

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

gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

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

ADK エージェントをデプロイすると、システムは自動的にコンテナイメージをビルドし、ソースコードを一時的な Cloud Storage バケットにアップロードしました。

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 ポリシーバインディングを削除してから、サービスアカウントを削除します。

# 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

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

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

ローカル構成を削除する

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

# Uninstall the AGY CLI plugin
agy plugin uninstall dataplex

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

9. 完了

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

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

重要なポイント

メタデータによる決定論的 AI: LLM が列名に基づいて正しいテーブルを推測するのではなく、Google が管理する Knowledge Catalog MCP サーバーを使用して厳密な推論ループを適用し、モデルがテーブルを推奨する前にデータ認証を確認するように強制しました。
分離されたアーキテクチャ: フロントエンドエージェントにデータベースロジックを含める必要はありません。MCP 標準を介して通信するだけで済みます。つまり、将来の AI モデルやクライアントを同じガバナンス対象のバックエンドに接続できます。
職務の分離: IAM ID を分離することで、最小権限の原則を適用しました。ユーザー向けの ADK エージェントは、モデルの呼び出しと API ルーティングに制限された権限で動作します。
コードファーストのエージェントオーケストレーション: Google Agent Development Kit（ADK）を使用して、Python エージェントロジックをスケーラブルな FastAPI バックエンドに瞬時にラップし、組み込みのデベロッパー UI を使用してエージェントの内部ツール実行を可視化してデバッグしました。

次のステップ

Knowledge Catalog の基本的なガバナンスに関する Codelab: AI レイヤを追加する前に、Knowledge Catalog でのデータガバナンスの基本を習得します。
Agent Development Kit（ADK）ドキュメント: ADK を使用してエージェントを構築、デプロイするための公式ドキュメントをご覧ください。
MCP の詳細: 公式の MCP 仕様を確認して、内部エンタープライズ API 用のカスタムサーバーを構築する方法を理解してください。

MCP と Cloud Run を使用してエンタープライズ ガバナンス対応エージェントをデプロイする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。