Enregistrer et gérer les agents A2A

Agent-to-Agent (A2A) est un protocole de communication ouvert et un langage universel pour les agents. Elle permet aux agents de différents compilateurs 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 associer à Gemini Enterprise des agents créés à l'aide du protocole 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 :

Configurer les informations d'autorisation

Créez des identifiants OAuth 2.0 pour que l'agent puisse accéder aux ressources Google Cloud , telles que les tables BigQuery, au nom d'un utilisateur.

Obtenir les détails de l'autorisation

Suivez ces étapes pour obtenir les détails de l'autorisation.

  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 des informations suivantes pour créer une ressource d'autorisation :

Ajouter une ressource d'autorisation à Gemini Enterprise

Exécutez la commande suivante pour enregistrer une ressource d'autorisation auprès de Gemini Enterprise :

REST

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_ID/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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.
  • ENDPOINT_LOCATION : région multirégionale pour votre requête API. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple pour votre datastore.
  • LOCATION : région multirégionale 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 que vous avez obtenu lorsque vous avez créé les identifiants OAuth. Son format est le suivant : https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  • OAUTH_TOKEN_URI : URI du jeton que vous avez obtenu lorsque vous avez créé les identifiants OAuth.

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 alors disponible pour les utilisateurs d'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 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": "v1.0",
  "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 du jeton que vous avez générés dans la section Obtenir les détails de l'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 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 : région multirégionale pour votre requête API. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple pour votre datastore.
  • LOCATION : région multirégionale 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 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.

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. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région multiple 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. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région multiple 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 JSON de la fiche de l'agent, mettez à jour les informations 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": "v3.0",
  "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. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple 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 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- : région multirégionale pour votre requête API. Attribuez l'une des valeurs suivantes :
    • us- pour la multirégion des États-Unis
    • eu- pour la multirégion de l'UE
    • global- pour l'emplacement "Global"
    Pour en savoir plus, consultez Spécifier une région multiple pour votre datastore.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région multiple 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.