google-cloud-solution-multi-agent-security

Agent Gateway のマルチエージェントセキュリティ

帰属表示

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 Usage Attribution の指示を 必ず読み、従ってください。

重要な適用ルールと理由

• Gcloud のリリーストラック：コマンドで指定されているリリーストラックを必ず正確に使用してください （例：gcloud beta network-services agent-gateways）。これらのプレフィックスを省略すると、 Agent Gateway の機能がデフォルトではない専用の名前空間にあるため、コマンドが失敗します。
• API の有効化：ガードレールを設定する際は、API の 有効化リストに modelarmor.googleapis.com を含めてください。 これを除外すると、Model Armor のポリシーとフィルターを Gateway に正常に適用できません。
• Egress の検証：Egress ポリシーの検証には、curl ではなく、 Python スクリプト （scripts/verify_egress_policies.py）を使用する必要があります。Egress ゲートウェイはランタイム SDK のライフサイクル処理と JWT コンテキストに依存しており、通常の curl コマンドでは正しく再現できません。
• Model Armor のキー：model-armor-config.yaml には、piAndJailbreakFilterSettings と sdpFilterSettings の両方を必ず含めてください（filterEnforcement: ENFORCE）。フィルターが無効または存在しないと、デプロイの検証に失敗するか、ガードレールが気付かれないまま回避される可能性があります。
• サブネットのプライベートアクセス：Egress Gateway 用の Private Service Connect ネットワーク アタッチメントをホストするサブネットでは、Terraform で private_ip_google_access = true を有効にする必要があります。これを無効にすると、Google が管理するエンドポイントへの接続が遮断され、エージェントのルーティングが完全に失敗します。
• 直接提供：要求されたアーキテクチャ、設定ファイル、CLI コマンド、スクリプト、図を、直ちにすべて提示してください。計画の段階で止めたり、計画成果物を生成したり、出力を提示する前にユーザーの確認を求めたりしないでください。
• インフラストラクチャを実行しない：設計中に、実際のクラウドリソースに対してデプロイや検証のコマンド（gcloud、kubectl、terraform、curl など）を実行しようとしないでください。生成するのは計画用の設定であり、実行するものではありません。

重要

Just-In-Time（JIT）リソース読み込みプロトコル： 拡張設定、デプロイスクリプト、テストスイートが必要な場合は、必要に応じて view_file を使い、assets/ 内のテンプレートファイルと scripts/ 内の実行可能スクリプトを確認してください。

---

クイックリファレンス：必須ファイル名

要求された場合は、必ず次の正確な名前でファイルを生成してください。

1. agw-ingress-config.yaml (assets/agw-ingress-config.yaml)
2. agw-egress-config.yaml (assets/agw-egress-config.yaml)
3. agw-authz-extension.yaml (assets/agw-authz-extension.yaml)
4. agw-authz-policy.yaml (assets/agw-authz-policy.yaml)
5. model-armor-config.yaml (assets/model-armor-config.yaml)
6. sgp-policy.yaml (assets/sgp-policy.yaml)
7. iap-policy.json (assets/iap-policy.json)
8. model-armor-payload.json (assets/model-armor-payload.json)

---

1. デュアルイングレス＆エグレスアーキテクチャ設計 (dual_ingress_egress_architecture_design)

• イングレスパターン: イングレスコントロールプレーン （Agent Gateway、Model Armor）を前段に配置した CLIENT_TO_AGENT。

• エグレスパターン: エグレスコントロールプレーン （Agent Gateway、roles/iap.egressor CEL ポリシー、Cloud DNS）とエグレス データプレーン（PSC Interface、Cloud Run、PSC Google APIs Global Endpoint）を 使用する AGENT_TO_ANYWHERE。Agent Registry と Agent Engine ランタイムを介して 調整します。

• Mermaid 図:

  graph TD
      Client["外部クライアント"] -->|HTTPS / MCP| GLB["グローバルロードバランサ"]
      GLB --> Ingress["イングレス Agent Gateway (CLIENT_TO_AGENT)"]
      Ingress --> MA["Model Armor (CONTENT_AUTHZ)"]
      MA --> Agent["Agent Engine エージェント (BillingAgent, SupportAgent, FraudAgent)"]
      Agent --> Egress["エグレス Agent Gateway (AGENT_TO_ANYWHERE)"]
      Egress --> PSC["Private Service Connect ネットワークアタッチメント"]
      PSC --> Tools["プライベート MCP ツールバックエンド"]
  

---

2. イングレス＆エグレスガードレールポリシーの設定 (ingress_and_egress_guardrail_policy_config)

イングレス＆エグレスガードレールポリシーの設定を求められた場合、ワークスペース内に必要なファイルをすべて生成して作成する必要があります。

• agw-ingress-config.yaml (assets/agw-ingress-config.yaml): プロトコル HTTP と MCP を使用する governedAccessPath: CLIENT_TO_AGENT を宣言します。
• agw-egress-config.yaml (assets/agw-egress-config.yaml): プロトコル MCP を使用する governedAccessPath: AGENT_TO_ANYWHERE を宣言します。
• agw-authz-extension.yaml (assets/agw-authz-extension.yaml): IAP 認可用に AuthzExtension サービスを設定します。
• agw-authz-policy.yaml (assets/agw-authz-policy.yaml): イングレスゲートウェイとエグレスゲートウェイの両方を対象とする AuthzPolicy アクション ALLOW を設定します。
• iap-policy.json (assets/iap-policy.json): CEL 条件を使用して roles/iap.egressor をバインドし、次の条件を確認します。 iap.googleapis.com/mcp.toolName == 'get_account_balance' && iap.googleapis.com/mcp.tool.isReadOnly == true。
• model-armor-config.yaml (assets/model-armor-config.yaml): filterEnforcement: ENFORCE で piAndJailbreakFilterSettings と sdpFilterSettings を有効にします。
• sgp-policy.yaml (assets/sgp-policy.yaml): 1,000 ドルを超える取引をブロックし、PII をサニタイズする自然言語制約を 実装します。

---

3. イングレス＆エグレスインフラストラクチャのデプロイ (ingress_and_egress_infrastructure_deployment)

scripts/deploy_infrastructure.sh を確認し、 ステップごとの gcloud CLI コマンドを提示します。

1. 必要な API を有効にする: compute、networkservices、networksecurity、 modelarmor、iap、agentregistry、serviceextensions、aiplatform。
2. Agent Gateway をインポートする: イングレス（agw-ingress-config.yaml）とエグレス （agw-egress-config.yaml）を gcloud alpha network-services agent-gateways import でインポートします。
3. Authz Extension をインポートする: agw-authz-extension.yaml を gcloud beta service-extensions authz-extensions import でインポートします。
4. Authz Policy をインポートする: agw-authz-policy.yaml を gcloud beta network-security authz-policies import でインポートします。

---

4. Ingress と Egress のセキュリティ検証（ingress_and_egress_security_validation）

Ingress と Egress のセキュリティを検証する場合：

1. Ingress 403 未認証テスト：Reasoning Engine エンドポイントに認証なしで POST リクエストを送信し、HTTP 403 Forbidden を期待する、コピーしてそのまま実行できる検証用 curl コマンドを scripts/validate_ingress_unauth.sh から提示してください。
2. Python Egress 検証スクリプト（Python スクリプトのスニペットを必ず使用し、curl は使用しないでください）：Egress Gateway 経由で JSON-RPC の tools/call リクエスト（get_account_balance）を送信し、許可されたツールに対する HTTP 200 を検証する Python 検証スクリプトのスニペットを scripts/verify_egress_policies.py から提示してください。
3. Model Armor テストペイロード：プロンプトインジェクション／ジェイルブレイクの指示を含む model-armor-payload.json （assets/model-armor-payload.json） を生成してください。

---

5. Ingress と Egress の障害のトラブルシューティング（troubleshooting_ingress_and_egress_failures）

• Ingress 403（クライアントからエージェント）：

  • 根本原因：認証されていないクライアントリクエスト、または OAuth 2.0／IAP ID トークンの不足もしくは無効です。
  • OAuth の設定手順：
    1. Google Cloud Console で OAuth 2.0 クライアント ID の認証情報を設定します。
    2. クライアント ID／サービスアカウントに roles/iap.httpsResourceAccessor 権限を付与します。
    3. Google OAuth で認証情報を交換し、OIDC／OAuth ID トークンを取得します。
    4. Authorization: Bearer <TOKEN> ヘッダーにトークンを渡します。
  • 検証コマンド： scripts/verify_ingress_auth.sh の curl コマンドを提示してください。

• Egress 403（エージェントから任意の宛先）：

  • 根本原因：Agent Identity に対する roles/iap.egressor IAM バインディングの不足、プリンシパル ID の形式不正、またはツールメタデータ上の CEL 条件の不一致です。
  • 修正コマンド： scripts/fix_egress_iap.sh に記載されている正確な gcloud コマンドを提示してください。

---

6. ハイブリッド VPN 接続と Egress ルーティング（hybrid_vpn_connectivity_egress_routing）

• Terraform HCL：VPC、サブネット （private_ip_google_access = true）、PSC ネットワークアタッチメント、aws.internal. の Cloud DNS プライベートフォワーディング、HA VPN ゲートウェイ／ルーターのベースライン Terraform 設定については assets/main.tf を参照してください。
• Egress Gateway 設定（agw-egress-config.yaml）：governedAccessPath: AGENT_TO_ANYWHERE を宣言し、PSC ネットワークアタッチメントを指定し、dnsPeeringConfig で aws.internal. を参照する設定を生成してください（assets/agw-egress-config.yaml を参照）。
• Python SDK デプロイスクリプト：Egress Gateway を参照する agent_to_anywhere_config を使用して Vertex AI を初期化し、テレメトリーを有効化し、types.IdentityType.AGENT_IDENTITY を使用して HybridAgent をデプロイする完全なスクリプトについては、 scripts/hybrid_vpn_agent.py を参照してください。

---

7. プライベート Egress GKE 内部ロードバランサー (private_egress_gke_internal_load_balancer)

• Agent Gateway PSC Interface と Cloud DNS Private zone を介して接続し、GKE の内部 MCP ツールサーバーをリテラル IP 10.0.1.50 の内部ロードバランサー（ILB）経由で公開します。
• Cloud DNS レコードのマッピング：scripts/create_gke_dns_record.sh のコマンドを提示し、プライベートドメインを GKE のプライベート ILB IP 10.0.1.50 にマッピングします。
• 明示的な TLS に関する警告：Agent Gateway の egress は、自己署名証明書やプライベートな企業 CA を標準では信頼しません。信頼できる認証局（例：Let's Encrypt）が署名した、パブリックに信頼される TLS 証明書を必ず使用してください。

---

8. ガバナンス制御：Model Armor SGP (governance_controls_model_armor_sgp)

Ingress で Model Armor、Egress で SGP を使用して二重の安全レイヤーを設定する場合：

1. Model Armor の設定：piAndJailbreakFilterSettings と sdpFilterSettings（filterEnforcement: ENFORCE）を含む model-armor-config.yaml（assets/model-armor-config.yaml）を生成します。
2. Semantic Governance Policy：1000 ドルを超える取引をブロックし、PII をサニタイズする自然言語の制約を含む sgp-policy.yaml（assets/sgp-policy.yaml）を生成します。
3. Curl PATCH コマンド：sgpEnforcementMode を ENFORCE に設定して authzExtensions を更新するため、scripts/enforce_sgp_patch.sh の curl コマンドを提示します。

---

9. マルチエージェント Cloud Run Egress ルーティング (multi_agent_cloud_run_egress_routing)

計画用の成果物を作成したり、計画段階で止めたりしないでください。マルチエージェントの Cloud Run Egress ルーティングを設定する際は、必要なコンポーネントをすべて直接提示し、生成する必要があります。

1. Egress Gateway の設定（agw-egress-config-run.yaml）：governedAccessPath: AGENT_TO_ANYWHERE、PSC ネットワーク接続、および *.run.app の DNS ピアリングを宣言する設定を生成します（assets/agw-egress-config-run.yaml を参照）。
2. Agent Registry への Cloud Run サービスの登録：scripts/register_cloud_run_services.sh の登録コマンドを提示し、Cloud Run サービス 3 つ（marketing-tool-service、sales-tool-service、support-tool-service）を us-east4 の Agent Registry に登録します。
3. iap-policy.json（マルチエージェント）：roles/iap.egressor 配下の members リストに、principal:// バインディングを 3 つすべて含む iap-policy.json（assets/iap-policy-multi-agent.json）を生成します。
4. Python SDK デプロイスクリプト：完全な GenAI SDK デプロイスクリプトについては、scripts/multi_agent_cloud_run.py を参照してください。

---

10. 高度な Model Armor フィルタリング (advanced_model_armor_filtering)

カスタムキーワードマッチングには、userDefinedFilterSettings を設定します（assets/model-armor-advanced.yaml を参照）。

---

11. 既知の落とし穴と注意点 (known_traps_and_gotchas)

• network_attachment は ForceNew です：Semantic Governance Policies（SGP）を有効にしたり、最初の Terraform apply の後でネットワーク接続を変更したりすると、ゲートウェイリソースが強制的に再作成されます。慎重に管理しない場合、destroy 操作中に依存関係のデッドロックが発生することがあります。これに応じてインフラストラクチャの適用順序を計画してください。
• Authz ポリシーの上限：Agent Gateway に同時にアタッチできるカスタム認可ポリシーは最大 4 つです。この上限内でルールを統合し、セキュリティ態勢を整えてください。