如要讓代理使用自己的授權，向 ServiceNow 或 Salesforce 等外部工具進行驗證，請在 Agent Identity 驗證管理工具中，使用雙足式 OAuth (用戶端憑證) 驗證提供者設定傳出驗證。
2-legged OAuth 驗證提供者會管理憑證和權杖，因此您不必編寫自訂程式碼來處理驗證流程。
雙足式 OAuth 工作流程
雙足式 OAuth 驗證提供者會使用代理的身分，不需要使用者同意。Google 會管理用戶端憑證的儲存空間。使用 Agent Development Kit (ADK) 時，系統會自動擷取產生的存取權杖，並插入工具叫用標頭。
事前準備
- 確認您選擇了正確的驗證方式。
啟用 Agent Identity API (如果尚未啟用)。
啟用 API 所需的角色
您必須具備
serviceusage.services.enable權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。從要連結的第三方應用程式取得用戶端 ID 和用戶端密鑰。
必要的角色
如要取得建立及使用 2-legged 代理身分驗證提供者所需的權限，請要求管理員授予您專案的下列 IAM 角色：
- 如要建立驗證提供者，請按照下列步驟操作：
-
如要使用驗證提供者：
- 代理身分使用者 (
roles/agentidentity.user) - 代理預設存取權 (
roles/aiplatform.agentDefaultAccess) - 代理情境編輯者 (
roles/aiplatform.agentContextEditor) - Vertex AI 使用者 (
roles/aiplatform.user) - 服務使用情形消費者 (
roles/serviceusage.serviceUsageConsumer)
- 代理身分使用者 (
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這些預先定義的角色具備建立及使用 2-legged 代理身分驗證提供者所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
您必須具備下列權限，才能建立及使用雙腳 Agent Identity 驗證提供者：
-
如要建立驗證提供者，請按照下列步驟操作：
agentidentity.authProviders.create -
如要使用驗證提供者：
-
agentidentity.authProviders.retrieveCredentials -
aiplatform.endpoints.predict -
aiplatform.sessions.create
-
建立雙腳驗證提供者
建立驗證提供者，定義第三方應用程式的設定和憑證。
如要建立 2-legged 驗證提供者，請使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。
控制台
- 前往 Google Cloud 控制台的「Agent Registry」頁面。
- 按一下要建立驗證提供者的代理名稱。
- 按一下「Identity」。
- 在「驗證提供者」部分，按一下「 新增驗證提供者」。
-
在「Add auth provider」(新增驗證供應商) 窗格中，輸入名稱和說明。
名稱只能使用小寫英文字母、數字或連字號，開頭須為小寫英文字母，結尾不得為連字號。
- 在「OAuth Type」清單中，選取「OAuth (2 legged)」。
- 點按「Create and continue」(建立並繼續)。
- 如要授予代理身分使用驗證提供者的權限，請按一下「Grant access」(授予存取權)。
這項程序會自動將 Agent Identity 使用者 (
roles/agentidentity.user) 角色指派給驗證提供者資源上的代理身分。 - 在「Auth provider credentials」(驗證供應商憑證) 部分，輸入下列資訊：
- 用戶端 ID
- 用戶端密鑰
- 權杖網址
- 按一下「Add provider config」。
新建立的驗證供應商會顯示在「Auth Providers」(驗證供應商) 清單中。
gcloud CLI
-
建立驗證提供者：
gcloud agent-identity auth-providers create
AUTH_PROVIDER_NAME\ --location="LOCATION" \ --two-legged-oauth-client-id="CLIENT_ID" \ --two-legged-oauth-client-secret="CLIENT_SECRET" \ --two-legged-oauth-token-url="TOKEN_URL" - 確認驗證提供者顯示在清單中，且狀態為
ENABLED：gcloud agent-identity auth-providers list \ --project="
PROJECT_ID" \ --location="LOCATION" -
授予存取權限，允許代理和本機開發環境從驗證提供者擷取憑證。如要允許部署的代理和個人使用者帳戶存取驗證供應商，請在驗證供應商資源上授予代理身分使用者 (
roles/agentidentity.user) 角色：-
授予已部署代理的 SPIFFE ID (代理身分) 存取權：
gcloud agent-identity auth-providers add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/agentidentity.user" \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
授予個人使用者帳戶存取權，以便在本機開發及測試 (
adk web)：gcloud agent-identity auth-providers add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/agentidentity.user" \ --member="user:USER_EMAIL"
-
更改下列內容：
PROJECT_ID： Google Cloud 專案 ID。LOCATION：部署驗證提供者和代理程式的位置 (例如us-west1)。AUTH_PROVIDER_NAME：驗證提供者的名稱 (例如jira-mcp-2lo-authprovider)。CLIENT_ID：您從第三方服務產生的 OAuth 用戶端 ID。CLIENT_SECRET：您從第三方服務產生的 OAuth 用戶端密鑰。TOKEN_URL：權杖伺服器網址 (例如https://oauth2.googleapis.com/token)。ORGANIZATION_ID：您的 Google Cloud 組織 ID。PROJECT_NUMBER：您的 Google Cloud 專案編號。ENGINE_ID：已部署推論引擎代理的 ID。USER_EMAIL：個人使用者帳戶的電子郵件地址。
REST
-
建立驗證提供者：
Agent Identity API 的
authProviders.create方法會在專案和位置建立 2-legged OAuth 驗證提供者。使用任何要求資料之前，請先修改下列項目的值：
PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 是英數字串，例如my-project。-
LOCATION：部署驗證服務供應商和代理程式的位置 (例如us-west1)。 -
AUTH_PROVIDER_NAME：驗證供應商的名稱 (例如jira-mcp-2lo-authprovider)。名稱只能包含小寫英文字母、數字或連字號，開頭須為小寫英文字母，結尾不得為連字號。 -
CLIENT_ID：您從第三方服務產生的 OAuth 用戶端 ID。 -
CLIENT_SECRET：您從第三方服務產生的 OAuth 用戶端密鑰。 -
TOKEN_URL：權杖伺服器網址 (例如https://oauth2.googleapis.com/token)。
HTTP 方法和網址：
POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME
JSON 要求主體：
{ "authProviderTypeParams": { "twoLeggedOauth": { "clientId": "CLIENT_ID", "clientSecret": "CLIENT_SECRET", "tokenUrl": "TOKEN_URL" } } }請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{ "name": "projects/my-project/locations/us-west1/authProviders/jira-mcp-2lo-authprovider", "createTime": "2026-04-03T21:15:41.367155Z", "updateTime": "2026-04-03T21:15:41.367155Z", "authProviderTypeParams": { "twoLeggedOauth": { "clientId": "my-oauth-client-id", "tokenUrl": "https://oauth2.googleapis.com/token" } }, "state": "ENABLED" } -
如要允許已部署的代理和個人使用者帳戶從驗證提供者擷取憑證，請在驗證提供者資源上授予 Agent Identity 使用者 (
roles/agentidentity.user) 角色：Agent Identity API 的
authProviders.setIamPolicy方法會設定驗證提供者資源的允許政策。使用任何要求資料之前，請先修改下列項目的值：
PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 是英數字串，例如my-project。-
LOCATION：部署驗證服務供應商和代理程式的位置 (例如us-west1)。 -
AUTH_PROVIDER_NAME：驗證提供者的名稱。 -
ORGANIZATION_ID：您的 Google Cloud組織 ID。 -
PROJECT_NUMBER：部署代理的 Google Cloud 專案編號 (例如987654321098)。 -
ENGINE_ID：已部署推論引擎代理的 ID。 -
USER_EMAIL：個人使用者帳戶的電子郵件地址。
HTTP 方法和網址：
POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy
JSON 要求主體：
{ "policy": { "bindings": [ { "role": "roles/agentidentity.user", "members": [ "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID", "user:USER_EMAIL" ] } ] } }請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{ "version": 1, "etag": "BwYKmjvelug=", "bindings": [ { "role": "roles/agentidentity.user", "members": [ "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899", "user:alex@example.com" ] } ] }
在代理程式碼中驗證
如要驗證代理，可以使用 ADK。
ADK
使用 ADK 中的 MCP 工具集，在代理的程式碼中參照驗證提供者。
from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.adk.auth.auth_tool import AuthConfig # Register the Google Cloud Auth Provider so the CredentialManager can use it. CredentialManager.register_auth_provider(GcpAuthProvider()) # Create the Google Cloud Auth Provider scheme # Note: If using the legacy V1 API, the resource name uses 'connectors' # instead of 'authProviders': projects/.../connectors/... auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME" ) # Configure an MCP tool with the authentication scheme. toolset = McpToolset( connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"), auth_scheme=auth_scheme, ) # Initialize the agent with the authenticated tools. agent = Agent( name="AGENT_NAME", model="gemini-2.5-flash", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
ADK
在 ADK 中使用已驗證的函式工具，在代理的程式碼中參照驗證提供者。
import httpx from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_identity import GcpAuthProviderScheme from google.adk.apps import App from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_tool import AuthConfig from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool from vertexai import agent_engines # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # Create Auth Config # Note: If using the legacy V1 API, the resource name uses 'connectors' # instead of 'authProviders': projects/.../connectors/... spotify_auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name=( "projects/PROJECT_ID/locations/" "LOCATION/authProviders/" "AUTH_PROVIDER_NAME" ) ) ) # Use the Auth Config in Authenticated Function Tool spotify_search_track_tool = AuthenticatedFunctionTool( func=spotify_search_track, auth_config=spotify_auth_config ) # Sample function tool async def spotify_search_track(credential: AuthCredential, query: str) -> str | list: token = None if credential.http and credential.http.credentials: token = credential.http.credentials.token if not token: return "Error: No authentication token available." async with httpx.AsyncClient() as client: response = await client.get( "https://api.spotify.com/v1/search", headers={"Authorization": f"Bearer {token}"}, params={"q": query, "type": "track", "limit": 1}, ) # Add your own logic here agent = Agent( name="AGENT_NAME", model="MODEL_NAME", instruction="AGENT_INSTRUCTIONS", tools=[spotify_search_track_tool], ) app = App( name="APP_NAME", root_agent=agent, ) vertex_app = agent_engines.AdkApp(app_name=app)
ADK
使用 ADK 中的 Agent Registry MCP 工具組，在代理程式碼中參照驗證提供者。
您不必為這個流程建構驗證配置。MCP 伺服器的傳出繫結已記錄要使用的驗證供應商。
from google.adk.agents import Agent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_registry import AgentRegistry # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # Set Agent Registry. LOCATION must be the same region as the auth provider. registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION") # The auth provider is resolved from the MCP server's outbound binding. toolset = registry.get_mcp_toolset( mcp_server_name=( "projects/PROJECT_ID/locations/" "LOCATION/mcpServers/" "agentregistry-00000000-0000-0000-0000-000000000000" ), ) agent = Agent( name="AGENT_NAME", model="MODEL_NAME", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
安裝本機測試所需的依附元件
如要在虛擬環境中測試代理，請安裝下列必要依附元件：
- 建立並啟用虛擬環境：
python3 -m venv env source env/bin/activate
- 安裝必要套件：
pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]
部署代理
將代理部署至 Google Cloud時，請務必啟用代理身分。
Agent CLI
如果您使用 Agent Development Kit (ADK) 和 Agent CLI，請按照下列步驟部署已啟用代理身分的代理：
-
在代理應用程式資料夾中，建立名為
.agent_engine_config.json的設定檔，啟用代理身分：echo '{ "identity_type": "AGENT_IDENTITY" }' >
AGENT_NAME/.agent_engine_config.json -
將代理部署至 Gemini Enterprise Agent Platform 的 Agent Runtime：
uv run adk deploy agent_engine
AGENT_NAME\ --project="PROJECT_ID" \ --region="LOCATION"更改下列內容：
AGENT_NAME：代理程式應用程式資料夾的名稱 (例如maps_agent)。PROJECT_ID：您的 Google Cloud專案 ID。LOCATION：要部署代理程式的支援區域 (例如us-west1)。
Python SDK
如果使用 Vertex AI Python SDK，透過程式輔助方式部署，請使用 identity_type=AGENT_IDENTITY 旗標：
import vertexai from vertexai import types from vertexai.agent_engines import AdkApp from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider # Initialize the Vertex AI client with v1beta1 API for Agent Identity support client = vertexai.Client( project="PROJECT_ID", location="LOCATION", http_options=dict(api_version="v1beta1") ) # Register the auth provider in set_up() so that it runs in the deployed # container. Use the proper wrapper class for your Agent Framework (for example, AdkApp). class AuthenticatedAdkApp(AdkApp): def set_up(self): CredentialManager.register_auth_provider(GcpAuthProvider()) super().set_up() app = AuthenticatedAdkApp(agent=agent) # Deploy the agent with Agent Identity enabled remote_app = client.agent_engines.create( agent=app, config={ "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": [ "google-cloud-aiplatform[agent_engines,adk]", "google-adk[agent-identity,mcp]>=2.7.1", ], }, )
更改下列內容：
PROJECT_ID：您的 Google Cloud 專案 ID。LOCATION：要部署代理程式的支援的地區 (例如us-west1)。