A2A エージェントを登録して管理する

Agent2Agent(A2A)プロトコルは、オープンな通信プロトコルであり、エージェントの共通言語です。このプロトコルにより、さまざまなビルダーやプラットフォームのエージェントが互いを検出し、コラボレーションやタスクの安全な委任を行えるようになります。このドキュメントでは、Gemini Enterprise の管理者が、A2A を使用して構築され、任意のプラットフォームにホストされているエージェントを Gemini Enterprise に接続し、Gemini Enterprise ウェブアプリでユーザーが利用できるようにする方法について説明します。

始める前に

以下のものが揃っていることを確認してください。

  • Gemini Enterprise 管理者のロール。

  • Discovery Engine API を有効にします。 Google Cloudプロジェクトで Discovery Engine API を有効にするには、 Google Cloud コンソールで [Discovery Engine API] ページに移動します。

    Discovery Engine API に移動

  • 既存の Gemini Enterprise app。アプリを作成するには、アプリを作成するをご覧ください。

  • A2A プロトコルを使用するエージェント。

    Gemini Enterprise は、A2A v0.3 ストリーミング メカニズムをサポートしています。

    A2A v1.0.0 以降を使用する場合は、SDK が提供する互換性パッケージを使用して、エージェントが以前のメカニズム(Go の a2acompat/a2av0 パッケージや Python の a2a.compat.v0_3 パッケージなど)で機能することを確認します。

  • A2A エージェントが Cloud Run でホストされ、デフォルトの .run.app URL を直接使用し、認証が必要な場合は、Cloud Run 起動元(roles/run.invoker)ロールを Discovery Engine サービス エージェントに付与します(これは、Cloud Run が Apigee、ロードバランサ、カスタム ドメインの背後にある場合は適用されません)。

    gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \
       --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
       --role="roles/run.invoker"
    

    次のように置き換えます。

    • PROJECT_ID: 実際のプロジェクトの ID。
    • PROJECT_NUMBER: Google Cloud プロジェクトの数。

認証と認可を構成する

エージェントのホスティング環境とセキュリティ要件に応じて、Gemini Enterprise がエージェントを認証する方法、エージェントがエンドユーザーに代わってダウンストリームのリソースとツールにアクセスする方法、エージェント エンドポイントを保護する方法を構成できます。

  • Gemini Enterprise がエージェントを認証する方法: Gemini Enterprise が A2A エージェント エンドポイントを呼び出すときに、サービス間 IAM ヘッダーとエンドユーザー OAuth 2.0 ヘッダーを送信する方法について説明します。
  • エンドユーザー認証用に OAuth 2.0 を構成する: Gemini Enterprise で OAuth 2.0 認証リソースを構成して、Gemini Enterprise がエンドユーザー トークンを取得し、エージェントを呼び出すときに Authorization ヘッダーで送信するようにします(たとえば、Gemini Enterprise Agent Platform の Agent Runtime でホストされている A2A エージェントを呼び出す、またはユーザー トークンをエージェント コンテナに直接渡す)。
  • Agent Identity Auth Manager で 3-legged OAuth を構成する: Agent Identity Auth Manager で 3-legged OAuth(3LO)認証プロバイダを構成して、A2A エージェントが Model Context Protocol(MCP)サーバーやサードパーティ API などの特定のツールに対して、ユーザー委任トークンをオンデマンドでリクエストできるようにします。

Gemini Enterprise がエージェントを認証する方法

Gemini Enterprise が A2A エージェントを呼び出すと、ホスティングとセキュリティの構成に応じて、リクエスト ヘッダーで認証データと認可データを送信できます。

ヘッダー 説明
X-Serverless-Authorization

サービス間の IAM 認証(Cloud Run の場合)。

A2A エージェントが Cloud Run でホストされ、エージェント URL がデフォルトの .run.app URL の場合、Gemini Enterprise は、エージェント URL をオーディエンスとして Discovery Engine サービス エージェント(service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com)の Google 署名付き OIDC ID トークンを自動的に生成し、X-Serverless-Authorization ヘッダーに添付します。エージェント URL で Apigee、ロードバランサ、カスタム ドメインを使用している場合、Gemini Enterprise はこのヘッダーを送信しません。

Gemini Enterprise がデフォルトの .run.app URL を直接呼び出すと、Cloud Run の上り(内向き)インフラストラクチャはこのヘッダーを使用して、サービス エージェントに roles/run.invoker IAM ロールがあることを確認してから(始める前にを参照)、リクエストをアプリケーション コンテナに転送します。

Authorization

エンドユーザーの OAuth 2.0 認可(エンドポイントの呼び出し、ユーザー コンテキスト、API アクセス用)。

A2A エージェントに OAuth 2.0 認証情報を構成すると(エンドユーザー認可に OAuth 2.0 を構成するを参照)、Gemini Enterprise は、ログインしたエンドユーザーが同意を付与した後に、そのエンドユーザーに代わって OAuth 2.0 アクセス トークンまたは ID トークンを取得し、標準の Authorization ヘッダー(例: Bearer USER_OAUTH_TOKEN)で送信します。

Cloud Run でホストされているエージェントの場合、Cloud Run は Authorization ヘッダーをコンテナに直接転送します。これにより、エージェント アプリケーション コードはユーザートークンを読み取り、ユーザーに代わってダウンストリーム API を呼び出すことができます。Agent Runtime でホストされている A2A エージェントの場合、https://www.googleapis.com/auth/cloud-platform スコープで OAuth 2.0 認可リソースを構成すると、Gemini Enterprise はユーザーに代わって Agent Runtime エンドポイントを認証できます。

エンドユーザー認可用の OAuth 2.0 を構成する(省略可)

A2A エージェントの場合、エージェント エンドポイントで Authorization ヘッダーにエンドユーザーの OAuth 2.0 トークンが必要な場合は、Gemini Enterprise で OAuth 2.0 認証情報を構成します(たとえば、Agent Runtime でホストされている A2A エージェントを呼び出す場合や、ユーザー トークンをエージェント コンテナに直接渡す場合)。認証ヘッダーと認可ヘッダーの仕組みについては、Gemini Enterprise がエージェントを認証する方法をご覧ください。

A2A エージェントがツールレベルの 3-legged OAuth に Agent Identity Auth Manager を使用している場合(ユーザーに代わって MCP サーバーやサードパーティ API にアクセスする場合など)、Agent Identity Auth Manager を使用して 3-legged OAuth を構成するをご覧ください。

OAuth クライアント ID を作成する手順は次のとおりです。

  1. Google Cloud コンソールの [API とサービス] ページで、[認証情報] ページに移動します。

    [認証情報] に移動

  2. エージェントにアクセスさせるデータソースを含む Google Cloud プロジェクトを選択します。たとえば、エージェントにクエリを実行させる BigQuery データセットを含むプロジェクトを選択します。

  3. [認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。

  4. [アプリケーションの種類] で [ウェブ アプリケーション] を選択します。

  5. [承認済みのリダイレクト URI] セクションに、次の URI を追加します。

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
  6. [作成] をクリックします。

  7. [OAuth クライアントを作成しました] パネルで、[JSON をダウンロード] をクリックします。ダウンロードした JSON には、選択したGoogle Cloud プロジェクトの Client ID、Authorization URI、Token URI、Client secret が含まれています。認可リソースを作成するには、次の情報が必要です。

Agent Identity Auth Manager で 3-legged OAuth を構成する(省略可)

A2A エージェントが Agent Development Kit(ADK)で構築され、3-legged OAuth(3LO)に Agent Identity Auth Manager を使用している場合、エージェントはログイン ユーザーに代わって、ダウンストリームの MCP サーバー、 Google Cloudサービス、サードパーティ API に対して認証を行うことができます。

A2A エージェントのツールでユーザーの同意が必要な場合、Gemini Enterprise はクライアントサイドの 3LO ワークフローを自動的に管理します。

  1. 同意プロンプト: エージェントが adk_request_credential ツール割り込み(TASK_STATE_AUTH_REQUIRED)を返すと、Gemini Enterprise ウェブアプリはユーザーにログインを求め、認証プロバイダから認可 URI を開きます。
  2. ユーザー検証とトークン ストレージ: ユーザーが同意すると、認証プロバイダは Gemini Enterprise 検証エンドポイント(https://vertexaisearch.cloud.google.com/validateUserId)にリダイレクトします。Gemini Enterprise はセッション状態を検証し、Agent Identity Auth Manager で認証情報を確定します。
  3. 会話の再開: Gemini Enterprise は、完了した adk_request_credential レスポンスを A2A エージェントに返します。A2A エージェントは、認証プロバイダからユーザーのアクセス トークンを取得してツールを呼び出します。

Gemini Enterprise は、同意プロンプト、検証エンドポイント、会話の再開を処理するため、カスタムのクライアントサイド UI アプリケーションを実装する必要はありません。

ステップ 1: 3-legged OAuth 認証プロバイダを設定する

認証マネージャーで 3-legged OAuth を使用して認証するの手順に沿って、Agent Identity API(agentidentity.googleapis.com)を有効にし、OAuth クライアント アプリケーションを構成して、3-legged OAuth 認証プロバイダを作成します。

Gemini Enterprise で使用する OAuth クライアントと認証プロバイダを構成するときは、次の設定を含めます。

  • 承認済みのリダイレクト URI: OAuth クライアント構成で、認証プロバイダのコールバック リダイレクト URI を追加します。

    https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallback
    

    Gemini Enterprise エージェントの認可リソースに同じ OAuth クライアントを再利用する場合(たとえば、Gemini Enterprise が Agent Runtime でホストされている A2A エージェントを呼び出せるようにする場合)は、Gemini Enterprise のリダイレクト URI(https://vertexaisearch.cloud.google.com/oauth-redirect)も追加します。

  • 続行 URI: 続行 URI(認証プロバイダのデフォルトの続行 URI またはエージェント コードの continue_uri)を Gemini Enterprise 検証エンドポイントに設定します。

    https://vertexaisearch.cloud.google.com/validateUserId
    

ステップ 2: A2A エージェント コードを設定する

ADK エージェントを構築し、Agent Runtime にデプロイするために A2aAgent でラップする場合は、エージェント コードが次の要件を満たしていることを確認してください。

  • 必要なパッケージ バージョンをインストールする: デプロイ要件に a2a-sdk[http-server]>=1.0.0、google-cloud-aiplatform[agent_engines,adk]>=1.156.0、google-adk[a2a,agent-identity,mcp]>2.7.1 を含めます。
  • continue_uri を Gemini Enterprise に設定する: GcpAuthProviderScheme または AgentRegistry.get_mcp_toolset で continue_uri を "https://vertexaisearch.cloud.google.com/validateUserId" に設定します(認証プロバイダでデフォルトの続行 URI として構成している場合を除く)。
  • ランナー ビルダー関数内で GcpAuthProvider を登録する: モジュールの最上位レベルだけでなく、デプロイされたコンテナ ワーカー プロセスで Runner をビルドする関数内で CredentialManager.register_auth_provider(GcpAuthProvider()) を呼び出します。
  • 組み込みの A2aAgentExecutor を使用する: A2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor)を A2aAgent に渡します。event.is_final_response() のみをチェックするカスタム AgentExecutor は使用しないでください。adk_request_credential 割り込みを TASK_STATE_AUTH_REQUIRED A2A タスク状態に変換するには、A2aAgentExecutor が必要です。
  • AgentCard に A2A プロトコル バージョン 0.3 を含める: protocol_version=PROTOCOL_VERSION_0_3 と protocol_binding=TransportProtocol.HTTP_JSON を含む AgentInterface を、デフォルトの 1.0 インターフェースとともに agent_card.supported_interfaces に追加します。これにより、Gemini Enterprise は A2A v0.3 ルートを介してエージェントと通信できます。

ADK + A2A

次の例では、McpToolset(または AgentRegistry.get_mcp_toolset)で GcpAuthProviderScheme を使用して、ユーザーに代わって MCP サーバーに対して認証を行う ADK A2A エージェントを構成します。

from a2a.types import AgentInterface, AgentSkill
from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.agents import LlmAgent
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
from google.adk.runners import Runner
from google.adk.sessions.in_memory_session_service import InMemorySessionService
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card

# Redirect URI for Gemini Enterprise user validation
CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId"

auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    scopes=["OAUTH_SCOPE"],
    continue_uri=CONTINUE_URI,
)

mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://YOUR_MCP_SERVER_URL"
    ),
    auth_scheme=auth_scheme,
)

# Alternatively, if your MCP server is registered in Agent Registry
# with an outbound auth provider binding, use AgentRegistry.get_mcp_toolset:
# from google.adk.integrations.agent_registry import AgentRegistry
# registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")
# mcp_tools = registry.get_mcp_toolset(
#     mcp_server_name="projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_ID",
#     continue_uri=CONTINUE_URI,
# )

adk_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="AGENT_NAME",
    description="AGENT_DESCRIPTION",
    instruction="AGENT_INSTRUCTIONS",
    tools=[mcp_tools],
)

def build_runner() -> Runner:
    # Register GcpAuthProvider inside the deployed worker process
    CredentialManager.register_auth_provider(GcpAuthProvider())
    return Runner(
        app_name=adk_agent.name,
        agent=adk_agent,
        artifact_service=InMemoryArtifactService(),
        session_service=InMemorySessionService(),
        memory_service=InMemoryMemoryService(),
    )

agent_card = create_agent_card(
    agent_name="AGENT_DISPLAY_NAME",
    description="AGENT_DESCRIPTION",
    skills=[
        AgentSkill(
            id="SKILL_ID",
            name="SKILL_NAME",
            description="SKILL_DESCRIPTION",
            tags=[],
        )
    ],
)

agent_card.supported_interfaces = [
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_1_0,
        url="",
    ),
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_0_3,
        url="",
    ),
]

a2a_agent = A2aAgent(
    agent_card=agent_card,
    agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner),
)

ADK + A2A

次の例では、AuthenticatedFunctionTool と GcpAuthProviderScheme を使用して、ユーザーに代わってサードパーティまたは Google CloudREST API を呼び出す ADK A2A エージェントを構成します。

from a2a.types import AgentInterface, AgentSkill
from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.agents import LlmAgent
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
from google.adk.runners import Runner
from google.adk.sessions.in_memory_session_service import InMemorySessionService
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
import httpx
from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card

# Redirect URI for Gemini Enterprise user validation
CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId"

auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        scopes=["OAUTH_SCOPE"],
        continue_uri=CONTINUE_URI,
    )
)

async def call_external_api(credential: AuthCredential, query: str) -> str:
    """Calls an external API using the end user's OAuth token."""
    token = None
    if credential and 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://YOUR_API_ENDPOINT",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query},
        )
        response.raise_for_status()
        return response.text

authenticated_tool = AuthenticatedFunctionTool(
    func=call_external_api,
    auth_config=auth_config,
)

adk_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="AGENT_NAME",
    description="AGENT_DESCRIPTION",
    instruction="AGENT_INSTRUCTIONS",
    tools=[authenticated_tool],
)

def build_runner() -> Runner:
    # Register GcpAuthProvider inside the deployed worker process
    CredentialManager.register_auth_provider(GcpAuthProvider())
    return Runner(
        app_name=adk_agent.name,
        agent=adk_agent,
        artifact_service=InMemoryArtifactService(),
        session_service=InMemorySessionService(),
        memory_service=InMemoryMemoryService(),
    )

agent_card = create_agent_card(
    agent_name="AGENT_DISPLAY_NAME",
    description="AGENT_DESCRIPTION",
    skills=[
        AgentSkill(
            id="SKILL_ID",
            name="SKILL_NAME",
            description="SKILL_DESCRIPTION",
            tags=[],
        )
    ],
)

agent_card.supported_interfaces = [
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_1_0,
        url="",
    ),
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_0_3,
        url="",
    ),
]

a2a_agent = A2aAgent(
    agent_card=agent_card,
    agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner),
)

ステップ 3: エージェント ID を使用して A2A エージェントをデプロイし、アクセス権を付与する

  1. identity_type=types.IdentityType.AGENT_IDENTITY を使用して A2aAgent を Agent Runtime にデプロイします。

    import vertexai
    from vertexai import types
    
    client = vertexai.Client(
        project="<var>PROJECT_ID</var>",
        location="<var>LOCATION</var>",
        http_options=dict(api_version="v1beta1"),
    )
    
    remote_a2a_agent = client.agent_engines.create(
        agent=a2a_agent,
        config={
            "display_name": "<var>AGENT_DISPLAY_NAME</var>",
            "identity_type": types.IdentityType.AGENT_IDENTITY,
            "requirements": [
                "a2a-sdk[http-server]>=1.0.0",
                "google-cloud-aiplatform[agent_engines,adk]>=1.156.0",
                "google-adk[a2a,agent-identity,mcp]>2.7.1",
                "google-genai",
                "httpx",
            ],
        },
    )
    
  2. デプロイが完了したら、デプロイされたエージェントの SPIFFE プリンシパルに、認証プロバイダの Agent Identity User(roles/agentidentity.user)ロールを付与します。

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

    次のように置き換えます。

    • AUTH_PROVIDER_NAME: 認証プロバイダの名前。
    • PROJECT_ID: 実際のプロジェクトの ID。
    • LOCATION: 認証プロバイダとエージェントがデプロイされているリージョン(例: us-central1)。
    • ORGANIZATION_ID: 実際の Google Cloud組織 ID。
    • PROJECT_NUMBER: Google Cloud プロジェクトの数。
    • ENGINE_ID: デプロイされた reasoningEngines エージェントのリソース ID。
  3. Gemini Enterprise に A2A エージェントを登録する(A2A 経由のカスタム エージェント)または Agent Registry から A2A エージェントをインポートする(Agent Runtime 経由のカスタム エージェント)を使用して、デプロイされた A2A エージェントを Gemini Enterprise に登録します。エージェントは Agent Runtime でホストされるため、Gemini Enterprise で https://www.googleapis.com/auth/cloud-platform スコープを使用して OAuth 2.0 認可リソースを構成し、Gemini Enterprise が Agent Runtime エンドポイントを呼び出せるようにします。

A2A エージェント エンドポイントを保護する

Gemini Enterprise が A2A エージェントに送信する認証ヘッダーについては、Gemini Enterprise がエージェントを認証する方法をご覧ください。エージェント エンドポイントまたはその前の API ゲートウェイを保護する場合は、次の点を考慮してください。

  • エージェント カードのセキュリティ スキーム: Gemini Enterprise は、エージェント カードの securitySchemes フィールドと security フィールドを使用してエージェントを認証しません。
  • API キーとカスタム ヘッダー: Gemini Enterprise は apiKey セキュリティ スキームをサポートしていません。また、エージェントに送信するリクエストに静的 API キーやその他のカスタム ヘッダー値を追加する方法も提供していません。
  • サービス エージェント ID トークン: Gemini Enterprise は、エージェント URL が .run.app で終わるデフォルトの Cloud Run URL の場合にのみ、X-Serverless-Authorization ヘッダーを送信します。エージェント URL でカスタム ドメイン、ロードバランサ、または API ゲートウェイを使用している場合、Gemini Enterprise はこのヘッダーを送信しません。
  • エンドユーザー トークン: エージェントに OAuth 2.0 を構成すると、Gemini Enterprise は OAuth 2.0 プロバイダからエンドユーザーのトークンを Authorization ヘッダーで送信します。

Apigee で Agent Endpoint を保護する

Apigee API プロキシを介して A2A エージェントを公開すると、プロキシは Authorization ヘッダーでエンドユーザー トークンを受け取りますが、X-Serverless-Authorization ヘッダーは受け取りません。プロキシを保護するには、次の操作を行います。

  1. エージェントのエンドユーザー認可用の OAuth 2.0 を構成し( Google Cloud OAuth 2.0 クライアント ID またはサードパーティの OAuth 2.0 プロバイダを使用)、エージェントを登録するときに、これらの OAuth 2.0 の詳細を指定します。Apigee API プロキシを保護する場合は、OAuth 2.0 を構成する必要があります。登録時に承認ステップをスキップしないでください。
  2. エージェント カードで、url を Apigee API プロキシの URL に設定します。
  3. API プロキシで、リクエストをエージェントに転送する前に、Authorization ヘッダーのエンドユーザー トークンを検証します。OAuth 2.0 プロバイダが発行するトークン形式に基づいて Apigee ポリシーを選択します。
    • 署名付き JWT アクセス トークンを発行するサードパーティの OAuth 2.0 プロバイダ: VerifyJWT ポリシーを使用して、プロバイダの公開 JSON Web Key Set(JWKS)URI に対してトークン署名を検証し、発行者(iss)とオーディエンス(aud)のクレームを検証します。
    • Google OAuth 2.0(accounts.google.com): Google OAuth 2.0 アクセス トークン(ya29...)は、署名付き JWT ではなく、不透明なトークンです。ServiceCallout ポリシーを使用して https://oauth2.googleapis.com/tokeninfo を呼び出し、オーディエンス(aud)フィールドと scope フィールドを検証します。

Gemini Enterprise に A2A エージェントを登録する

Google Cloud コンソールまたは REST API を使用して、A2A エージェントを Gemini Enterprise に登録できます。これにより、Gemini Enterprise app 内のユーザーがエージェントを利用できるようになります。

コンソール

Google Cloud コンソールを使用して A2A エージェントを登録する手順は次のとおりです。

  1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

    Gemini Enterprise

  2. エージェントを登録するアプリの名前をクリックします。

  3. [エージェント] > [エージェントの追加] をクリックします。

  4. [エージェント タイプの選択] セクションで、[A2A によるカスタム エージェント] の [追加] をクリックします。

  5. [エージェント カードの JSON] フィールドに、エージェント カードの詳細を JSON 形式で入力します。 使用可能なフィールドの完全なリストについては、Agent2Agent(A2A)プロトコルの公式仕様をご覧ください。 次の例では、必須フィールドのみを使用しています。

    例:

    {
      "protocolVersion": "0.3",
      "name": "Hello World Agent",
      "description": "Just a hello world agent",
      "url": "https://example.com/myagent",
      "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
      "version": "1.0.0",
      "capabilities": {
      },
      "skills": [
        {
          "id": "data-analysis",
          "name": "Data Analysis",
          "description": "Data analysis",
          "tags": []
        }
      ],
      "defaultInputModes": [
        "text/plain"
      ],
      "defaultOutputModes": [
        "text/plain"
      ]
    }
    
  6. [エージェントの詳細をプレビュー] > [次へ] をクリックします。

  7. 次のいずれかの方法で設定を完了します。

    • エージェントがユーザーに代わって Google Cloud リソースにアクセスすることを許可せず、Agent Endpoint に Authorization ヘッダーが必要ない場合は、[スキップして終了] をクリックしてこの手順をスキップします。
    • 認証マネージャーで 3LO を構成している場合は、[スキップして終了] をクリックすると、エージェントがアクセスを動的にリクエストします。
    • 認証マネージャーで 3LO を構成していない場合、またはエージェント エンドポイントに Authorization ヘッダーが必要な場合(Apigee API プロキシを保護する場合など)は、次の操作を行います。

      1. エンドユーザー認可用の OAuth 2.0 を構成する(省略可)で生成したクライアント ID、クライアント シークレット、認可 URI、トークン URI を入力します。

      2. [スコープ] を入力します。

      3. [完了] をクリックします。

REST

REST API を使用して A2A エージェントを登録する手順は次のとおりです。

Gemini Enterprise に認可リソースを追加する(省略可)

エージェントがユーザーに代わって Google Cloud リソースにアクセスする必要がある場合は、次のコマンドを実行して、認可の詳細を構成する(省略可)セクションで作成した認可リソースを Gemini Enterprise に登録します。

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

次のように置き換えます。

  • PROJECT_ID: 実際のプロジェクトの ID。
  • PROJECT_NUMBER: Google Cloud プロジェクトの数。
  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • LOCATION: データストアのマルチリージョン(global、us、eu)
  • AUTH_ID: 認可リソースの ID。任意に定義する英数字の ID です。この ID は、OAuth サポートが必要なエージェントを登録するときに参照する必要があります。
  • OAUTH_CLIENT_ID: OAuth 認証情報を作成したときに取得した OAuth 2.0 クライアント ID。
  • OAUTH_CLIENT_SECRET: OAuth 認証情報を作成したときに取得した OAuth 2.0 クライアント シークレット。
  • OAUTH_AUTH_URI: 認可 URI。アプリを認可するには、OAuth 認証情報の JSON ファイルの詳細を使用して、特定の認可 URI を作成します。次のテンプレートをコピーし、プレースホルダを独自の値に置き換えます。

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    
    • YOUR_CUSTOM_SCOPES: 必要なスコープを追加できます。たとえば、次の OAuth スコープ文字列は、Google ドライブと Google ドキュメントへの読み取り専用アクセスをリクエストします。

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
      
  • OAUTH_TOKEN_URI: OAuth 認証情報の作成時に取得したトークン URI。

認可 URI パラメータの詳細。

URI が正しく機能することを確認するには、次のフィールドを確認します。

パラメータ 値またはアクション
client_id ダウンロードした JSON に含まれている client_id に置き換えます。
redirect_uri 変更しないでください。https://vertexaisearch.cloud.google.com/static/oauth/oauth.html を指定します。
scope

アプリがユーザーに代わってアクセスする必要がある Google API スコープを一覧表示します。たとえば、BigQuery へのアクセス権を付与するにはスコープ https://www.googleapis.com/auth/bigquery を使用し、Google ドキュメントへの読み取り専用アクセス権を付与するには https://www.googleapis.com/auth/documents.readonly を使用します。

複数のスコープを使用する場合は、スペースで区切ります。スペースは URL では %20 になります。

include_granted_scopes true を指定します。
response_type 認証コードを受け取るには、code である必要があります。
access_type 更新トークンを確実に受け取るには、offline に設定します。
prompt consent に設定すると、ユーザーに常に同意画面が表示されます。

A2A エージェントを登録する

Gemini Enterprise でエージェントを作成して登録するには、agents.create メソッドを使用します。次のコマンドでは、必須フィールドのみを使用します。使用可能なフィールドの完全なリストについては、Agent2Agent(A2A)プロトコルの公式仕様をご覧ください。

次のコマンドを実行して、Gemini Enterprise に A2A エージェントを登録します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

次のように置き換えます。

  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • LOCATION: データストアのマルチリージョン(global、us、eu)
  • PROJECT_ID: 実際のプロジェクトの ID。
  • APP_ID: エージェントを登録するアプリの ID。
  • AGENT_NAME: エージェントの固有識別子。
  • AGENT_DISPLAY_NAME: ウェブアプリに表示されるエージェントの名前。
  • AGENT_DESCRIPTION: エージェントが実行できることの説明。
  • PROTOCOLVERSION: エージェントがサポートする A2A プロトコルのバージョン。サポートされているバージョンの詳細については、A2A リリースノートをご覧ください。
  • AGENT_URL: エージェントのエンドポイント URL。
  • AGENT_VERSION: エージェントのバージョン。
  • INPUT_MODE: デフォルトの入力メディアタイプ。たとえば、application/json や text/plain です。
  • OUTPUT_MODE: デフォルトの出力メディアタイプ。たとえば、text/plain" や image/png です。
  • CAPABILITIES: サポートされている A2A 機能を含む JSON オブジェクト。たとえば、\"streaming\": true や \"pushNotifications\": false です。
  • SKILLS: エージェントが提供する AgentSkill オブジェクトのリスト。
  • authorizationConfig: 認可の詳細情報を取得し、エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにする場合は、JSON リソースに authorization_config フィールドを追加します。

エージェントの作成者と連絡先情報を表示する(省略可)

デフォルトでは、登録した A2A エージェントの作成者は Gemini Enterprise に表示されません。エージェントの作成者と、ユーザーがエージェントについて問い合わせる相手を表示するには、エージェントの登録または更新に使用するエージェント カード JSON の capabilities.extensions フィールドに、エージェント メタデータ拡張機能を追加します。

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
        "params": {
          "authorName": "Example Team",
          "contactEmail": "agent-support@example.com"
        }
      }
    ]
  }
}

登録の例の他のエージェント カード フィールドを capabilities とともに保持します。REST API では、拡張子はエスケープされた jsonAgentCard 文字列の一部です。

params フィールドは、次の値をサポートしています。どちらも省略可能です。

パラメータ 説明
authorName エージェントを構築した個人、チーム、または会社の名前。エージェント ギャラリーでは、エージェントのカードに「AUTHOR_NAME 作成」と表示され、[エージェント情報] ダイアログには「作成者」と表示されます。ギャラリーにこの名前が表示されるのは、エージェントに独自のオーナー名がない場合のみです。「Google」という単語を含む名前は、Google が作成したエージェントと間違われないように表示されません。
contactEmail ユーザーが作成者に連絡できるメールアドレス。[Agent Info] ダイアログには、[Contact] として表示されます。

各値は 256 文字以下の文字列にする必要があります。contactEmail は有効なメールアドレスにする必要があります。Gemini Enterprise は、これらの要件を満たさない値を無視します。Gemini Enterprise は、作成者の名前や連絡先メールアドレスを確認しません。

アプリに接続されているエージェントを一覧表示する

次のコードサンプルは、アプリに接続されているすべてのエージェントの詳細を取得する方法を示したものです。

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

変数部分は、次のように実際の値に置き換えます。

  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • LOCATION: アプリのマルチリージョン(global、us、eu)。
  • APP_ID: Gemini Enterprise app の ID。

エージェントが Google によって事前構築されていない場合、レスポンスの最初の数行に name フィールドが含まれます。このフィールドの値には、パスの末尾にエージェント ID が含まれます。たとえば、次のレスポンスでは、エージェント ID は 12345678901234567890 です。

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

A2A エージェントの詳細を確認する

次のコードサンプルが示すのは、Gemini Enterprise に登録されたエージェントの詳細を取得する方法です。

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

変数部分は、次のように実際の値に置き換えます。

  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • LOCATION: アプリのマルチリージョン(global、us、eu)。
  • APP_ID: Gemini Enterprise app の ID。
  • AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。

A2A エージェントを更新する

Gemini Enterprise に登録されている既存の A2A エージェントの詳細は、 Google Cloud コンソールまたは REST API を使用して変更できます。

コンソール

Google Cloud コンソールを使用して A2A エージェントを更新する手順は次のとおりです。

  1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

    Gemini Enterprise

  2. 更新するエージェントを含むアプリの名前をクリックします。

  3. [エージェント] をクリックします。

  4. 更新する A2A(カスタム)エージェントの名前をクリックし、[編集] をクリックします。

  5. [エージェント カードの JSON] フィールドに、エージェント カードの詳細を JSON 形式で更新します。 使用可能なフィールドの完全なリストについては、Agent2Agent(A2A)プロトコルの公式仕様をご覧ください。 次の例では、必須フィールドのみを使用しています。

    例:

    {
      "protocolVersion": "0.3",
      "name": "Hello World Agent",
      "description": "Just a hello world agent",
      "url": "https://example.com/myagent",
      "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
      "version": "1.1.0",
      "capabilities": {
      },
      "skills": [
        {
          "id": "data-analysis",
          "name": "Data Analysis",
          "description": "Data analysis",
          "tags": []
        }
      ],
      "defaultInputModes": [
        "text/plain"
      ],
      "defaultOutputModes": [
        "text/plain"
      ]
    }
    
  6. [保存] をクリックします。

REST

Gemini Enterprise に登録されている A2A エージェントの詳細を更新するには、agents.patch メソッドを使用します。次のコマンドでは、必須フィールドのみを使用します。使用可能なフィールドの完全なリストについては、Agent2Agent(A2A)プロトコルの公式仕様をご覧ください。

Gemini Enterprise で A2A エージェントを更新するには、次のコマンドを実行します。

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

次のように置き換えます。

  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • LOCATION: データストアのマルチリージョン(global、us、eu)。
  • PROJECT_ID: 実際のプロジェクトの ID。
  • APP_ID: エージェントを登録するアプリの ID。
  • AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。
  • AGENT_NAME: エージェントの固有識別子。
  • AGENT_DISPLAY_NAME: ウェブアプリに表示されるエージェントの名前。
  • AGENT_DESCRIPTION: エージェントが実行できることの説明。
  • PROTOCOLVERSION: エージェントがサポートする A2A プロトコルのバージョン。サポートされているバージョンの詳細については、A2A リリースノートをご覧ください。
  • AGENT_URL: エージェントのエンドポイント URL。
  • AGENT_VERSION: エージェントのバージョン。
  • INPUT_MODE: デフォルトの入力メディアタイプ。たとえば、application/json や text/plain です。
  • OUTPUT_MODE: デフォルトの出力メディアタイプ。たとえば、text/plain や image/png です。
  • CAPABILITIES: サポートされている A2A 機能を含む JSON オブジェクト。たとえば、\"streaming\": true や \"pushNotifications\": false です。
  • SKILLS: エージェントが提供する AgentSkill オブジェクトのリスト。
  • authorizationConfig: 認可の詳細情報を取得し、エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにする場合は、JSON リソースに authorization_config フィールドを追加します。

A2A エージェントを削除する

次のコードサンプルが示すのは、アプリに接続されているエージェントを削除する方法です。

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

変数部分は、次のように実際の値に置き換えます。

  • ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
    • 米国のマルチリージョンの場合は us
    • EU のマルチリージョンの場合は eu
    • グローバル ロケーションの場合は global
    詳細については、データストアのマルチリージョンを指定するをご覧ください。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • LOCATION: アプリのマルチリージョン(global、us、eu)
  • APP_ID: Gemini Enterprise app の ID。
  • AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。

次のステップ

  • Gemini Enterprise に登録したエージェントをウェブアプリで使用する。