Déployer un agent

Pour déployer un agent sur Vertex AI Agent Engine, vous avez le choix entre deux méthodes principales :

  • Déployer à partir d'un objet d'agent : idéal pour le développement interactif dans des environnements tels que Colab, permettant le déploiement d'objets local_agent en mémoire. Cette méthode est idéale pour les agents dont les structures ne contiennent pas de composants complexes non sérialisables.
  • Déployer à partir de fichiers sources : cette méthode est idéale pour les workflows automatisés tels que les pipelines CI/CD et les outils Infrastructure as Code (IaC) comme Terraform, car elle permet des déploiements entièrement déclaratifs et automatisés. Il déploie votre agent directement à partir du code source local et ne nécessite pas de bucket Cloud Storage.

Pour commencer, procédez comme suit :

  1. Remplissez les conditions préalables.
  2. (Facultatif) Configurez votre agent pour le déploiement.
  3. Créez une instance AgentEngine.
  4. (Facultatif) Obtenez l'ID de ressource de l'agent.
  5. (Facultatif) Listez les opérations compatibles.
  6. (Facultatif) Accordez les autorisations à l'agent déployé.

Vous pouvez également utiliser les modèles Agent Starter Pack pour le déploiement.

Prérequis

Avant de déployer un agent, assurez-vous d'avoir effectué les tâches suivantes :

  1. Configurez votre environnement.
  2. Développez un agent.

(Facultatif) Configurer votre agent pour le déploiement

Vous pouvez effectuer les configurations facultatives suivantes pour votre agent :

Créer une instance AgentEngine

Cette section explique comment créer une instance AgentEngine pour déployer un agent.

Pour déployer un agent sur Vertex AI Agent Engine, vous pouvez choisir l'une des méthodes suivantes :

  • Déployer à partir d'un objet agent pour le développement interactif.

  • Déployer à partir de fichiers sources pour les workflows automatisés basés sur des fichiers.

À partir d'un objet agent

Pour déployer l'agent sur Vertex AI, utilisez client.agent_engines.create pour transmettre l'objet local_agent ainsi que les configurations facultatives :

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

Le déploiement prend quelques minutes, pendant lesquelles les étapes suivantes se déroulent en arrière-plan :

  1. Un ensemble des artefacts suivants est généré localement :

  2. Le bundle est importé dans Cloud Storage (dans le dossier correspondant) pour la préproduction des artefacts.

  3. Les URI Cloud Storage des artefacts respectifs sont spécifiés dans PackageSpec.

  4. Le service Vertex AI Agent Engine reçoit la requête, crée des conteneurs et démarre des serveurs HTTP sur le backend.

La latence de déploiement dépend du temps total nécessaire à l'installation des packages requis. Une fois déployé, remote_agent correspond à une instance de local_agent qui s'exécute sur Vertex AI et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les attributs suivants :

  • un remote_agent.api_resource contenant des informations sur l'agent déployé. Vous pouvez également appeler agent.operation_schemas() pour renvoyer la liste des opérations compatibles avec l'agent. Pour en savoir plus, consultez Lister les opérations compatibles.
  • un remote_agent.api_client qui permet des interactions de service synchrones.
  • un remote_agent.async_api_client qui permet des interactions de service asynchrones.

À partir de fichiers sources

Pour déployer à partir de fichiers sources sur Vertex AI, utilisez client.agent_engines.create en fournissant source_packages, entrypoint_module, entrypoint_object et class_methods dans le dictionnaire de configuration, ainsi que d'autres configurations facultatives. Avec cette méthode, vous n'avez pas besoin de transmettre un objet d'agent ni un bucket Cloud Storage.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

Voici les paramètres pour le déploiement de source intégrée :

  • source_packages (obligatoire, list[str]) : liste des chemins d'accès aux fichiers ou répertoires locaux à inclure dans le déploiement. La taille totale des fichiers et des répertoires dans source_packages ne doit pas dépasser 8 Mo.
  • entrypoint_module (obligatoire, str) : nom complet du module Python contenant le point d'entrée de l'agent (par exemple, agent_dir.agent).
  • entrypoint_object (obligatoire, str) : nom de l'objet appelable dans le entrypoint_module qui représente l'application d'agent (par exemple, root_agent).

  • class_methods (obligatoire, list[dict]) : liste de dictionnaires qui définissent les méthodes exposées de l'agent. Chaque dictionnaire inclut un champ name (obligatoire), un champ api_mode (obligatoire) et un champ parameters. Pour en savoir plus sur les méthodes d'un agent personnalisé, consultez Lister les opérations compatibles.

    Exemple :

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (facultatif, str) : chemin d'accès à un fichier de requirements pip dans les chemins d'accès spécifiés dans source_packages. La valeur par défaut est requirements.txt dans le répertoire racine de la source empaquetée.

Le déploiement prend quelques minutes, pendant lesquelles les étapes suivantes se déroulent en arrière-plan :

  1. Le SDK Vertex AI crée une archive tar.gz des chemins d'accès spécifiés dans source_packages.
  2. Cette archive est encodée et envoyée directement à l'API Vertex AI.
  3. Le service Vertex AI Agent Engine reçoit l'archive, l'extrait, installe les dépendances à partir de requirements_file (si fourni) et démarre l'application d'agent à l'aide des entrypoint_module et entrypoint_object spécifiés.

La latence de déploiement dépend du temps total nécessaire à l'installation des packages requis. Une fois déployé, remote_agent correspond à une instance de l'application d'agent qui s'exécute sur Vertex AI et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les attributs suivants :

  • un remote_agent.api_resource contenant des informations sur l'agent déployé. Vous pouvez également appeler agent.operation_schemas() pour renvoyer la liste des opérations compatibles avec l'agent. Pour en savoir plus, consultez Lister les opérations compatibles.
  • un remote_agent.api_client qui permet des interactions de service synchrones.
  • un remote_agent.async_api_client qui permet des interactions de service asynchrones.

Voici un exemple de déploiement d'un agent à partir de fichiers sources :

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

(Facultatif) Obtenir l'ID de ressource de l'agent

Chaque agent déployé possède un identifiant unique. Vous pouvez exécuter la commande suivante pour obtenir le nom de ressource de votre agent déployé :

remote_agent.api_resource.name

La réponse doit ressembler à la chaîne suivante :

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

Où :

  • PROJECT_ID correspond à l' Google Cloud ID du projet dans lequel l'agent déployé s'exécute.

  • LOCATION est la région dans laquelle l'agent déployé s'exécute.

  • RESOURCE_ID est l'ID de l'agent déployé en tant que ressource reasoningEngine.

(Facultatif) Lister les opérations compatibles

Chaque agent déployé dispose d'une liste d'opérations compatibles. Vous pouvez exécuter la commande suivante pour obtenir la liste des opérations prises en charge par l'agent déployé :

remote_agent.operation_schemas()

Le schéma de chaque opération est un dictionnaire qui documente les informations d'une méthode pour l'agent que vous pouvez appeler. L'ensemble des opérations compatibles dépend du framework que vous avez utilisé pour développer votre agent :

(Facultatif) Accorder des autorisations à l'agent déployé

Si l'agent déployé a besoin d'autorisations supplémentaires, suivez les instructions de la section Configurer l'identité et les autorisations de votre agent.

Étapes suivantes