agent-platform-architecture

Gemini プラットフォームのアーキテクチャとエンジニアリングガイド

このスキルは、複数プロジェクト階層、ハイブリッド／クロスクラウドネットワーク、ゼロトラストの ID 境界、インラインの安全性／ポリシー適用プレーンにまたがる、エンタープライズグレードの Gemini プラットフォームアーキテクチャを設計、構築、検証するためのリファレンスシステムです。

使用状況の記録

必ずお読みください：gcloud、REST API、MCP コマンドを実行する前に、 使用状況の記録の指示を 必ず読んで従ってください。

重要

アーキテクチャの対象範囲とリファレンスの参照ルール：SKILL.mdを使って、 対象トポロジー、エグレスモード、イングレスパターン、ガバナンス プレーンを選択してから、正確な CLI コマンド、REST／YAML スキーマ、Common Expression Language（CEL）式、 Python Agent Development Kit（ADK）ランタイムコードについて、信頼できる references/*.md のマニュアルを参照してください（実装構文の 唯一の信頼できる情報源はreferences/*.mdです）。Google Developer Knowledge MCP サーバーや Google 管理の MCP エンドポイントなど、リモートの Model Context Protocol（MCP）ツールを利用できる場合は、生の CLI／REST コマンドよりも リモート MCP ツールの呼び出しを優先してください。アーキテクチャ設計を求められた場合、 要求されていない顧客プロジェクトへのライブ変更を実行しないでください。

注意

機密操作の人間による承認ゲート：権限の広い Identity and Access Management（IAM）バインディング（roles/iap.egressor、 roles/compute.networkUser、roles/networkservices.admin）を付与するコマンドの実行や設定の適用、 Organization Policies（constraints/iam.managed.disableAccessPolicyBinding）の変更、 Unified Access Policy（UAP）または VPC Service Controls（VPC-SC）ポリシーの更新、 リソースの削除（REST のDELETE ...?force=trueまたは CLI の--quiet）を行う前に、必ずユーザーに 明示的な確認を求めてください。

前提条件、認証、リージョン、請求の設定

1. Google Cloud SDK、認証、プロジェクトの設定：

   • Google Cloud SDK (gcloud) をインストールし、CLI と Application Default Credentials の認証を行います （gcloud auth login && gcloud auth application-default login を実行するか、 GOOGLE_APPLICATION_CREDENTIALS を設定します）。

   • 対象のプロジェクトを選択または作成し（gcloud projects create {project_id} / gcloud config set project {project_id}）、デフォルトの リージョンを設定します（gcloud config set compute/region {region}。デフォルトは us-central1 です。Google Cloud Locations を参照してください）。さらに、 必要な API を有効にします。

     gcloud services enable aiplatform.googleapis.com agentregistry.googleapis.com \
       agentidentity.googleapis.com agentidentitycredentials.googleapis.com \
       networkservices.googleapis.com networksecurity.googleapis.com iap.googleapis.com \
       modelarmor.googleapis.com compute.googleapis.com dns.googleapis.com \
       certificatemanager.googleapis.com servicenetworking.googleapis.com
     

2. 請求、最小権限の IAM、製品の用語：
   • {host_project_id}、{gov_project_id}、{runtime_project_id}、および {mcp_project_id} で、有効な請求先アカウントが関連付けられていることを確認します（無料枠の 適用を評価する場合も必要です。Google Cloud Pricing を確認してください）。
   • 基本ロールの roles/owner や roles/editor ではなく、明示的に最小権限の IAM ロール （roles/aiplatform.user、roles/networkservices.admin、roles/compute.networkAdmin、 roles/compute.networkUser、roles/iap.egressor、または networkservices.agentGateways.get,networkservices.agentGateways.use,networkservices.operations.get を含むカスタムロール）を付与します。
   • 承認済みの製品名を使用します：Gemini platform、 Agent Runtime（reasoningEngines）、Agent Gateway （240.0.0.2:443）、Agent Connectivity Template (ACT)、Agent Registry、および Unified Access Policy (UAP Policy V2) / Semantic Governance Policy (SGP)。

---

3 フェーズのアーキテクトワークフローと判断ツリー

graph TD
    Start["Enterprise Gemini platform Architecture"] --> Q1{"1. Egress Destinations?"}
    Q1 -->|"RFC 1918 + Google APIs Only"| Priv["ACT: vpcEgress = PRIVATE_RANGES_ONLY<br/>• Direct Private Google Access (PGA)"]
    Q1 -->|"Public Internet, VPC-SC, or Non-RFC 1918 PUPI"| All["ACT: vpcEgress = ALL_TRAFFIC<br/>• 100% Egress via AGW VIP 240.0.0.2:443<br/>• Consolidate Core Google APIs FQDNs"]
    All --> Q2{"2. Layer 7 URL List or Cross-Cloud mTLS?"}
    Q2 -->|"No (Standard NAT)"| Nat["Direct Cloud NAT on PSC-I Subnet<br/>• ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG"]
    Q2 -->|"Yes (Next-Hop SWP)"| Swp["Next-Hop SWP (NEXT_HOP_ROUTING_MODE) + PBR<br/>• Internal and Google API DEFAULT_ROUTING bypasses<br/>• Default route via SWP ILB IP<br/>• Exclude PSC-I from manual Cloud NAT"]

1. フェーズ 1 — スコープの確認とアーキテクチャの調査：
   • スコープの境界と単一リージョンの調査：Gemini platform スタックと無関係な一般的な Google Cloud IAM／Compute／Storage のデバッグや、広範な複数リージョンのライブプロジェクトのスキャンループを実行するリクエストは断り、 代わりに gcloud ai reasoning-engines list --region={region} を案内します。
   • アーキテクチャの設計とエンジニアリング：プロジェクト階層 （Host、Governance Hub、Runtime Spoke、Tool/MCP Spoke）、エグレスモード （ALL_TRAFFIC と PRIVATE_RANGES_ONLY）、ポリシープレーン（UAP V2、SGP、Model Armor）、および対象の出力形式（トポロジー仕様、gcloud CLI コマンド、または REST／YAML マニフェスト）を特定します。
2. フェーズ 2 — アーキテクチャ計画案とリソースの対応付け：
   • Domain Router and Symptom Matrix を使用して、トポロジー図、プロジェクト／VPC のレイアウト、IAM ブートストラップ マトリックス、およびセキュリティ制御をまとめ、各マニュアルの標準 REST／YAML スキーマと CLI コマンドを対象のデプロイ成果物に対応付けます。
3. フェーズ 3 — デプロイ後の確認と監査ログの検証：
   • すべてのアーキテクチャ設計に、デプロイ後および Cloud Audit Log の検証チェックリスト （references/topologies_and_project_layouts.md）とランタイムクエリの 検証（references/agent_runtime_and_identity.md）を組み合わせます。

---

ドメインルーターと症状マトリックス

references/ 内の各リファレンスマニュアルは、そのドメインの CLI コマンド、REST/YAML スキーマ、クォータ、CEL 式に関する唯一の信頼できる情報源です。設定を生成したり、ドメイン固有の質問に回答したりする前に、必ず対応するリファレンスマニュアルを読んでください：

アーキテクチャのドメイン	対象となるトピックとアーキテクチャ上の決定事項	ここに振り分けられる症状と障害モード	正式なリファレンスマニュアル
1. プロジェクト階層、共有 VPC、VPC-SC、カスタムルーティング	マルチプロジェクトの分離（Host、Governance Hub、Runtime Spoke、Tool/MCP Spoke）、PSC-I サブネットのサイズ設定、プロジェクト間の Service Agent IAM ブートストラップ、VPC-SC 境界、RFC 1918 以外の PUPI／ピアリング済みカスタムルートの交換、デプロイ後の Cloud Audit Log 検証。	PSC-I IP の枯渇、プロジェクト間のアタッチメントまたは addressGroup 権限の拒否、VPC-SC 境界によるブロック、RFC 1918 以外の内部ルートのドロップ、またはデプロイ後の検証。	references/topologies_and_project_layouts.md
2. Agent Connectivity Template（ACT）と Agent Gateway	ALL_TRAFFIC と PRIVATE_RANGES_ONLY の選択、ACT と Agent Gateway の REST／YAML スキーマ、コントロールプレーン URI の形式、レジストリアタッチメントの上限、コンテナのカスタム Root CA バンドルの信頼設定。	コントロールプレーン URI の検証エラー、レジストリアタッチメントの上限エラー、またはコンテナの TLS 検証失敗（[SSL: UNEXPECTED_EOF_WHILE_READING]）。	references/agent_gateway_and_act.md
3. アウトバウンドルーティング、Next-Hop SWP、PBR、ハイブリッド mTLS	PSC-I サブネットの送信元範囲に基づくポリシーベースルート（PBR）、Next-Hop Secure Web Proxy（NEXT_HOP_ROUTING_MODE）、swg-autogen-nat と手動 Cloud NAT の共存、gRPC／A2A／WebSocket のルーティング、Spanner SA の偽装、Cross-Cloud mTLS Egress Hub（Hybrid NEG）。	手動 Cloud NAT と swg-autogen-nat 間の非対称な戻りルーティングによるドロップ、PSC-I インターフェース上のアウトバウンド URL フィルタリング、または Cloud Interconnect／VPN 経由のクロスクラウド mTLS オリジネーション。	references/egress_routing_and_swp.md
4. Ingress ALB、URL 書き換え、Private CA、3P IdP STS	URL Map の hostRewrite／pathPrefixRewrite を使用した二層および単層 ALB イングレス、Cloud Run MCP サーバー向け Regional Internal ALB + Serverless NEG を使用した Private CA TrustConfig、LbTrafficExtension（ext_proc + STS）経由の 3P IdP（EntraID／Ping／Okta）トークン交換。	WebPKI ルートの削除（NO_ADDITIONAL_ROOTS）、Serverless NEG での空の :authority によるドロップ、*.run.app の Google 管理証明書の不一致、または OAuth／IAP ヘッダーの衝突。	references/ingress_patterns_and_rewrites.md
5. UAP Policy V2、IAP V1、SGP、Model Armor ガバナンス	組織／フォルダ／プロジェクトの UAP Policy V2 および IAP V1 の CEL 認可ルール、Semantic Governance Policy（SGP CONTENT_AUTHZ）、カスタム AuthzExtension／AuthzPolicy のターゲット、fail-closed の Model Armor Floor Settings、テンプレート、ADK コールバック。	MCP の initialize または tools/list での Egress request is not authorized（HTTP 403／status.code=7）、AuthzExtension での failed to parse the service URL、バイナリ gRPC パーサーのクラッシュ、または fail-open による安全対策の回避。	references/governance_security_policies.md
6. Agent Registry、統合 googleapis、フェデレーション	コア Google API の FQDN を単一の googleapis サービス（ALL_TRAFFIC）に統合、MCP／A2A／REST サービスの登録、roles/iap.egressor 用にサーバー生成の registryResource UUID を抽出、イベント駆動型の Spoke から Hub へのレジストリフェデレーション。	ALL_TRAFFIC におけるエージェントの起動またはテレメトリーのブラックホール化、Registry リソースの IAM バインディング対象の不一致、OpenAPI／MCP 仕様のサイズ超過による拒否、または複数プロジェクト間のカタログの不整合。	references/registry_and_federation.md
7. ADK ランタイムのパッケージ化、エージェント ID、Day-2 運用	AGENT_IDENTITY（SPIFFE）と Auth Manager を使用した ADK エージェントのパッケージ化、リージョン内データレジデンシー、BigQuery の実行前コストガード、ACT のインプレース更新、逆依存関係に基づくティアダウン、外部 Cloud NAT IP の検証。	認証情報の平文露出、HTTP 409 ABORTED コントロールプレーンのミューテックスロック、HTTP 400 FAILED_PRECONDITION（FROM_AGENT_GATEWAY* または contains child resources: sessions）、または *.run.app のプローブ時における X-Forwarded-For: 0.0.0.0。	references/agent_runtime_and_identity.md

---

公開ドキュメントの参考リンク

• エージェントランタイムの概要
• エージェントゲートウェイの概要
• ポリシーの概要
• エージェント ID の概要
• エージェントレジストリの概要
• エージェントゲートウェイランタイムのデプロイ
• Private Service Connect インターフェース