Enregistrer et gérer des agents A2A

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 .

    Accéder à l'API Discovery Engine

  • 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/a2av0 pour Go ou le package a2a.compat.v0_3 pour Python).

  • Si votre agent A2A est hébergé sur Cloud Run, utilise directement une URL .run.app par 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

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 .run.app par défaut, Gemini Enterprise génère automatiquement un jeton d'ID OIDC signé par Google pour l'agent de service Discovery Engine (service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com) avec l'URL de votre agent comme audience, et l'associe dans l'en-tête X-Serverless-Authorization. Si l'URL de votre agent utilise Apigee, un équilibreur de charge ou un domaine personnalisé, Gemini Enterprise n'envoie pas cet en-tête.

Lorsque Gemini Enterprise appelle directement une URL .run.app par défaut, l'infrastructure d'entrée Cloud Run utilise cet en-tête pour vérifier que l'agent de service dispose du rôle IAM roles/run.invoker (voir Avant de commencer) avant de transférer la requête au conteneur de votre application.

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 Authorization standard (par exemple, Bearer USER_OAUTH_TOKEN).

Pour les agents hébergés sur Cloud Run, Cloud Run transfère l'en-tête Authorization directement à votre conteneur, ce qui permet au code de votre application d'agent de lire le jeton utilisateur et d'appeler les API en aval au nom de l'utilisateur. Pour les agents A2A hébergés sur Agent Runtime, la configuration d'une ressource d'autorisation OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/cloud-platform permet à Gemini Enterprise de s'authentifier auprès du point de terminaison Agent Runtime au nom de l'utilisateur.

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 :

  1. Dans la console Google Cloud , sur la page API et services, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. 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.

  3. Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth.

  4. Dans Type d'application, sélectionnez Application Web.

  5. Dans la section URI de redirection autorisés, ajoutez les URI suivants :

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
  6. Cliquez sur Créer.

  7. 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 URI et Client secret du 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 :

  1. 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.
  2. 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.
  3. Reprise de la conversation : Gemini Enterprise renvoie la réponse adk_request_credential complé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>/oauthcallback
    

    Si 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_uri dans 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.0 et google-adk[a2a,agent-identity,mcp]>2.7.1 dans vos exigences de déploiement.
  • Définissez continue_uri sur Gemini Enterprise : définissez continue_uri sur "https://vertexaisearch.cloud.google.com/validateUserId" dans GcpAuthProviderScheme ou AgentRegistry.get_mcp_toolset (sauf si vous l'avez configuré comme URI de continuation par défaut sur le fournisseur d'authentification).
  • Enregistrez GcpAuthProvider dans la fonction de compilateur de l'exécuteur : appelez CredentialManager.register_auth_provider(GcpAuthProvider()) dans la fonction qui compile Runner dans le processus de nœud de calcul du conteneur déployé, plutôt qu'uniquement au niveau supérieur du module.
  • Utilisez le A2aAgentExecutor intégré : transmettez A2aAgentExecutor(runner=build_runner) (from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) à A2aAgent. N'utilisez pas de AgentExecutor personnalisé qui ne vérifie que event.is_final_response(), car A2aAgentExecutor est requis pour convertir les interruptions adk_request_credential en état de tâche A2A TASK_STATE_AUTH_REQUIRED.
  • Incluez la version 0.3 du protocole A2A sur AgentCard : ajoutez un AgentInterface avec protocol_version=PROTOCOL_VERSION_0_3 et protocol_binding=TransportProtocol.HTTP_JSON à agent_card.supported_interfaces, en plus de l'interface 1.0 par 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

  1. Déployez votre A2aAgent sur Agent Runtime avec identity_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",
            ],
        },
    )
    
  2. 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 agent reasoningEngines déployé.
  3. 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-platform afin 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 securitySchemes et security de 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é apiKey et 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-Authorization que 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 :

  1. 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.
  2. Dans votre fiche d'agent, définissez url sur l'URL de votre proxy d'API Apigee.
  3. Dans le proxy d'API, validez le jeton de l'utilisateur final dans l'en-tête Authorization avant 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 appeler https://oauth2.googleapis.com/tokeninfo et vérifier les champs d'audience (aud) et scope.

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 :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Cliquez sur le nom de l'application auprès de laquelle vous souhaitez enregistrer l'agent.

  3. Cliquez sur Agents > Ajouter des agents.

  4. Dans la section Choisir un type d'agent, cliquez sur Ajouter pour Agent personnalisé via A2A.

  5. 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"
      ]
    }
    
  6. Cliquez sur Prévisualiser les détails de l'agent > Suivant.

  7. 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êteAuthorization, 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 :

      1. 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).

      2. Saisissez les champs d'application.

      3. Cliquez sur Terminer.

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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • LOCATION : emplacement multirégional de votre data store : global, us ou eu
  • AUTH_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 https://www.googleapis.com/auth/bigquery, et pour l'accès en lecture seule à Google Docs, utilisez https://www.googleapis.com/auth/documents.readonly.

Si vous utilisez plusieurs champs d'application, séparez-les par un espace, qui devient %20 dans l'URL.

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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • LOCATION : emplacement multirégional de votre data store : global, us ou eu
  • PROJECT_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/json ou text/plain.
  • OUTPUT_MODE : type de média de sortie par défaut. Par exemple, text/plain" ou image/png.
  • CAPABILITIES : objet JSON contenant les fonctionnalités A2A compatibles. Par exemple, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS : liste des objets AgentSkill proposé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 champ authorization_config à votre ressource JSON.

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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement multirégional de votre application : global, us ou eu.
  • 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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement multirégional de votre application : global, us ou eu.
  • 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 :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Cliquez sur le nom de l'application qui inclut l'agent que vous souhaitez mettre à jour.

  3. Cliquez sur Agents.

  4. Cliquez sur le nom de l'agent A2A (personnalisé) à mettre à jour, puis sur Modifier.

  5. 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"
      ]
    }
    
  6. 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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • LOCATION : emplacement multirégional de votre data store : global, us ou eu.
  • 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/json ou text/plain.
  • OUTPUT_MODE : type de média de sortie par défaut. Par exemple, text/plain ou image/png.
  • CAPABILITIES : objet JSON contenant les fonctionnalités A2A compatibles. Par exemple, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS : liste des objets AgentSkill proposé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 champ authorization_config à votre ressource JSON.

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 :
    • us pour l'emplacement multirégional US
    • eu pour l'emplacement multirégional EU
    • global pour l'emplacement mondial
    Pour en savoir plus, consultez Spécifier un emplacement multirégional pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement multirégional de votre application : global, us ou eu
  • 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.