Agent Development Kit で作った Agent を adk deploy で Vertex AI Agent Engine にデプロイする

はじめに

七尾百合子さん、お誕生日 264日目 おめでとうございます！ nikkieです。

Agent Development Kit と Vertex AI Agent Engine の素振りです¹。

目次

• はじめに
• 目次
• 動画「Build an AI Agent with Gemini 3」
• ADK ドキュメント「Deploy to Vertex AI Agent Engine」
  • Google Cloud の前準備
  • adk deploy agent_engine
  • adk deployのエラーは Cloud Logging を見る
• 動作確認スクリプト
• Gemini 3 Pro はまだ叩けていない
• 終わりに

動画「Build an AI Agent with Gemini 3」

Google 検索して答えてくれるエージェントが ADK (Agent Development Kit) で5分程度でできます

PythonのADKで
adk createとgoogle_search toolのコードのコピペで
Google検索できるアシスタントAgentをgemini-3-pro-previewで作る。
環境にuvあればわずか5分

Build an AI Agent with Gemini 3 https://t.co/61hxTYasfd

— nikkie(にっきー) / にっP (@ftnext) 2025年11月27日

ソースコード：
https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/ai-ml/agent-labs/gemini-3-pro-agent-demo

Gemini 3 Pro、検索上手くて、OpenAI・Anthropic・Google の直近の動向をまとめてくれます²。
ただムラがあって、プロンプト調整で7回くらい試したうち、1回はリンクに飛べる完璧な出力👏、2回はなぜか2024年の12月の情報を検索😫（内部知識が勝った？）でした

これを Vertex AI Agent Engine にデプロイすることにしました。
無料枠ができたと聞いてやってみました

Vertex AI Agent Engine に無料枠が登場。月に 180,000 vCPU秒と 360,000 GiB秒が無料で使える。例えば 1 vCPU、2 GiB RAM の開発環境なら丸2日間、デプロイできる #GoogleCloudhttps://t.co/FH7SwT97LR

— Yuma Sugimura | 杉村 勇馬 (@y_sugi_it) 2025年11月8日

ADK ドキュメント「Deploy to Vertex AI Agent Engine」

google.github.io

色々書いてありますが、今回私がやりたかったことはadk deployだけで達成できます

This guide provides an accelerated deployment instruction set for when you want to deploy an ADK project quickly, and a standard, step-by-step set of instructions for when you want to carefully manage deploying an agent to Agent Engine.

• Accelerated deployment
  • agent-starter-pack 使用
  • 速いのかもしれないですが、Agent Engine 自体よく分かっていないところに、新規のパッケージを加えたらハマる未来しか見えなかったので見送り
• Standard deployment（今回採用）
  • 要はadk deploy
  • google-cloud-aiplatform を使ったスクリプトdeploy.pyが出てきますが、これはローカルでroot_agentを import して確認するためのものみたいで、この確認自体は必須ではないです

ADKのVertex AI Agent Engineへのデプロイのドキュメント、
2つのやり方が書いてあって、Pythonスクリプトも出てくるけれど、
要はadk deployコマンドだけと認識しました。
デプロイできたっぽい✌️https://t.co/dTRFcA8hTi

— nikkie(にっきー) / にっP (@ftnext) 2025年12月6日

Google Cloud の前準備

Standard deployment の Prerequisites 参照
https://google.github.io/adk-docs/deploy/agent-engine/#prerequisites

Google Cloud の Project について

• API の有効化
  • Vertex AI API
  • （私の環境だけかもですが）Cloud Resource Manager API も
• Cloud Storage のバケット作成

gcloud storage buckets create gs://nikkie-agentengine-staging --project adk-practice-480404 --location=asia-northeast1

adk deploy agent_engine

作業ディレクトリはこんな感じです。

.
├── search_agent/
│   ├── __init__.py
│   ├── .env
│   └── agent.py
├── pyproject.toml
└── uv.lock

uv run adk deploy agent_engine \
  --project adk-practice-480404 \
  --region asia-northeast1 \
  --staging_bucket gs://nikkie-agentengine-staging \
  --display_name "Search Agent" \
  --trace_to_cloud \
  ./search_agent

リファレンス：
https://google.github.io/adk-docs/api-reference/cli/cli.html#adk-deploy-agent-engine

ソースコードのアップデートは、--agent_engine_idの指定を追加します。
コマンドリファレンスにまだないですが、Codex CLI で発見³。
（毎回コンソールで削除してからadk deployで作り直していたので、まず持っているセッション⁴を全部消してから Agent Engine を消すという方法を覚えました）

adk deployのエラーは Cloud Logging を見る

初回のadk deployはエラーになりました（Cloud Resource Manager API の有効化漏れ）。
手元のエラー表示は数行で、何が悪いかさっぱり分からず絶望しました。
唯一案内されたトラブルシューティングのページへ
https://docs.cloud.google.com/agent-builder/agent-engine/troubleshooting/deploy?hl=ja

注: エージェントのエラーログを検索してフィルタするには、ログ エクスプローラを使用し、RESOURCE TYPE に「Vertex AI Reasoning Engine」を選択して、対応する RESOURCE CONTAINER 値（プロジェクト番号など）と REASONING ENGINE ID 値を選択します。

Cloud Logging をクエリでフィルタしていくとエラーの詳細が見え、解決に大きく近づきました！

Traceback (most recent call last):
google.api_core.exceptions.PermissionDenied: 403 Cloud Resource Manager API has not been used in project 748276364070 before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=748276364070 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry. [reason: \"SERVICE_DISABLED\"

動作確認スクリプト

Agent Engine のドキュメントを参考にして、Agent Engine にデプロイした Agent を呼び出すスクリプトを作りました。

今回私は離れてしまいましたが、「Deploy to Vertex AI Agent Engine」にも記載があります。
https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment

Gemini 3 Pro はまだ叩けていない

今回は Gemini 2.5 Pro で動かしました。
adk deployした Agent Engine から Gemini 3 Pro を叩けた方がいたら、ぜひ教えてください！

ローカルで動かすときは、（ADKが依存する）google-genai に沿った.envを用意しています。
https://googleapis.github.io/python-genai/#create-a-client
「(Optional) Using environment variables」

Gemini Developer API: Set the GEMINI_API_KEY or GOOGLE_API_KEY.

Gemini API on Vertex AI: Set GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION

ADK が/runへのリクエストを契機に環境変数として読み込んで⁵、それを元に Gemini API 用のクライアントが初期化されると理解しています。

今回の Agent Engine はコマンドに指定した asia-northeast1 リージョンにあります。
そこで動かす Agent では、GOOGLE_CLOUD_LOCATIONの値が asia-northeast1 になるようです
（adk deployの出力には.envの環境変数指定を無視するという警告がありました）

2025年12月上旬時点では Gemini 3 Pro は global リージョンにしかありません。
Gemini 3 を使ってみる  |  Generative AI on Vertex AI  |  Google Cloud Documentation

Gemini 3 Pro プレビュー版モデル gemini-3-pro-preview は、グローバル エンドポイントでのみ使用できます。

asia-northeast1 リージョンの Agent Engine からは asia-northeast1 リージョンの gemini-3-pro-preview へリクエストを送りますが、そこに Gemini 3 Pro はないのでエラーとなります

Gemini Developer API を向けられるかも試みたのですが、クライアントの初期化エラーでした（環境変数の設定を見落としたかも）

Agent Engine には手厚いドキュメントがあり、そこに記載された方法をadk deployがラップして提供しているという理解です。
asia-northeast1 リージョンの Agent Engine から global リージョンの gemini-3-pro-preview へリクエストを送る環境変数の設定方法は、宿題事項です

終わりに

ADK で Agent をローカルで簡単に動かせるので、無料枠ができた Agent Engine にデプロイしてみました

• Google Cloud の前準備の後はadk deploy agent_engine
• Agent Engine と同じリージョンの gemini-3-pro-preview へリクエストする設定になっており、global のみの Gemini 3 Pro はまだ叩けていない

今回のソースコードはこちらです