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

使用雙足式 OAuth 和驗證管理工具進行驗證

如要讓代理使用自己的授權，向 ServiceNow 或 Salesforce 等外部工具進行驗證，請在 Agent Identity 驗證管理工具中，使用雙足式 OAuth (用戶端憑證) 驗證提供者設定傳出驗證。

雙足式 OAuth 驗證提供者會為您管理憑證和權杖。因此您不必編寫自訂程式碼來處理驗證流程。

雙足式 OAuth 工作流程

雙足式 OAuth 驗證提供者會使用代理的身分，不需要使用者同意。Google 會管理用戶端憑證的儲存空間。使用 Agent Development Kit (ADK) 時，系統會自動擷取產生的存取權杖，並插入工具叫用標頭。

事前準備

確認您選擇了正確的驗證方式。
啟用 Agent Identity Connector API (如果尚未啟用)。
啟用 API 所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
建立及部署代理。
從要連結的第三方應用程式取得用戶端 ID 和用戶端密鑰。
確認您具備完成這項工作所需的角色。

必要的角色

如要取得建立及使用 2-legged 代理身分驗證提供者所需的權限，請要求管理員授予您專案的下列 IAM 角色：

如要建立驗證提供者，請按照下列步驟操作：
- IAM 連接器管理員 (roles/iamconnectors.admin)
- IAM 連接器編輯者 (roles/iamconnectors.editor)
如要使用驗證提供者：
- IAM 連接器使用者 (roles/iamconnectors.user)
- 代理預設存取權 (roles/aiplatform.agentDefaultAccess)
- 代理情境編輯者 (roles/aiplatform.agentContextEditor)
- 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)

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

這些預先定義的角色具備建立及使用 2-legged 代理身分驗證提供者所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

您必須具備下列權限，才能建立及使用雙腳 Agent Identity 驗證提供者：

如要建立驗證提供者，請按照下列步驟操作： iamconnectors.connectors.create
如要使用驗證提供者：
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

建立雙腳驗證提供者

建立驗證提供者，定義第三方應用程式的設定和憑證。

如要建立 2-legged 驗證提供者，請使用 Google Cloud 控制台或 Google Cloud CLI。

控制台

前往 Google Cloud 控制台的「Agent Registry」頁面。
前往「Agent Registry」
按一下要建立驗證提供者的代理名稱。
按一下「Identity」。
在「驗證提供者」部分，按一下「新增驗證提供者」。
在「Add auth provider」(新增驗證供應商) 窗格中，輸入名稱和說明。

名稱只能使用小寫英文字母、數字或連字號，開頭須為小寫英文字母，結尾不得為連字號。
在「OAuth Type」清單中，選取「OAuth (2 legged)」。
點按「Create and continue」(建立並繼續)。
如要授予代理身分使用驗證提供者的權限，請按一下「Grant access」(授予存取權)。
系統會自動將連接器使用者 (roles/iamconnectors.user) 角色指派給驗證提供者資源上的代理身分。
在「Auth provider credentials」(驗證供應商憑證) 部分，輸入下列資訊：
- 用戶端 ID
- 用戶端密鑰
- 權杖網址
按一下「Add provider config」。

新建立的驗證供應商會顯示在「Auth Providers」(驗證供應商) 清單中。

gcloud CLI

建立驗證提供者：

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

確認驗證提供者顯示在清單中，且狀態為 ENABLED：

gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

授予存取權限，允許代理和本機開發環境從驗證提供者擷取憑證。如要允許已部署的代理和個人使用者帳戶存取驗證提供者，請在驗證提供者資源上授予連接器使用者 (roles/iamconnectors.user) 角色：

授予已部署代理的 SPIFFE ID (代理身分) 存取權：

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

授予個人使用者帳戶存取權，以便在本機開發及測試 (adk web)：

gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.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_ENDPOINT：權杖端點網址 (例如 https://oauth2.googleapis.com/token)。
ORGANIZATION_ID：您的 Google Cloud 組織 ID。
PROJECT_NUMBER：您的 Google Cloud 專案編號。
ENGINE_ID：已部署推論引擎代理的 ID。
USER_EMAIL：個人使用者帳戶的電子郵件地址。

在代理程式碼中驗證

如要驗證代理，可以使用 ADK。

ADK

使用 ADK 中的 MCP 工具集，在代理的程式碼中參照驗證提供者。

from google.adk.agents.llm_agent import LlmAgent
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 using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

在 ADK 中使用已驗證的函式工具，在代理的程式碼中參照驗證提供者。

import httpx
from google.adk.agents.llm_agent import LlmAgent
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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/connectors/"
            "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 = LlmAgent(
    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 工具組，在代理程式碼中參照驗證提供者。

  from google.adk.agents.llm_agent import LlmAgent
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.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
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Google Cloud auth provider scheme by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/connectors/"
        "AUTH_PROVIDER_NAME"
    )
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    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時，請務必啟用代理身分。

如要部署至 Gemini Enterprise Agent Platform 的 Agent Runtime，請使用 identity_type=AGENT_IDENTITY 旗標：

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# 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")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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]"],
    },
)