如要管理 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。
服務帳戶具備 Vertex AI 推論引擎服務代理角色 (roles/aiplatform.reasoningEngineServiceAgent),可授予已部署代理所需的預設權限。如要查看預設權限的完整清單,請參閱 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是根據代理部署至執行階段時使用的服務帳戶。
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 是根據在執行階段部署代理時使用的服務帳戶。
授予已部署代理的角色
控制台 (建議)
前往身分與存取權管理頁面。
選取與 Google Cloud 專案對應的專案。
找出與代理身分所用服務帳戶相符的主體。
按一下「編輯」按鈕,將必要角色新增至主體,然後按一下「儲存」按鈕。
gcloud
首先,安裝並初始化 gcloud CLI。然後執行下列指令:
gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
不建議自行編寫 Python 程式碼,為已部署的代理授予或撤銷角色。建議您改用 Google Cloud 控制台或gcloud執行一次性作業,或使用 Terraform 以程式輔助方式管理 IAM 存取控管。如果您想或需要使用 Python 執行這項操作,請參閱 IAM 用戶端程式庫說明文件。
撤銷已部署代理的角色
控制台 (建議)
前往身分與存取權管理頁面。
選取與 Google Cloud 專案對應的專案。
找出與代理身分所用服務帳戶相符的主體。
按一下「編輯」按鈕,移除相應角色,然後點選「儲存」按鈕,撤銷主體的角色。
gcloud
首先,請安裝並初始化 gcloud CLI。然後執行下列指令:
gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
不建議自行編寫 Python 程式碼,為已部署的代理授予或撤銷角色。建議您改用 Google Cloud 控制台或gcloud執行一次性作業,或使用 Terraform 以程式輔助方式管理 IAM 存取控管。如果您想或需要使用 Python 執行這項操作,請參閱 IAM 用戶端程式庫說明文件。
API 金鑰
API 金鑰會使用密鑰,其中包含一或多個密鑰版本,以及標籤和複製資訊等中繼資料。密鑰的實際酬載會儲存在密鑰版本中。Secret 是在專案層級透過 Secret Manager 管理,可供已部署的代理共用。如要在 Secret Manager 中列出與代理程式對應的 Secret,可以新增標籤並用於篩選。
建立密鑰
控制台
前往「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 名稱。
「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」表格中,按一下「篩選器」欄位。
選擇篩選器屬性和對應的值,例如
Location:asia-east1。系統會根據輸入的值自動篩選表格。
(選用) 如要篩選 Secret 版本,請選取 Secret 以存取其版本,然後使用「Versions」(版本) 表格中的「Filter」(篩選器) 選項。
gcloud
如要列出專案的所有 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 名稱旁的核取方塊。
如果「資訊面板」已關閉,請按一下「顯示資訊面板」。
在「資訊面板」中,選取「標籤」分頁標籤。
按一下「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」頁面中,找到密鑰的「動作」欄,然後按一下「查看更多」。
在選單中選取「刪除」。
在「Delete secret」(刪除 Secret) 對話方塊中,輸入 Secret 名稱。
按一下「刪除密鑰」按鈕。
gcloud
如要刪除 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 用戶端憑證
在 Google Cloud 控制台,依序前往「Google Auth Platform」>「Clients」頁面。
(如有需要) 如果畫面顯示「尚未設定 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 用戶端憑證。
刪除 OAuth 用戶端
在 Google Cloud 控制台,依序前往「Google Auth Platform」>「Clients」頁面。
選取要刪除的 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 時,須遵守下列限制:
多區域和全域端點限制:在 Agent Runtime 部署的代理,僅支援 Cloud Key Management Service 中的單一區域金鑰,且金鑰環和金鑰區域必須與 Agent Platform 執行個體的區域相符。多區域端點 (
us或eu) 不支援使用 CMEK 部署代理執行階段。不過,如果您建立獨立的上層 Agent Platform 執行個體,但不部署代理執行階段程式碼 (用於儲存 Agent Platform 工作階段或 Agent Platform Memory Bank 資料),則可在區域和多區域位置設定 CMEK (us搭配us金鑰,或eu搭配europe金鑰)。global端點不支援任何資源的 CMEK。無法更新 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) 部署作業,則不需要額外的輸入規則。
搭配使用 VPC Service Controls 和 Agent Gateway
2026 年 9 月 8 日後建立的代理到任何位置 (輸出) 部署作業,可搭配 Agent Gateway 使用 VPC Service Controls。如要在 VPC Service Controls service perimeter 內,搭配 Agent Gateway 執行 Agent Runtime,部署作業必須符合下列規定:
- 閘道必須使用代理連線範本 (
AgentConnectivityTemplate),並將vpcEgress設為ALL_TRAFFIC,這樣所有傳出代理流量都會透過虛擬私有雲網路轉送。 - 虛擬私有雲網路必須為
googleapis.com.設定私人 Cloud DNS 區域和 DNS 對接,將 Google API 流量解析為restricted.googleapis.com(199.36.153.4/30) 或內部 Private Service Connect 端點。 - 如果代理程式繫結至強制執行閘道,您必須在代理程式註冊資料庫中,將必要的區域和 mTLS
Agent Platform API端點加入許可清單。
如需逐步設定操作說明,請參閱下列資源:
- Agent Gateway 的 VPC Service Controls 法規遵循
- 透過 Agent Gateway 轉送 Agent Runtime 流量
- 工作階段的 VPC Service Controls