Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将 Apigee Extension Processor 连接到 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 Extension Processor 是 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新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $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 实例页面。

转到 Apigee 实例
在 Apigee 实例所在的区域中部署 Agent Gateway，并将 governedAccessPath 设置为 AGENT_TO_ANYWHERE，以便网关管理代理的出站流量。如需了解详情，请参阅配置 Agent Gateway。

您可以在 DNS 区域存在后，在更新 Agent Gateway中更新此网关的网络配置。
确认您拥有 Agent Gateway 和 Private Service Connect 端点都可以使用的 VPC 和子网。

前往“VPC 网络”

所需的角色

如需获得将 Apigee 扩展处理器连接到代理网关所需的权限，请让您的管理员为您授予以下 IAM 角色：

创建和管理 Apigee 资源：组织的 Apigee Org Admin (roles/apigee.admin)
创建和管理服务扩展：组织的 Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin)
创建和管理授权政策：组织的 Network Security Admin (roles/networksecurity.admin)
创建和管理网络资源，包括 Private Service Connect 端点和 DNS：组织的 Compute Network Admin (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。这会给出 apigee-extproc.internal.example.com 的 EXTPROC_HOST。您可以使用 apigee-extproc 以外的标签，只要主机名保持在 DNS_DOMAIN 内即可。

重要提示： 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 是您为扩展处理器代理选择的名称，例如 extproc-authz。

配置的 Apigee 端与负载均衡器相同。按照快速入门中的配置 Apigee Extension Processor 操作，执行以下操作：

创建一个 Apigee 环境，并将属性 apigee-service-extension-enabled 设置为 true，然后将其附加到您的实例，并创建一个主机名为 $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

网关通过 VPC 中的 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 代码块，并将每个占位符替换为相应环境变量的值。该文件是直接编辑的，因此此处不会替换 shell 变量：
```
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。

配置授权扩展程序

有两个资源将网关连接到扩展处理器代理：指向 Apigee 的授权扩展程序，以及将扩展程序附加到网关的授权政策。

创建授权扩展程序

为授权扩展程序选择一个名称，例如 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 字段中的通用表达式语言 (CEL) 表达式缩小范围，以便仅处理您打算管控的流量。

验证连接

如需生成流量，您需要一个出站流量受此网关控制的代理。创建代理时，通过将其 Agent Gateway 配置设置为 $GATEWAY，可将代理绑定到网关；您无法通过向网关发出直接 HTTP 请求来建立连接。如需了解详情，请参阅配置 Agent Gateway。

在扩展处理器代理上启动 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 基本路径；
request.content 和 response.content 已填充，这确认了授权扩展程序上的正文元数据正常运行。

如果未显示任何交易，请检查以下各项：环境组主机名、DNS 记录、扩展程序的 authority 和 service 字段是否均为 $EXTPROC_HOST；Private Service Connect 端点是否报告 ACCEPTED；网关的 governedAccessPath 是否为 AGENT_TO_ANYWHERE。

后续步骤

阅读 Apigee Extension Processor 概览。
开始使用负载均衡器上的 Apigee 扩展处理器。
使用扩展处理器配置 Apigee 政策，其中介绍了特定于扩展处理器的政策配置。

将 Apigee Extension Processor 连接到 Agent Gateway 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

设置环境变量

选择宣传信息主机名

配置身份验证令牌

配置 Apigee 扩展处理器

将 Agent Gateway 连接到 Apigee

查找服务连接

创建网络连接

创建 Private Service Connect 端点

创建专用 DNS 区域

更新 Agent Gateway

配置授权扩展程序

创建授权扩展程序

创建授权政策

验证连接

后续步骤

将 Apigee Extension Processor 连接到 Agent Gateway