Le protocole Agent2Agent (A2A) est un protocole de communication ouvert et un langage universel pour les agents. Le protocole permet aux agents de différents créateurs et plates-formes de se découvrir, de collaborer et de déléguer des tâches de manière sécurisée. Ce document explique comment les administrateurs Gemini Enterprise peuvent connecter à Gemini Enterprise des agents créés à l'aide d'A2A et hébergés sur n'importe quelle plate-forme, afin de les mettre à la disposition des utilisateurs dans l'application Web Gemini Enterprise.
Avant de commencer
Assurez-vous de disposer des éléments suivants :
Le rôle Administrateur Gemini Enterprise.
Activez l'API Discovery Engine. Pour activer l'API Discovery Engine pour le projet Google Cloud, accédez à la page API Discovery Engine dans la console Google Cloud .
Une application Gemini Enterprise existante. Pour créer une application, consultez Créer une application.
Agent qui utilise le protocole A2A.
Gemini Enterprise est compatible avec le mécanisme de streaming A2A v0.3.
Si vous utilisez A2A v1.0.0 ou une version ultérieure, utilisez les packages de compatibilité fournis par le SDK pour vous assurer que votre agent fonctionne avec l'ancien mécanisme (par exemple, le package
a2acompat/a2av0pour Go ou le packagea2a.compat.v0_3pour Python).Si votre agent A2A est hébergé sur Cloud Run, utilise directement une URL
.run.apppar défaut et nécessite une authentification, attribuez le rôle de demandeur Cloud Run (roles/run.invoker) à l'agent de service Discovery Engine (cela ne s'applique pas lorsque Cloud Run se trouve derrière Apigee, un équilibreur de charge ou un domaine personnalisé) :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"Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.PROJECT_NUMBER: numéro de votre projet Google Cloud .
Configurer l'authentification et l'autorisation
En fonction de l'environnement d'hébergement de votre agent et de vos exigences de sécurité, vous pouvez configurer la manière dont Gemini Enterprise s'authentifie auprès de votre agent, la manière dont votre agent accède aux ressources et outils en aval au nom de l'utilisateur final, et la manière de sécuriser le point de terminaison de votre agent :
- Comment Gemini Enterprise s'authentifie auprès de votre agent : découvrez comment Gemini Enterprise envoie des en-têtes IAM de service à service et OAuth 2.0 d'utilisateur final lorsqu'il appelle le point de terminaison de votre agent A2A.
- Configurer OAuth 2.0 pour l'autorisation de l'utilisateur final : configurez une ressource d'autorisation OAuth 2.0 dans Gemini Enterprise afin que Gemini Enterprise acquière un jeton d'utilisateur final et l'envoie dans l'en-tête
Authorizationlors de l'appel de votre agent (par exemple, pour appeler un agent A2A hébergé sur Agent Runtime sur la plate-forme d'agents Gemini Enterprise ou transmettre un jeton utilisateur directement à votre conteneur d'agent). - Configurer l'authentification OAuth à trois acteurs avec le gestionnaire d'authentification Agent Identity : configurez un fournisseur d'authentification OAuth à trois acteurs (3LO) dans le gestionnaire d'authentification Agent Identity afin que votre agent A2A puisse demander des jetons délégués par l'utilisateur à la demande pour des outils spécifiques, tels que des serveurs MCP (Model Context Protocol) ou des API tierces.
Comment Gemini Enterprise s'authentifie auprès de votre agent
Lorsque Gemini Enterprise appelle un agent A2A, il peut envoyer des données d'authentification et d'autorisation dans les en-têtes de requête, en fonction de votre configuration d'hébergement et de sécurité :
| En-tête | Description |
|---|---|
X-Serverless-Authorization |
Authentification IAM de service à service (pour Cloud Run). Si votre agent A2A est hébergé sur Cloud Run et que son URL est une URL Lorsque Gemini Enterprise appelle directement une URL |
Authorization |
Autorisation OAuth 2.0 de l'utilisateur final (pour l'appel de point de terminaison, le contexte utilisateur et l'accès à l'API). Si vous configurez des identifiants OAuth 2.0 pour votre agent A2A (voir Configurer OAuth 2.0 pour l'autorisation de l'utilisateur final), Gemini Enterprise acquiert un jeton d'accès ou un jeton d'ID OAuth 2.0 au nom de l'utilisateur final connecté après qu'il a donné son consentement, et l'envoie dans l'en-tête Pour les agents hébergés sur Cloud Run, Cloud Run transfère l'en-tête |
Configurer OAuth 2.0 pour l'autorisation de l'utilisateur final (facultatif)
Pour les agents A2A, configurez des identifiants OAuth 2.0 dans Gemini Enterprise si votre point de terminaison d'agent nécessite un jeton OAuth 2.0 d'utilisateur final dans l'en-tête Authorization (par exemple, pour appeler un agent A2A hébergé sur Agent Runtime ou pour transmettre un jeton utilisateur directement à votre conteneur d'agent). Pour en savoir plus sur le fonctionnement des en-têtes d'authentification et d'autorisation, consultez Comment Gemini Enterprise s'authentifie auprès de votre agent.
Si votre agent A2A utilise le gestionnaire d'authentification Agent Identity pour l'authentification OAuth en trois étapes au niveau de l'outil (par exemple, pour accéder aux serveurs MCP ou aux API tierces au nom de l'utilisateur), consultez Configurer l'authentification OAuth en trois étapes avec le gestionnaire d'authentification Agent Identity.
Pour créer un ID client OAuth, procédez comme suit :
Dans la console Google Cloud , sur la page API et services, accédez à la page Identifiants.
-
Sélectionnez le projet Google Cloud , qui contient la source de données à laquelle vous souhaitez que l'agent accède. Par exemple, sélectionnez le projet contenant l'ensemble de données BigQuery que l'agent doit interroger.
Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth.
Dans Type d'application, sélectionnez Application Web.
Dans la section URI de redirection autorisés, ajoutez les URI suivants :
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
Cliquez sur Créer.
Dans le panneau Client OAuth créé, cliquez sur Télécharger au format JSON. Le fichier JSON téléchargé inclut les éléments
Client ID,Authorization URI,Token URIetClient secretdu projetGoogle Cloud sélectionné. Vous aurez besoin de ces informations pour créer une ressource d'autorisation.
Configurer l'authentification OAuth en trois étapes avec le gestionnaire d'authentification Agent Identity (facultatif)
Si votre agent A2A est conçu avec l'Agent Development Kit (ADK) et utilise le gestionnaire d'authentification Agent Identity pour l'authentification OAuth à trois étapes (3LO), il peut s'authentifier auprès des serveurs MCP, Google Cloudservices ou API tierces en aval au nom de l'utilisateur connecté.
Lorsqu'un outil de votre agent A2A nécessite le consentement de l'utilisateur, Gemini Enterprise gère automatiquement le workflow 3LO côté client :
- Invite de consentement : lorsque votre agent renvoie une interruption d'outil
adk_request_credential(TASK_STATE_AUTH_REQUIRED), l'application Web Gemini Enterprise invite l'utilisateur à se connecter et ouvre l'URI d'autorisation du fournisseur d'authentification. - Validation de l'utilisateur et stockage du jeton : une fois que l'utilisateur a donné son consentement, le fournisseur d'authentification le redirige vers le point de terminaison de validation Gemini Enterprise (
https://vertexaisearch.cloud.google.com/validateUserId). Gemini Enterprise valide l'état de la session et finalise les identifiants avec le gestionnaire d'authentification Agent Identity. - Reprise de la conversation : Gemini Enterprise renvoie la réponse
adk_request_credentialcomplétée à votre agent A2A, qui récupère le jeton d'accès de l'utilisateur auprès du fournisseur d'authentification et appelle l'outil.
Étant donné que Gemini Enterprise gère l'invite de consentement, le point de terminaison de validation et la reprise de la conversation, vous n'avez pas besoin d'implémenter une application d'interface utilisateur côté client personnalisée.
Étape 1 : Configurez un fournisseur d'authentification OAuth en trois étapes
Suivez les étapes de la section S'authentifier à l'aide d'OAuth à trois acteurs avec le gestionnaire d'authentification pour activer l'API Agent Identity (agentidentity.googleapis.com), configurer votre application cliente OAuth et créer un fournisseur d'authentification OAuth à trois acteurs.
Lorsque vous configurez votre client OAuth et votre fournisseur d'authentification pour les utiliser avec Gemini Enterprise, incluez les paramètres suivants :
URI de redirection autorisés : dans la configuration de votre client OAuth, ajoutez l'URI de redirection de rappel du fournisseur d'authentification :
https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallbackSi vous réutilisez le même client OAuth pour votre ressource d'autorisation d'agent Gemini Enterprise (par exemple, pour permettre à Gemini Enterprise d'appeler un agent A2A hébergé sur Agent Runtime), incluez également l'URI de redirection Gemini Enterprise (
https://vertexaisearch.cloud.google.com/oauth-redirect).URI de continuation : définissez l'URI de continuation (soit comme URI de continuation par défaut sur le fournisseur d'authentification, soit comme
continue_uridans le code de votre agent) sur le point de terminaison de validation Gemini Enterprise :https://vertexaisearch.cloud.google.com/validateUserId
Étape 2 : Configurer le code de votre agent A2A
Lorsque vous créez un agent ADK et l'encapsulez avec A2aAgent pour le déployer sur Agent Runtime, assurez-vous que le code de votre agent répond aux exigences suivantes :
- Installez les versions de package requises : incluez
a2a-sdk[http-server]>=1.0.0,google-cloud-aiplatform[agent_engines,adk]>=1.156.0etgoogle-adk[a2a,agent-identity,mcp]>2.7.1dans vos exigences de déploiement. - Définissez
continue_urisur Gemini Enterprise : définissezcontinue_urisur"https://vertexaisearch.cloud.google.com/validateUserId"dansGcpAuthProviderSchemeouAgentRegistry.get_mcp_toolset(sauf si vous l'avez configuré comme URI de continuation par défaut sur le fournisseur d'authentification). - Enregistrez
GcpAuthProviderdans la fonction de compilateur de l'exécuteur : appelezCredentialManager.register_auth_provider(GcpAuthProvider())dans la fonction qui compileRunnerdans le processus de nœud de calcul du conteneur déployé, plutôt qu'uniquement au niveau supérieur du module. - Utilisez le
A2aAgentExecutorintégré : transmettezA2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) àA2aAgent. N'utilisez pas deAgentExecutorpersonnalisé qui ne vérifie queevent.is_final_response(), carA2aAgentExecutorest requis pour convertir les interruptionsadk_request_credentialen état de tâche A2ATASK_STATE_AUTH_REQUIRED. - Incluez la version
0.3du protocole A2A surAgentCard: ajoutez unAgentInterfaceavecprotocol_version=PROTOCOL_VERSION_0_3etprotocol_binding=TransportProtocol.HTTP_JSONàagent_card.supported_interfaces, en plus de l'interface1.0par défaut, afin que Gemini Enterprise puisse communiquer avec votre agent via les routes A2A v0.3.
ADK + A2A
L'exemple suivant configure un agent A2A ADK qui utilise GcpAuthProviderScheme avec McpToolset (ou AgentRegistry.get_mcp_toolset) pour s'authentifier auprès d'un serveur MCP au nom de l'utilisateur :
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
L'exemple suivant configure un agent ADK A2A qui utilise AuthenticatedFunctionTool avec GcpAuthProviderScheme pour appeler une API REST tierce ou Google Cloudau nom de l'utilisateur :
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), )
Étape 3 : Déployer l'agent A2A avec l'identité de l'agent et accorder l'accès
Déployez votre
A2aAgentsur Agent Runtime avecidentity_type=types.IdentityType.AGENT_IDENTITY: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", ], }, )Une fois le déploiement terminé, attribuez le rôle Utilisateur de l'identité de l'agent (
roles/agentidentity.user) sur le fournisseur d'authentification au compte principal SPIFFE de votre agent déployé :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>"Remplacez les éléments suivants :
AUTH_PROVIDER_NAME: nom de votre fournisseur d'authentification.PROJECT_ID: par l'ID du projet.LOCATION: région où votre fournisseur d'authentification et votre agent sont déployés (par exemple,us-central1).ORGANIZATION_ID: ID de votre organisation Google Cloud.PROJECT_NUMBER: numéro de votre projet Google Cloud .ENGINE_ID: ID de ressource de votre agentreasoningEnginesdéployé.
Enregistrez l'agent A2A déployé auprès de Gemini Enterprise à l'aide de l'option Enregistrer un agent A2A auprès de Gemini Enterprise (Agent personnalisé via A2A) ou Importer des agents A2A depuis Agent Registry (Agent personnalisé via Agent Runtime). Comme l'agent est hébergé sur Agent Runtime, configurez une ressource d'autorisation OAuth 2.0 dans Gemini Enterprise avec le champ d'application
https://www.googleapis.com/auth/cloud-platformafin que Gemini Enterprise puisse appeler le point de terminaison Agent Runtime.
Sécuriser le point de terminaison de votre agent A2A
Pour connaître les en-têtes d'authentification que Gemini Enterprise envoie à votre agent A2A, consultez Comment Gemini Enterprise s'authentifie auprès de votre agent. Lorsque vous sécurisez votre point de terminaison d'agent ou une passerelle API devant celui-ci, tenez compte des points suivants :
- Schémas de sécurité de la fiche d'agent : Gemini Enterprise n'utilise pas les champs
securitySchemesetsecurityde votre fiche d'agent pour s'authentifier auprès de votre agent. - Clés API et en-têtes personnalisés : Gemini Enterprise n'est pas compatible avec le schéma de sécurité
apiKeyet ne permet pas d'ajouter des clés API statiques ou d'autres valeurs d'en-tête personnalisées aux requêtes qu'il envoie à votre agent. - Jeton d'ID de l'agent de service : Gemini Enterprise n'envoie l'en-tête
X-Serverless-Authorizationque lorsque l'URL de votre agent est une URL Cloud Run par défaut se terminant par.run.app. Si l'URL de votre agent utilise un domaine personnalisé, un équilibreur de charge ou une API Gateway, Gemini Enterprise n'envoie pas cet en-tête. - Jeton de l'utilisateur final : si vous configurez OAuth 2.0 pour votre agent, Gemini Enterprise envoie le jeton de l'utilisateur final depuis votre fournisseur OAuth 2.0 dans l'en-tête
Authorization.
Sécuriser un point de terminaison d'agent avec Apigee
Si vous exposez votre agent A2A via un proxy d'API Apigee, le proxy reçoit le jeton de l'utilisateur final dans l'en-tête Authorization, mais ne reçoit pas l'en-tête X-Serverless-Authorization. Pour sécuriser le proxy, procédez comme suit :
- Configurez OAuth 2.0 pour l'autorisation de l'utilisateur final pour votre agent (à l'aide d'un ID client OAuth 2.0 Google Cloud ou d'un fournisseur OAuth 2.0 tiers), et fournissez ces informations OAuth 2.0 lorsque vous enregistrez l'agent. La configuration d'OAuth 2.0 est requise pour sécuriser un proxy d'API Apigee. Ne sautez pas l'étape d'autorisation lors de l'enregistrement.
- Dans votre fiche d'agent, définissez
urlsur l'URL de votre proxy d'API Apigee. - Dans le proxy d'API, validez le jeton de l'utilisateur final dans l'en-tête
Authorizationavant de transférer la requête à votre agent. Choisissez la règle Apigee en fonction du format de jeton émis par votre fournisseur OAuth 2.0 :- Fournisseurs OAuth 2.0 tiers qui émettent des jetons d'accès JWT signés : utilisez la stratégie VerifyJWT pour vérifier la signature du jeton par rapport à l'URI JWKS (JSON Web Key Set) public de votre fournisseur et valider les revendications de l'émetteur (
iss) et de l'audience (aud). - Google OAuth 2.0 (
accounts.google.com) : les jetons d'accès Google OAuth 2.0 (ya29...) sont des jetons opaques plutôt que des jetons JWT signés. Utilisez une règle ServiceCallout pour appelerhttps://oauth2.googleapis.com/tokeninfoet vérifier les champs d'audience (aud) etscope.
- Fournisseurs OAuth 2.0 tiers qui émettent des jetons d'accès JWT signés : utilisez la stratégie VerifyJWT pour vérifier la signature du jeton par rapport à l'URI JWKS (JSON Web Key Set) public de votre fournisseur et valider les revendications de l'émetteur (
Enregistrer un agent A2A auprès de Gemini Enterprise
Vous pouvez enregistrer votre agent A2A auprès de Gemini Enterprise à l'aide de la consoleGoogle Cloud ou de l'API REST. L'agent est ainsi disponible pour les utilisateurs dans une application Gemini Enterprise.
Console
Pour enregistrer un agent A2A à l'aide de la console Google Cloud , procédez comme suit :
Dans la console Google Cloud , accédez à la page Gemini Enterprise.
Cliquez sur le nom de l'application auprès de laquelle vous souhaitez enregistrer l'agent.
Cliquez sur Agents > Ajouter des agents.
Dans la section Choisir un type d'agent, cliquez sur Ajouter pour Agent personnalisé via A2A.
Dans le champ Agent card JSON (JSON de la fiche de l'agent), saisissez les détails de la fiche de l'agent au format JSON. Pour obtenir la liste complète des champs disponibles, consultez la spécification officielle du protocole Agent2Agent (A2A). L'exemple suivant n'utilise que les champs obligatoires.
Exemple :
{ "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" ] }Cliquez sur Prévisualiser les détails de l'agent > Suivant.
Terminez la configuration à l'aide de l'une des méthodes suivantes :
- Si vous ne souhaitez pas que l'agent accède aux ressources Google Cloud en votre nom et que votre point de terminaison d'agent ne nécessite pas d'en-tête
Authorization, cliquez sur Ignorer et terminer pour ignorer cette étape. - Si vous avez configuré 3LO avec le gestionnaire d'authentification, cliquez sur Ignorer et terminer. L'agent demande l'accès de manière dynamique.
Si vous n'avez pas configuré 3LO avec le gestionnaire d'authentification ou si votre point de terminaison d'agent nécessite un en-tête
Authorization(par exemple, lors de la sécurisation d'un proxy d'API Apigee), procédez comme suit :Saisissez l'ID client, le code secret du client, l'URI d'autorisation et l'URI du jeton que vous avez générés dans Configurer OAuth 2.0 pour l'autorisation de l'utilisateur final (facultatif).
Saisissez les champs d'application.
Cliquez sur Terminer.
- Si vous ne souhaitez pas que l'agent accède aux ressources Google Cloud en votre nom et que votre point de terminaison d'agent ne nécessite pas d'en-tête
REST
Pour enregistrer un agent A2A à l'aide de l'API REST, procédez comme suit :
Ajouter la ressource d'autorisation à Gemini Enterprise (facultatif)
Si l'agent doit accéder aux ressources Google Cloud au nom d'un utilisateur, exécutez la commande suivante pour enregistrer la ressource d'autorisation que vous avez créée dans la section Configurer les détails d'autorisation (facultatif) avec 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"
}
}'
Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.PROJECT_NUMBER: numéro de votre projet Google Cloud .ENDPOINT_LOCATION: emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
LOCATION: emplacement multirégional de votre data store :global,usoueuAUTH_ID: ID de la ressource d'autorisation. Il s'agit d'un ID alphanumérique arbitraire que vous définissez. Vous devrez référencer cet ID ultérieurement lors de l'enregistrement d'un agent nécessitant la compatibilité avec OAuth.OAUTH_CLIENT_ID: identifiant client OAuth 2.0 que vous avez obtenu lors de la création des identifiants OAuth.OAUTH_CLIENT_SECRET: code secret du client OAuth 2.0 que vous avez obtenu lors de la création des identifiants OAuth.OAUTH_AUTH_URI: URI d'autorisation. Pour autoriser votre application, créez un URI d'autorisation spécifique à l'aide des détails de votre fichier JSON d'identifiants OAuth. Copiez le modèle suivant et remplacez les espaces réservés par vos valeurs spécifiques.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: vous pouvez ajouter les champs d'application dont vous avez besoin. Par exemple, la chaîne de champ d'application OAuth suivante demande un accès en lecture seule à Google Drive et Google Docs.scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
OAUTH_TOKEN_URI: URI du jeton que vous avez obtenu lors de la création des identifiants OAuth.
En savoir plus sur les paramètres d'URI d'autorisation.
Pour vous assurer que l'URI fonctionne correctement, vérifiez les champs suivants :
| Paramètre | Valeur ou action |
|---|---|
client_id |
Remplacez par la valeur client_id qui se trouve dans le fichier JSON téléchargé. |
redirect_uri |
Ne pas modifier. Doit être https://vertexaisearch.cloud.google.com/static/oauth/oauth.html. |
scope |
Répertoriez les champs d'application de l'API Google auxquels votre application doit accéder au nom de l'utilisateur. Par exemple, pour accorder l'accès à BigQuery, utilisez le champ d'application Si vous utilisez plusieurs champs d'application, séparez-les par un espace, qui devient |
include_granted_scopes |
doit être true |
response_type |
Vous devez être code pour recevoir un code d'autorisation. |
access_type |
Définissez cette valeur sur offline pour vous assurer de recevoir un jeton d'actualisation. |
prompt |
Définissez la valeur sur consent pour vous assurer qu'un écran de consentement s'affiche toujours pour l'utilisateur. |
Enregistrer votre agent A2A
Pour créer et enregistrer un agent avec Gemini Enterprise, utilisez la méthode agents.create. La commande suivante n'utilise que les champs obligatoires. Pour obtenir la liste complète des champs disponibles, consultez la spécification officielle du protocole Agent2Agent (A2A).
Exécutez cette commande pour enregistrer votre agent A2A auprès de Gemini Enterprise :
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"
}
}
'
Remplacez les éléments suivants :
ENDPOINT_LOCATION: emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
LOCATION: emplacement multirégional de votre data store :global,usoueuPROJECT_ID: par l'ID du projet.APP_ID: ID de l'application auprès de laquelle vous souhaitez enregistrer l'agent.AGENT_NAME: identifiant unique de l'agent.AGENT_DISPLAY_NAME: nom de l'agent affiché dans l'application Web.AGENT_DESCRIPTION: description de ce que l'agent peut faire.PROTOCOLVERSION: version du protocole A2A compatible avec l'agent. Pour en savoir plus sur les versions compatibles, consultez les notes de version d'A2A.AGENT_URL: URL du point de terminaison de l'agent.AGENT_VERSION: version de l'agent.INPUT_MODE: type de média d'entrée par défaut. Par exemple,application/jsonoutext/plain.OUTPUT_MODE: type de média de sortie par défaut. Par exemple,text/plain"ouimage/png.CAPABILITIES: objet JSON contenant les fonctionnalités A2A compatibles. Par exemple,\"streaming\": trueou\"pushNotifications\": false.SKILLS: liste des objetsAgentSkillproposés par l'agent.authorizationConfig: si vous avez obtenu les détails d'autorisation et que vous souhaitez que l'agent accède aux ressources Google Cloud au nom de l'utilisateur, ajoutez le champauthorization_configà votre ressource JSON.AUTH_ID: valeur que vous avez utilisée pour AUTH_ID dans la section Ajouter une ressource d'autorisation à Gemini Enterprise.
Afficher l'auteur et les coordonnées d'un agent (facultatif)
Par défaut, un agent A2A que vous enregistrez n'affiche aucun auteur dans Gemini Enterprise. Pour indiquer qui a créé l'agent et qui les utilisateurs peuvent contacter à son sujet, ajoutez l'extension de métadonnées de l'agent au champ capabilities.extensions du fichier JSON de la fiche de l'agent que vous utilisez pour enregistrer ou mettre à jour l'agent :
{
"capabilities": {
"extensions": [
{
"uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
"params": {
"authorName": "Example Team",
"contactEmail": "agent-support@example.com"
}
}
]
}
}
Conservez les autres champs de la fiche d'agent de l'exemple d'enregistrement avec capabilities. Dans l'API REST, l'extension fait partie de la chaîne jsonAgentCard échappée.
Le champ params accepte les valeurs suivantes : qui sont tous deux facultatifs.
| Paramètre | Description |
|---|---|
authorName |
Nom de la personne, de l'équipe ou de l'entreprise qui a créé l'agent. La galerie d'agents l'affiche sous la forme Par AUTHOR_NAME sur la fiche de l'agent, et la boîte de dialogue Informations sur l'agent l'affiche sous la forme Auteur. La galerie n'affiche ce nom que si l'agent n'a pas de nom de propriétaire qui lui est propre. Les noms contenant le mot "Google" ne sont pas affichés, afin qu'ils ne soient pas confondus avec des agents créés par Google. |
contactEmail |
Adresse e-mail à laquelle les utilisateurs peuvent contacter l'auteur. La boîte de dialogue Agent Info (Informations sur l'agent) l'affiche sous le nom Contact. |
Chaque valeur doit être une chaîne de 256 caractères au maximum, et contactEmail doit être une adresse e-mail valide. Gemini Enterprise ignore les valeurs qui ne respectent pas ces exigences. Gemini Enterprise ne valide pas le nom de l'auteur ni l'adresse e-mail de contact.
Lister les agents connectés à une application
L'exemple de code suivant montre comment obtenir les détails de tous les agents connectés à votre application :
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"
Remplacez les variables par des valeurs :
- ENDPOINT_LOCATION : emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :
uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
- PROJECT_ID : ID de votre projet Google Cloud .
- LOCATION : emplacement multirégional de votre application :
global,usoueu. - APP_ID : ID de votre application Gemini Enterprise.
Si votre agent n'est pas prédéfini par Google, la réponse inclut un champ name dans les premières lignes. La valeur de ce champ contient l'ID de l'agent à la fin du chemin d'accès. Par exemple, dans la réponse suivante, l'ID de l'agent est 12345678901234567890 :
{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}
Afficher les détails d'un agent A2A
L'exemple de code suivant montre comment récupérer les détails d'un agent enregistré auprès de 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"
Remplacez les variables par des valeurs :
- ENDPOINT_LOCATION : emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :
uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
- PROJECT_ID : ID de votre projet Google Cloud .
- LOCATION : emplacement multirégional de votre application :
global,usoueu. - APP_ID : ID de votre application Gemini Enterprise.
- AGENT_ID : ID de l'agent. Vous pouvez trouver l'ID de l'agent en répertoriant les agents connectés à votre application.
Mettre à jour un agent A2A
Vous pouvez modifier les détails d'un agent A2A existant enregistré auprès de Gemini Enterprise à l'aide de la console Google Cloud ou de l'API REST.
Console
Pour mettre à jour un agent A2A à l'aide de la console Google Cloud , procédez comme suit :
Dans la console Google Cloud , accédez à la page Gemini Enterprise.
Cliquez sur le nom de l'application qui inclut l'agent que vous souhaitez mettre à jour.
Cliquez sur Agents.
Cliquez sur le nom de l'agent A2A (personnalisé) à mettre à jour, puis sur Modifier.
Dans le champ Fiche d'agent JSON, mettez à jour les détails de la fiche d'agent au format JSON. Pour obtenir la liste complète des champs disponibles, consultez la spécification officielle du protocole Agent2Agent (A2A). L'exemple suivant n'utilise que les champs obligatoires.
Exemple :
{ "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" ] }Cliquez sur Enregistrer.
REST
Pour mettre à jour les détails d'un agent A2A enregistré auprès de Gemini Enterprise, utilisez la méthode agents.patch. La commande suivante n'utilise que les champs obligatoires. Pour obtenir la liste complète des champs disponibles, consultez la spécification officielle du protocole Agent2Agent (A2A).
Exécutez cette commande pour mettre à jour votre agent A2A avec Gemini Enterprise :
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"
}
}
'
Remplacez les éléments suivants :
ENDPOINT_LOCATION: emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
LOCATION: emplacement multirégional de votre data store :global,usoueu.PROJECT_ID: par l'ID du projet.APP_ID: ID de l'application pour laquelle vous souhaitez enregistrer l'agent.- AGENT_ID : ID de l'agent. Vous pouvez trouver l'ID de l'agent en répertoriant les agents connectés à votre application.
AGENT_NAME: identifiant unique de l'agent.AGENT_DISPLAY_NAME: nom de l'agent affiché dans l'application Web.AGENT_DESCRIPTION: description de ce que l'agent peut faire.PROTOCOLVERSION: version du protocole A2A compatible avec l'agent. Pour en savoir plus sur les versions compatibles, consultez les notes de version d'A2A.AGENT_URL: URL du point de terminaison de l'agent.AGENT_VERSION: version de l'agent.INPUT_MODE: type de média d'entrée par défaut. Par exemple,application/jsonoutext/plain.OUTPUT_MODE: type de média de sortie par défaut. Par exemple,text/plainouimage/png.CAPABILITIES: objet JSON contenant les fonctionnalités A2A compatibles. Par exemple,\"streaming\": trueou\"pushNotifications\": false.SKILLS: liste des objetsAgentSkillproposés par l'agent.authorizationConfig: si vous avez obtenu les détails d'autorisation et que vous souhaitez que l'agent accède aux ressources Google Cloud au nom de l'utilisateur, ajoutez le champauthorization_configà votre ressource JSON.AUTH_ID: valeur que vous avez utilisée pour AUTH_ID dans la section Ajouter une ressource d'autorisation à Gemini Enterprise.
Supprimer un agent A2A
L'exemple de code suivant montre comment supprimer un agent connecté à votre application :
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"
Remplacez les variables par des valeurs :
- ENDPOINT_LOCATION : emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :
uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
- PROJECT_ID : ID de votre projet Google Cloud .
- LOCATION : emplacement multirégional de votre application :
global,usoueu - APP_ID : ID de votre application Gemini Enterprise.
- AGENT_ID : ID de l'agent. Vous pouvez trouver l'ID de l'agent en répertoriant les agents connectés à votre application.
Étapes suivantes
- Utilisez l'agent que vous avez enregistré avec Gemini Enterprise sur l'application Web.