google-agents-cli-deploy

デプロイガイド

必要条件： agents-cli（uv tool install google-agents-cli）— 必要に応じて、最初に uv をインストールしてください。

このガイド全体を通じて、agents-cli コマンドの使用をおすすめします。Terraform、Docker、デプロイを、テスト済みのパイプラインとして実行できます。プロジェクトのスキャフォールディングがまだ済んでいない場合は、まず /google-agents-cli-scaffold を参照して、デプロイ機能を追加してください。

リファレンスファイル

詳しい情報については、references/ 内の以下のリファレンスファイルを参照してください。

• cloud-run.md — スケーリングのデフォルト設定、Dockerfile、セッションの種類、ネットワーキング
• agent-runtime.md — コンテナベースのデプロイ、統合された FastAPI アプリ、/api パススルー、Terraform リソース、デプロイメタデータ、CI/CD の違い
• gke.md — GKE Autopilot クラスター、Kubernetes マニフェスト、Workload Identity、セッションの種類、ネットワーキング
• terraform-patterns.md — カスタムインフラストラクチャ、IAM、状態管理、リソースのインポート
• batch-inference.md — BigQuery Remote Function トリガー。ADK での Pub/Sub / Eventarc については /google-agents-cli-adk-code を参照してください
• cicd-pipeline.md — CI/CD パイプラインの完全な設定、infra cicd フラグ、ランナーの比較、WIF 認証、パイプラインのステージ
• testing-deployed-agents.md — デプロイ先ごとのテスト手順、curl の例、負荷テスト
• cmek.md — Gemini プラットフォームの Agent Runtime における顧客管理の暗号化キー：キーの付与、開発用の deploy --key、ステージング／本番環境向けの Terraform 編集

オブザーバビリティ： Cloud Trace、プロンプトとレスポンスのロギング、BigQuery Analytics、サードパーティ統合については、/google-agents-cli-observability スキルを参照してください。

---

デプロイ先の選択マトリックス

要件に基づいて、適切なデプロイ先を選択します。

基準	Agent Runtime	Cloud Run	GKE
スケーリング	マネージド自動スケーリング（最小／最大数、同時実行数を設定可能）	完全に設定可能（最小／最大インスタンス数、同時実行数、CPU 割り当て）	Kubernetes のフルスケーリング（HPA、VPA、ノードの自動プロビジョニング）
ネットワーキング	VPC-SC と PSC-I をサポート（ネットワークアタッチメント経由のプライベート VPC 接続）	フル VPC サポート、直接 VPC エグレス、IAP、イングレスルール	Kubernetes のフルネットワーキング
セッション状態	Gemini プラットフォーム上のセッション（ADK が VertexAiSessionService を自動的に接続します）	インメモリ（開発用）、Cloud SQL、またはマネージドセッションバックエンド	インメモリ（開発用）、Cloud SQL、またはマネージドセッションバックエンド
バッチ／イベント処理	Agent Runtime の /api パススルー経由でアクセス可能なトリガーエンドポイント	ネイティブのトリガーエンドポイント（Pub/Sub、Eventarc）。ADK の場合は /google-agents-cli-adk-code を参照してください	カスタム（Kubernetes Jobs、Pub/Sub）
料金モデル	vCPU 時間＋メモリ時間（アイドル時は課金されません）	インスタンス秒単位＋最小インスタンス料金	ノードプール料金（常時稼働または自動プロビジョニング）
セットアップの複雑さ	低め（マネージドで、エージェント専用に設計されています）	中程度（Dockerfile、Terraform、ネットワーキング）	高め（Kubernetes の専門知識が必要です）
最適な用途	マネージドインフラ、最小限の運用	カスタムインフラ、ネットワーキングを完全に制御したい場合	Kubernetes を完全に制御したい場合

ユーザーに、要件に合うデプロイ先を確認してください。それぞれ異なるトレードオフがある、本番環境で有効な選択肢です。

3 つのデプロイ先はすべてコンテナベースのため、どの言語でも使用できます。

製品名の対応関係：「Agent Engine」「Vertex AI Agent Engine」「Agent Runtime」は、いずれも Agent Runtime を指します。--deployment-target agent_runtime を使用してください。

アンビエント／スケジュール実行／イベント駆動型エージェント（ADK プロジェクト）： ADK の trigger_sources は、すべてのデプロイ先で同じ FastAPI アプリに /apps/{app}/trigger/* エンドポイントを登録します。Cloud Run／GKE では、これらは Pub/Sub のプッシュサブスクリプションまたは Eventarc トリガーの送信先となるパブリック HTTP ルートです。Agent Runtime では、同じルートに /api パススルー経由でアクセスできます（例：.../reasoningEngines/v1/{resource}/api/apps/{app}/trigger/pubsub）。認証なしのトリガーソースには、引き続き Cloud Run が最もシンプルなデプロイ先です。trigger_sources のパターンについては /google-agents-cli-adk-code（references/adk-python.md の「12. Event-Driven / Ambient Agents」セクション）を参照してください。

OAuth／ユーザーの同意が必要なエージェント： OAuth 2.0 によるユーザーの同意が必要なエージェント（Google Drive、Calendar、その他のユーザー単位の API へのアクセスなど）には、Gemini に登録した Agent Runtime を使用してください。Cloud Run は現在、マネージド OAuth フローをサポートしていません。ADK の具体的な例については、/google-agents-cli-adk-code のトピックインデックスで「OAuth user consent」を検索し、references/samples.md を参照してください。

ライブエージェントと音声エージェント： Cloud Run では --timeout 3600 を指定して、セッションがデフォルトの 300 秒を超えて継続するようにしてください。また、アイドル後の最初の呼び出しでコールドスタートが発生しないよう、Cloud Run または Agent Runtime で --min-instances 1 を指定してください。GKE では Terraform で Pod のサイズを設定します。URL 形式とセッションの上限については、/google-agents-cli-adk-code（references/adk-python-live.md）を参照してください。

---

Dev へのデプロイ

デプロイのワークフロー

タスクの追跡： デプロイには複数の順次ステップ（インフラのセットアップ、CI/CD の設定、デプロイ、検証）が含まれます。これらのステップの進捗を追跡するにはタスクリストを使用してください。1 つでも飛ばすと、後続のステップで障害が発生し、原因の特定が難しくなることがよくあります。

1. プロトタイプの場合（デプロイ先がない場合）、まず次のコマンドで拡張します：agents-cli scaffold enhance . --deployment-target <target>
2. 人間に通知します：評価スコアとテスト結果を貼り付け、「開発環境にデプロイする準備はできていますか？」と尋ねます。
3. 明示的な承認を待ちます
4. 承認されたら、次を実行します：agents-cli deploy

Agent Runtime のタイムアウトからの復旧： Agent Runtime のデプロイには 5〜10 分かかることがあり、コマンドのタイムアウトを超える場合があります。デプロイコマンドがキャンセルされた場合やタイムアウトした場合でも、デプロイはサーバー側で続行されます。進捗を確認するには agents-cli deploy --status を実行します。完了または失敗が報告されるまで、60 秒ごとに確認してください。

重要： 人間から明示的な承認を得ずに agents-cli deploy を実行してはいけません。

必須の前提条件ではありません。 agents-cli deploy は単独で動作します。例外として、ユーザーが Terraform で管理する可観測性（プロンプトと応答のログ記録、BigQuery 分析）を希望する場合は、先に agents-cli infra single-project --apply を実行してください。詳しくは /google-agents-cli-observability を参照してください。

単一プロジェクトのインフラストラクチャ設定（任意 — 上級者向け）

agents-cli infra single-project --apply は、deployment/terraform/single-project/ で terraform apply を実行します。これを使用すると、CI/CD を使わずに単一プロジェクトの GCP インフラストラクチャ（サービスアカウント、IAM バインディング、テレメトリリソース、Artifact Registry）をプロビジョニングできます。Terraform で可観測性を管理する場合に限り、デプロイ前に実行する必要があります。基本的な Agent Runtime と Cloud Run のデプロイでは不要ですが、GKE のデプロイでは対象を絞った独自の Terraform が処理されます。

# Optional — provision infrastructure in a single GCP project
agents-cli infra single-project --apply

注： agents-cli deploy は、Terraform で作成された app_sa を自動的には使用しません。サービスアカウントを明示的に渡してください：agents-cli deploy --service-account SA_EMAIL

デプロイフラグのリファレンス

フラグ	説明	対象
--project	GCP プロジェクト ID	すべて
--region	GCP リージョン	すべて
--service-account	デプロイされたエージェントのサービスアカウントのメールアドレス	すべて
--service-name	デプロイするサービス名を上書きします（Cloud Run サービスまたは Agent Runtime の表示名）。デフォルトはプロジェクト名です。上書きする場合は、Terraform と CI（存在する場合）も更新することを検討してください。これらはプロジェクト名を使ってリソース名を付けています。名前が Terraform によって完全に管理される GKE ではサポートされていません。	Agent Runtime、Cloud Run
--secrets / --update-secrets	カンマ区切りの ENV=SECRET または ENV=SECRET:VERSION のペアです。Cloud Run では既存のサービスシークレットに追加されます。Agent Runtime では、渡したシークレットでエージェントの既存のシークレットが置き換えられます。	Agent Runtime、Cloud Run
--env-vars / --update-env-vars	カンマ区切りの KEY=VALUE 環境変数	すべて
--agent-identity	Agent Identity を有効にします	Agent Runtime
--no-agent-identity	Agent Identity を無効にします。--agent-identity も --no-agent-identity も指定しない場合、新しいエージェントでは Agent Identity を無効にし、以降の再デプロイでは現在の ID タイプを維持します。	Agent Runtime
--network-attachment	PSC インターフェース用のネットワークアタッチメントリソース名（プライベート VPC 接続を有効にします）	Agent Runtime
--dns-peering-domain	DNS ピアリングのドメインサフィックス。例：my-internal.corp.（--network-attachment が必要です）	Agent Runtime
--dns-peering-project	DNS ピアリング用の Cloud DNS マネージドゾーンが存在するプロジェクト ID（--network-attachment が必要です）	Agent Runtime
--dns-peering-network	DNS ピアリング用の対象プロジェクト内の VPC ネットワーク名（--network-attachment が必要です）	Agent Runtime
--agent-gateway-egress	エージェントを、送信トラフィックを管理する Agent Gateway にバインドします。governedAccessPath=AGENT_TO_ANYWHERE を持つゲートウェイの完全なリソース名を指定します。空の値を指定するとバインドを解除します。省略すると変更されません。Agent Gateway を参照してください	Agent Runtime
--agent-gateway-ingress	エージェントを、受信トラフィックを管理する Agent Gateway にバインドします。governedAccessPath=CLIENT_TO_AGENT を持つゲートウェイの完全なリソース名を指定します。空の値を指定するとバインドを解除します。省略すると変更されません	Agent Runtime
--key	顧客管理暗号化（CMEK）用の Cloud KMS キー。完全な projects/PROJECT/locations/REGION/keyRings/RING/cryptoKeys/KEY 名で指定します。作成時のみ設定できます。開発環境へのデプロイでは、ステージング環境／本番環境のキーを Terraform で設定してください。顧客管理暗号化を参照してください	Agent Runtime
--memory	メモリ上限（デフォルト：4Gi）	Agent Runtime、Cloud Run
--cpu	CPU 上限（デフォルト：1）	Agent Runtime、Cloud Run
--min-instances	インスタンスの最小数（デフォルト：0、つまりゼロまでスケールします。生成される Terraform では 1 を使用します）	Agent Runtime、Cloud Run
--max-instances	インスタンスの最大数（デフォルト：10）	Agent Runtime、Cloud Run
--concurrency	コンテナあたりの同時リクエスト数（デフォルト：8。デプロイのサイジングを参照してください）	Agent Runtime、Cloud Run
--timeout	リクエストのタイムアウト（秒単位。最大 3600。Cloud Run のデフォルト：300）。作成時と更新時に適用されます。指定しない場合、サービスの現在の値が維持されます	Cloud Run
--port	コンテナポート	Cloud Run、Agent Runtime
--build-args	カンマ区切りの KEY=VALUE Docker ビルド引数	Agent Runtime
--labels / --update-labels	追加または更新する、カンマ区切りの KEY=VALUE リソースラベル。既存のラベルは保持されます。指定したラベルを追加または更新し、指定していないラベルはそのまま残します。	Agent Runtime、Cloud Run
--remove-labels	削除するラベルの KEY をカンマ区切りで指定します。存在しないキーは無視されます。--labels と併用できますが、同じキーを両方に指定することはできません。--clear-labels とは併用できません。	Agent Runtime、Cloud Run
--clear-labels	すべてのリソースラベルを削除します（Cloud Run では予約済みの created-by ラベルが保持されます）。--labels と併用すると、ラベルセットを置き換えます。最初にラベルをすべて削除します。--remove-labels とは併用できません。	Agent Runtime、Cloud Run
--framework	デプロイするコンテナが実装するフレームワークです（デフォルトは agents-cli-manifest.yaml の framework:。テンプレートではこれが設定されています。指定がない場合は google-adk）。デプロイに agent_framework を設定します。これにより、デプロイで宣言されたランタイム契約と、Google Cloud コンソールのプレイグラウンドが選択されます。受け付ける値は API が管理します（リファレンス）	Agent Runtime
--iap	Identity-Aware Proxy を有効にします	Cloud Run
--image	コンテナイメージ URI（ソースビルドをスキップします。Agent Runtime ではサポートされていません）	Cloud Run、GKE
--no-wait	デプロイを開始し、すぐに戻ります	Agent Runtime、Cloud Run
--status	保留中の --no-wait デプロイのステータスを確認します	Agent Runtime、Cloud Run
--list	既存のデプロイを一覧表示して終了します	すべて
--dry-run / -n	実行せずに、実行される内容を表示します	すべて
--no-confirm-project	プロジェクトの確認プロンプトをスキップします	すべて
完全なフラグリファレンスについては、agents-cli deploy --help を実行してください。

Cloud Run への高度なデプロイ： agents-cli のフラグで公開されていない機能が必要な場合は、--dry-run（または -n）を使って完全な gcloud コマンドを出力し、コピーして必要な追加引数を加えてください。

プロジェクトの確認： プロジェクトが自動的に解決される場合（--project で指定されていない場合）、インタラクティブモードではコマンドによって確認を求められます。エージェントは通常、非インタラクティブモードで実行されるため、自動的なプロジェクト解決に依存して処理を進めるには、--no-confirm-project を必ず指定してください。

---

デプロイのサイズ設定

デフォルト値（Agent Runtime と Cloud Run で共通）：--cpu 1、--memory 4Gi、--concurrency 8、--min-instances 0、--max-instances 10。生成される service.tf も同じ設定ですが、本番デプロイでコールドスタートが発生しないよう、min_instances = 1 に固定しています。推奨値は Python エージェントを基準に調整されているため、出発点として利用し、負荷テストで調整してください（以下を参照）。

agents-cli deploy はデフォルトでゼロまでスケールするため、アイドル状態の開発用エージェントやデモ用エージェントが容量を占有しません。インスタンスを起動状態にしておく必要がある場合は、--min-instances 1 を指定するか、Terraform でデプロイしてください。

各パラメーターは連動するため、まとめて調整してください。

• プロセスは 1 つ — 上方向ではなく、水平にスケールします。 コンテナは単一のサーバープロセスを実行し、多数のリクエストを同時に処理します。そのため、スループットは追加のワーカープロセスではなく、--concurrency と水平方向のスケール（--max-instances）によって向上します。プロファイリングで、モデルの応答待ちではなく、実際に CPU が飽和していることが確認された場合に限り、--cpu を増やしてください。
• メモリが同時実行数を制限します。 モデルの応答を待つ間、各同時リクエストは作業セット全体（コンテキストウィンドウ、履歴、RAG チャンク、応答バッファー）をメモリ上に保持します。そのため、ピーク使用量はおよそ「ベース使用量 + concurrency × リクエストあたりのメモリ使用量」になります。最初に上限となるのは CPU ではなくメモリです。--memory を増やさずに --concurrency を増やすことが、OOM の主な原因です。
• 同時実行数のデフォルト値は保守的です。 ワーカーはモデルの応答を待つ間、多数のリクエストを同時に処理できますが、リクエストあたりのメモリ使用量はエージェントごとに異なるため、8 はメモリを多く使う（RAG／マルチモーダル）エージェントを想定した値です。軽量なエージェントでは、負荷テスト後に 16～32 以上に増やせます。非効率な非同期ワーカーを参照してください。

# 4x throughput: scale every param, not just one
agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20

足場として生成される負荷テストで調整してください（Python プロジェクトでは tests/load_test/、Go プロジェクトでは e2e/load_test/ にあります。ローカルまたは CI/CD ステージングパイプラインで実行してください）。負荷をかけ、最大レイテンシとメモリ／OOM による再起動を確認してから調整します。最大レイテンシが高い場合は、同時実行数（およびワーカー数／CPU）を増やし、OOM が発生する場合は、メモリを増やすか同時実行数を減らしてください。

GKE ではこれらのサイズ設定フラグは拒否されます。deployment/terraform/ にある Terraform マニフェストと HorizontalPodAutoscaler でサイズを設定してください。

---

本番デプロイ — CI/CD パイプライン

CI/CD パイプライン全体のセットアップガイド（前提条件、infra cicd フラグ、ランナーの比較、WIF 認証、パイプラインのステージ、本番環境への承認）については、references/cicd-pipeline.md を参照してください。

---

Cloud Run 固有の情報

インフラストラクチャの詳細な設定（スケーリングのデフォルト値、Dockerfile、FastAPI エンドポイント、セッションの種類、ネットワーク）については、references/cloud-run.md を参照してください。ADK： Cloud Run へのデプロイに関する ADK ドキュメントを確認するには、https://adk.dev/deploy/cloud-run/index.md を取得してください。

ADK プロジェクト。 Cloud Run へのイベント駆動型／アンビエントエージェントのデプロイについては、ambient-expense-agent のサンプルと、trigger_sources パターンについて /google-agents-cli-adk-code（references/adk-python.md の「12. Event-Driven / Ambient Agents」セクション）を参照してください。

---

Agent Runtime の詳細

Agent Runtime は、エージェントをコンテナとしてデプロイするためのマネージド Gemini プラットフォームサービスです。コンテナベースのデプロイを使用します。agents-cli deploy はプロジェクトをパッケージ化し、Agent Runtime はプロジェクトの Dockerfile（必須）からイメージをビルドします。これは Cloud Run と GKE で使用されるものと同じイメージです。

Agent Runtime 用の gcloud CLI はありません。 デプロイには agents-cli deploy を使用してください。クエリには Python の agentplatform.Client SDK を使用してください。

デプロイには 5～10 分かかる場合があります。--no-wait を使うと、デプロイを開始してすぐに戻り、後から --status で状態を確認できます。

# Start deployment without blocking
agents-cli deploy --no-wait

# Check on progress later
agents-cli deploy --status

--status が処理の完了を検出すると、deployment_metadata.json を書き込み、通常のデプロイと同じ成功メッセージを出力します。

インフラストラクチャの設定の詳細（コンテナのデプロイフロー、統合された FastAPI アプリと /api パススルー、Terraform リソース、デプロイメタデータ、セッション／アーティファクトサービス、CI/CD の違い）については、references/agent-runtime.md を参照してください。ADK： Agent Runtime へのデプロイに関する ADK ドキュメントは、https://adk.dev/deploy/agent-runtime/index.md を取得してください。

---

GKE の詳細

インフラストラクチャの設定の詳細（Kubernetes マニフェスト、Terraform リソース、Workload Identity、セッションの種類、ネットワーク）については、references/gke.md を参照してください。ADK： GKE へのデプロイに関する ADK ドキュメントは、https://adk.dev/deploy/gke/index.md を取得してください。

---

サービスアカウントのアーキテクチャ

スキャフォールドで生成されたプロジェクトでは、2 つのサービスアカウントを使用します。

• app_sa（環境ごと）— デプロイされたエージェントのランタイム ID です。ロールは deployment/terraform/iam.tf で定義されています。
• cicd_runner_sa（CI/CD プロジェクト）— CI/CD パイプライン（GitHub Actions／Cloud Build）の ID です。CI/CD プロジェクト（デフォルトでは本番プロジェクト）に属し、ステージングと本番の両方のプロジェクトで権限が必要です。

正確なロールバインディングは deployment/terraform/iam.tf で確認してください。プロジェクト間の権限（Cloud Run サービスエージェント、Artifact Registry へのアクセス）もここで設定されています。

よくある 403 エラー：

• 「Cloud Run で権限が拒否されました」→ 対象プロジェクトで cicd_runner_sa にデプロイ用ロールがありません
• 「サービスアカウントとして操作できません」→ app_sa に iam.serviceAccountUser のバインディングがありません
• 「シークレットへのアクセスが拒否されました」→ app_sa に secretmanager.secretAccessor がありません
• 「Cloud SQL 接続に失敗しました／認可されていません」→ ランタイムサービスアカウントに roles/cloudsql.client がありません
• 「Artifact Registry の読み取りが拒否されました」→ Cloud Run サービスエージェントに CI/CD プロジェクトでの読み取りアクセス権がありません

---

CI/CD の設定に必要な権限

• CI/CD プロジェクトで、Cloud Build サービスアカウント（service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com）に roles/secretmanager.admin を付与します。これにより、Cloud Build は Secret Manager に保存された GitHub トークンにアクセスできます。

---

必須 API

スキルとデプロイを機能させるには、プロジェクトで次の Google Cloud API を有効にする必要があります。

• cloudbuild.googleapis.com — コンテナイメージのビルドと CI/CD パイプラインの実行に必要です。
• secretmanager.googleapis.com — シークレットと API キーの管理に必要です。
• run.googleapis.com — Cloud Run へのデプロイに必要です。

デプロイまたは CI/CD の設定コマンドを実行する前に、これらが有効になっていることを確認してください。

gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID

---

Secret Manager（API 認証情報用）

機密性の高いキーを環境変数として渡す代わりに、GCP Secret Manager を使用してください。

# Create a secret
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-

# Update an existing secret
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

アクセス権の付与： Cloud Run の場合は、app_sa に secretmanager.secretAccessor を付与してください。Agent Runtime の場合は、プラットフォーム管理の SA（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）に付与してください。GKE の場合は、app_sa に secretmanager.secretAccessor を付与してください。シークレットには、Kubernetes Secrets を介してアクセスするか、Workload Identity を使って Secret Manager API から直接アクセスしてください。

デプロイ時にシークレットを渡す（Agent Runtime、Cloud Run）：

agents-cli deploy --secrets "API_KEY=my-api-key,DB_PASS=db-password:2"

形式：ENV_VAR=SECRET_ID または ENV_VAR=SECRET_ID:VERSION（デフォルトは latest）。

---

Cloud SQL の権限（手動デプロイ）

Terraform を使わない構成で --add-cloudsql-instances を追加する場合など、Cloud Run で Cloud SQL を手動デプロイとして使用する際は、ランタイムのサービスアカウントに Cloud SQL Client ロールを手動で付与する必要があります。

この設定がないと、デプロイは成功しても、実行時に cloudsql.instances.get の認可エラーが発生することがあります。

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
  --role="roles/cloudsql.client"

注: Terraform で完全に管理された構成（infra cicd／infra single-project）では、このロールは自動的に設定および管理されます。

---

可観測性

可観測性の設定（Cloud Trace、プロンプトと応答のログ記録、BigQuery Analytics、サードパーティ統合）については、agents-cli-observability スキルを参照してください。

---

デプロイしたエージェントのテスト

デプロイしたエージェントを最も手早くテストするには、agents-cli run --url <service-url> --mode a2a "your prompt" を実行します。認証、セッション、ストリーミングを自動的に処理します（Agent Runtime と Cloud Run に対応）。ADK: --mode adk は、代わりに ADK ストリーミング API と通信します。

高度なテスト（カスタムヘッダー、セッションの再利用、スクリプト、負荷テスト）については、references/testing-deployed-agents.md を参照してください。

---

UI を使ったデプロイ（IAP）

IAP（Identity-Aware Proxy）は Cloud Run サービスを保護し、認可された Google アカウントのみがアクセスできるようにします。デプロイ時に --iap フラグを追加して有効にします（Cloud Run のみ）：agents-cli deploy --iap。

カスタムフロントエンドを Agent Runtime で使用する場合は、分離デプロイを使用してください。フロントエンドを Cloud Run または Cloud Storage に個別にデプロイし、Agent Runtime バックエンド API に接続します。

Cloud Run での IAP の詳細については、Cloud Console の IAP 設定を参照してください。

---

ロールバックと復旧

主なロールバック方法はGit ベースです。問題を修正してコミットし、main にプッシュします。CI/CD パイプラインによって、新しいバージョンがステージングから本番環境へ自動的にビルド、デプロイされます。

新しいコミットなしで Cloud Run をすぐにロールバックするには、リビジョンのトラフィック切り替えを使用します：

gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION

Agent Runtime はリビジョンベースのロールバックに対応していません。修正後、agents-cli deploy で再デプロイしてください。

GKE をロールバックするには、kubectl rollout undo を使用します：

kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE

---

カスタムインフラストラクチャ（Terraform）

重要：エージェントにカスタムインフラストラクチャ（Cloud SQL、Pub/Sub、Eventarc、BigQuery など）が必要な場合は、必ず Terraform で定義してください。gcloud コマンドを使って手動でリソースを作成してはいけません。例外として、gcloud またはコンソールを使った簡単な実験は問題ありませんが、本番インフラストラクチャは Terraform で管理する必要があります。

カスタムインフラストラクチャのパターンについては、references/terraform-patterns.md を参照してください。内容は以下のとおりです。

• カスタム Terraform ファイルの配置場所（単一プロジェクトと CI/CD）
• リソースの例（Pub/Sub、BigQuery、Eventarc トリガー）
• カスタムリソースの IAM バインディング
• Terraform の状態管理（リモートとローカル、リソースのインポート）
• 一般的なインフラストラクチャのパターン

---

トラブルシューティング

問題	解決策
Terraform の state がロックされている	deployment/terraform/ で terraform force-unlock -force LOCK_ID を実行します
GitHub Actions の認証に失敗する	CI/CD の terraform ディレクトリで terraform apply を再実行し、WIF のプール／プロバイダーを確認します
Cloud Build の認可が保留中	代わりに github_actions ランナーを使用します
リソースがすでに存在する	terraform import を実行します（references/terraform-patterns.md を参照）
Agent Runtime のデプロイがタイムアウトする／停止する	デプロイには 5～10 分かかります。エンジンが作成されたか確認します（Agent Runtime 固有の情報を参照）
シークレットを利用できない	デフォルトの compute SA ではなく、app_sa に secretAccessor が付与されていることを確認します
Cloud SQL の接続に失敗する／403 エラーが発生する	手動デプロイを使用する場合は、ランタイムのサービスアカウントに roles/cloudsql.client を付与します
デプロイ時に 403 エラーが発生する	deployment/terraform/iam.tf を確認します。cicd_runner_sa には、ターゲットプロジェクトでデプロイおよび SA の偽装に必要なロールが必要です
Cloud Run のテスト時に 403 エラーが発生する	デフォルトでは --no-allow-unauthenticated が設定されています。Authorization: Bearer $(gcloud auth print-identity-token) ヘッダーを含めます
コールドスタートが遅すぎる	Cloud Run の Terraform 設定で min_instance_count > 0 に設定します
Cloud Run で 503 エラーが発生する	リソース制限（メモリ／CPU）を確認し、max_instance_count を増やすか、コンテナのクラッシュログを確認します
IAM ロールを付与した直後に 403 エラーが発生する	IAM の反映には時間がかかります。再試行する前に数分待ってください。同じロールを何度も付与しないでください
Terraform で作成されたはずのリソースが見つからない	terraform state list を実行して、Terraform が実際に管理しているリソースを確認します。null_resource と local-exec で作成されたリソース（例：BQ のリンク済みデータセット）は、gcloud CLI の出力には表示されません
デプロイに失敗した、またはエージェントが応答しない	Cloud Logging を確認します。Cloud Run の場合は gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project=PROJECT --limit=50 --format="table(timestamp,severity,textPayload)"、Agent Runtime の場合は gcloud logging read "resource.type=aiplatform.googleapis.com/ReasoningEngine" --project=PROJECT --limit=50 を実行します
デプロイ後にエージェントがエラーを返す	Console で Cloud Logging を開き、サービス名（Cloud Run）または reasoning engine リソース（Agent Runtime）でフィルタリングし、最近のログエントリでスタックトレースや権限エラーを探します

---

プラットフォーム登録

デプロイしたエージェントを Gemini に登録する方法については、/google-agents-cli-publish を参照してください。

---

エージェントゲートウェイ

注： Agent Gateway や Semantic Governance ポリシーを作成、管理するための agents-cli コマンドはありません。これらは別途（Terraform または Cloud Console を使用して）設定してください。 ゲートウェイに対応しているコマンドは agents-cli deploy のみで、そのサポートはパススルーです。Agent Runtime の作成／更新呼び出しの一環として、エージェントを既存のゲートウェイにバインドします。

Agent Gateway は、すべてのエージェント間のやり取り（ユーザー↔エージェント、エージェント↔ツール、エージェント↔エージェント）におけるネットワークとセキュリティの入口／出口となるポイントです。アクセス制御と、管理された接続（イングレス／エグレス）を一元化します。デプロイ先ではありません。

ゲートウェイを設定するには、Agent Gateway の設定とAgent Runtime のトラフィックを Agent Gateway 経由でルーティングするの手順に従ってください。Terraform の google_network_services_agent_gateway（現在は google-beta プロバイダー）を使ってゲートウェイを管理することもできます。

ゲートウェイが作成されると、agents-cli deploy は --agent-gateway-egress および／または --agent-gateway-ingress を使ってエージェントをバインドします。どちらのフラグにも、完全なリソース名 （projects/PROJECT/locations/REGION/agentGateways/GATEWAY）を指定します。Agent Runtime のデプロイのみがサポートされ、エージェントには Agent Identity が必要です。

エグレスゲートウェイは、エージェントの送信通信を TLS 復号して検査するため、イメージがゲートウェイのルート CA を信頼している必要があります。この設定はスキャフォールド作成時にオプトインします。新しいプロジェクトを作成する場合は、agents-cli create に --agent-gateway フラグを渡してください。

agents-cli create my-agent --agent adk -d agent_runtime --agent-gateway

または、agents-cli scaffold enhance に同じフラグを渡して、既存のプロジェクトを更新できます。

agents-cli scaffold enhance . --agent-gateway

いずれの場合も、プラットフォームが挿入する AGENT_GATEWAY_ROOT_CERTIFICATES ビルド引数を使用する Dockerfile が書き込まれ、create_params の下に agent_gateway: true が記録されるため、scaffold upgrade でも設定が維持されます。ビルド引数のない Dockerfile に対して --agent-gateway-egress を指定してデプロイすると、上記のコマンドを案内するエラーが発生します。--no-agent-gateway を指定すると、この設定を再び削除できます。

詳細：Agent Gateway の概要。

顧客管理の暗号化（CMEK）

Agent Runtime エージェントは、Cloud KMS キーを使用して暗号化できます。キーは作成時に固定されるため、エージェントの作成場所で設定してください。開発用デプロイでは deploy --key を、ステージング／本番環境（infra cicd）および infra single-project では Terraform ファイルを使用します。Terraform で作成したエージェントに --key でキーを追加することはできません。必要なキーの付与設定と Terraform の編集については、references/cmek.md を参照してください。

Semantic Governance

Semantic Governance Policies（SGP） は、エージェントによるツールの呼び出しをユーザーの意図や組織の制約に沿ったものにする、自然言語によるセキュリティ／コンプライアンスレイヤーです。

• 概要：https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/semantic-governance-overview
• 設定：https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/configure-semantic-governance

---

関連スキル

• /google-agents-cli-workflow — 開発ワークフロー、コーディングガイドライン、運用ルール
• /google-agents-cli-adk-code — エージェントコードを記述するための ADK API クイックリファレンス
• /google-agents-cli-eval — 評価方法、データセットのスキーマ、eval-fix ループ
• /google-agents-cli-scaffold — agents-cli scaffold create／scaffold enhance を使ったプロジェクトの作成と拡張
• /google-agents-cli-observability — Cloud Trace、ロギング、BigQuery Analytics、サードパーティ統合
• /google-agents-cli-publish — Gemini の登録