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 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 ADK auprès de 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 >  Ajouter des agents.

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

  5. Si vous souhaitez que l'agent accède aux ressources Google Cloud en votre nom, 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 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.

    4. Cliquez sur Ajouter une autorisation.

  6. Cliquez sur Suivant.

  7. 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. Configurez les paramètres de l'outil :

      1. Saisissez une description dans le champ Description de l'outil. Cette description est utilisée par le LLM pour comprendre l'objectif de l'outil et décider quand l'utiliser.

      2. Saisissez le nom dans le champ Nom du paramètre d'entrée. Il s'agit du nom de paramètre pour l'appel de fonction. Ce nom de paramètre indique au LLM le type d'entrée attendu, par exemple question, command ou search_query.

      3. Saisissez la description dans le champ Description du paramètre d'entrée. Cette description de paramètre fournit au LLM plus d'informations sur le paramètre, comme le contenu attendu et les actions à effectuer.

    5. 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_ID/locations/global/authorizations/AUTH_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 .

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

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

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

  • DISPLAY_NAME : obligatoire. Nom convivial de 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. 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.

Emplacement du moteur de raisonnement

Pour que votre appel d'API soit envoyé au bon moteur de raisonnement, utilisez le tableau suivant :

Emplacement Cloud que vous appelez Emplacement du moteur de raisonnement
us us-central1
eu europe-west1
Autres (y compris global) us-central1