Agents CLI を使用して ADK エージェントを Agent Runtime にデプロイする

1. 概要

このラボは、Kaggle の「5 日間の AI エージェント: Google による集中的なバイブ コーディング コース」 の一部です。その他の Codelab とリソースについては、イベントサイトをご覧ください。

この Codelab では、ADK 2.0 エージェント をローカル開発環境から本番環境グレードのデプロイに移行します。agents-cli を使用して、グラフベースのワークフローをパッケージ化、検証し、Google Cloud のAgent Runtime でホストします。

このデプロイ プロセスを詳しく確認するために、クラウドにデプロイする前に、Ambient Expense Agent のローカル プロトタイプをゼロから構築します（このエージェントのコアロジックの設計の詳細については、Kaggle イベントサイトの基礎 Codelab をご覧ください）。Ambient Expense Agent は、標準的な請求を即座に承認し、高額な請求には人間参加型レビューのフラグを設定することで、従業員の経費報告を効率化します。内部的には、ADK 2.0 グラフベースのワークフロー を使用して、これらの自動承認とリスク分析の手順を調整します。

学習内容

• クラウド ホスティング用にローカルの Ambient Expense Agent プロジェクトを準備する方法。
• 必要なデプロイ記述子と本番環境ラッパーをスキャフォールディングする方法。
• ドライランを実行して、コードをエージェント ランタイム に直接デプロイする方法。
• Cloud Trace を使用して、本番環境エージェントの実行トレースをモニタリングする方法。

必要なもの

• 課金が有効になっている有効な Google Cloud プロジェクト。
• gcloud SDK がインストールされ、認証されていること。
• uv パッケージ マネージャーがインストールされていること。
• Google Antigravity IDE がインストールされていること。

前提条件

この Codelab では、次のことを理解していることを前提としています。

• ターミナルを使用してシステムを操作する。
• Python 開発の基本的なコンセプト。
• Google Cloud の基本的なコンセプト。

2. Google Cloud 環境を設定する

デプロイする前に、Google Cloud プロジェクトを構成し、必要な API を有効にする必要があります。

👉 Antigravity にプロンプトを表示します。

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Antigravity がこのプロンプトを実行すると、プロジェクトを構成してサービスを有効にするために必要な gcloud ターミナル コマンドが提案され、実行されます。認証ステップでは、Antigravity はターミナルに認証 URL を表示します。リンクをクリックしてウェブブラウザからログインし、アクセスを許可します。ブラウザでのログインが完了すると、Antigravity は実行を再開してプロジェクト環境変数を設定し、必要な API を有効にします。

注: 新しいプロジェクトの場合は、最初に Service Usage API を有効にするよう gcloud から求められることがあります。要求された場合は、ターミナルに表示されるリンクをクリックして Cloud コンソールで有効にしてください。

3. Agents CLI と ADK スキルを設定する

Antigravity が ADK エージェントを適切にビルドしてデプロイするには、ADK スキルセット が必要です。これらは、ADK API、プロジェクト スキャフォールディング、agents-cli デプロイ ワークフロー、評価のバンドルされたリファレンスです。agents-cli ツールチェーンをインストールすると、これらのスキルがコーディング エージェントにインストールされ、ローカル スキャフォールディングからクラウド デプロイまで、エージェントのライフサイクル全体を管理できるようになります。

👉 次のプロンプトをコピーして Antigravity に貼り付けます。

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Antigravity がこのプロンプトを実行すると、ターミナルで uvx google-agents-cli setup が実行され、CLI とそのコンパニオン スキルがインストールされます。次に、agents-cli info を実行してインストールを確認し、新しくインストールされたドメイン スキル（google-agents-cli-deploy や google-agents-cli-workflow など）をチャットに直接表示します。

Antigravity ユーザー向けの注: この Codelab では、Antigravity はコマンドの実行やコードの記述の前に、実装プランを生成したり、ポップアップを表示したりすることがあります。Antigravity がタスクを進められるように、これらのプランまたはポップアップを確認して承認 してください。

割り当てに関するヒント: テストまたは開発中に割り当てが不足した場合は、Antigravity のモデルを別の利用可能なモデルに切り替えます。

4. エージェント プロジェクトを作成する

クラウド環境を構成し、CLI スキルをインストールしたら、エージェントのローカル コードベースを生成する準備が整います。このステップでは、Antigravity を使用して、ADK 2.0 と互換性のある完全に機能する Ambient Expense Agent プロトタイプをスキャフォールディングします。

Kaggle 5 日間の AI エージェント ユーザー向けの注: 4 日目の Vibecode Ambient Expense Agent Codelab を完了し、既存のカスタム エージェント コードベースをデプロイする場合は、このスキャフォールディングの手順をスキップして次のステップに進むことができます。

👉 Antigravity にプロンプトを表示します。

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Antigravity がこのプロンプトを実行すると、新しくインストールされたスキャフォールディング スキルを利用して、ターミナルで agents-cli scaffold create expense-agent --adk が実行されます。次に、生成されたプロトタイプ コードを確認して調整し、expense-agent が $100 の自動承認しきい値と人間参加型レビュー フローを Agent Development Kit（ADK） グラフ ワークフロー内で正しく実装するようにします。

5. 本番環境デプロイの準備

エージェント ランタイムは、本番環境で AI エージェントをデプロイ、管理、スケーリングできる Google Cloud のフルマネージド サービスです。エージェント ランタイムは、ホスティングの運用上の複雑さを処理し、セッション管理、長期メモリ、安全なコード実行サンドボックスなどの機能を備えたステートフル環境を提供します。

Agent Runtime にデプロイする理由

Antigravity を使用してエージェントをローカルでビルドすると、エージェントはローカルマシンで localhost に対して実行されます。迅速なプロトタイピングには最適ですが、ローカル エージェントはノートパソコンを閉じるとすぐに実行を停止します。

エージェントをエージェント ランタイムにデプロイすると、ワークフローがフルマネージドで常時稼働の Google Cloud 環境に移行します。これにより、24 時間 365 日稼働する安全なライブ バックエンド エンドポイントが確立されます。次の Codelab では、このクラウド エンドポイントに直接接続するウェブ フロントエンドを構築し、エージェントに公開 URL を付与します。

さらに、エージェント ランタイムは、AI エージェント専用に最適化された専用インフラストラクチャを提供し、次のような組み込み機能を提供します。

• マネージド ステートフル実行: 会話のターン全体でセッション管理と長期メモリの永続化が組み込まれています。
• 安全なサンドボックス: 隔離された環境で動的なツール呼び出しとエージェント生成コードを安全に実行します。
• エンタープライズ オブザーバビリティ: Cloud Trace と Cloud Logging に直接テレメトリーをストリーミングする機能がすぐに使用できます。

エージェントを Agent Runtime でホストするには、本番環境記述子、スキーマ、エンドポイント ラッパーを使用してローカル プロジェクト ディレクトリを拡張する必要があります。

👉 Antigravity にプロンプトを表示します。

Scaffold the production deployment files for Agent Runtime.

Antigravity がこのプロンプトを実行すると、プロジェクト ルートで agents-cli scaffold enhance --deployment-target agent_runtime --yes が実行されます。このコマンドはディレクトリをスキャンし、次のものを自動的に生成します。

• app/agent_runtime_app.py: 本番環境グレードのサービス ラッパー。
• deployment_metadata.json: Agent Runtime がリソースをスピンアップするために使用するレイアウト スキーマ。

app/agent.py のコア エージェント ロジックは完全に変更されず、保持されます。

6. パッケージ化とローカル検証

クラウドへのアップロードを開始する前に、パッケージをロックし、ローカルでドライランを実行して、依存関係の競合の可能性を特定します。

👉 Antigravity にプロンプトを表示します。

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Antigravity がこのプロンプトを実行すると、最初にターミナルで uv lock を実行して決定論的なロックファイルを生成し、クラウドでライブラリのバージョンが一致するようにします。次に、agents-cli deploy --dry-run を実行して構成の有効性を検証し、クラウド リソースをプロビジョニングせずにデプロイ ステップをプレビューします。ターミナルでドライランの出力を確認して、すべてのファイルと設定が正しいことを確認できます。

7. Agent Runtime にデプロイする

Ambient Expense Agent を Agent Runtime にデプロイします。

👉 Antigravity にプロンプトを表示します。

Deploy this agent to Agent Runtime.

Antigravity がこのプロンプトを実行すると、google-agents-cli-deploy スキルが有効になり、agents-cli deploy --project YOUR_PROJECT_ID --region us-west1 が実行されます。パッケージ化、アップロード、Agent Runtime のプロビジョニング プロセスには通常 5 ～ 10 分 かかります。Antigravity はターミナルでデプロイの進行状況をモニタリングし、完了するとライブ エンドポイント URL を表示します。

💡 プロのヒント（タイムアウト ウィンドウの管理）: 長いデプロイ中にターミナルをロックしたくない場合は、--no-wait フラグを使用して非同期でデプロイを開始し、後で agents-cli deploy --status を使用して進行状況を確認するように Antigravity に指示できます。

エージェントのデプロイで問題が発生した場合は、別のリージョンの使用を検討してください。Google Cloud リージョン選択ツールを使用すると、レイテンシ、料金、温室効果ガス排出量に基づいてプロジェクトに最適なリージョンを判断できます。

8. エージェントをテストする

エージェントがデプロイされたら、少額の経費が自動的に承認され、高額な経費には人間参加型検証のフラグが適切に設定されていることを確認できます。

👉 Antigravity にプロンプトを表示して、デプロイされたライブエンジンを確認します。

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

注: Antigravity がライブ エンドポイントに対してこのテスト プロンプトを実行したときに、デプロイ エラーまたは実行エラーが発生した場合、問題のデバッグ、必要なコード修正の適用、エージェントの再デプロイが自動的に試行されます。

または、Cloud Console Playground のプレビューを使用して、エージェントを手動でテストすることもできます。Playground を開くには:

1. Google Cloud コンソールで、ナビゲーション メニューを使用して [Agent Platform] > [デプロイ] を選択します。
2. デプロイ リストからデプロイされたエージェントを選択します。
3. [Playground] ボタンをクリックして、インタラクティブなテストチャット インターフェースを開きます。

👉 自動承認（<$100）をテストするには、次の JSON ペイロードをチャットボックスに貼り付けます。

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

ステータスが「承認済み」の auto_approve ノードの出力を示す JSON レスポンスが返されます。

👉 人間参加型（HITL）フローをテストするには、次の JSON ペイロードを貼り付けます。

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

これにより、review_agent がトリガーされ、警告アラートが発行され、実行が一時停止して、承認を求める RequestInput（人間参加型）が生成されます。

9. 本番環境エージェントをモニタリングして観察する

Agent Runtime では、テレメトリーが自動的に接続されます。すべてのインタラクション、モデル呼び出し、ツール実行は、リアルタイムのログとスパンをプロジェクトにストリーミングします。

1. トレースを検査する: Cloud Trace コンソールを開いて、ライブ トランザクション マップ、モデルのレイテンシ、ツールの実行ステップを監査します。
2. 監査ログ: Cloud Logging を使用して、リアルタイムの標準出力と診断スタック トレースを検査します。

3. 分析を集計する: スキャフォールディング時に --bq-analytics フラグが有効になっている場合は、SQL を使用して BigQuery 内のログをクエリし、承認率と会話のターンの傾向を確認します。

次の SQL クエリは、承認率を計算する例を示しています。Antigravity にプロンプトを表示して、特定のプロジェクトと BigQuery データセット用にこのクエリをカスタマイズできます。

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. （省略可）エージェント レジストリで登録を確認する

組織内の他のサービス、デベロッパー、エージェントが経費エージェントを安全に検出して使用できるようにするには、エンタープライズ エージェント レジストリ （Gemini Enterprise）に登録する必要があります。

エージェントを Agent Runtime にデプロイしたため、エージェント レジストリに自動的に登録されます。Agent Runtime でエージェントを今後更新または削除すると、エージェント レジストリにも自動的に同期されます。

👉 Antigravity にプロンプトを表示して、エージェントの自動登録を確認します。

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Antigravity がこのプロンプトを実行すると、ターミナルで agents-cli publish gemini-enterprise --list が実行されます。これにより、エージェント レジストリにクエリが送信され、プロジェクトに登録されているすべての Gemini Enterprise エージェントが一覧表示されます。これにより、Ambient Expense Agent が組織全体でアクティブで検出可能であることを確認できます。

11. クリーンアップ

Kaggle コースの参加者: このラボを Kaggle の「5 日間の AI エージェント」 コースの一環として完了し、次のラボ（Vibecode と ADK エージェントのフロントエンドのデプロイ）に進んでフロントエンド クライアントと Pub/Sub 統合を構築する場合は、デプロイしたエージェントを削除しないでください。次のラボでは、このアクティブなクラウド インフラストラクチャが必要になります。

Google Cloud アカウントで継続的な課金が発生しないようにするには、完了したらデプロイしたリソースをシャットダウンしてクリーンアップする必要があります。

👉 Antigravity にプロンプトを表示します。

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Antigravity がこのプロンプトを実行すると、リソースのクリーンアップ プロセス全体が自動化されます。

1. デプロイされたエージェントを削除する: deployment_metadata.json を読み取ってリモート エージェント ランタイム ID を取得し、Vertex AI からライブエンジン インスタンスをプログラムで削除します。
2. ローカル ワークスペースをクリーンアップする: プロジェクト ルートから古い deployment_metadata.json ファイルを削除します。
3. Artifact Registry をクリーンアップする: ビルドされたコンテナ イメージを Artifact Registry から削除してクラウド ストレージ スペースを解放するために、gcloud artifacts docker images delete を実行します。

12. 完了

おめでとうございます！Google Cloud で本番環境グレードの Ambient Expense Agent をデプロイして検証しました。

学習した内容

• Google Cloud の設定: プロジェクトの認証情報を構成し、必要なプラットフォーム API を有効にしました。
• ツールとスキル: agents-cli をインストールし、ADK コンパニオン スキルを Antigravity に読み込みました。
• プロダクション スキャフォールディング: ADK 2.0 エージェントの Agent Runtime スキャフォールディングを生成しました。
• ローカル検証: 決定論的なロックファイル（uv lock）を作成し、ドライラン チェックを実行しました。
• Cloud Deployment: マネージド Agent Runtime インフラストラクチャでエージェントをライブでホストしました。
• オブザーバビリティと分析: Cloud Trace で実行をトレースし、BigQuery でテレメトリーを分析しました。
• エンタープライズ検出: エンタープライズ エージェント レジストリへの自動登録を確認しました。

次のステップ

• BigQuery 分析を実行する: BigQuery でエージェントのテレメトリー ログをクエリして、承認率と会話のターンの傾向を分析します。
• Vibe to Live Codelab: Google Antigravity を使用して Cloud Run でフロントエンド クライアントを開発し、ライブ Agent Runtime バックエンド エンドポイントに直接接続します。

Kaggle 5 日間の AI エージェント バッジを獲得する 🎉

Kaggle の「5 日間の AI エージェント: Google による集中的なバイブ コーディング コース」 の一環としてこのラボを完了しましたか？完了バッジを受け取ります。

5 日間の AI エージェント バッジを取得する

参照

• Agent Development Kit（ADK）のドキュメント
• Gemini Enterprise Agent Platform ランタイム
• Agents CLI（agents-cli）リファレンス ガイド
• Gemini Enterprise Agent Registry の概要
• Google Cloud Trace のドキュメント