Agent2Agent(A2A)プロトコルは、オープンな通信プロトコルであり、エージェントの共通言語です。このプロトコルにより、さまざまなビルダーやプラットフォームのエージェントが互いを検出し、コラボレーションやタスクの安全な委任を行えるようになります。このドキュメントでは、Gemini Enterprise の管理者が、A2A を使用して構築され、任意のプラットフォームにホストされているエージェントを Gemini Enterprise に接続し、Gemini Enterprise ウェブアプリでユーザーが利用できるようにする方法について説明します。
始める前に
以下のものが揃っていることを確認してください。
Discovery Engine API を有効にします。 Google Cloudプロジェクトで Discovery Engine API を有効にするには、 Google Cloud コンソールで [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.appURL を直接使用し、認証が必要な場合は、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 がデフォルトの Gemini Enterprise がデフォルトの |
Authorization |
エンドユーザーの OAuth 2.0 認可(エンドポイントの呼び出し、ユーザー コンテキスト、API アクセス用)。 A2A エージェントに OAuth 2.0 認証情報を構成すると(エンドユーザー認可に OAuth 2.0 を構成するを参照)、Gemini Enterprise は、ログインしたエンドユーザーが同意を付与した後に、そのエンドユーザーに代わって OAuth 2.0 アクセス トークンまたは ID トークンを取得し、標準の Cloud Run でホストされているエージェントの場合、Cloud Run は |
エンドユーザー認可用の 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 を作成する手順は次のとおりです。
Google Cloud コンソールの [API とサービス] ページで、[認証情報] ページに移動します。
-
エージェントにアクセスさせるデータソースを含む Google Cloud プロジェクトを選択します。たとえば、エージェントにクエリを実行させる BigQuery データセットを含むプロジェクトを選択します。
[認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
[アプリケーションの種類] で [ウェブ アプリケーション] を選択します。
[承認済みのリダイレクト URI] セクションに、次の URI を追加します。
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
[作成] をクリックします。
[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 ワークフローを自動的に管理します。
- 同意プロンプト: エージェントが
adk_request_credentialツール割り込み(TASK_STATE_AUTH_REQUIRED)を返すと、Gemini Enterprise ウェブアプリはユーザーにログインを求め、認証プロバイダから認可 URI を開きます。 - ユーザー検証とトークン ストレージ: ユーザーが同意すると、認証プロバイダは Gemini Enterprise 検証エンドポイント(
https://vertexaisearch.cloud.google.com/validateUserId)にリダイレクトします。Gemini Enterprise はセッション状態を検証し、Agent Identity Auth Manager で認証情報を確定します。 - 会話の再開: 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>/oauthcallbackGemini 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_REQUIREDA2A タスク状態に変換するには、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 エージェントをデプロイし、アクセス権を付与する
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", ], }, )デプロイが完了したら、デプロイされたエージェントの 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。
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 ヘッダーは受け取りません。プロキシを保護するには、次の操作を行います。
- エージェントのエンドユーザー認可用の OAuth 2.0 を構成し( Google Cloud OAuth 2.0 クライアント ID またはサードパーティの OAuth 2.0 プロバイダを使用)、エージェントを登録するときに、これらの OAuth 2.0 の詳細を指定します。Apigee API プロキシを保護する場合は、OAuth 2.0 を構成する必要があります。登録時に承認ステップをスキップしないでください。
- エージェント カードで、
urlを Apigee API プロキシの URL に設定します。 - 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フィールドを検証します。
- 署名付き JWT アクセス トークンを発行するサードパーティの OAuth 2.0 プロバイダ: VerifyJWT ポリシーを使用して、プロバイダの公開 JSON Web Key Set(JWKS)URI に対してトークン署名を検証し、発行者(
Gemini Enterprise に A2A エージェントを登録する
Google Cloud コンソールまたは REST API を使用して、A2A エージェントを Gemini Enterprise に登録できます。これにより、Gemini Enterprise app 内のユーザーがエージェントを利用できるようになります。
コンソール
Google Cloud コンソールを使用して A2A エージェントを登録する手順は次のとおりです。
Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
エージェントを登録するアプリの名前をクリックします。
[エージェント] > [エージェントの追加] をクリックします。
[エージェント タイプの選択] セクションで、[A2A によるカスタム エージェント] の [追加] をクリックします。
[エージェント カードの 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" ] }[エージェントの詳細をプレビュー] > [次へ] をクリックします。
次のいずれかの方法で設定を完了します。
- エージェントがユーザーに代わって Google Cloud リソースにアクセスすることを許可せず、Agent Endpoint に
Authorizationヘッダーが必要ない場合は、[スキップして終了] をクリックしてこの手順をスキップします。 - 認証マネージャーで 3LO を構成している場合は、[スキップして終了] をクリックすると、エージェントがアクセスを動的にリクエストします。
認証マネージャーで 3LO を構成していない場合、またはエージェント エンドポイントに
Authorizationヘッダーが必要な場合(Apigee API プロキシを保護する場合など)は、次の操作を行います。エンドユーザー認可用の OAuth 2.0 を構成する(省略可)で生成したクライアント ID、クライアント シークレット、認可 URI、トークン URI を入力します。
[スコープ] を入力します。
[完了] をクリックします。
- エージェントがユーザーに代わって Google Cloud リソースにアクセスすることを許可せず、Agent Endpoint に
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 へのアクセス権を付与するにはスコープ 複数のスコープを使用する場合は、スペースで区切ります。スペースは URL では |
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フィールドを追加します。AUTH_ID: Gemini Enterprise に認可リソースを追加するセクションの AUTH_ID に使用した値。
エージェントの作成者と連絡先情報を表示する(省略可)
デフォルトでは、登録した 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 エージェントを更新する手順は次のとおりです。
Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
更新するエージェントを含むアプリの名前をクリックします。
[エージェント] をクリックします。
更新する A2A(カスタム)エージェントの名前をクリックし、[編集] をクリックします。
[エージェント カードの 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" ] }[保存] をクリックします。
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フィールドを追加します。AUTH_ID: Gemini Enterprise に認可リソースを追加するセクションの AUTH_ID に使用した値。
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 に登録したエージェントをウェブアプリで使用する。