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

管理已部署代理程式的存取權

如要管理 Gemini Enterprise Agent Platform 中已部署代理的存取權，必須為存取外部資源的代理，以及存取代理的外部用戶端，設定驗證和授權機制。本文說明可用的驗證方式，包括代理身分、服務帳戶、API 金鑰和 OAuth 用戶端。

不同的存取模式適用不同的驗證方式：

驗證方式	用途	關於這種驗證方式
代理身分 (預先發布版)	直接從代理存取資料來源。	使用代理身分部署的代理，可根據您授予代理的 IAM 權限存取資源。
服務帳戶	直接從代理存取資料來源。	已部署的代理程式可以存取其服務帳戶有權存取的所有資源。
API 金鑰	在代理中使用 API 金鑰，將要求傳送至端點。	使用這個驗證方式前，請先確認您要使用的 API 支援 API 金鑰。
OAuth 用戶端 ID	處理代理使用者帳戶、註冊、登入或授權。	代理必須向使用者要求並取得同意聲明。

代理身分

如果您使用代理身分設定代理的身分和權限，請參閱「搭配使用代理身分與 Agent Runtime」，瞭解如何管理資源的存取控管。

服務帳戶

如果您使用服務帳戶設定代理的身分和權限，則在 Agent Runtime 部署的代理會使用 AI 平台推論引擎服務代理或自訂服務帳戶執行。

AI 平台推論引擎服務代理

AI 平台推論引擎服務代理服務帳戶的格式為 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com。

服務帳戶具備 Gemini Enterprise Agent Platform 推論引擎服務代理 角色 (roles/aiplatform.reasoningEngineServiceAgent)，可授予已部署代理所需的預設權限。如要查看預設權限的完整清單，請參閱 IAM 說明文件。

列出已部署代理的角色

控制台

前往身分與存取權管理頁面。

前往「IAM」(身分與存取權管理) 頁面
選取與 Google Cloud 專案對應的專案。
找出與代理身分所用服務帳戶相符的主體。
已部署代理的角色會顯示在「Role」(角色) 欄下方。

gcloud

首先，安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

其中

PROJECT_ID_OR_NUMBER 是專案 ID 或編號，
PRINCIPAL 是根據代理部署至執行階段時使用的服務帳戶。

詳情請參閱 IAM 說明文件和 CLI 參考資料。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-api-python-client

接著驗證身分，並執行下列指令，列出已部署代理的角色：

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

其中 PRINCIPAL 是根據在執行階段部署代理時使用的服務帳戶。

授予已部署代理的角色

控制台 (建議)

前往身分與存取權管理頁面。

前往「IAM」(身分與存取權管理) 頁面
選取與 Google Cloud 專案對應的專案。
找出與代理身分所用服務帳戶相符的主體。
按一下「編輯」按鈕，將必要角色新增至主體，然後按一下「儲存」按鈕。

gcloud

首先，安裝並初始化 gcloud CLI。接著執行下列指令：

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

其中

PRINCIPAL 是根據代理部署至執行階段時使用的服務帳戶。
ROLE_NAME 是要授予的角色名稱。如需預先定義角色的清單，請參閱「瞭解角色」。

詳情請參閱 IAM 說明文件和 CLI 參考資料。

Python

不建議自行編寫 Python 程式碼，為已部署的代理授予或撤銷角色。建議您改用 Google Cloud 控制台或 gcloud 執行一次性作業，或使用 Terraform 以程式輔助方式管理 IAM 存取控管。如要使用 Python 執行這項操作，請參閱 IAM 用戶端程式庫說明文件。

撤銷已部署代理的角色

控制台 (建議)

前往身分與存取權管理頁面。

前往「IAM」(身分與存取權管理) 頁面
選取與 Google Cloud 專案對應的專案。
找出與代理身分所用服務帳戶相符的主體。
按一下「編輯」按鈕，移除相應角色，然後點選「儲存」按鈕，撤銷主體的角色。

gcloud

首先，請安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

其中

PRINCIPAL 是根據代理部署至執行階段時使用的服務帳戶。
ROLE_NAME 是要撤銷的角色名稱。如需預先定義角色的清單，請參閱「瞭解角色」。

詳情請參閱 IAM 說明文件和 CLI 參考資料。

Python

不建議自行編寫 Python 程式碼，為已部署的代理授予或撤銷角色。建議您改用 Google Cloud 控制台或gcloud執行一次性作業，或使用 Terraform 以程式輔助方式管理 IAM 存取控管。如果您想或需要使用 Python 執行這項操作，請參閱 IAM 用戶端程式庫說明文件。

API 金鑰

API 金鑰會使用密鑰，其中包含一或多個密鑰版本，以及標籤和複製資訊等中繼資料。密鑰的實際酬載會儲存在密鑰版本中。Secret 是在專案層級透過 Secret Manager 管理，可供已部署的代理共用。如要在 Secret Manager 中列出與代理程式對應的 Secret，可以新增標籤並用於篩選。

建立密鑰

控制台

前往「Secret Manager」頁面。

前往「Secret Manager」
在「Secret Manager」頁面，點選「建立密鑰」。
在「Name」(名稱) 欄位中，輸入密鑰名稱 (例如 my-secret)。
選用：如要在建立初始密鑰時新增密鑰版本，請在「Secret value」(密鑰值) 欄位中輸入密鑰值 (例如 abcd1234)。
前往「標籤」，然後按一下「新增標籤」。
輸入鍵和對應的值，即可建立標籤。
點選「建立密鑰」。

gcloud

首先，請安裝並初始化 gcloud CLI。接著執行下列指令：

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

其中

SECRET_ID 是密鑰 ID 或完整 ID。
FILE_PATH 是包含版本詳細資料的檔案完整路徑 (包括檔案名稱)。

詳情請參閱 Secret Manager 說明文件，瞭解如何建立密鑰和密鑰版本，或參閱 CLI 參考資料，瞭解如何分別建立密鑰和密鑰版本。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-cloud-secret-manager

接著驗證身分，並執行下列指令

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

取得 Secret

控制台

前往「Secret Manager」頁面。

前往「Secret Manager」
在「Secret Manager」頁面，點選要查看說明的 Secret 名稱。
「Secret detail」(密鑰詳細資料) 頁面會列出密鑰相關資訊。

gcloud

首先，請安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

其中

VERSION_ID 是密鑰版本的 ID，
SECRET_ID 是密鑰的 ID 或完整 ID。

詳情請參閱 Secret Manager 說明文件或 CLI 參考資料。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-cloud-secret-manager

接著驗證身分，並執行下列指令

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

列出密鑰

控制台

前往「Secret Manager」頁面。

前往「Secret Manager」
在「Secret」表格中，按一下「篩選器」欄位。
選擇篩選器屬性和對應的值，例如 Location:asia-east1。
系統會根據輸入的值自動篩選表格。
(選用) 如要篩選 Secret 版本，請選取 Secret 以存取其版本，然後使用「Versions」(版本) 表格中的「Filter」(篩選器) 選項。

gcloud

首先，安裝並初始化 gcloud CLI。

如要列出專案的所有 Secret，請執行下列指令：

gcloud secrets list --filter="FILTER"

其中 FILTER 是字串 (例如 name:asecret OR name:bsecret) 或規則運算式 (例如 name ~ "secret_ab.*")。

如要列出密鑰的所有版本，請執行下列指令：

gcloud secrets versions list SECRET_ID

其中 SECRET_ID 是密鑰 ID 或完整 ID。

詳情請參閱 Secret Manager 說明文件，瞭解如何篩選 Secret 和列出 Secret 版本，或參閱 CLI 參考資料，瞭解如何分別列出 Secret 和 Secret 版本。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-cloud-secret-manager

接著驗證身分，並執行下列指令

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

更新密鑰

控制台

前往「Secret Manager」頁面。

前往「Secret Manager」
在「Secret Manager」頁面，勾選 Secret 名稱旁的核取方塊。
如果「資訊面板」已關閉，請按一下「顯示資訊面板」。
在「資訊面板」中，選取「標籤」分頁標籤。
按一下「Add label」(新增標籤)，然後輸入標籤的鍵和值。
按一下 [儲存]。

gcloud

首先，請安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

其中

SECRET_ID 是密鑰 ID 或完整 ID，
KEY 是標籤鍵，
VALUE 是標籤的對應值。

詳情請參閱 Secret Manager 說明文件或 CLI 參考資料。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-cloud-secret-manager

接著驗證身分，並執行下列指令

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

刪除 Secret

控制台

前往「Secret Manager」頁面。

前往「Secret Manager」
在「Secret Manager」頁面中，找到密鑰的「動作」欄，然後按一下「查看更多」。
在選單中選取「刪除」。
在「Delete secret」(刪除 Secret) 對話方塊中，輸入 Secret 名稱。
按一下「刪除密鑰」按鈕。

gcloud

首先，安裝並初始化 gcloud CLI。

如要刪除 Secret 版本，請執行下列指令：

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

其中

VERSION_ID 是密鑰版本的資源名稱，
SECRET_ID 是密鑰的 ID 或完整 ID。

如要刪除 Secret 及其所有版本，請執行下列指令：

gcloud secrets delete SECRET_ID

其中 SECRET_ID 是密鑰的 ID 或完整 ID

詳情請參閱 Secret Manager 說明文件，瞭解如何刪除密鑰和刪除密鑰版本，或參閱 CLI 參考資料，瞭解如何刪除密鑰和刪除密鑰版本。

Python

首先，請執行下列指令來安裝用戶端程式庫：

pip install google-cloud-secret-manager

接著驗證身分，並執行下列指令

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

OAuth 用戶端和憑證

Google 的 OAuth 伺服器會使用用戶端 ID 來識別個別代理。如果代理在多個平台上執行，每個平台都需要專屬的用戶端 ID。大致來說，如要整合以 OAuth 為基礎的代理，請按照下列步驟操作：

建立 OAuth 用戶端和憑證。
將用戶端 ID 和密鑰儲存在 Secret Manager。(請參閱「建立密鑰」)。
在開發期間，於代理中存取 Secret。

建立 OAuth 用戶端憑證

在 Google Cloud 控制台，依序前往「Google Auth Platform」>「Clients」頁面。

前往「Google Auth Platform」>「用戶端」
(如有需要) 如果畫面顯示「尚未設定 Google 驗證平台」，請按一下「開始使用」，然後填寫「專案設定」。(日後可再更新)。如要進一步瞭解正式版完備性，請參閱「OAuth 2.0 政策遵循」。
按一下「Create Client」(建立用戶端)。
將「Application type」(應用程式類型) 設為 Web application。
將 OAuth 用戶端名稱設為 OAUTH_CLIENT_DISPLAY_NAME。
在「已授權的重新導向 URI」下方，新增 REDIRECT_URI 的 URI。
在「用戶端密鑰」下方，點選「下載 JSON」按鈕。系統會下載 client_secret.json 檔案，其中包含下列內容：

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

將用戶端 ID 和密鑰儲存在 Secret Manager 中，例如：

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

列出 OAuth 用戶端

在 Google Cloud 控制台中，前往「Google Auth Platform」>「用戶端」頁面，其中會列出 OAuth 用戶端憑證。

前往「Google Auth Platform」>「用戶端」

刪除 OAuth 用戶端

在 Google Cloud 控制台，依序前往「Google Auth Platform」>「Clients」頁面。

前往「Google Auth Platform」>「用戶端」
選取要刪除的 OAuth 用戶端憑證，然後按一下「刪除」。

客戶自行管理的加密金鑰 (CMEK)

根據預設， Google Cloud 會使用 Google 代管的加密金鑰，自動加密靜態資料。如果對於保護資料的金鑰，有特定的法規遵循或監管要求，可以對已部署的代理使用客戶自行管理的加密金鑰 (CMEK)。

請參閱「Gemini Enterprise Agent Platform 的 CMEK」說明文件，瞭解一般需求條件，以及如何搭配 Gemini Enterprise Agent Platform 使用 CMEK，包括：

專案設定 (計費功能和已啟用的 API)
建立金鑰環和金鑰
必要權限授予

如要為代理啟用 CMEK，請在建立 Agent Platform 執行個體時，指定 encryption_spec 和 Cloud Key Management Service 金鑰。如需程式碼範例，請參閱「設定客戶自行管理的加密金鑰」。

限制

搭配使用 CMEK 和 Agent Runtime 時，須遵守下列限制：

不允許使用多區域金鑰：僅支援單一區域金鑰。金鑰環和金鑰的區域必須與代理平台執行個體相同。
無法更新 CMEK 執行個體的加密金鑰：使用 CMEK 金鑰部署代理後，就無法變更該部署作業的加密金鑰。如要使用新金鑰，請部署新的 Agent Platform 執行個體。
特定中繼資料和作業資料不會以您的金鑰加密：CMEK 會加密代理的靜態核心資料。不過，特定中繼資料和執行階段作業資料「不會」使用您的金鑰加密。而是使用 Google 的預設加密機制加密。包括：
- 代理中繼資料：
  - 顯示名稱
  - 說明
- 執行階段作業資料：
  - 服務帳戶電子郵件地址
  - 代理物件類別方法名稱
  - 環境變數

VPC Service Controls (VPC-SC)

Agent Runtime 支援 VPC Service Controls，可強化資料安全性，降低資料竊取風險。

設定 VPC Service Controls 後，部署的代理程式仍可安全存取 Google API 和服務，例如 BigQuery API、Cloud SQL Admin API 和 Agent Platform API，確保在定義的 perimeter 內順暢運作。重要的是，VPC Service Controls 可有效封鎖所有公開網路連線能力，將資料移動限制在授權網路邊界內，大幅提升企業資安態勢。

如要查看可用的部署選項，請參閱「部署代理程式」。視部署選項而定，您需要設定下列輸入規則：

如果是以 pickle 為基礎的部署作業，則必須具備 storage.googleapis.com 服務和 artifactregistry.googleapis.com 服務的輸入權限。
如果是來源部署、Git 部署和自備 Dockerfile (BYOD) 部署，則必須輸入 artifactregistry.googleapis.com 服務。
如果是自備容器 (BYOC) 部署作業，則不需要額外的輸入規則。

限制

Agent Gateway 不支援 VPC Service Controls。

不過，您可以使用自訂組織政策限制，限制哪些閘道可以與代理建立關聯。詳情請參閱「透過 Agent Gateway 轉送流量」。

管理已部署代理程式的存取權 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

代理身分

服務帳戶

AI 平台推論引擎服務代理

列出已部署代理的角色

控制台

gcloud

Python

授予已部署代理的角色

控制台 (建議)

gcloud

Python

撤銷已部署代理的角色

控制台 (建議)

gcloud

Python

API 金鑰

建立密鑰

控制台

gcloud

Python

取得 Secret

控制台

gcloud

Python

列出密鑰

控制台

gcloud

Python

更新密鑰

控制台

gcloud

Python

刪除 Secret

控制台

gcloud

Python

OAuth 用戶端和憑證

建立 OAuth 用戶端憑證

列出 OAuth 用戶端

刪除 OAuth 用戶端

客戶自行管理的加密金鑰 (CMEK)

限制

VPC Service Controls (VPC-SC)

限制

管理已部署代理程式的存取權