Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Apigee Extension Processor を Agent Gateway に接続する

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

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

このページでは、Apigee 拡張機能プロセッサを Agent Gateway に接続して、AI エージェントがモデル、ツール、使用する Model Context Protocol（MCP）サーバーに対して行う呼び出しに Apigee ポリシーを適用する方法について説明します。この接続では、エージェントを変更する必要はありません。

Agent Gateway は、エージェントのトラフィックのネットワークエントリポイントと出口ポイントです。ロードバランサではないため、トラフィック拡張機能は使用しません。代わりに、ゲートウェイは認可拡張機能に認可を委任します。拡張機能プロセッサをその拡張機能として構成します。接続されると、ゲートウェイは各エージェントのリクエストとレスポンスを Apigee に送信して処理し、Apigee は判定を返します。

次の図は、このページで作成するリソースと、単一エージェントリクエストがそれらのリソースを通過するパスを示しています。

エージェントリクエストは Agent Gateway で保持され、Private Service Connect 経由で Apigee に送信されて判定を受け、転送されます。 — **図 1.** Apigee 拡張機能プロセッサが Agent Gateway の認可拡張機能である場合のコンポーネントとリクエストフロー。

図 1 では、リクエストは次のように処理されます。

エージェントは、モデル、ツール、MCP サーバーに通常の HTTPS リクエストを送信します。エージェントは作成時にゲートウェイにバインドされるため、変更は必要ありません。
ゲートウェイはリクエストを保持し、判定のために認可拡張機能を呼び出します。
コールアウトはネットワークアタッチメントを介して送信されるため、VPC ネットワーク内で発生します。
プライベート DNS ゾーンは、コールアウトホスト名を Private Service Connect エンドポイントの内部 IP アドレスに解決します。
エンドポイントは、コールアウトを Apigee インスタンスのサービスアタッチメントに転送します。
環境グループは、ホスト名でコールアウトをターゲットなしプロキシにルーティングします。ここで、ポリシーが実行されます。
プロキシがゲートウェイに判定結果を返します。Apigee はエージェントのトラフィックを転送しません。プロキシにターゲットはありません。
判定でリクエストが許可された場合、ゲートウェイは元のリクエストを宛先に転送します。

図 1 の AuthzPolicy と AuthzExtension は、トラフィックではなく構成です。ポリシーは拡張機能をゲートウェイに接続し、拡張機能は実行される拡張機能プロセッサプロキシに名前を付けます。どちらも、認可拡張機能を構成するで作成します。

拡張機能プロセッサをロードバランサに接続する場合は、Apigee 拡張機能プロセッサを使ってみるをご覧ください。

以降のセクションでは、手順について詳しく説明します。

Apigee 拡張機能プロセッサを構成する。
Agent Gateway を Apigee に接続します。
認可拡張機能を構成します。
接続を確認します。

始める前に

始める前に、次のタスクを完了します。

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

Roles required to enable APIs

Enable the APIs

Google Cloud CLI をインストールします。

Google Cloud CLI をインストールしたら、gcloud components update コマンドを実行して最新の gcloud コンポーネントを取得します。
Apigee インスタンスをまだプロビジョニングしていない場合は、プロビジョニングします。

Google Cloud コンソールで、[Apigee インスタンス] ページに移動します。

[Apigee インスタンス] に移動
Apigee インスタンスと同じリージョンに Agent Gateway をデプロイし、governedAccessPath を AGENT_TO_ANYWHERE に設定して、ゲートウェイがエージェントのアウトバウンドトラフィックを制御するようにします。詳細については、Agent Gateway を構成するをご覧ください。

このゲートウェイのネットワーク構成は、DNS ゾーンが存在するようになった後で、Agent Gateway を更新するで更新します。
Agent Gateway と Private Service Connect エンドポイントの両方で使用できる VPC とサブネットがあることを確認します。

[VPC ネットワーク] に移動

必要なロール

Apigee 拡張機能プロセッサを Agent Gateway に接続するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

Apigee リソースを作成して管理する: 組織に対する Apigee 組織管理者（roles/apigee.admin）
サービス拡張機能を作成して管理する: 組織のサービス拡張機能管理者（roles/networkservices.serviceExtensionsAdmin）
認可ポリシーを作成して管理する: 組織に対するネットワークセキュリティ管理者（roles/networksecurity.admin）
Private Service Connect エンドポイントや DNS などのネットワーキングリソースを作成して管理する: 組織に対する Compute ネットワーク管理者（roles/compute.networkAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

環境変数を設定する

次の環境変数を設定して、始める前にで作成したリソースを特定します。このページの以降の各セクションでは、名前付きリソースの作成時に必要な追加の変数を定義します。

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

ここで

PROJECT_ID は、Apigee インスタンスを含むプロジェクトの ID です。
REGION は Apigee インスタンスの Google Cloud リージョンです。
INSTANCE: Apigee インスタンスの名前。
VPC_NETWORK_NAME と SUBNET は、Agent Gateway と Private Service Connect エンドポイントが使用する VPC ネットワークとサブネットです。
GATEWAY は、デプロイした Agent Gateway の名前です。

環境変数が正しく設定されていることを確認するには、次のコマンドを実行して出力を確認します。

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

コールアウトホスト名を選択する

ゲートウェイは、選択したプライベートホスト名で Apigee にアクセスします。最初に作成するリソース（Apigee 環境グループ）は、これをホスト名として使用しますが、これを解決する DNS ゾーンは限定公開 DNS ゾーンを作成するまで作成されないため、今、何かを作成する前に選択します。

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

ここで、DNS_DOMAIN はパブリックインターネットで解決する必要のない限定公開 DNS ドメインです。末尾のドットなしで記述します（例: internal.example.com）。これにより、EXTPROC_HOST は apigee-extproc.internal.example.com になります。ホスト名が DNS_DOMAIN 内に収まる限り、apigee-extproc 以外のラベルを使用できます。

重要: EXTPROC_HOST は、Apigee 環境グループのホスト名、プライベート DNS レコード、認可拡張機能の authority フィールドと service フィールドの 3 か所で使用されます。3 つすべてが同じである必要があります。そうでない場合、コールアウトは Apigee に到達しません。ホスト名も DNS_DOMAIN 内に配置する必要があります。そのため、上記のコマンドでは、その変数からホスト名を取得しています。

認証トークンを構成する

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

注: 組織でデータ所在地を使用している場合は、このページのコマンドで apigee.googleapis.com を組織のリージョンエンドポイントに置き換えます。詳細については、データ所在地にリージョンエンドポイントを使用するをご覧ください。

Apigee 拡張機能プロセッサを構成する

このセクションで作成する Apigee リソースに名前を付けます。

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

ここで

EXTPROC_ENV と EXTPROC_ENVGROUP は、拡張機能プロセッサ専用の Apigee 環境と環境グループに選択する名前です（extproc-env や extproc-envgroup など）。各名前は、2 ～ 32 文字の小文字、数字、ハイフンで構成し、先頭は文字にする必要があります。末尾をハイフンにすることはできません。環境名は、組織内の他のすべての環境名と異なる必要があります。
PROXY_NAME は、拡張機能プロセッサプロキシに選択する名前です（例: extproc-authz）。

構成の Apigee 側はロードバランサと同じです。クイックスタートの Apigee Extension Processor を構成するに沿って、次の操作を行います。

プロパティ apigee-service-extension-enabled が true に設定された Apigee 環境を作成し、インスタンスに接続して、ホスト名が $EXTPROC_HOST の環境グループを作成します。
その環境にターゲットなしの拡張機能プロセッサプロキシを作成してデプロイします。

注: クイックスタートでは、これらのリソースに ENV_NAME、ENV_GROUP_NAME、ENV_GROUP_HOSTNAME という名前が付けられています。それぞれ $EXTPROC_ENV、$EXTPROC_ENVGROUP、$EXTPROC_HOST を使用します。

注: プロキシのポリシーが Google Cloud API を呼び出す場合は、デプロイリクエストに ?serviceAccount=SERVICE_ACCOUNT_EMAIL を追加して、サービスアカウントでプロキシをデプロイします。それ以外の場合、デプロイは MISSING_SERVICE_ACCOUNT で失敗します。

次に、環境内のデプロイを一覧表示します。

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

環境には複数のプロキシをデプロイできるため、レスポンスで apiProxy が $PROXY_NAME のエントリを見つけて、その revision をメモします。

プロキシは Google Cloud コンソールで確認できます。

[API プロキシ] に移動

次の変数をそのリビジョンに設定します。これは、接続を確認するで必要になります。

export REVISION=REVISION

Agent Gateway を Apigee に接続する

ゲートウェイは、プライベート DNS ゾーンで $EXTPROC_HOST を解決して見つけた VPC の Private Service Connect エンドポイントを介して Apigee に到達します。

サービスアタッチメントを見つける

Apigee インスタンスのサービスアタッチメントを見つけます。

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

次の変数を、リージョンのインスタンスの serviceAttachment 値に設定します。

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

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

Agent Gateway は、ネットワークアタッチメントを介して VPC に下り（外向き）します。名前（agent-gateway-attachment など）を選択して作成します。

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

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

内部 IP アドレスを予約して、Private Service Connect エンドポイントを作成します。

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

Google Cloud コンソールで、[Private Service Connect] ページに移動します。

[Private Service Connect] に移動

エンドポイントが pscConnectionStatus: ACCEPTED を報告していることを確認し、次の変数をその IP アドレスに設定します。

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

ステータスが PENDING の場合、プロジェクトは Apigee インスタンスの consumerAcceptList に存在せず、接続を受け入れることができません。

限定公開 DNS ゾーンを作成する

$DNS_DOMAIN のプライベート DNS ゾーンと、$EXTPROC_HOST をエンドポイントの IP アドレスに解決する A レコードを作成します。

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

Agent Gateway を更新する

始める前にの説明に沿って Agent Gateway を更新し、ネットワークアタッチメントを介して下り（外向き）トラフィックを送信し、作成したゾーンを解決できるようにします。

注意: Agent Gateway をインポートすると、リソース全体が置き換えられます。常にエクスポートされた構成から開始して編集します。新しいファイルを作成したり、protocols や registries などの省略したフィールドを記述したりすると、ゲートウェイから削除されます。

現在の構成をエクスポートします。

gcloud network-services agent-gateways export $GATEWAY \
    --location=$REGION --destination=agent-gateway.yaml

agent-gateway.yaml で、次の networkConfig ブロックを追加し、各プレースホルダを対応する環境変数の値に置き換えます。ファイルは直接編集されるため、シェル変数は置き換えられません。
```
networkConfig:
  egress:
    networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
  dnsPeeringConfig:
    domains: [ DNS_DOMAIN. ]
    targetProject: PROJECT_ID
    targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME
```
googleManaged.governedAccessPath、protocols、registries など、残りのファイルはエクスポートされたままにします。

編集した構成をインポートします。

gcloud network-services agent-gateways import $GATEWAY \
    --location=$REGION --source=agent-gateway.yaml

Agent Gateway のフィールドの完全なセットについては、Agent Gateway を構成するをご覧ください。

認可拡張機能を構成する

2 つのリソースがゲートウェイを拡張プロセッサプロキシに接続します。1 つは Apigee を指す認可拡張機能、もう 1 つは拡張機能をゲートウェイに接続する認可ポリシーです。

認可拡張機能を作成する

認可拡張機能の名前を選択します（例: apigee-authz-extension）。metadata フィールドは、実行する Apigee プロキシと、メッセージ本文をそのプロキシに送信するかどうかを選択します。

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

ここで

apigee-extension-processor は、トラフィックを処理する拡張機能プロセッサプロキシを選択します。
apigee-request-body と apigee-response-body は、リクエストとレスポンスの本文をプロキシで request.content と response.content として使用できるようにします。これらがないと、ペイロードを検査するポリシーは何も見つけられません。

認可ポリシーを作成する

認可ポリシーの名前を選択します（例: apigee-content-authz-policy）。このポリシーは、拡張機能をゲートウェイに接続し、Apigee に送信されるトラフィックを決定します。

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

メッセージ本文が検査されるように policyProfile: CONTENT_AUTHZ を使用します。REQUEST_AUTHZ ポリシーはリクエストヘッダーのみを評価します。

重要: 上記の例では、すべてのリクエストが prefix: "/" と一致するため、エージェントのトラフィック（セッション、テレメトリー、ツール呼び出しなど）がすべて Apigee に送信されます。to.operations.paths を使用するか、when フィールドの Common Expression Language（CEL）式を使用して範囲を絞り込み、管理対象のトラフィックのみが処理されるようにします。

接続を確認する

トラフィックを生成するには、このゲートウェイによって下り（外向き）が制御されるエージェントが必要です。エージェントが作成されるときに、エージェントの Agent Gateway 構成を $GATEWAY に設定することで、エージェントはゲートウェイにバインドされます。ゲートウェイへの直接 HTTP リクエストで接続を確立することはできません。詳細については、Agent Gateway を構成するをご覧ください。

拡張機能プロセッサプロキシで Apigee のデバッグセッションを開始し、エージェントを介して 1 つのリクエストを送信します。

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

注: エージェントのセッションとテレメトリーの呼び出しもゲートウェイを通過するため、1 回のエージェントのターンで複数のトランザクションが生成されます。filter フィールドを使用して、検査するトラフィックのみをキャプチャします。そうしないと、探しているリクエストが到着する前にバッファが満杯になる可能性があります。

キャプチャされたトランザクションで、次のことを確認します。

リクエスト URL は、Apigee ベースパスではなく、モデルエンドポイントやツールホストなど、エージェントが呼び出したアドレスです。
request.content と response.content が入力されます。これにより、認可拡張機能の本文メタデータが機能していることが確認されます。

トランザクションが表示されない場合は、環境グループのホスト名、DNS レコード、拡張機能の authority フィールドと service フィールドがすべて $EXTPROC_HOST であること、Private Service Connect エンドポイントが ACCEPTED を報告していること、ゲートウェイの governedAccessPath が AGENT_TO_ANYWHERE であることを確認します。

次のステップ

Apigee Extension Processor の概要をご覧ください。
ロードバランサで Apigee 拡張機能プロセッサを使ってみる。

Apigee Extension Processor を Agent Gateway に接続する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

環境変数を設定する

コールアウト ホスト名を選択する

認証トークンを構成する

Apigee 拡張機能プロセッサを構成する

Agent Gateway を Apigee に接続する

サービス アタッチメントを見つける

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

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

限定公開 DNS ゾーンを作成する

Agent Gateway を更新する

認可拡張機能を構成する

認可拡張機能を作成する

認可ポリシーを作成する

接続を確認する

次のステップ

Apigee Extension Processor を Agent Gateway に接続する

コールアウトホスト名を選択する

サービスアタッチメントを見つける

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