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

設定 IAM 代理程式政策

您可以建立政策，控管代理程式與服務之間的通訊。 Agent Gateway 會使用 Identity-Aware Proxy (IAP) 強制執行政策。

您可以在 Google Cloud 控制台的「政策」頁面中，建立 Agent Gateway IAM 允許政策。

您可以使用 Google Cloud CLI 建立 IAM 允許和拒絕政策。

事前準備

建立 IAM 允許政策前，請先完成下列事項：

設定 Google Cloud 帳單專案。
瞭解要管理存取權的代理程式身分。如要使用 Google Cloud 控制台管理整個登錄檔的存取權，請選取包含登錄檔的專案。
- Agent Platform 和 Gemini Enterprise 代理程式：瞭解代理程式身分。
- DIY 代理程式 (Cloud Run)：瞭解以服務帳戶為基礎的身分。
如要管理代理資源 (代理、MCP 伺服器和端點) 的存取權，必須先在 Agent Registry 中註冊這些資源。
設定代理閘道。建議您先以模擬測試模式設定 Agent Gateway。如要瞭解 Agent Gateway，請參閱代理程式閘道總覽。

必要的角色

如要取得設定 AI 代理程式專用 Agent Platform 的權限，請要求管理員授予您專案的下列 IAM 角色：

IAP 政策管理員 (roles/iap.admin)
代理程式登錄檢視者 (roles/agentregistry.viewer)
專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
網路安全管理員 (roles/networksecurity.admin)
服務擴充功能管理員 (roles/serviceextensions.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

使用 IAP 建立 IAM 允許政策

您可以為下列類型的代理互動定義輸出政策：

代理程式至登錄檔
代理對代理
代理至 MCP 伺服器
代理程式到端點

建立代理程式到登錄檔的政策

代理對儲存庫政策可讓代理存取目前專案的 Agent Registry 中所有代理、MCP 伺服器和端點。

控制台

Google Cloud 控制台，請執行下列操作：

選取來源代理程式和目標登錄檔。
1. 前往 Google Cloud 控制台的「Policies」(政策) 頁面：
  
  前往「政策」
2. 如要為 Agent Gateway 輸出內容新增 IAM 允許政策，請按一下「新增 IAM 政策」。
3. 如要選取來源代理程式，請按照下列步驟操作：
  - 如要選取目前所選專案中的所有代理，請選取「所有代理」。
  - 如要在目前專案中選取特定代理程式，請按照下列步驟操作：
    - 選取「個別代理商」。如要尋找代理商，請使用「篩選條件」「篩選」欄位進行搜尋。
    - 選取要授予存取權的來源代理程式。
    - 如要選取代理程式，請按一下「確定」。
4. 在「存取目標」中，按一下「登錄」。
5. 如要建立 IAM 允許政策並繫結至登錄檔，請按一下「建立」。
如要建立條件，請按照下列步驟操作：
1. 在「條件」中，按一下「新增條件」。
2. 在「新增條件」對話方塊中，執行下列操作：
  1. 在「Title」中，輸入條件名稱。
  2. 在「說明」中，輸入條件說明。
  3. 如要使用條件建構工具新增條件，請執行下列步驟：
    1. 在「條件類型」中，從下列選項選取條件類型：
      - 名稱：系統會根據存取資源的名稱限制代理程式存取權。
      - ReadOnly：代理是否只能讀取資料，防止代理執行寫入作業。
      - 破壞性：代理程式是否可執行有害或無法復原的動作，例如刪除資源。
      - 等冪：是否可覆寫代理程式存取權。
      - 開放世界：代理是否能與外部實體的「開放世界」互動 (例如網路搜尋工具)。如果將這項條件設為 `false`，系統會將專員互動視為已結束。
    2. 在「運算子」中，選取布林運算子。
    3. 在「值」中，選取條件的值。
    4. 如要新增其他條件，請按一下「新增其他條件」。
    5. 如要儲存條件，請按一下「儲存」。
  4. 如要使用條件編輯器新增條件，請在文字欄位中輸入 CEL 運算式。

gcloud

如要使用 gcloud CLI 建立從代理程式到登錄檔的輸出政策，請執行下列操作：

建立包含 IAM 政策的 IAP 政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}
```
更改下列內容：
- AGENT_PRINCIPAL：來源代理程式身分的主體，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER，例如 principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - 自行建立的代理程式：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如 principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
- CONDITION：
  條件參數，格式如下：
```
"condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}
```
  更改下列內容：
  - CONDITION_TITLE：條件標題
  - CONDITION_DESCRIPTION：條件說明
  - CEL_EXPRESSION：條件運算式。這個運算式必須是有效的 CEL 運算式。必須評估為 True，才能允許存取。

在 IAP 中，為 Agent Registry 中的所有資源設定 IAM 允許政策：

gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=AgentRegistry \
    --region=REGION

更改下列內容：

PROJECT_ID：包含資源的專案 ID。或者，您也可以分別指定 --folder 或 --organization 旗標，將政策繫結至資料夾或機構。
REGION：資源所在的區域

以下範例顯示代理程式階層的輸出存取權：

{
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/1234"
      ]
    }
  ]
}
}

建立代理程式對代理程式的出站政策

控制台

如要使用 Google Cloud 控制台定義代理程式對代理程式的輸出政策，請按照下列步驟操作：

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

前往「政策」
如要為 Agent Gateway 輸出內容新增 IAM 允許政策，請按一下「新增 IAM 政策」。
如要選取來源代理程式，請按照下列步驟操作：
- 如要選取目前所選專案中的所有代理，請選取「所有代理」。
- 如要在目前專案中選取特定代理程式，請按照下列步驟操作：
  - 選取「個別代理商」。如要尋找代理商，請使用「篩選條件」「篩選」欄位進行搜尋。
  - 選取要授予存取權的來源代理程式。
  - 如要選取代理程式，請按一下「確定」。
在「存取目標」中，按一下「代理程式」。
在「選取代理程式」中，選取要讓來源代理程式存取的目標代理程式。如要尋找代理程式，請使用篩選器「Filter」(篩選器) 欄位進行搜尋。
如要建立 IAM 允許政策並繫結至代理程式，請按一下「建立」。

gcloud

在 JSON 格式的檔案中建立 IAM 允許政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ]
      }
    ]
  }
}
```
更改下列內容：
- AGENT_PRINCIPAL：來源代理程式身分的主體，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER，例如 principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - 自行建立的代理程式：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如 principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
將 IAM 政策繫結至 IAP。
```
gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --agent=AGENT_ID \
    --region=REGION
```
更改下列內容：
- PROJECT_ID：包含資源的專案 ID。或者，您也可以分別指定 --folder 或 --organization 旗標，將政策繫結至資料夾或機構。
- AGENT_ID：代理程式的 ID
- REGION：資源所在的區域

建立從代理程式到 MCP 伺服器的輸出政策

控制台

如要使用 Google Cloud 控制台定義代理至 MCP 伺服器的輸出政策，請執行下列操作：

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

前往「政策」
如要為 Agent Gateway 輸出內容新增 IAM 允許政策，請按一下「新增 IAM 政策」。
如要選取來源代理程式，請按照下列步驟操作：
- 如要選取目前所選專案中的所有代理，請選取「所有代理」。
- 如要在目前專案中選取特定代理程式，請按照下列步驟操作：
  - 選取「個別代理商」。如要尋找代理商，請使用「篩選條件」「篩選」欄位進行搜尋。
  - 選取要授予存取權的來源代理程式。
  - 如要選取代理程式，請按一下「確定」。
在「存取目標」中，按一下「MCP 伺服器」。
在「Select MCP server」(選取 MCP 伺服器) 中，選取要讓來源代理存取的目標 MCP 伺服器。如要尋找 MCP 伺服器，請使用「Filter」(篩選器) 欄位搜尋。
如要建立 IAM 允許政策並繫結至 MCP 伺服器，請按一下「建立」。

建立條件：
1. 在「條件」中，按一下「新增條件」。
2. 在「新增條件」對話方塊中，執行下列操作：
  1. 在「Title」中，輸入條件名稱。
  2. 在「說明」中，輸入條件說明。
  3. 如要使用條件建構工具新增條件，請執行下列步驟：
    1. 在「條件類型」中，從下列選項選取條件類型：
      - 名稱：系統會根據存取資源的名稱限制代理程式存取權。
      - ReadOnly：代理是否只能讀取資料，防止代理執行寫入作業。
      - 破壞性：代理程式是否可執行有害或無法復原的動作，例如刪除資源。
      - 等冪：是否可覆寫代理程式存取權。
      - 開放世界：代理是否能與外部實體的「開放世界」互動 (例如網路搜尋工具)。如果將這項條件設為 `false`，系統會將專員互動視為已結束。
    2. 在「運算子」中，選取布林運算子。
    3. 在「值」中，選取條件的值。
    4. 如要新增其他條件，請按一下「新增其他條件」。
    5. 如要儲存條件，請按一下「儲存」。
  4. 如要使用條件編輯器新增條件，請在文字欄位中輸入 CEL 運算式。

gcloud

如要使用 gcloud CLI 建立從代理程式到 MCP 伺服器的輸出政策，請執行下列操作：

包括：以 JSON 格式的檔案建立 IAM 允許政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}
```
更改下列內容：
- AGENT_PRINCIPAL：來源代理程式身分的主體，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER，例如 principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - 自行建立的代理程式：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如 principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
- CONDITION：
  條件參數，格式如下：
```
"condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}
```
  更改下列內容：
  - CONDITION_TITLE：條件標題
  - CONDITION_DESCRIPTION：條件說明
  - CEL_EXPRESSION：條件運算式。這個運算式必須是有效的 CEL 運算式。必須評估為 True，才能允許存取。

將 IAM 政策繫結至 IAP。

gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --mcpServer=MCP_SERVER_ID 
    --region=REGION

更改下列內容：

PROJECT_ID：包含資源的專案 ID。或者，您也可以分別指定 --folder 或 --organization 旗標，將政策繫結至資料夾或機構。
MCP_SERVER_ID：MCP 伺服器的 ID
REGION：資源所在的區域

以下範例顯示 IAM 允許政策，該政策允許 DIY 代理程式使用 MCP 授權類型，對名為 GitHubTool 的工具進行唯讀存取。

{
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-pool.svc.id.goog/subject/ns/default/sa/my-ae-agent"
      ],
      "condition": {
        "title": "Allow AE Agent Read-Only Egress to GitHub MCP server",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') == 'GitHubTool' && api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true && api.getAttribute('iap.googleapis.com/request.auth.type', '') == 'MCP'"
      }
    }
  ]
}
}

建立代理程式到端點的傳出政策

控制台

如要使用 Google Cloud 控制台定義代理程式至端點的輸出政策，請按照下列步驟操作：

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

前往「政策」
如要為 Agent Gateway 輸出內容新增 IAM 允許政策，請按一下「新增 IAM 政策」。
如要選取來源代理程式，請按照下列步驟操作：
- 如要選取目前所選專案中的所有代理，請選取「所有代理」。
- 如要在目前專案中選取特定代理程式，請按照下列步驟操作：
  - 選取「個別代理商」。如要尋找代理商，請使用「篩選條件」「篩選」欄位進行搜尋。
  - 選取要授予存取權的來源代理程式。
  - 如要選取代理程式，請按一下「確定」。
在「存取目標」中，按一下「端點」。
在「選取端點」中，選取要讓來源代理程式存取的目標端點。如要尋找端點，請使用篩選器「Filter」(篩選器) 欄位進行搜尋。
如要建立 IAM 允許政策並繫結至端點，請按一下「建立」。

建立條件：
1. 在「條件」中，按一下「新增條件」。
2. 在「新增條件」對話方塊中，執行下列操作：
  1. 在「Title」中，輸入條件名稱。
  2. 在「說明」中，輸入條件說明。
  3. 如要使用條件建構工具新增條件，請執行下列步驟：
    1. 在「條件類型」中，從下列選項選取條件類型：
      - 名稱：系統會根據存取資源的名稱限制代理程式存取權。
      - ReadOnly：代理是否只能讀取資料，防止代理執行寫入作業。
      - 破壞性：代理程式是否可執行有害或無法復原的動作，例如刪除資源。
      - 等冪：是否可覆寫代理程式存取權。
      - 開放世界：代理是否能與外部實體的「開放世界」互動 (例如網路搜尋工具)。如果將這項條件設為 `false`，系統會將專員互動視為已結束。
    2. 在「運算子」中，選取布林運算子。
    3. 在「值」中，選取條件的值。
    4. 如要新增其他條件，請按一下「新增其他條件」。
    5. 如要儲存條件，請按一下「儲存」。
  4. 如要使用條件編輯器新增條件，請在文字欄位中輸入 CEL 運算式。

gcloud

包括：以 JSON 格式的檔案建立 IAM 允許政策。
```
{
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPAL"
        ]
      }
    ]
  }
}
```
更改下列內容：
- AGENT_PRINCIPAL：來源代理程式身分的主體，格式如下：
  - Agent Runtime 和 Gemini Enterprise 代理：principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER，例如 principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent
  - 自行建立的代理程式：principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/AGENT_SERVICE_ACCOUNT_IDENTIFIER — 例如 principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
將 IAM 政策繫結至 IAP。
```
gcloud beta iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --endpoint=ENDPOINT_ID \
    --region=REGION
```
更改下列內容：
- PROJECT_ID：包含資源的專案 ID。或者，您也可以分別指定 --folder 或 --organization 旗標，將政策繫結至資料夾或機構。
- ENDPOINT_ID：端點 ID
- REGION：資源所在的區域

使用 IAP 驗證 Cloud Run MCP 伺服器

如要為部署在 Cloud Run 的 MCP 伺服器設定以 IAP 為基礎的驗證機制，請按照下列步驟操作：

在 Cloud Run 上啟用 IAP。
將叫用者角色授予 IAP 服務代理：
```
gcloud beta run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'
```
更改下列內容：
- SERVICE_NAME：服務名稱
- PROJECT_NUMBER：專案編號
1. 在新或現有的 Cloud Run 服務上啟用 IAP。
新服務
如要部署新服務，請執行下列指令：
gcloud beta run deploy SERVICE_NAME \ --image=CONTAINER_IMAGE \ --region=REGION \ --project=PROJECT_ID \ --allow-unauthenticated \ --iap \ --functional-type=mcp-server
更改下列內容：
- SERVICE_NAME：服務名稱
- CONTAINER_IMAGE：您的容器映像檔
- REGION：部署服務的區域
- PROJECT_ID：啟用 Cloud Run 的專案 ID。
現有服務
如要更新現有執行個體，請執行下列指令：
gcloud run services update SERVICE_NAME \ --region=REGION \ --iap \ --functional-type=mcp-server
更改下列內容：
- SERVICE_NAME：服務名稱。
- REGION：區域。
建立及設定 OAuth 用戶端。

請按照「以程式輔助方式存取時共用 OAuth 用戶端」一文中的操作說明，註冊 OAuth 用戶端的通用用戶端 ID，以便搭配 IAP 使用。

請務必記錄完成這個步驟時取得的下列值：
- OAuth 用戶端 ID
- OAuth 用戶端密鑰
- 重新導向 URI
編輯 Gemini 主目錄 (~/.gemini/) 中的 settings.json 檔案，設定 Gemini CLI 或代理程式等用戶端，連線至已部署的 MCP 伺服器。

以下是 settings.json 範本：
```
{
  "mcpServers": {
    "my_mcp_server": {
      "httpUrl": "https://SERVICE_URL",
      "oauth": {
        "enabled": "true",
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [ "email", "openid" ],
        "redirectUri": "REDIRECT_URI"
      }
    }
  }
}
```
更改下列內容：
- SERVICE_URL：您的 Cloud Run 服務網址。
- OAUTH_CLIENT_ID：步驟 2 中的用戶端 ID。
- OAUTH_CLIENT_SECRET：步驟 2 中的用戶端密鑰。
- REDIRECT_URI：重新導向 URI，必須與步驟 2 中的 URI 相符。
測試是否可以連線至 MCP 伺服器。

後續步驟

總覽

Agent Gateway 總覽

概略瞭解 Agent Gateway。

指南

設定內容和業務政策

瞭解如何設定內容和商家政策。

指南

測試政策

瞭解如何測試政策。

設定 IAM 代理程式政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

使用 IAP 建立 IAM 允許政策

建立代理程式到登錄檔的政策

控制台

gcloud

建立代理程式對代理程式的出站政策

控制台

gcloud

建立從代理程式到 MCP 伺服器的輸出政策

控制台

gcloud

建立代理程式到端點的傳出政策

控制台

gcloud

使用 IAP 驗證 Cloud Run MCP 伺服器

新服務

現有服務

後續步驟

Agent Gateway 總覽

設定內容和業務政策

測試政策

設定 IAM 代理程式政策