Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將 Apigee 擴充功能處理器連線至 Agent Gateway

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何將 Apigee 擴充功能處理器連線至 Agent Gateway，以便將 Apigee 政策套用至 AI 代理對模型、工具和所用 Model Context Protocol (MCP) 伺服器發出的呼叫，而不必變更代理。

Agent Gateway 是代理流量的網路進入和退出點。這不是負載平衡器，因此不會使用流量擴充功能。閘道會將授權委派給授權擴充功能，您則將擴充功能處理器設定為該擴充功能。連線後，閘道會將每個代理程式要求和回應傳送至 Apigee 進行處理，Apigee 則會傳回結果。

下圖顯示您在這個頁面建立的資源，以及單一代理程式要求通過這些資源的路徑：

代理程式要求會保留在 Agent Gateway，透過 Private Service Connect 傳送至 Apigee 取得結果，然後轉送。 — **圖 1：**當 Apigee 擴充功能處理器是 Agent Gateway 的授權擴充功能時，元件和要求流程。

在圖 1 中，要求的處理方式如下：

代理會向模型、工具或 MCP 伺服器發出一般 HTTPS 要求。代理程式會在建立時繫結至閘道，不需要變更。
閘道會保留要求，並呼叫授權擴充功能來取得裁決結果。
呼叫會透過網路連結離開，因此源自虛擬私有雲網路內部。
私人 DNS 區域會將呼叫主機名稱解析為 Private Service Connect 端點的內部 IP 位址。
端點會將呼叫轉送至 Apigee 執行個體的服務附件。
環境群組會依據主機名稱，將呼叫轉送至無目標 Proxy，並在該處執行政策。
Proxy 會將結果傳回閘道。Apigee 絕不會轉送代理程式的流量，因為 Proxy 沒有目標。
如果判決結果允許要求，閘道會將原始要求傳送至目的地。

圖 1 中的 AuthzPolicy 和 AuthzExtension 是設定，而非流量：政策會將擴充功能附加至閘道，而擴充功能會命名執行的擴充功能處理器 Proxy。您可以在「設定授權擴充功能」中建立這兩者。

如要改為將擴充功能處理器連線至負載平衡器，請參閱「開始使用 Apigee 擴充功能處理器」。

以下各節將逐步說明相關步驟：

設定 Apigee 擴充功能處理器。
將 Agent Gateway 連線至 Apigee。
設定授權擴充功能。
驗證連線。

事前準備

開始之前，請先完成下列工作：

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $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, if any are not already enabled.

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, if any are not already enabled.

Roles required to enable APIs

Enable the APIs

安裝 Google Cloud CLI。

安裝 Google Cloud CLI 後，請執行 gcloud components update 指令，取得最新版 gcloud 元件。
如果尚未佈建 Apigee 執行個體，請先佈建。

前往 Google Cloud 控制台的「Apigee Instances」(Apigee 執行個體) 頁面。

前往 Apigee 執行個體
在與 Apigee 執行個體相同的區域中部署 Agent Gateway，並將 governedAccessPath 設為 AGENT_TO_ANYWHERE，讓閘道控管代理的輸出流量。詳情請參閱「設定 Agent Gateway」。

您稍後會在「更新 Agent Gateway」中，於 DNS 區域存在後更新這個閘道的網路設定。
確認您有 Agent Gateway 和 Private Service Connect 端點都能使用的虛擬私有雲和子網路。

前往「VPC Networks」(虛擬私有雲網路) 頁面

必要的角色

如要取得將 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 端點使用的虛擬私有雲網路和子網路。
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 欄位。這三者必須完全相同，否則摘要不會傳送至 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 是您為擴充功能處理器 Proxy 選擇的名稱，例如 extproc-authz。

設定 Apigee 時，與負載平衡器相同。按照快速入門導覽課程中的設定 Apigee 擴充功能處理器操作，完成下列步驟：

建立 Apigee 環境，並將 apigee-service-extension-enabled 屬性設為 true，然後將該環境連結至執行個體，並建立主機名稱為 $EXTPROC_HOST 的環境群組。
在該環境中建立及部署「無目標」擴充功能處理器 Proxy。

注意：本快速入門導覽課程會將這些資源命名為 ENV_NAME、ENV_GROUP_NAME 和 ENV_GROUP_HOSTNAME。請分別使用 $EXTPROC_ENV、$EXTPROC_ENVGROUP 和 $EXTPROC_HOST。

注意：如果 Proxy 中的任何政策呼叫 Google Cloud API，請在部署要求中附加 ?serviceAccount=SERVICE_ACCOUNT_EMAIL，藉此使用服務帳戶部署 Proxy。否則部署作業會失敗，並顯示 MISSING_SERVICE_ACCOUNT。

接著列出環境中的部署作業：

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

環境可以部署多個 Proxy，因此請在回應中找出 apiProxy 為 $PROXY_NAME 的項目，並記下其 revision。

您可以在 Google Cloud 控制台中查看 Proxy：

前往 API Proxy

將下列變數設為該修訂版本，您需要此版本才能驗證連線：

export REVISION=REVISION

將 Agent Gateway 連線至 Apigee

閘道會透過虛擬私有雲中的 Private Service Connect 端點連線至 Apigee，並在私人 DNS 區域解析 $EXTPROC_HOST，找出該端點。

找出服務連結

找出 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」。

設定授權擴充功能

有兩項資源可將閘道連結至擴充功能處理器 Proxy：指向 Apigee 的授權擴充功能，以及將擴充功能附加至閘道的授權政策。

建立授權擴充功能

選擇授權擴充功能的名稱，例如 apigee-authz-extension。 metadata 欄位會選取要執行的 Apigee Proxy，以及是否要將訊息主體傳送至該 Proxy：

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 選取處理流量的擴充功能處理器 Proxy。
apigee-request-body 和 apigee-response-body 會在 Proxy 中提供要求和回應內容，分別為 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 欄位中使用一般運算語言 (CEL) 運算式，只處理您要控管的流量。

驗證連線

如要產生流量，您需要一個代理，其輸出內容受這個閘道控管。建立代理程式時，只要將 Agent Gateway 設定為 $GATEWAY，代理程式就會繫結至閘道；您無法透過直接向閘道發出的 HTTP 要求來行使連線。詳情請參閱「設定 Agent Gateway」。

在擴充功能處理器 Proxy 上啟動 Apigee 偵錯工作階段，然後透過代理程式傳送一項要求：

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*\")"}'

注意：單一代理回合會產生多筆交易，因為代理的工作階段和遙測呼叫也會通過閘道。使用 filter 欄位只擷取要檢查的流量，否則緩衝區可能會在您要尋找的要求抵達前填滿。

在擷取的交易中，確認：

要求網址是代理程式呼叫的位址，例如模型端點或工具主機，而非 Apigee 基準路徑；
和 response.content 都已填入，這表示授權擴充功能的本文中繼資料運作正常。request.content

如果沒有顯示任何交易，請檢查環境群組主機名稱、DNS 記錄和擴充功能的 authority 和 service 欄位是否都為 $EXTPROC_HOST，Private Service Connect 端點是否回報 ACCEPTED，以及閘道的 governedAccessPath 是否為 AGENT_TO_ANYWHERE。

將 Apigee 擴充功能處理器連線至 Agent Gateway 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

設定環境變數

選擇回呼主機名稱

設定驗證權杖

設定 Apigee 擴充功能處理器

將 Agent Gateway 連線至 Apigee

找出服務連結

建立網路連結

建立 Private Service Connect 端點

建立私人 DNS 區域

更新 Agent Gateway

設定授權擴充功能

建立授權擴充功能

建立授權政策

驗證連線

後續步驟

將 Apigee 擴充功能處理器連線至 Agent Gateway