创建 IAM Unified Access Policies

您可以创建 Identity and Access Management (IAM) Unified Access Policies (UAP)，用于管理智能体与目标资源（例如Agent Registry、MCP 服务器、智能体以及已注册和未注册的端点）之间的智能体通信。

Agent Gateway 使用 Identity-Aware Proxy (IAP) 来评估和强制执行 UAP。

在 Google Cloud 控制台中，您可以使用政策页面创建 Agent Gateway IAM UAP。 UAP 可以包含允许规则、拒绝规则或两者。

您可以使用 Google Cloud CLI、REST API 或 Terraform 创建 IAM UAP，并将其绑定到包含 Agent Gateway 实例的项目。

如需了解如何更新和删除 UAP，请参阅管理 IAM UAP。

准备工作

在创建 IAM UAP 之前，请执行以下操作：

  1. 您必须为停用将访问权限政策绑定到资源 (constraints/iam.managed.disableAccessPolicyBindings) 托管式限制停用强制执行。默认情况下，系统会为新组织启用此布尔值限制条件，并阻止您将 IAM v3 API 访问权限政策绑定到资源。如需了解详情，请参阅使用布尔值规则更新政策。

  2. 设置 Google Cloud 结算项目。

  3. 启用必需的 API：

    gcloud services enable \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    iam.googleapis.com \
    networkservices.googleapis.com

  4. 确保您已使用 IAP v2 政策设置了 Agent Gateway 和 IAP。我们建议您最初在试运行模式下配置 Agent Gateway。如需详细了解 Agent Gateway，请参阅 Agent Gateway 概览。

  5. 使用目标资源（例如智能体、MCP 服务器和端点）填充 Agent Registry。

  6. 确定您要管理其访问权限的来源代理的代理身份。如需使用 Google Cloud 控制台管理对整个制品库的访问权限，请选择包含该制品库的项目。

  7. 查看应用内购买和 UAP 最佳实践。

所需的角色

如需获得为 AI 智能体配置 Agent Platform 所需的权限，请让管理员向您授予项目的以下 IAM 角色：

  • 创建 Agent Gateway 实例：IAP Policy Admin (roles/iap.admin) 或 Network Security Admin (roles/networksecurity.admin)
  • 创建和绑定 UAP：Access Policy Admin (roles/iam.accessPolicyAdmin)
  • 将政策绑定到项目：Project IAM Admin (roles/resourcemanager.projectIamAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建 IAM UAP

UAP 允许您配置多条规则。每条规则都可以具有允许效果或拒绝效果。

创建具有允许规则的 UAP

您可以使用Google Cloud 控制台、gcloud CLI、REST API 或 Terraform 创建具有允许规则的 UAP。

控制台

如需在 Google Cloud 控制台中创建 UAP，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 如需为 Agent Gateway 出站流量添加 IAM UAP，请点击 创建。
  4. 在政策详情中，执行以下操作：
    1. 点击政策字段。
    2. 在下拉列表中，选择创建新政策。
    3. 在政策名称字段中，输入政策的名称。系统会根据政策名称自动生成政策 ID。
    4. 可选：点击修改以修改政策 ID。在政策 ID 字段中，您可以更改政策 ID 的名称。
    5. 在添加规则中，展开默认规则规则 1，或点击添加规则。
  5. 为 UAP 创建一个或多个规则。 查看不同政策的示例。
  6. 如需创建政策，请点击创建。

保存政策后，会发生以下情况：

  • IAM iap.resources.egressViaIAP 权限会授予政策中的主账号。

  • 该政策会自动绑定到所选项目。

  • 此项目中的所有 Agent Gateway 实例都可以强制执行与该项目关联的任何政策。

gcloud

如需在 gcloud CLI 中创建 UAP，请执行以下操作：

  1. 创建 JSON 格式的政策文件。UAP 可以包含一条或多条规则。每条规则都控制着一个或多个智能体主体对一个或多个目标资源的访问权限。

    [
  {
    "description": "RULE_DESCRIPTION",
    "effect": "RULE_EFFECT",
    "principals": [
      AGENT_PRINCIPALS
    ],
    "operation": {
      "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
    },
    
    "conditions": {
      "iap.googleapis.com": {
        "expression": "CEL_EXPRESSION"
      }
    }
    
  }
]

    替换以下内容：

    • RULE_DESCRIPTION：规则的说明
    • RULE_EFFECT：规则的效果，可以是 ALLOW 或 DENY
    • AGENT_PRINCIPALS：来源代理身份的主账号。智能体主体可以是由一个或多个单独的主体或主体集组成的数组：
      • 内置代理身份：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER

        AGENT_UNIQUE_IDENTIFIER 的结构取决于托管代理的 Google Cloud 服务：

        • Agent Runtime（推理引擎）： principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-agent
        • Gemini Enterprise（Discovery Engine）： principal://agents.global.org-123456789012.system.id.goog/resources/discoveryengine/projects/9876543210/locations/global/engines/my-engine/assistants/default_assistant/agents/default/core_assistant
        • Cloud Run（代理身份）： principal://agents.global.org-123456789012.system.id.goog/resources/run/projects/9876543210/locations/us-central1/services/my-cloud-run-agent

        替换以下内容：

        • TRUST_DOMAIN：包含智能体主体的项目或组织的信任域（例如 agents.global.org-ORGANIZATION_ID.system.id.goog 或 agents.global.proj-PROJECT_NUMBER.system.id.goog）
        • AGENT_UNIQUE_IDENTIFIER：代理实例的资源 URI 路径
      • 工作负载身份联合（自定义或外部代理）： principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT - 例如 principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent

        替换以下内容：

        • PROJECT_NUMBER：包含工作负载身份池的项目的编号
        • POOL_ID：工作负载身份池的 ID
        • SUBJECT：智能体主体的对象标识符
    • CONDITION：条件参数，格式如下： 
      "conditions": {
  "iap.googleapis.com": {
    "expression": "CEL_EXPRESSION"
  }
}

      将 CEL_EXPRESSION 替换为条件表达式，例如：

      "destination.agent_registry.mcp_server.name == 'projects/corp-apim-prod/locations/us-east1/mcpServers/finance-data-service' && destination.agent_registry.mcp_server.tool.name == 'updateRecord'"

      此表达式必须是有效的 CEL 表达式。其计算结果必须为 true 才能允许访问。

    在所有代理出站流量政策中，您必须将权限设置为 iap.resources.egressViaIAP。

    如需了解详情，请参阅 UAP 规则和示例政策。

  2. 如需创建 UAP，请运行以下命令：

    gcloud iam access-policies create POLICY_NAME \
    --details-rules=POLICY_FILE \
    --project=PROJECT_ID \
    --location=global

    替换以下内容：

    • POLICY_NAME：政策的名称
    • POLICY_FILE：政策文件的路径，例如：my-policy.json
    • PROJECT_ID：包含政策的项目 ID

REST API

如需使用 REST API 创建和绑定政策，请执行以下操作：

  1. 将 JSON 格式的政策详细信息保存到名为 agent-access-policy.json 的文件中：

    {
  "details": {
    "rules": [
      RULES
    ]
  }
}

    将 RULES 替换为一个或多个规则。

  2. 如需创建 UAP，请向 accessPolicies 端点发出 POST 请求：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

Terraform

如需以声明方式创建 UAP 并将其绑定到托管 Agent Gateway 的项目，请配置 google_iam_project_access_policy 和 google_iam_projects_policy_binding 资源：

resource "google_iam_project_access_policy" "agent_egress_policy" {
project          = "PROJECT_ID"
location         = "global"
access_policy_id = "POLICY_NAME"
display_name     = "POLICY_DISPLAY_NAME"

details {
  rules {
    effect      = "ALLOW"
    description = "Allow runtime agents to call registered MCP tool"

    principals = [
      "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER"
    ]

    operation {
      permissions = ["iap.googleapis.com/resources.egressViaIAP"]
    }

    conditions {
      service    = "iap.googleapis.com"
      expression = "destination.agent_registry.mcp_server.name == 'projects/PROJECT_ID/locations/REGION/mcpServers/MCP_SERVER_ID' && destination.agent_registry.mcp_server.tool.name == 'TOOL_NAME'"
    }
  }
}
}

resource "google_iam_projects_policy_binding" "agent_egress_binding" {
project           = "PROJECT_ID"
location          = "global"
policy_binding_id = "POLICY_BINDING_ID"
policy_kind       = "ACCESS"
policy            = "projects/PROJECT_ID/locations/global/accessPolicies/${google_iam_project_access_policy.agent_egress_policy.access_policy_id}"

target {
  resource = "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID"
}
}

替换以下内容：

  • PROJECT_ID：托管 Agent Gateway 和 Agent Registry 的项目的 ID

  • POLICY_NAME：访问权限政策的 ID

  • POLICY_DISPLAY_NAME：访问权限政策的人类可读说明

  • ORGANIZATION_ID：您的组织 ID。

  • AGENT_RUNTIME_PROJECT_NUMBER：托管代理的项目编号

  • REGION：注册表位置

  • MCP_SERVER_ID：已注册 MCP 服务器的 ID

  • TOOL_NAME：允许的 MCP 工具的名称

  • POLICY_BINDING_ID：项目政策绑定的 ID

创建组合允许和拒绝 UAP

您可以使用 Google Cloud 控制台、gcloud CLI 和 REST API 配置包含允许和拒绝规则的 UAP。

控制台

如需在Google Cloud 控制台中创建同时包含允许规则和拒绝规则的 UAP，请执行以下操作：

  1. 在添加规则中，配置允许规则：
    1. 在规则说明中，输入允许规则的说明。
    2. 在规则效果中，选择允许。
    3. 选择智能体主体和目标资源，然后添加允许 CEL 条件。
    4. 如需保存允许规则，请点击保存。
  2. 如需添加拒绝规则，请点击添加规则：
    1. 在规则说明中，输入拒绝规则的说明。
    2. 在规则效果中，选择拒绝。
    3. 选择智能体主体和目标资源，然后添加拒绝 CEL 条件。
    4. 如需保存拒绝规则，请点击保存。
  3. 如需创建政策，请点击创建。

gcloud

如需创建同时包含允许和拒绝规则的 UAP 文件，请执行以下操作：

  1. 将以下内容保存到 JSON 格式的政策文件中：

    [
  {
    "description": "ALLOW_RULE_DESCRIPTION",
    "effect": "ALLOW",
    "principals": [
      "AGENT_PRINCIPALS_ALLOW"
    ],
    "operation": {
      "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": "CEL_EXPRESSION_ALLOW"
      }
    }
  },
  {
    "description": "DENY_RULE_DESCRIPTION",
    "effect": "DENY",
    "principals": [
      "AGENT_PRINCIPALS_DENY"
    ],
    "operation": {
      "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": "CEL_EXPRESSION_DENY"
      }
    }
  }
]

    替换以下内容：

    • ALLOW_RULE_DESCRIPTION：允许规则的说明
    • DENY_RULE_DESCRIPTION：拒绝规则的说明
    • AGENT_PRINCIPALS_ALLOW：您要允许的智能体主体，例如 principal://agents.global.proj-PROJECT_NUMBER.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_NAME
    • AGENT_PRINCIPALS_DENY：您要拒绝的智能体主体，例如 principal://agents.global.proj-PROJECT_NUMBER.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_NAME
    • CEL_EXPRESSION_ALLOW：允许规则的 CEL 表达式，例如 destination.agent_registry.mcp_server.name == "projects/my-project/locations/us-east1/mcpServers/finance-data-service" && destination.agent_registry.mcp_server.tool.name == "getStatements"
    • CEL_EXPRESSION_DENY：拒绝规则的 CEL 表达式，例如 destination.agent_registry.mcp_server.name == "projects/my-project/locations/us-east1/mcpServers/finance-data-service" && destination.agent_registry.mcp_server.tool.name == "updateRecord"

  2. 如需创建 UAP，请运行以下命令：

    gcloud iam access-policies create POLICY_NAME \
    --details-rules=POLICY_FILE \
    --project=PROJECT_ID \
    --location=global

    替换以下内容：

    • POLICY_NAME：政策的名称
    • POLICY_FILE：政策文件的路径，例如：my-policy.json
    • PROJECT_ID：包含政策的项目 ID

  3. 如需激活该政策，请将 UAP 绑定到您的项目。

REST API

如需使用 REST API 创建同时包含允许规则和拒绝规则的 UAP，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "ALLOW_RULE_DESCRIPTION",
        "effect": "ALLOW",
        "principals": [
          "AGENT_PRINCIPALS_ALLOW"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "CEL_EXPRESSION_ALLOW"
          }
        }
      },
      {
        "description": "DENY_RULE_DESCRIPTION",
        "effect": "DENY",
        "principals": [
          "AGENT_PRINCIPALS_DENY"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "CEL_EXPRESSION_DENY"
          }
        }
      }
    ]
  }
}

    替换以下内容：

    • ALLOW_RULE_DESCRIPTION：允许规则的说明
    • DENY_RULE_DESCRIPTION：拒绝规则的说明
    • AGENT_PRINCIPALS_ALLOW：您要允许的智能体主体
    • AGENT_PRINCIPALS_DENY：您要拒绝的代理主体
    • CEL_EXPRESSION_ALLOW：允许规则的 CEL 表达式
    • CEL_EXPRESSION_DENY：拒绝规则的 CEL 表达式

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

  3. 如需激活该政策，请将 UAP 绑定到您的项目。

将 UAP 绑定到项目

控制台

保存政策后，会发生以下情况：

  • IAM iap.resources.egressViaIAP 权限会授予政策中的主账号。

  • 该政策会自动绑定到所选项目。

  • 此项目中的所有 Agent Gateway 实例都可以强制执行与该项目关联的任何政策。

gcloud

如需将政策绑定到目标资源，请运行以下命令：

gcloud iam policy-bindings create BINDING_NAME \
    --policy="projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME" \
    --target-resource="TARGET_RESOURCE" \
    --project=PROJECT_ID \
    --location=global

替换以下内容：

  • BINDING_NAME：政策绑定的名称
  • PROJECT_ID：您的 Google Cloud 项目 ID
  • POLICY_NAME：您的访问权限政策的名称
  • TARGET_RESOURCE：项目的完整资源 URI，格式如下： 
        //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

REST API

如需将政策绑定到目标资源，请向 policyBindings 端点发出 POST 请求：

curl -X POST \
  "https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings?policyBindingId=BINDING_NAME" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME",
    "target": {
      "resource": "TARGET_RESOURCE"
    }
  }'

替换以下内容：

  • PROJECT_ID：项目 ID
  • BINDING_NAME：绑定的名称
  • POLICY_NAME：您在本文档前面部分创建的政策的名称
  • TARGET_RESOURCE：绑定目标的完整资源 URI，可以是以下项之一：
    • 项目：//cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    • Agent Gateway：//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/GATEWAY_NAME

创建规则

UAP 可以包含一条或多条规则。每条规则都控制着一个或多个智能体主体对一个或多个目标资源的访问权限。

控制台

在 Google Cloud 控制台中，修改 UAP 并执行以下操作：

  1. 修改现有规则。如需添加规则，请点击添加规则。
  2. 规则说明：此规则的人类可读说明
  3. 选择智能体主体：规则管理其访问权限的来源智能体主体。主账号可以是以下任一类型：
    • 此项目中的所有代理：当前项目中存在的所有代理。
    • 个别代理：您可以选择的一个或多个特定主账号。代理通过其代理身份进行定义。
    • 自定义主体集：您可以通过输入主体标识符来指定一个或多个主体集。主账号标识符必须以 principalSet:// 开头，并引用代理身份。
  4. 效果：规则的效果，可以是以下任一项：
    • 允许：允许主账号访问资源
    • 拒绝：禁止主账号访问资源
  5. 选择资源：您可以选择的一种或多种类型的目标资源。资源类型包括：
    • Registry：在 Agent Registry 位置注册的所有资源
    • 智能体：在 Agent Registry 中注册的目标智能体

    • MCP 服务器：在 Agent Registry 中注册的目标 MCP 服务器。您可以使用条件进一步控制 MCP 服务器访问权限。

    • 端点：在 Agent Registry 中注册的目标端点

    • 未注册的端点：未在智能体注册表中注册且通过外部网址访问的目标端点。您可以使用条件进一步控制未注册端点访问权限。

gcloud

JSON 格式文件中的规则具有以下常规格式：

{
  "description": "RULE_DESCRIPTION",
  "effect": "EFFECT",
  "principals": [
    "AGENT_PRINCIPALS"
  ],
  "operation": {
    "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
  },
  "conditions": {
    "iap.googleapis.com": {
      "expression": "CONDITION"
    }
  }
}

政策文件包含以下内容：

  • RULE_DESCRIPTION：此规则的人类可读说明

  • EFFECT：规则的效果，可以是以下值之一：

  • ALLOW 允许主账号访问资源

  • DENY 不允许主账号访问资源

  • CONDITION：有条件地求值为 true 或 false 的 CEL 表达式。如果表达式的计算结果为 true，则规则生效。条件还可以包含对主账号可以访问的特定资源的引用：

  • destination.agent_registry：目标资源已在 Agent Registry 中注册。

  • destination.unregistered：目标资源未注册。它通过网址进行访问。您可以在条件中控制访问权限。

如需详细了解条件，请参阅条件。 如需详细了解条件属性，请参阅 CEL 属性。

REST API

如需使用 REST API 创建和绑定政策，请执行以下操作：

  1. 将 JSON 格式的政策详细信息保存到名为 agent-access-policy.json 的文件中：

    {
  "details": {
    "rules": [
      {
        "description": "RULE_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "AGENT_PRINCIPALS"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "CONDITION"
          }
        }
      }
    ]
  }
}

    向 details 字段添加一条或多条规则。在每条规则中，替换以下内容：

    • RULE_DESCRIPTION：一个或多个规则

    • EFFECT：规则的效果，可以是以下值之一：

      • ALLOW 允许主账号访问资源

      • DENY 不允许主账号访问资源

    • AGENT_PRINCIPALS：您要授予访问权限的智能体主体。

    • CONDITION：有条件地求值为 true 或 false 的 CEL 表达式。如果表达式的计算结果为 true，则规则生效。条件还可以包含对主账号可以访问的特定资源的引用：

      • destination.agent_registry：目标资源已在 Agent Registry 中注册。
      • destination.unregistered：目标资源未注册。 可通过网址访问。您可以在条件中控制访问权限。

    如需详细了解条件，请参阅条件。 如需详细了解条件属性，请参阅 CEL 属性。

  2. 如需创建 UAP，请向 accessPolicies 端点发出 POST 请求：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

  3. 如需将政策绑定到目标资源，请向 policyBindings 端点发出 POST 请求：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings?policyBindingId=BINDING_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "policy": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME",
  "target": {
    "resource": "TARGET_RESOURCE"
  }
}'

    替换以下内容：

    • PROJECT_ID：项目 ID
    • BINDING_NAME：绑定的名称
    • POLICY_NAME：您在本文档前面部分创建的政策的名称
    • TARGET_RESOURCE：项目的完整资源 URI，格式如下：//cloudresourcemanager.googleapis.com/projects/PROJECT_ID

创建条件

条件是布尔值 CEL 表达式，用于确定智能体主体对特定资源的访问权限。

控制台

在 Google Cloud 控制台中，您可以通过执行以下操作来创建条件：

  1. 在规则的选择资源部分中，选择以下标签页之一：

    • 标准：在标准标签页中，选择一种或多种资源类型，然后使用条件构建器或条件编辑器创建条件。

    • 自定义：在自定义标签页中，您可以使用条件编辑器创建自定义条件，在其中可以使用 CEL 属性指定目标资源和其他条件。

  2. 如需保存条件和规则，请点击保存。

gcloud

在政策文件中，条件决定了智能体主体可以访问哪些目标资源，以及在什么条件下访问这些资源。

条件在规则的 conditions 字段中定义。例如：

"conditions": {
  "iap.googleapis.com": {
    "expression": "destination.agent_registry.mcp_server.name == 'projects/my-project/locations/us-east1/mcpServers/finance-data-service' && destination.agent_registry.mcp_server.tool.name == 'getStatements'"
  }
}

如需了解详情，请参阅示例政策。

REST API

在政策文件中，条件决定了智能体主体可以访问哪些目标资源，以及在什么条件下访问这些资源。

条件在规则的 conditions 字段中定义。例如：

"conditions": {
  "iap.googleapis.com": {
    "expression": "destination.agent_registry.mcp_server.name == 'projects/my-project/locations/us-east1/mcpServers/finance-data-service' && destination.agent_registry.mcp_server.tool.name == 'getStatements'"
  }
}

如需了解详情，请参阅示例政策。

测试和验证 UAP

创建并绑定政策后，请执行以下操作，验证您的代理是否可以访问资源：

  1. 通过代理触发操作，以测试 UAP 中的规则。请务必测试允许效果规则和拒绝效果规则是否按预期执行。

  2. 使用以下查询过滤日志，检查 Cloud Audit Logs 中是否有 IAP 条目：

    protoPayload.metadata.iapPolicyVersion="v2"
protoPayload.serviceName="iap.googleapis.com"
resource.labels.project_id="PROJECT_ID"

    将 PROJECT_ID 替换为您的项目 ID。

    日志条目会显示访问权限决策、主账号、目标和 CEL 表达式评估详情。我们建议您在测试期间使用 DRY_RUN 模式，以免违反政策的行为阻止访问。

  3. 根据审核日志中的评估结果调整政策规则。

  4. 确认规则按预期运行后，更新网关服务扩展程序元数据，并将 iamEnforcementMode 设置为 "ENFORCE"。

示例政策

以下是智能体主体交互的出站流量政策示例：

如需了解如何创建和绑定政策，请参阅创建 UAP。

创建代理到注册表 UAP

通过代理到注册表政策，您的代理可以访问项目中特定 Agent Registry 位置的所有代理、MCP 服务器和端点。

控制台

如需在 Google Cloud 控制台中创建代理到注册表政策，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 在政策详情中，选择一项政策或创建一项新政策。如果您要创建新政策，请输入政策名称，例如 allow-registry-access。
  4. 在添加规则中，配置规则：
    • 规则说明：Allow all agents in project to access us-central1 registry
    • 规则效果：允许
    • 选择主账号：在主账号集中，选择此项目中的所有代理。
    • 选择资源：依次选择标准 > 注册表，然后选择 us-central1。
  5. 如需保存规则，请点击保存。
  6. 如需创建政策，请点击创建。

如需了解如何创建和绑定政策，请参阅创建 IAM UAP。

gcloud

以下示例政策展示了一条 UAP 规则，该规则允许项目中的所有代理访问特定注册表中的所有目标资源：

{
  [
    {
      "description": "Allow all agents in project 9876543210 to access all destination resources in the us-central1 registry",
      "effect": "ALLOW",
      "principals": [
        "principalSet://agents.global.org-123456789012.system.id.goog/attribute.platformContainer/aiplatform/projects/9876543210"
      ],
      "operation": {
        "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
      },
      "conditions": {
        "iap.googleapis.com": {
          "expression": "destination.is_registered == true && destination.agent_registry.location == 'us-central1'"
        }
      }
    }
  ]
}

如需激活该政策，请将 UAP 绑定到您的项目。

REST API

如需创建允许项目中的所有代理访问特定注册表中的所有目标资源的 UAP，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "Allow all agents in project 9876543210 to access all destination resources in the us-central1 registry",
        "effect": "ALLOW",
        "principals": [
          "principalSet://agents.global.org-123456789012.system.id.goog/attribute.platformContainer/aiplatform/projects/9876543210"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "destination.is_registered == true && destination.agent_registry.location == 'us-central1'"
          }
        }
      }
    ]
  }
}

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

如需激活该政策，请将 UAP 绑定到您的项目。

代理到注册表的 CEL 属性

下表介绍了可在代理到注册表规则条件中使用的 CEL 属性：

属性 详细信息
destination.is_registered
值类型 布尔值
支持的值 true，false
支持的操作 ==，!=
destination.agent_registry.resource_type
值类型 字符串
支持的值 'AGENT'、'ENDPOINT'、'MCP_SERVER'、'SKILL'
支持的操作 ==、!=、in
destination.agent_registry.location
值类型 字符串
支持的值 Google Cloud 位置 ID（例如 'global'、'us-central1'）
支持的操作 ==、!=、in
destination.agent_registry.project_id
值类型 字符串
支持的值 Google Cloud 项目 ID
支持的操作 ==、!=、in

创建代理到代理出站 UAP

智能体到智能体政策允许源智能体调用在 Agent Registry 中注册的目标智能体。

控制台

如需在 Google Cloud 控制台中创建代理到代理政策，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 在政策详情中，选择一项政策或创建一项新政策。如果您要创建新政策，请输入政策名称，例如 allow-orchestrator-to-support-agent。
  4. 在添加规则中，配置规则：
    • 规则说明：Allow orchestrator agent to invoke customer-support agent
    • 规则效果：允许
    • 选择主账号：选择特定代理，然后选择 orchestrator-agent。
    • 选择资源：依次选择标准 > 代理，然后选择 customer-support-agent。
  5. 如需保存规则，请点击保存。
  6. 如需创建政策，请点击创建。

如需激活该政策，请将 UAP 绑定到您的项目。

gcloud

以下示例政策展示了一条 IAM 允许规则，该规则允许编排器代理调用在代理注册表中注册的特定子代理：

{
  [
    {
      "description": "Allow orchestrator agent to invoke customer-support agent",
      "effect": "ALLOW",
      "principals": [
        "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/orchestrator-agent"
      ],
      "operation": {
        "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
      },
      "conditions": {
        "iap.googleapis.com": {
          "expression": "destination.agent_registry.agent.name == 'projects/9876543210/locations/us-central1/agents/customer-support-agent'"
        }
      }
    }
  ]
}

如需使用 gcloud CLI 创建和绑定政策，请参阅创建 IAM UAP。

REST API

如需创建包含允许规则的 IAM 政策，以允许编排器代理调用在代理注册表中注册的特定子代理，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "Allow orchestrator agent to invoke customer-support agent",
        "effect": "ALLOW",
        "principals": [
          "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/orchestrator-agent"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "destination.agent_registry.agent.name == 'projects/9876543210/locations/us-central1/agents/customer-support-agent'"
          }
        }
      }
    ]
  }
}

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

如需激活该政策，请将 UAP 绑定到您的项目。

代理到代理 CEL 属性

下表介绍了可在代理到代理政策条件中使用的 CEL 属性：

属性 详细信息
destination.agent_registry.agent.name
值类型 字符串
支持的值 代理资源名称 (projects/PROJECT_ID/locations/LOCATION/agents/AGENT_NAME)
支持的操作 ==、!=、in

创建智能体到 MCP 服务器的出站 UAP

代理到 MCP 服务器的出站流量政策用于控制代理对 Model Context Protocol (MCP) 服务器上的特定工具或注解的访问。

控制台

如需在 Google Cloud 控制台中创建智能体到 MCP 服务器政策，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 在政策详情中，选择一项政策或创建一项新政策。如果您要创建新政策，请输入政策名称，例如 allow-github-read-only。
  4. 在添加规则中，配置规则：
    • 规则说明：Allow read-only access to GitHubTool on MCP server
    • 规则效果：允许
    • 选择主体：选择智能体主体，例如 my-ae-agent。
    • 选择资源：选择自定义标签页。
    • 条件：在条件编辑器中，输入： 
      destination.agent_registry.mcp_server.tool.name == 'GitHubTool' && destination.agent_registry.mcp_server.tool.annotations.read_only_hint == true
  5. 如需保存规则，请点击保存。
  6. 如需创建政策，请点击创建。

如需激活该政策，请将 UAP 绑定到您的项目。

gcloud

以下示例政策展示了一条 IAM 允许规则，该规则允许采用工作负载身份联合格式的智能体主体对名为 GitHubTool 的工具拥有只读权限：

{
  [
    {
      "description": "Allow read-only access to GitHubTool on MCP server",
      "effect": "ALLOW",
      "principals": [
        "principal://iam.googleapis.com/projects/9876543210/locations/global/workloadIdentityPools/POOL_ID/subject/ns/default/sa/my-ae-agent"
      ],
      "operation": {
        "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
      },
      "conditions": {
        "iap.googleapis.com": {
          "expression": "destination.agent_registry.mcp_server.tool.name == 'GitHubTool' && destination.agent_registry.mcp_server.tool.annotations.read_only_hint == true"
        }
      }
    }
  ]
}

替换以下内容：

  • POOL_ID：工作负载身份池 ID。根据池类型，按以下格式设置 ID：
  • Google 管理的池： PROJECT_ID.svc.id.goog
  • 自行管理的池： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog

如需使用 gcloud CLI 创建和绑定政策，请参阅创建 IAM UAP。

REST API

如需创建 IAM 访问权限政策，以允许使用工作负载身份联合的智能体对名为 GitHubTool 的工具拥有只读权限，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "Allow read-only access to GitHubTool on MCP server",
        "effect": "ALLOW",
        "principals": [
          "principal://iam.googleapis.com/projects/9876543210/locations/global/workloadIdentityPools/POOL_ID/subject/ns/default/sa/my-ae-agent"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "destination.agent_registry.mcp_server.tool.name == 'GitHubTool' && destination.agent_registry.mcp_server.tool.annotations.read_only_hint == true"
          }
        }
      }
    ]
  }
}

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • POOL_ID：工作负载身份池 ID。根据池类型，按以下格式设置 ID：
    • Google 管理的池： PROJECT_ID.svc.id.goog
    • 自行管理的池： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog
    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

如需使用 REST API 创建和绑定政策，请参阅创建 UAP。

智能体到 MCP 的 CEL 属性

下表介绍了您可以在代理到 MCP 服务器政策条件中使用的 CEL 属性：

属性 详细信息
destination.agent_registry.mcp_server.name
值类型 字符串
支持的值 MCP 服务器资源名称 (projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_NAME)
支持的操作 ==、!=、in
destination.agent_registry.mcp_server.method
值类型 字符串
支持的值 MCP 方法名称（例如 'tools'、'prompts'、'resources'）
支持的操作 ==、!=、in
destination.agent_registry.mcp_server.tool.name
值类型 字符串
支持的值 工具名称（例如 'search_code'、'execute'）
支持的操作 ==、!=、in
destination.agent_registry.mcp_server.tool.annotations.read_only_hint
值类型 布尔值
支持的值 true，false
支持的操作 ==，!=
destination.agent_registry.mcp_server.tool.annotations.destructive_hint
值类型 布尔值
支持的值 true，false
支持的操作 ==，!=
destination.agent_registry.mcp_server.tool.annotations.idempotent_hint
值类型 布尔值
支持的值 true，false
支持的操作 ==，!=
destination.agent_registry.mcp_server.tool.annotations.open_world_hint
值类型 布尔值
支持的值 true，false
支持的操作 ==，!=
destination.agent_registry.mcp_server.prompt.name
值类型 字符串
支持的值 提示名称
支持的操作 ==、!=、in
destination.agent_registry.mcp_server.resource.name
值类型 字符串
支持的值 资源名称
支持的操作 ==、!=、in

创建代理到端点出站 UAP

“智能体到端点”出站流量政策允许智能体访问 Agent Registry 中注册的服务端点。

控制台

如需在 Google Cloud 控制台中创建代理到端点政策，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 在政策详情中，选择一项政策或创建一项新政策。如果您要创建新政策，请输入政策名称，例如 allow-translator-to-endpoint。
  4. 在添加规则中，配置规则：
    • 规则说明：Allow translator agent to access translation endpoint
    • 规则效果：允许
    • 选择主账号：选择特定代理，然后选择 translator-agent。
    • 选择资源：选择自定义标签页。
    • 条件：在条件编辑器中，输入： 
      destination.agent_registry.endpoint.name == 'projects/9876543210/locations/us-central1/endpoints/translation-service'
  5. 如需保存规则，请点击保存。
  6. 如需创建政策，请点击创建。

如需激活该政策，请将 UAP 绑定到您的项目。

gcloud

以下示例展示了允许代理访问已注册服务端点的 IAM 允许政策：

[
  {
    "description": "Allow translator agent access to registered translation endpoint",
    "effect": "ALLOW",
    "principals": [
      "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/translator-agent"
    ],
    "operation": {
      "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": "destination.agent_registry.endpoint.name == 'projects/9876543210/locations/us-central1/endpoints/translation-service'"
      }
    }
  }
]

如需激活该政策，请将 UAP 绑定到您的项目。

REST API

如需创建允许代理访问已注册服务端点的 IAM 允许政策，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "Allow translator agent access to registered translation endpoint",
        "effect": "ALLOW",
        "principals": [
          "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/translator-agent"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "destination.agent_registry.endpoint.name == 'projects/9876543210/locations/us-central1/endpoints/translation-service'"
          }
        }
      }
    ]
  }
}

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

如需激活该政策，请将 UAP 绑定到您的项目。

代理到端点 CEL 属性

下表介绍了您可以在代理到端点政策条件中使用的 CEL 属性：

属性 详细信息
destination.agent_registry.endpoint.name
值类型 字符串
支持的值 端点资源名称 (projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_NAME)
支持的操作 ==、!=、in

创建代理到未注册端点 UAP

“智能体到未注册端点”政策允许智能体访问未在 Agent Registry 中注册的外部第三方 API 和端点。

控制台

如需在Google Cloud 控制台中创建代理到未注册端点政策，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往政策页面：

    前往“政策”

  2. 在项目选择器中，选择包含将使用 UAP 的 Agent Gateway 的项目。
  3. 在政策详情中，选择一项政策或创建一项新政策。如果您要创建新政策，请输入政策名称，例如 allow-ocr-api-access。
  4. 在添加规则中，配置规则：
    • 规则说明：Allow POST access to external OCR service
    • 规则效果：允许
    • 选择主体：选择智能体主体（例如 my-ae-agent）。
    • 选择资源：依次选择标准 > 未注册的端点。
    • 条件：点击自定义标签页。
    • 在条件编辑器中，输入： 
      destination.unregistered.host.endsWith('example-ocr.com') && destination.unregistered.path.startsWith('/v2/process') && destination.unregistered.method == 'POST'
  5. 如需保存规则，请点击保存。
  6. 如需创建政策，请点击创建。

如需激活该政策，请将 UAP 绑定到您的项目。

gcloud

以下示例展示了一个 UAP，它允许代理访问路径以 /v2/process 开头并以 example-ocr.com 结尾的未注册端点：

[
  {
    "description": "Allow POST access to unregistered OCR endpoint",
    "effect": "ALLOW",
    "principals": [
      "principal://iam.googleapis.com/projects/9876543210/locations/global/workloadIdentityPools/POOL_ID/subject/ns/default/sa/my-ae-agent"
    ],
    "operation": {
      "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": "destination.unregistered.host.endsWith('example-ocr.com') && destination.unregistered.path.startsWith('/v2/process') && destination.unregistered.method == 'POST'"
      }
    }
  }
]

替换以下内容：

  • POOL_ID：工作负载身份池 ID。根据池类型，按以下格式设置 ID：
  • Google 管理的池： PROJECT_ID.svc.id.goog
  • 自行管理的池： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog

如需激活该政策，请将 UAP 绑定到您的项目。

REST API

如需创建允许智能体访问路径以 /v2/process 开头并以 example-ocr.com 结尾的未注册端点的 UAP，请执行以下操作：

  1. 将以下内容保存到名为 agent-access-policy.json 的 JSON 格式政策文件中：

    {
  "details": {
    "rules": [
      {
        "description": "Allow POST access to unregistered OCR endpoint",
        "effect": "ALLOW",
        "principals": [
          "principal://iam.googleapis.com/projects/9876543210/locations/global/workloadIdentityPools/POOL_ID/subject/ns/default/sa/my-ae-agent"
        ],
        "operation": {
          "permissions": ["iap.googleapis.com/resources.egressViaIAP"]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "destination.unregistered.host.endsWith('example-ocr.com') && destination.unregistered.path.startsWith('/v2/process') && destination.unregistered.method == 'POST'"
          }
        }
      }
    ]
  }
}

  2. 如需创建政策，请运行以下 curl 命令：

    curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @agent-access-policy.json

    替换以下内容：

    • POOL_ID：工作负载身份池 ID。根据池类型，按以下格式设置 ID：
    • Google 管理的池： PROJECT_ID.svc.id.goog
    • 自行管理的池： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog
    • PROJECT_ID：项目 ID
    • POLICY_NAME：政策名称

如需激活该政策，请将 UAP 绑定到您的项目。

代理到未注册端点的 CEL 属性

下表介绍了您可以在代理到未注册端点政策条件中使用的 CEL 属性：

属性 详细信息
destination.unregistered.host
值类型 字符串
支持的值 主机名（例如 'google.com'、'example.com'）
支持的操作 ==、!=、in、.startsWith()、.endsWith()、.contains()
destination.unregistered.path
值类型 字符串
支持的值 请求路径（例如 '/admin'、'/api/v1'）
支持的操作 ==、!=、in、.startsWith()、.endsWith()、.contains()
destination.unregistered.method
值类型 字符串
支持的值 HTTP 方法（例如 'get'、'post'、'put'、'delete'）
支持的操作 ==、!=、in

后续步骤

窗口概览

简要了解 Agent Gateway。

指南

配置内容和业务政策

了解如何配置内容和业务政策。

指南

了解如何测试政策。