認証マネージャーで API キーを使用して認証する

エージェントが Google マップや天気予報 API などの外部ツールに対して認証できるようにするには、エージェント ID 認証マネージャーで API キー認証プロバイダを使用してアウトバウンド認証を構成します。

API キー認証プロバイダは、暗号鍵を管理します。この機能により、エージェントのコードで鍵をハードコードしたり、手動で管理したりする必要がなくなります。

API キーのワークフロー

API キー認証プロバイダはエージェントの ID を使用し、ユーザーの同意を必要としません。Google は、保存中の API キーを保護するための対策を講じています。Agent Development Kit（ADK）を使用すると、API キーが自動的に取得され、ツール呼び出しヘッダーに挿入されます。

始める前に

正しい認証方法を選択していることを確認します。
Agent Identity Connector API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。
API の有効化
エージェントを作成してデプロイする。
接続するサードパーティサービスから API キーを取得します。
このタスクの完了に必要なロールが付与されていることを確認します。

必要なロール

API キー認証プロバイダの作成と使用に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

認証プロバイダを作成するには:
- IAM コネクタ管理者（roles/iamconnectors.admin）
- IAM Connector 編集者（roles/iamconnectors.editor）
認証プロバイダを使用するには:
- IAM コネクタユーザー（roles/iamconnectors.user）
- エージェントのデフォルトアクセス（roles/aiplatform.agentDefaultAccess）
- エージェントコンテキスト編集者（roles/aiplatform.agentContextEditor）
- Vertex AI ユーザー（roles/aiplatform.user）
- Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、API キー認証プロバイダの作成と使用に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

API キー認証プロバイダを作成して使用するには、次の権限が必要です。

認証プロバイダを作成するには: iamconnectors.connectors.create
認証プロバイダを使用するには:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

API キー認証プロバイダを作成する

認証プロバイダを作成して、サードパーティアプリケーションの構成と認証情報を定義します。

API キー認証プロバイダを作成するには、 Google Cloud コンソールまたは Google Cloud CLI を使用します。

コンソール

Google Cloud コンソールで、[エージェントレジストリ] ページに移動します。
Agent Registry に移動
認証プロバイダを作成するエージェントの名前をクリックします。
[ID] をクリックします。
[認証プロバイダ] セクションで、[ 認証プロバイダを追加] をクリックします。
[認証プロバイダを追加] ペインで、名前と説明を入力します。

名前に使用できるのは、英小文字、数字、ハイフンに限られます。末尾をハイフンにすることはできず、先頭は英小文字にする必要があります。
[OAuth Type] リストから [API key] を選択します。
[作成して続行] をクリックします。
認証プロバイダを使用する権限をエージェント ID に付与するには、[アクセスを許可] をクリックします。
これにより、認証プロバイダリソースのエージェント ID に Connector User（roles/iamconnectors.user）ロールが自動的に割り当てられます。
[認証プロバイダの認証情報] セクションで、API キーを入力します。
[プロバイダ設定を追加] をクリックします。

新しく作成された認証プロバイダが [認証プロバイダ] リストに表示されます。

Google Cloud CLI

認証プロバイダを作成します。

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --api-key="API_KEY"

認証プロバイダを使用する権限をエージェント ID に付与するには、プロジェクトまたは特定の認証プロバイダの IAM 許可ポリシーを更新し、エージェントプリンシパルにコネクタユーザー（roles/iamconnectors.user）ロールを付与します。

エージェント ID は、業界標準の SPIFFE ID 形式に基づいています。IAM 許可ポリシーでは、エージェント ID はプリンシパル ID を使用して参照されます。
プロジェクトレベル（gcloud）

プロジェクトレベルでロールを付与すると、エージェントはそのプロジェクト内の任意の認証プロバイダを使用できます。
- 単一のエージェントにプロジェクト内の認証プロバイダへのアクセス権を付与するには、次のコマンドを実行します。
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- プロジェクト内のすべてのエージェントに認証プロバイダへのアクセス権を付与するには、次のコマンドを実行します。
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
コネクタレベル（curl）

特定の認証プロバイダへのアクセス権を単一のエージェントに付与するには、setIamPolicy API を使用します。このコマンドは、リソースの既存の許可ポリシーを上書きします。
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- AUTH_PROVIDER_NAME: 認証プロバイダの名前。
- ORGANIZATION_ID: Google Cloud 組織 ID。
- PROJECT_NUMBER: Google Cloud プロジェクトの番号。
- LOCATION: エージェントのロケーション（例: us-central1）。
- ENGINE_ID: Reasoning Engine の ID。

エージェントコードで認証する

エージェントを認証するには、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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

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
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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

エージェントをデプロイする

エージェントを Google Cloudにデプロイするときは、エージェント ID が有効になっていることを確認してください。

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]"],
    },
)

認証マネージャーで API キーを使用して認証する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

API キーのワークフロー

始める前に

必要なロール

必要な権限

API キー認証プロバイダを作成する

コンソール

Google Cloud CLI

プロジェクト レベル（gcloud）

コネクタレベル（curl）

エージェント コードで認証する

ADK

ADK

ADK

エージェントをデプロイする

次のステップ

認証マネージャーで API キーを使用して認証する

プロジェクトレベル（gcloud）

エージェントコードで認証する