Enregistrer et gérer les agents ADK hébergés sur Vertex AI Agent Engine

Cette page explique comment les administrateurs Gemini Enterprise peuvent enregistrer des agents Agent Development Kit (ADK) hébergés sur Vertex AI Agent Engine afin de les rendre disponibles pour les utilisateurs de l'application Web Gemini Enterprise.

Avant de commencer

Assurez-vous de disposer des éléments suivants :

Configurer les détails de l'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. Spécifiez 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. 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=YOUR_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

    Répartition des paramètres

    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 Action requise : listez les niveaux d'accès aux API Google dont votre application a besoin (par exemple, https://www.googleapis.com/auth/bigquery). Si vous utilisez plusieurs niveaux d'accès, 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.

  • OAUTH_TOKEN_URI : URI du jeton que vous avez obtenu lorsque vous avez créé les identifiants OAuth.

Enregistrer un agent ADK avec Gemini Enterprise

Vous pouvez enregistrer votre agent ADK 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 ADK à 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. La page Agents s'affiche.

  4. Cliquez sur  Ajouter un agent. Le panneau Ajouter un agent s'affiche.

  5. Cliquez sur Ajouter pour Agent personnalisé via Agent Engine. La page Autorisations s'affiche.

  6. Si vous souhaitez que l'agent accède aux ressources Google Cloud en votre nom, chaque ressource doit être autorisée. Pour configurer une autorisation pour une seule ressource, procédez comme suit :

    1. Cliquez sur Ajouter une autorisation.

    2. Saisissez une valeur unique pour le Nom de l'autorisation. Un ID est généré en fonction du nom et ne peut pas être modifié ultérieurement.

    3. Saisissez les valeurs que vous avez générées dans la section Obtenir les détails de l'autorisation dans les champs suivants :

      1. Saisissez la valeur dans le champ ID client.

      2. Saisissez la valeur dans le champ Code secret du client.

      3. Saisissez la valeur dans le champ URI du jeton.

      4. Cliquez sur OK.

  7. Cliquez sur Suivant.

  8. Pour configurer votre agent, procédez comme suit :

    1. Saisissez un nom dans le champ Nom de l'agent. Cette valeur apparaît dans l'application Web Gemini Enterprise comme nom à afficher de votre agent.

    2. Saisissez une description dans le champ Décrivez votre agent. Cette valeur est utilisée par un LLM pour déterminer s'il doit appeler votre agent en réponse à une requête utilisateur.

    3. Saisissez le chemin d'accès à la ressource du moteur de raisonnement Agent Engine. Le chemin d'accès aux ressources se présente au format suivant :

          https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

      Pour savoir comment lister les agents hébergés sur Vertex AI Agent Engine et obtenir le chemin d'accès aux ressources, consultez Lister les agents déployés.

    4. Cliquez sur Créer.

REST

Cet exemple de code montre comment enregistrer vos agents ADK.

   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/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

Remplacez les variables par des valeurs :

  • ENDPOINT_LOCATION : région multirégionale pour votre requête API. Spécifiez 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 .

  • PROJECT_NUMBER : numéro de votre projet Google Cloud .

  • APP_ID : identifiant unique de l'application Gemini Enterprise.

  • DESCRIPTION : description de l'agent affichée dans Gemini Enterprise.

  • ICON_URI : URI public de l'icône à afficher à côté du nom de l'agent. Vous pouvez également transmettre le contenu d'un fichier image encodé en base64. Dans ce cas, utilisez icon.content.

  • ADK_RESOURCE_ID : ID du point de terminaison du moteur de raisonnement où l'agent ADK est déployé. Pour savoir comment lister les agents hébergés sur Vertex AI Agent Engine et obtenir l'ID de ressource, consultez Lister les agents déployés.

  • REASONING_ENGINE_LOCATION : emplacement cloud du moteur de raisonnement. Pour en savoir plus, consultez Emplacement du moteur de raisonnement.

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

     * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.

Ajouter des utilisateurs autorisés

Pour ajouter des utilisateurs autorisés à un agent ADK à l'aide de la console Google Cloud , consultez Ajouter ou modifier des utilisateurs et leurs autorisations.

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 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 ADK

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 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 ADK

Vous pouvez modifier les détails d'un agent existant enregistré auprès de Gemini Enterprise à l'aide de la console Google Cloud ou de l'API REST.

Console

Pour mettre à jour l'agent à 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 Agent Engine que vous souhaitez mettre à jour, puis sur Modifier.

  5. Modifiez le nom à afficher, la description ou le moteur de raisonnement Agent Engine.

    Le chemin d'accès aux ressources se présente au format suivant :

      https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

    Pour savoir comment lister les agents hébergés sur Vertex AI Agent Engine et obtenir le chemin d'accès aux ressources, consultez Lister les agents déployés.

  6. Cliquez sur Enregistrer.

REST

Vous pouvez mettre à jour tous les champs lors de l'enregistrement de l'agent. Toutefois, les champs suivants doivent être mis à jour :

  • displayName
  • description

  • reasoningEngine

    Cet exemple de code montre comment mettre à jour l'enregistrement d'un agent ADK existant :

    curl -X PATCH \
   -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/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_ID"
         },
      }
}'

    Remplacez les variables par des valeurs :

  • ENDPOINT_LOCATION : région multirégionale pour votre requête API. Spécifiez 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 .

  • AGENT_RESOURCE_NAME : nom de ressource de l'enregistrement de l'agent à mettre à jour.

  • DISPLAY_NAME : nom convivial requis pour votre agent, qui s'affiche dans Gemini Enterprise.

  • DESCRIPTION : Obligatoire. Brève explication de ce que fait votre agent, visible par les utilisateurs dans Gemini Enterprise.

  • REASONING_ENGINE_LOCATION : Obligatoire. Emplacement cloud du moteur de raisonnement pour lequel vous créez un agent. Pour en savoir plus, consultez Emplacement du moteur de raisonnement.

  • ADK_RESOURCE_ID : ID du point de terminaison du moteur de raisonnement où l'agent ADK est déployé. Pour savoir comment lister les agents hébergés sur Vertex AI Agent Engine et obtenir l'ID de ressource, consultez Lister les agents déployés.

Supprimer un agent ADK

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

Emplacement du moteur de raisonnement

Lorsque vous enregistrez ou mettez à jour un agent ADK, l'emplacement de la ressource du moteur de raisonnement sous-jacent doit être compatible avec l'emplacement de votre agent. Les emplacements du moteur de raisonnement dépendent de l'emplacement de l'agent, comme suit :

  • Agents globaux : si votre agent se trouve dans l'emplacement global, vous pouvez utiliser un moteur de raisonnement déployé dans n'importe quelle région acceptée.

  • Agents multirégionaux :

    • Si votre agent se trouve dans la multirégion us, le moteur de raisonnement doit être déployé dans une région basée aux États-Unis, comme us-central1, us-east1 ou us-west1.
    • Si votre agent se trouve dans la multirégion eu, le moteur de raisonnement doit être déployé dans une région européenne, telle que europe-west1, europe-west2 ou europe-central2. Voici un tableau récapitulatif :
Emplacement de l'agent Emplacement(s) autorisé(s) pour le moteur de raisonnement
global Toutes les régions Google Cloud prises en charge
us Toute région commençant par us-, comme us-central1 ou us-east4
eu Toute région commençant par europe-, comme europe-west1 ou europe-west3

Des emplacements différents entraînent une erreur lors de l'enregistrement ou de la mise à jour de l'agent.