Déployer un agent

Le déploiement d'un agent sur Agent Runtime le rend disponible à distance pour traiter les requêtes. Ce document explique comment déployer un agent en fonction de votre workflow de développement : à partir d'un objet d'exécution, de fichiers sources locaux, d'un fichier Dockerfile, d'une image de conteneur hébergée dans Artifact Registry ou directement via un dépôt Git connecté.

Pour déployer un agent sur Agent Runtime, choisissez l'une des méthodes suivantes :

Developer Connect

Recommandé pour les projets gérés dans un dépôt Git et associés via Developer Connect. Cette méthode simplifie le déploiement des agents directement à partir de votre code source et prend en charge de manière native le contrôle des versions, la collaboration en équipe et les pipelines CI/CD. Avant d'utiliser cette méthode, configurez le lien de votre dépôt Git en suivant les instructions de la section Configurer le lien de dépôt Git Developer Connect.

Vous ne pouvez utiliser cette méthode de déploiement qu'avec Python.

Fichiers sources

Convient parfaitement aux workflows automatisés tels que les pipelines CI/CD et les outils Infrastructure as Code comme Terraform, ce qui 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.

Vous ne pouvez utiliser cette méthode de déploiement qu'avec Python.

Dockerfile

Semblable au déploiement à partir de fichiers sources. Vous déployez votre agent directement à partir du code source local, sans avoir besoin d'un bucket Cloud Storage. Cette méthode est appropriée si vous devez définir et contrôler le serveur d'API déployé. Le conteneur déployé doit respecter le contrat d'exécution.

Vous pouvez utiliser cette méthode de déploiement avec n'importe quel langage. Les exemples de cette page utilisent Python.

Image de conteneur

Semblable au déploiement à partir de Dockerfile. Vous déployez une image de conteneur hébergée dans Artifact Registry. Utilisez cette méthode si vous avez besoin de contrôler le processus de compilation de l'image de conteneur et de réduire la latence de déploiement. L'image de conteneur doit respecter le contrat d'exécution.

Vous pouvez utiliser cette méthode de déploiement avec n'importe quel langage. Les exemples de cette page utilisent Python.

SDK Agent Platform

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 fonctionne mieux pour les agents dont les structures ne contiennent pas de composants complexes non sérialisables.

Pour commencer, procédez comme suit :

  1. Effectuer les opérations prérequises
  2. Facultatif : Configurer votre agent pour le déploiement
  3. Créer une instance Agent Platform
  4. Facultatif : Obtenir l'ID de ressource de l'agent
  5. Facultatif : Lister les opérations compatibles
  6. Facultatif : Accorder des autorisations à l'agent déployé

Prérequis

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

  1. Configurer votre environnement
  2. Créer un agent

Facultatif : Configurer votre agent pour le déploiement

Vous pouvez configurer des paramètres facultatifs pour votre agent. Les exemples de cette section utilisent Python.

Créer une instance Agent Platform

Cette section explique comment créer une instance Agent Platform pour déployer un agent. Vous avez le choix entre les méthodes suivantes :

Developer Connect

Pour déployer à partir de Developer Connect sur Agent Platform, utilisez client.agent_engines.create en fournissant developer_connect_source, entrypoint_module et entrypoint_object dans le dictionnaire de configuration, ainsi que d'autres configurations facultatives. Cette méthode vous permet de déployer du code directement à partir d'un dépôt Git connecté.

Vous ne pouvez utiliser cette méthode de déploiement qu'avec Python. 

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Voici les paramètres de déploiement de Developer Connect :

  • developer_connect_source (dict) : configuration pour l'extraction du code source. Pour en savoir plus, consultez Configurer un lien de dépôt Git Developer Connect.
    • git_repository_link (str) : nom de ressource du lien vers le dépôt Git Developer Connect.
    • revision (str) : révision à récupérer (branche, tag ou SHA de commit).
    • dir (str) : répertoire racine du code de l'agent dans le dépôt.
  • entrypoint_module (str) : nom du module Python contenant le point d'entrée de l'agent, par rapport au répertoire spécifié dans developer_connect_source.dir.
  • entrypoint_object (str) : nom de l'objet appelable dans entrypoint_module qui représente l'application de l'agent (par exemple, root_agent).
  • requirements_file (str) : facultatif, chemin d'accès à un fichier de requirements pip par rapport à la racine source. La valeur par défaut est requirements.txt.

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

  1. Le service Agent Runtime récupère le code source à partir de la révision du dépôt Git spécifiée.
  2. Le service installe les dépendances à partir de requirements_file (le cas échéant).
  3. Le service démarre l'application de l'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 local_agent qui s'exécute sur Agent Platform et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les éléments suivants :

Fichiers sources

Pour déployer à partir de fichiers sources sur la plate-forme Agent, 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 d'objet d'agent ni de bucket Cloud Storage.

Vous ne pouvez utiliser cette méthode de déploiement qu'avec Python. 

# 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={
        "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 du déploiement de source intégrée :

  • source_packages (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 (str) : nom complet du module Python contenant le point d'entrée de l'agent (par exemple, agent_dir.agent).
  • entrypoint_object (str) : nom de l'objet appelable dans entrypoint_module qui représente l'application de l'agent (par exemple, root_agent).
  • class_methods (list[dict]) : liste de dictionnaires qui définissent les méthodes exposées de l'agent. Chaque dictionnaire inclut un champ name, api_mode et parameters facultatif. 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": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str) : facultatif. 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 Agent Platform 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 Agent Platform.
  3. Le service Agent Runtime reçoit l'archive, l'extrait, installe les dépendances à partir de requirements_file (le cas échéant) 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 local_agent qui s'exécute sur Agent Platform et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les éléments suivants :

Dockerfile

Le déploiement à partir d'un fichier Dockerfile sur l'Agent Platform suit une approche semblable à celle du déploiement à partir de fichiers sources, sauf que vous utilisez image_spec dans la configuration au lieu de entrypoint_module, entrypoint_object et requirements_file. Le conteneur créé à partir du fichier Dockerfile doit respecter le contrat d'exécution.

Vous pouvez utiliser cette méthode de déploiement avec n'importe quel langage. L'exemple de cette section utilise Python.

Voici un exemple de déploiement d'un agent à l'aide d'un fichier Dockerfile :

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

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 Agent Platform et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les éléments suivants :

Image de conteneur

Pour effectuer un déploiement à partir d'une image de conteneur, suivez d'abord les instructions de configuration pour Apportez votre propre conteneur, en veillant à installer une version de google-cloud-aiplatform satisfaisant >=1.144. L'image de conteneur doit respecter le contrat d'exécution.

Vous pouvez utiliser cette méthode de déploiement avec n'importe quel langage. L'exemple de cette section utilise Python.

Voici un exemple de déploiement d'un agent à l'aide d'une image de conteneur :

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

Où CONTAINER_IMAGE_URI correspond à l'URI de l'image de conteneur dans Artifact Registry (par exemple, us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

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 Agent Platform et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les éléments suivants :

SDK Agent Platform

Pour déployer l'agent sur Agent Platform, 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 Agent Runtime reçoit la requête, crée des conteneurs et lance 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 Agent Platform et peut être interrogée ou supprimée.

L'objet remote_agent correspond à une classe AgentEngine qui contient les éléments suivants :

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 utiliser AgentEngine.operation_schemas 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.

Facultatif : Déployer des agents avec une infrastructure d'entreprise

Pour déployer votre agent avec un environnement complet incluant des couches de sécurité et de gouvernance, copiez et personnalisez les modèles Application Design Center suivants :

Étapes suivantes

Guide

Découvrez comment gérer les agents déployés dans l'environnement d'exécution géré Agent Platform.

Guide

Utiliser un agent avec Agent Platform Runtime