建立 IAM 統一存取政策

控制台

如要在 Google Cloud 控制台中建立 UAP，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 如要為 Agent Gateway 輸出新增 IAM UAP，請按一下「add 建立」。
4. 在「Policy details」(政策詳細資料) 中，執行下列操作：
   1. 按一下「Policy」(政策) 欄位。
   2. 在下拉式清單中，選取「建立新政策」。
   3. 在「Policy name」(政策名稱) 欄位中，輸入政策名稱。系統會根據政策名稱自動產生政策 ID。
   4. 選用：按一下「編輯」即可編輯政策 ID。在「Policy ID」欄位中，您可以變更政策 ID 的名稱。
   5. 在「新增規則」中，展開預設規則「規則 1」，或按一下「新增規則」。
5. 為UAP建立一或多項規則。查看不同政策的示例。
6. 如要建立政策，請按一下「Create」(建立)。

儲存政策後，會發生下列情況：

• 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 路徑
     • Workload Identity Federation (自訂或外部代理)： 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：workload identity pool 所在專案的專案編號
       • POOL_ID：workload identity pool 的 ID
       • SUBJECT：代理主體的主體 ID
   • 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

控制台

如要在Google Cloud 控制台中建立同時包含允許和拒絕規則的 UAP，請按照下列步驟操作：

1. 在「Add Rules」(新增規則) 中，設定允許規則：
   1. 在「Rule description」(規則說明) 中，輸入允許規則的說明。
   2. 在「Rule effect」(規則效果) 中，選取「Allow」(允許)。
   3. 選取代理主體和目標資源，並新增允許 CEL 條件。
   4. 如要儲存允許規則，請按一下「儲存」。
2. 如要新增拒絕規則，請按一下「Add a rule」(新增規則)：
   1. 在「Rule description」(規則說明) 中，輸入拒絕規則的說明。
   2. 在「Rule effect」(規則效果) 中，選取「Deny」(拒絕)。
   3. 選取代理主體和目標資源，然後新增拒絕 CEL 條件。
   4. 如要儲存拒絕規則，請按一下「Save」(儲存)。
3. 如要建立政策，請按一下「Create」(建立)。

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. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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 繫結至專案。

控制台

儲存政策後，會發生下列情況：

• 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

控制台

在 Google Cloud 控制台中編輯 UAP，並執行下列操作：

1. 編輯現有規則。如要新增規則，請按一下「新增規則」。
2. 規則說明：這項規則的人類可讀說明
3. 選取主體：規則會管理這些來源代理主體的存取權。主體可以是下列其中一項：
   • 這項專案中的所有代理：目前專案中的所有代理。
   • 個別代理：您可以選取一或多個特定主體。代理是由代理身分定義。
   • 自訂主體集：您可以輸入主體 ID，指定一或多個主體集。主體 ID 必須以 principalSet:// 開頭，並參照代理身分。
4. Effect：規則的效用，可以是下列其中一種：
   • 允許：允許主體存取資源
   • 拒絕：禁止主體存取資源
5. 選取資源：可選取一或多種目的地資源。資源類型包括：
   • Registry：在 Agent Registry 位置註冊的所有資源
   • 代理：在 Agent Registry 註冊的目的地代理

   • MCP 伺服器：在 Agent Registry 中註冊的目的地 MCP 伺服器。您可以使用條件進一步控管 MCP 伺服器存取權。

   • 端點：在 Agent Registry 中註冊的目的地端點

   • 未註冊的端點：未在 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

控制台

在 Google Cloud 控制台中，您可以按照下列步驟建立條件：

1. 在規則的「Select resource(s)」(選取資源) 部分，選取下列其中一個分頁標籤：

   • 標準：在「標準」分頁中，選取一或多個資源類型，然後使用條件建構工具或條件編輯器建立條件。

   • 自訂：在「自訂」分頁中，您可以使用條件編輯器建立自訂條件，並在其中使用 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'"
  }
}

詳情請參閱「政策範例」。

控制台

如要在 Google Cloud 控制台建立代理到登錄檔政策，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 在「政策詳細資料」中，選取政策或建立新政策。如果您要建立新政策，請輸入政策名稱，例如 allow-registry-access。
4. 在「Add Rules」(新增規則) 中設定規則：
   • 規則說明：Allow all agents in project to access us-central1 registry
   • 規則效果：允許
   • 選取主體：在「主體集」中，選取「這項專案中的所有代理」。
   • 選取資源：依序選取「標準」 >「登錄檔」，然後選取 us-central1。
5. 按一下「儲存」即可儲存規則。
6. 如要建立政策，請按一下「Create」(建立)。

如要瞭解如何建立及繫結政策，請參閱「建立 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. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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 繫結至專案。

控制台

如要在 Google Cloud 控制台建立代理對代理政策，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 在「政策詳細資料」中，選取政策或建立新政策。如果您要建立新政策，請輸入政策名稱，例如 allow-orchestrator-to-support-agent。
4. 在「Add Rules」(新增規則) 中設定規則：
   • 規則說明：Allow orchestrator agent to invoke customer-support agent
   • 規則效果：允許
   • 選取主體：選取「特定代理」，然後選取 orchestrator-agent。
   • 選取資源：依序選取「標準」 >「代理」，然後選取 customer-support-agent。
5. 按一下「儲存」即可儲存規則。
6. 如要建立政策，請按一下「Create」(建立)。

如要啟用政策，請將 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 政策，並透過允許規則，允許 orchestrator 代理叫用在代理登錄資料庫中註冊的特定子代理，請按照下列步驟操作：

1. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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 繫結至專案。

控制台

如要在 Google Cloud 控制台建立代理到 MCP 伺服器政策，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 在「政策詳細資料」中，選取政策或建立新政策。如果您要建立新政策，請輸入政策名稱，例如 allow-github-read-only。
4. 在「Add Rules」(新增規則) 中設定規則：
   • 規則說明：Allow read-only access to GitHubTool on MCP server
   • 規則效果：允許
   • 「Select principals」(選取主體)：選取代理主體，例如 my-ae-agent。
   • 選取資源：選取「自訂」分頁標籤。
   • 條件：在條件編輯器中輸入：

     destination.agent_registry.mcp_server.tool.name == 'GitHubTool' && destination.agent_registry.mcp_server.tool.annotations.read_only_hint == true

5. 按一下「儲存」即可儲存規則。
6. 如要建立政策，請按一下「Create」(建立)。

如要啟用政策，請將 UAP 繫結至專案。

gcloud

下列範例政策顯示一項 IAM 允許規則，允許 Workload Identity Federation 格式的代理主體，對名為 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：workload identity pool 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 存取權政策，允許使用 Workload Identity Federation 的代理唯讀存取名為 GitHubTool 的工具，請按照下列步驟操作：

1. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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：workload identity pool 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」。

控制台

如要在 Google Cloud 控制台建立代理到端點政策，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 在「政策詳細資料」中，選取政策或建立新政策。如果您要建立新政策，請輸入政策名稱，例如 allow-translator-to-endpoint。
4. 在「Add Rules」(新增規則) 中設定規則：
   • 規則說明：Allow translator agent to access translation endpoint
   • 規則效果：允許
   • 選取主體：選取「特定代理」，然後選取 translator-agent。
   • 選取資源：選取「自訂」分頁標籤。
   • 條件：在條件編輯器中輸入：

     destination.agent_registry.endpoint.name == 'projects/9876543210/locations/us-central1/endpoints/translation-service'

5. 按一下「儲存」即可儲存規則。
6. 如要建立政策，請按一下「Create」(建立)。

如要啟用政策，請將 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. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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 繫結至專案。

控制台

如要在Google Cloud 控制台建立代理到未註冊端點政策，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：

   前往「政策」

2. 在專案選取器中，選取要使用 UAP 的 Agent Gateway 所屬的專案。
3. 在「政策詳細資料」中，選取政策或建立新政策。如果您要建立新政策，請輸入政策名稱，例如 allow-ocr-api-access。
4. 在「Add Rules」(新增規則) 中設定規則：
   • 規則說明：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. 如要建立政策，請按一下「Create」(建立)。

如要啟用政策，請將 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：workload identity pool ID。請根據集區類型，按照下列格式設定 ID：
• Google 代管集區： PROJECT_ID.svc.id.goog
• 自行管理的集區： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog

如要啟用政策，請將 UAP 繫結至專案。

REST API

如要建立 UAP，允許代理存取路徑開頭為 /v2/process、結尾為 example-ocr.com 的未註冊端點，請按照下列步驟操作：

1. 將下列內容儲存至 JSON 格式的政策檔案，並命名為 agent-access-policy.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：workload identity pool ID。請根據集區類型，按照下列格式設定 ID：
   • Google 代管集區： PROJECT_ID.svc.id.goog
   • 自行管理的集區： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog
   • PROJECT_ID：專案 ID
   • POLICY_NAME：政策名稱

如要啟用政策，請將 UAP 繫結至專案。