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 du protocole A2A et hébergés sur n'importe quelle plate-forme. Les utilisateurs peuvent ainsi y accéder 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 utilisant le protocole A2A.

    Gemini Enterprise est compatible avec le mécanisme de streaming A2A v0.3.

    Si vous utilisez A2A v1.0.0 ou 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).

Configurer les détails de l'autorisation (facultatif)

Pour les agents A2A, vous pouvez utiliser les identifiants OAuth 2.0 pour contrôler l'accès des utilisateurs finaux aux agents A2A. Toutefois, si l'agent s'exécute sur Cloud Run et utilise Identity and Access Management pour le contrôle des accès, les identifiants OAuth 2.0 ne sont pas nécessaires.

  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 vous souhaitez que l'agent interroge.

  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 Client ID, Authorization URI, Token URI et Client secret pour le projetGoogle Cloud sélectionné. Vous aurez besoin de ces informations pour créer une ressource d'autorisation.

Enregistrer un agent A2A avec 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 mis à la disposition des 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 JSON de la fiche de l'agent, saisissez les informations relatives à la carte 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 informations sur l'agent > Suivant.

  7. Configurez l'appareil à l'aide de l'une des méthodes suivantes :

    • Si vous souhaitez que l'agent accède aux ressources Google Cloud en votre nom, procédez comme suit :

      1. Saisissez l'ID client, le code secret du client, l'URI d'autorisation et l'URI de jeton que vous avez générés dans la section Obtenir les détails d'autorisation.

      2. Saisissez les scopes.

      3. Cliquez sur Terminer.

    • Si vous ne souhaitez pas que l'agent accède aux ressources Google Cloud en votre nom, cliquez sur Ignorer et 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 de l'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 : région multirégionale pour 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 faire référence à cet ID ultérieurement lorsque vous enregistrerez un agent nécessitant la compatibilité avec OAuth.
  • OAUTH_CLIENT_ID : identifiant client OAuth 2.0 que vous avez obtenu lorsque vous avez créé les identifiants OAuth.
  • OAUTH_CLIENT_SECRET : code secret du client OAuth 2.0 que vous avez obtenu lorsque vous avez créé les identifiants OAuth.

  • OAUTH_AUTH_URI : URI d'autorisation. Pour autoriser votre application, créez un URI d'autorisation spécifique à l'aide des informations 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 niveaux d'accès dont vous avez besoin. Par exemple, la chaîne de champ d'application OAuth suivante demande un accès en lecture seule à votre 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 lorsque vous avez créé les identifiants OAuth.

En savoir plus sur les paramètres de l'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 le client_id qui se trouve dans le fichier JSON que vous avez téléchargé.
redirect_uri Ne pas modifier Doit être https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Listez les niveaux d'accès aux API Google dont votre application a besoin pour accéder aux données au nom de l'utilisateur. Par exemple, pour accorder l'accès à BigQuery, utilisez le champ d'application https://www.googleapis.com/auth/bigquery. Pour accorder 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 avoir code pour recevoir un code d'autorisation.
access_type Définissez-le sur offline pour vous assurer de recevoir un jeton d'actualisation.
prompt Définissez cette valeur sur consent pour vous assurer que l'utilisateur voit toujours un écran de consentement.

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 avec 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 : région multirégionale pour 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 avec 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 A2A.
  • AGENT_URL : URL du point de terminaison de l'agent.
  • AGENT_VERSION : version de l'agent.
  • INPUT_MODE : type de support d'entrée par défaut. Par exemple, application/json ou text/plain.
  • OUTPUT_MODE : type de support 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 informations 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.

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 : région multirégionale pour 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 : région multirégionale pour 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 listant 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é) à modifier, puis sur Modifier.

  5. Dans le champ Carte d'agent JSON, mettez à jour les informations relatives à la carte 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 informations 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 : région multirégionale pour 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 listant 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 A2A.
  • AGENT_URL : URL du point de terminaison de l'agent.
  • AGENT_VERSION : version de l'agent.
  • INPUT_MODE : type de support d'entrée par défaut. Par exemple, application/json ou text/plain.
  • OUTPUT_MODE : type de support 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 informations 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 : région multirégionale pour 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 listant les agents connectés à votre application.

Étapes suivantes

  • Utilisez l'agent que vous avez enregistré avec Gemini Enterprise dans l'application Web.