Gemini Enterprise Agent Platform から Apigee に非公開でアクセスする

このページの内容は Apigee に適用されます。Apigee ハイブリッドには適用されません。

Apigee Edge のドキュメントを表示する

このドキュメントでは、Private Service Connect を使用して、Gemini Enterprise Agent Platform Agent Runtime にデプロイされたエージェントから、Apigee で公開された API と Model Context Protocol（MCP）ツールへのプライベート接続を構成する方法について説明します。このパターンでは、エージェントから Apigee へのトラフィックは完全にプライベートな状態を維持し、公共のインターネットを経由しません。

概要

Agent Runtime は、Virtual Private Cloud（VPC）ネットワークにアクセスできない Google が管理する安全なネットワークにエージェントをデプロイします。同様に、Apigee は安全な Google マネージド ネットワークで実行されます。大規模言語モデル（LLM）または Apigee を介して公開された MCP ツールに対するエージェントの呼び出しを非公開で転送する場合は、ユーザーが制御する VPC ネットワークを介して、これら 2 つの Google 管理ネットワークをブリッジする方法が必要です。

このドキュメントでは、そのブリッジの次のパターンについて説明します。

この構成では、エージェントが https://APIGEE_HOSTNAME/... を呼び出すと、リクエストは VPC の Private Service Connect エンドポイント IP に解決され、サービス アタッチメントを介して Apigee インスタンスに転送され、リクエスト パスに一致する API プロキシによって処理されます。

始める前に

このドキュメントでは、コマンドで次のプレースホルダを使用します。これらは、実際の環境の値に置き換えてください。

  • APIGEE_PROJECT_ID: Apigee 組織を含む Google Cloud プロジェクト ID。
  • SERVICE_PROJECT_ID: エージェントを Agent Runtime にデプロイする Google Cloud プロジェクト ID。これは、Google Cloud リソースの整理方法に応じて、APIGEE_PROJECT_ID と同じプロジェクトにすることも、別のプロジェクトにすることもできます。
  • SERVICE_PROJECT_NUMBER: SERVICE_PROJECT_ID の数値プロジェクト番号。これは gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)" で取得できます。
  • HOST_PROJECT_ID: コンシューマー VPC ネットワーク、サブネット、Cloud DNS プライベート ゾーンを含む Google Cloud プロジェクト ID。共有 VPC を使用している場合を除き、これは SERVICE_PROJECT_ID と同じです。共有 VPC を使用している場合は、サービス プロジェクトが接続するホスト プロジェクトになります。
  • REGION: Apigee インスタンスのリージョン（例: us-west1）。
  • VPC_NAME: HOST_PROJECT_ID 内のコンシューマー VPC ネットワークの名前。
  • SUBNET_NAME: REGION にある VPC_NAME のサブネットの名前。
  • APIGEE_HOSTNAME: Apigee 環境グループで構成したホスト名（api.internal.example.com など）。
  • BASE_PATH: Apigee にデプロイされた API プロキシのベースパス（/mcp や /orders など）。
  • PARENT_DNS_NAME: プライベート ゾーンから提供する APIGEE_HOSTNAME の親 DNS ドメイン（internal.example.com. など）。値はドットで終わる必要があります。
  • APIGEE_INSTANCE_NAME: REGION 内の Apigee インスタンスの名前。

次のものが必要です。

  • 課金が有効になっている 1 つ以上の Google Cloud プロジェクト（前のメモを参照）。
  • APIGEE_PROJECT_ID に既存の Apigee 組織があり、少なくとも 1 つのインスタンスがある。このドキュメントでは、最もシンプルな構成である Apigee インスタンスと同じリージョンに、すべてのコンシューマー ネットワーキング リソース（ネットワーク アタッチメント、Private Service Connect エンドポイント、Agent Runtime デプロイ）を作成します。
  • 環境がその Apigee インスタンスにデプロイされ、エージェントが呼び出すホスト名を含む環境グループ。このドキュメントでは、このホスト名を APIGEE_HOSTNAME と呼びます。
  • その環境グループの環境にデプロイされた API プロキシが 1 つ以上ある。エージェントに呼び出させるプロキシは、https://APIGEE_HOSTNAME/BASE_PATH で到達可能である必要があります。
  • HOST_PROJECT_ID の VPC ネットワークとサブネット。Apigee インスタンスと同じリージョンに存在します。このドキュメントでは、これらを VPC_NAME と SUBNET_NAME とします。Agent Runtime には最小 /28 サブネットが必要であり、追加の範囲制限が適用されます。詳細については、Agent Platform ドキュメントのサブネットワークの IP 範囲の要件をご覧ください。
  • 適切なプロジェクトで次の API が有効になっている。
    • APIGEE_PROJECT_ID の Apigee（apigee.googleapis.com）。
    • HOST_PROJECT_ID の Compute Engine（compute.googleapis.com）と Cloud DNS（dns.googleapis.com）。
    • SERVICE_PROJECT_ID の Agent Platform（aiplatform.googleapis.com）。
  • HOST_PROJECT_ID で Cloud DNS ゾーンとレコード、Compute Engine アドレス、ネットワーク アタッチメント、Private Service Connect 転送ルールを作成し、APIGEE_PROJECT_ID で Apigee インスタンスと環境グループの構成を更新するのに十分な IAM 権限。必要なロールの詳細については、Apigee のロール、Cloud DNS アクセス制御、Compute Engine IAM ロールをご覧ください。

アーキテクチャ

次の手順では、コンシューマー VPC の Private Service Connect エンドポイントをブリッジとして使用して、Agent Runtime にデプロイされたエージェントと Apigee でホストされている API プロキシ間のトラフィック フローについて説明します。

  1. Agent Runtime で実行されているエージェントが APIGEE_HOSTNAME に HTTPS リクエストを送信します。
  2. Agent Runtime PSC インターフェースで構成された DNS ピアリングは、ルックアップをコンシューマー VPC の Cloud DNS プライベート ゾーンに転送します。このゾーンは、Private Service Connect エンドポイントの IP アドレスを返します。
  3. エージェントのリクエストは、PSC インターフェースを介してコンシューマー VPC に送信され、その IP アドレスの Private Service Connect エンドポイントに到達します。
  4. Private Service Connect エンドポイントは、サービス接続を介してリクエストを Apigee インスタンスのサービス アタッチメントに転送します。
  5. Apigee インスタンスは TLS を終了し、リクエストのホスト名を環境グループと照合して、正しい API プロキシに転送します。

ステップ 1: コンシューマー VPC でネットワーキングを構成する

このセクションでは、2 つのプロジェクトにまたがってリソースを構成します。各コマンドには明示的な --project フラグが含まれているため、アクティブな gcloud 構成からコマンドを実行できます。

  • 限定公開ゾーンはコンシューマー VPC ネットワークに接続されるため、Cloud DNS リソース（限定公開ゾーンとレコード）は HOST_PROJECT_ID に作成されます。
  • Private Service Connect エンドポイント リソース（静的内部 IP アドレスと転送ルール）とネットワーク アタッチメントは SERVICE_PROJECT_ID に作成されます。これらの各コマンドは、HOST_PROJECT_ID の共有サブネットまたは VPC ネットワークへのプロジェクト間の参照を使用します。単一プロジェクトのデプロイでは、SERVICE_PROJECT_ID と HOST_PROJECT_ID は同じであるため、ステップ間で所有権が変更されることはありません。Private Service Connect エンドポイントの共有 VPC モデルの詳細については、共有 VPC サービス プロジェクトにエンドポイントを作成するをご覧ください。

Cloud DNS プライベート ゾーンを作成する

コンシューマー VPC にのみ表示される Cloud DNS 限定公開ゾーンを作成します。エージェントは、このゾーン（DNS ピアリング経由）を使用して APIGEE_HOSTNAME をプライベート IP アドレスに解決します。

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Cloud DNS 限定公開ゾーンの詳細については、限定公開ゾーンをご覧ください。

ネットワーク アタッチメントを作成する

Agent Runtime PSC インターフェースを表示するリージョンとサブネットにネットワーク アタッチメントを作成します。エージェントがデプロイされると、Agent Runtime は PSC インターフェースをこのアタッチメントにバインドします。

単一プロジェクトのデプロイでは、SERVICE_PROJECT_ID（HOST_PROJECT_ID でもあります）にネットワーク アタッチメントを作成します。共有 VPC デプロイでは、サービス プロジェクトまたはホスト プロジェクトのいずれかにネットワーク アタッチメントを作成できます。権限を簡素化するために、Agent Platform ではサービス プロジェクトをおすすめします。選択と対応する IAM ロールのガイダンスについては、共有 VPC で Private Service Connect インターフェースを使用するをご覧ください。

次のコマンドは、SERVICE_PROJECT_ID にネットワーク アタッチメントを作成します。共有 VPC デプロイでは、サブネット参照にホスト プロジェクト ID を含める必要があります。

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

静的内部 IP アドレスの予約

エージェントが接続する Private Service Connect エンドポイントの IP として使用する内部 IP アドレスを予約します。SERVICE_PROJECT_ID にアドレス リソースを作成し、HOST_PROJECT_ID で共有サブネットを参照して、アドレス値がそのサブネットの範囲から割り当てられるようにします。これは、共有 VPC で静的内部 IP アドレスを使用するの共有 VPC のガイダンスと一致します。

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

後の手順で使用する予約済みアドレスを取得します。

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

このドキュメントでは、このアドレスを PSC_ENDPOINT_IP と呼びます。

Apigee インスタンスのサービス アタッチメントを取得する

Apigee API の organizations.instances.get メソッドを使用して、Apigee インスタンスのサービス アタッチメント URI を取得します。この URI は、Private Service Connect エンドポイントのターゲットとして使用します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

レスポンスには serviceAttachment フィールドが含まれます。このドキュメントでは、この値を APIGEE_SERVICE_ATTACHMENT と呼びます。Apigee が各インスタンスでサービス アタッチメントを公開する方法の詳細については、インスタンスの管理をご覧ください。

Private Service Connect エンドポイントを作成する

Private Service Connect エンドポイントとして機能する転送ルールを作成します。Apigee サービス アタッチメントをターゲットとし、予約した静的 IP を使用します。SERVICE_PROJECT_ID に転送ルールを作成し、HOST_PROJECT_ID の共有 VPC ネットワークと SERVICE_PROJECT_ID のアドレスを参照します。

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Apigee サービスが接続を受け入れたことを確認します。

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

エンドポイントがトラフィックを転送するには、ステータスが ACCEPTED である必要があります。Private Service Connect エンドポイントの詳細については、エンドポイントを介した公開サービスへのアクセスについてをご覧ください。

ホスト名の DNS レコードを追加する

限定公開ゾーンで、APIGEE_HOSTNAME を PSC_ENDPOINT_IP に解決する A レコードを作成します。このレコードは VPC_NAME 内でのみ表示されるため、外部クライアントは引き続きパブリック DNS を介してホスト名を解決します。

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

ステップ 2: Apigee を構成する

インスタンスのコンシューマー承認リストにサービス プロジェクトを追加する

Apigee インスタンスは、consumerAcceptList にあるコンシューマー プロジェクトからの Private Service Connect 接続のみを受け入れます。接続のコンシューマー側は SERVICE_PROJECT_ID に関連付けられています。これは、エージェントがデプロイされているプロジェクトであるためです。

デフォルトでは、Apigee 組織（APIGEE_PROJECT_ID）に関連付けられているプロジェクトがすでにリストに表示されています。SERVICE_PROJECT_ID が APIGEE_PROJECT_ID と同じ場合は、変更は不要で、このセクションをスキップできます。それ以外の場合は、SERVICE_PROJECT_ID をリストに追加します。

まず、organizations.instances.get メソッドを使用して、consumerAcceptList の現在の値を確認します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

レスポンスで consumerAcceptList フィールドを探します。

次に、consumerAcceptList の更新マスクを使用して organizations.instances.patch メソッドを呼び出し、リストを更新します。このフィールドは既存のリストを置き換えるため、APIGEE_PROJECT_ID やエージェントをデプロイする追加のサービス プロジェクトなど、アクセスを保持する必要があるすべてのプロジェクト ID を含めます。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

get コマンドを再度実行し、SERVICE_PROJECT_ID が consumerAcceptList に含まれていることを確認して、更新を確認します。

環境グループのホスト名を確認する

API プロキシをホストする環境グループに APIGEE_HOSTNAME がリストされていることを確認します。ない場合は追加します。

手順については、環境グループの操作をご覧ください。

ステップ 3: PSC インターフェースと DNS ピアリングを使用してエージェントをデプロイする

エージェントを Agent Runtime にデプロイするときは、作成したネットワーク アタッチメントを参照する PSC インターフェースを使用してエージェントを構成し、プライベート ゾーンへの DNS ピアリングを構成します。完全なデプロイ手順とサポートされているフレームワークについては、Agent Platform ドキュメントのAgent Runtime で Private Service Connect インターフェースを使用するとエージェントをデプロイするをご覧ください。

エージェントの PSC インターフェース構成で次の 2 つのフィールドを構成します（PscInterfaceConfig リファレンスを参照）。

  • networkAttachment: ステップ 1 で作成したネットワーク アタッチメントの完全なリソース名（projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment 形式）に設定します。ホスト プロジェクトにネットワーク アタッチメントを作成した場合は、このパスで HOST_PROJECT_ID を使用します。
  • dnsPeeringConfigs: 次のフィールドを使用してエントリを 1 つ追加し、Agent Runtime がプライベート ゾーンを介して APIGEE_HOSTNAME を解決するようにします。
    • domain: PARENT_DNS_NAME。値の末尾はピリオドにする必要があります。
    • targetProject: HOST_PROJECT_ID。これは、コンシューマー VPC とプライベート ゾーンを含むプロジェクトです。
    • targetNetwork: VPC_NAME

SERVICE_PROJECT_ID（service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com）の Agent Platform サービス エージェントには、DNS ピアリングを構成してネットワーク アタッチメントを更新する権限が必要です。Agent Platform サービス エージェントに必要なロールの説明に従って、必要なロールを付与します。共有 VPC デプロイでは、ホスト プロジェクトに追加のロールが適用されます。共有 VPC で Private Service Connect インターフェースを使用するをご覧ください。

エージェント コードから、https://APIGEE_HOSTNAME/BASE_PATH で API プロキシを呼び出します。Agent Runtime 環境内では、このホスト名は DNS ピアリングを介して PSC_ENDPOINT_IP に解決され、リクエストは Private Service Connect エンドポイントを介して VPC に転送され、Apigee に転送されます。

プライベート パスを確認する

エージェントをデプロイしたら、リクエストがプライベート パスを介して Apigee に到達することを確認します。

  • Private Service Connect エンドポイントを作成するのコマンドを使用して、転送ルールのステータスが ACCEPTED であることを確認します。
  • REGION の VPC_NAME に接続された Compute Engine VM から（共有 VPC デプロイでは、この VM はホスト プロジェクトまたは共有 VPC に接続されたサービス プロジェクトのいずれかに存在します）、dig +short APIGEE_HOSTNAME を実行します。結果は PSC_ENDPOINT_IP にする必要があります。これにより、限定公開ゾーンが VPC 内でホスト名を正しく解決することが確認されます。
  • 同じ VM から、デプロイされた API プロキシ（https://APIGEE_HOSTNAME/BASE_PATH）にリクエストを送信し、想定されるレスポンスを受信することを確認します。
  • デプロイされたエージェントを呼び出し、リクエストが処理されたことを確認します。次に、Apigee Analytics または Debug を使用して、リクエストが環境グループのホスト名で想定される API プロキシに到達したことを確認します。

次のステップ