Déployer un agent

Pour déployer un agent sur Vertex AI Agent Engine, 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) Lister 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.

Remarque : Le déploiement de Vertex AI Agent Engine n'est compatible qu'avec Python.

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 :

Définir les exigences du package

Fournissez l'ensemble des packages requis par l'agent pour le déploiement. L'ensemble de packages peut être une liste d'éléments à installer par pip ou le chemin d'accès à un fichier qui suit le format de fichier d'exigences. Appliquez les bonnes pratiques suivantes :

1. Épinglez vos versions de package pour les builds reproductibles. Les packages courants à suivre sont les suivants : google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai et pydantic.
2. Minimisez le nombre de dépendances dans votre agent. Cela réduit le nombre de modifications destructives lors de la mise à jour de vos dépendances et de votre agent.

Si l'agent n'a aucune dépendance, vous pouvez définir requirements sur None :

requirements = None

Si l'agent utilise un modèle spécifique au framework, vous devez spécifier la version du SDK importée (par exemple, 1.112.0) lors du développement de l'agent.

ADK

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

A2A

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "a2a-sdk>=0.3.4"
    # any other dependencies
]

LangChain

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

AG2

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

LlamaIndex

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les instructions suivantes concernent le pipeline de requête LlamaIndex :

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

Vous pouvez également effectuer les opérations suivantes avec le package requirements :

• Définissez une limite supérieure ou épinglez la version d'un package donné (tel que google-cloud-aiplatform) :

    requirements = [
        # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
    ]
    

• Ajoutez des packages et des contraintes supplémentaires :

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
        "cloudpickle==3.0", # new
    ]
    

• Indiquez la version d'un package sur une branche ou une demande d'extraction GitHub :

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    ]
    

• Conservez la liste des exigences dans un fichier (par exemple, path/to/requirements.txt) :

    requirements = "path/to/requirements.txt"
    

  où path/to/requirements.txt est un fichier texte qui suit le format du fichier des exigences. Exemple :

    google-cloud-aiplatform[agent_engines,adk]
    cloudpickle==3.0
    

Définir des packages supplémentaires

Vous pouvez inclure des fichiers ou des répertoires locaux contenant les fichiers sources Python locaux requis. Par rapport aux exigences de package, cela vous permet d'utiliser des utilitaires privés que vous avez développés et qui ne sont pas disponibles sur PyPI ni sur GitHub.

Si l'agent ne nécessite aucun package supplémentaire, vous pouvez définir extra_packages sur None :

extra_packages = None

Vous pouvez également effectuer les opérations suivantes avec extra_packages :

• Incluez un seul fichier (par exemple, agents/agent.py) :

    extra_packages = ["agents/agent.py"]
    

• Incluez l'ensemble des fichiers d'un répertoire entier (par exemple, agents/) :

    extra_packages = ["agents"] # directory that includes agents/agent.py
    

• Spécifiez les binaires de roue Python (par exemple, path/to/python_package.whl) :

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]",
        "cloudpickle==3.0",
        "python_package.whl",  # install from the whl file that was uploaded
    ]
    extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading
    

Définir des variables d'environnement

Si votre agent dépend de variables d'environnement, vous pouvez les spécifier dans l'argument env_vars=. Si l'agent ne dépend d'aucune variable d'environnement, vous pouvez le définir sur None :

env_vars = None

Avertissement : Vous ne devez pas définir les variables d'environnement suivantes : GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION et GOOGLE_APPLICATION_CREDENTIALS. De plus, vous devez éviter le préfixe GOOGLE_CLOUD_AGENT_ENGINE pour éviter les conflits de noms avec les variables d'environnement Vertex AI Agent Engine.

Pour spécifier les variables d'environnement, plusieurs options sont disponibles :

Dictionnaire

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

Pour référencer un secret dans Secret Manager et le rendre disponible en tant que variable d'environnement (par exemple, CLOUD_SQL_CREDENTIALS_SECRET), commencez par suivre les instructions pour créer un secret pour CLOUD_SQL_CREDENTIALS_SECRET dans votre projet, avant de spécifier les variables d'environnement comme suit :

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID},
}

Où :

• SECRET_VERSION_ID est l'ID de la version du secret.
• SECRET_ID est l'ID du secret.

Remarque : Vous ne pouvez référencer que les secrets (et leurs versions) gérés dans le même projet que l'agent déployé.

Dans votre code d'agent, vous pouvez ensuite faire référence au secret comme suit :

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON
  # payloads.
  return json.loads(secret)

Liste

Remarque : Cette option n'est pas compatible avec l'intégration de Secret Manager. Si vous devez spécifier des secrets gérés, vous devez spécifier les variables d'environnement sous forme de dictionnaire.

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

Vous devez également suivre les instructions de la section Configurer l'identité et les autorisations de votre agent pour accorder à votre agent l'autorisation Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor).

Définir des contrôles de ressources personnalisés

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez spécifier des contrôles des ressources d'exécution pour l'agent, tels que le nombre minimal et maximal d'instances d'application, les limites de ressources pour chaque conteneur et la simultanéité pour chaque conteneur.

• min_instances : nombre minimal d'instances d'application à maintenir en cours d'exécution à tout moment, avec une plage de [0, 10]. La valeur par défaut est de 1.

  Remarque : Tant que cette fonctionnalité est en version Preview, même si vous configurez un nombre minimal d'instances plus élevé, le temps d'inactivité d'un agent ne vous sera pas facturé. Ce comportement de facturation est susceptible de changer à l'avenir.

• max_instances : nombre maximal d'instances d'application pouvant être lancées pour gérer l'augmentation du trafic, avec une plage de [1, 1000]. La valeur par défaut est 100. Si VPC-SC ou PSC-I sont activés, la plage acceptable est [1, 100].

• resource_limits : limites de ressources pour chaque conteneur. Seules les clés cpu et memory sont acceptées. La valeur par défaut est {"cpu": "4", "memory": "4Gi"}.

  • Les seules valeurs acceptées pour cpu sont 1, 2, 4, 6 et 8. Pour en savoir plus, consultez Configurer l'allocation du processeur.

  • Les seules valeurs acceptées pour memory sont 1Gi, 2Gi, ... 32Gi.

  • Pour connaître le processeur requis pour différentes valeurs de mémoire, consultez Configurer les limites de mémoire.

• container_concurrency : simultanéité pour chaque conteneur et serveur d'agent. La valeur recommandée est 2 * cpu + 1. La valeur par défaut est 9.

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

Définir les options de compilation

Vous pouvez spécifier des options de compilation pour l'agent, telles que des scripts d'installation à exécuter lors de la compilation de l'image de conteneur de l'agent. Cela est utile pour installer des dépendances système (par exemple, gcloud cli, npx) ou d'autres configurations personnalisées. Les scripts sont exécutés avec les autorisations root.

Pour utiliser des scripts d'installation, créez un répertoire nommé installation_scripts et placez-y vos scripts shell :

.
├── ...
└── installation_scripts/
    └── install.sh

Ensuite, spécifiez le répertoire installation_scripts dans extra_packages et les chemins d'accès aux scripts dans build_options :

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

Vous pouvez utiliser l'un des scripts d'installation courants suivants :

install_npx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

install_uvx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

install_gcloud_cli.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

Définir un dossier Cloud Storage

Les artefacts de préproduction sont écrasés s'ils correspondent à un dossier existant dans un bucket Cloud Storage. Si nécessaire, vous pouvez spécifier le dossier Cloud Storage pour les artefacts de préproduction. Vous pouvez définir gcs_dir_name sur None si vous ne craignez pas d'écraser potentiellement les fichiers du dossier par défaut :

gcs_dir_name = None

Pour éviter d'écraser les fichiers (par exemple, pour différents environnements tels que le développement, la préproduction et la production), vous pouvez configurer le dossier correspondant et spécifier le dossier dans lequel organiser l'artefact :

gcs_dir_name = "dev" # or "staging" or "prod"

Si vous souhaitez ou devez éviter les collisions, vous pouvez générer un uuid aléatoire :

import uuid
gcs_dir_name = str(uuid.uuid4())

Définir le nom à afficher

Vous pouvez définir le nom à afficher pour la ressource ReasoningEngine :

display_name = "Currency Exchange Rate Agent (Staging)"

Définir la description

Vous pouvez définir la description de la ressource ReasoningEngine :

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

Définir les libellés

Vous pouvez définir les libellés de la ressource ReasoningEngine sous forme de dictionnaire de paires clé/valeur. En voici un exemple :

labels = {"author": "username", "version": "latest"}

Configurer un compte de service personnalisé

Vous pouvez configurer un compte de service personnalisé comme identité de votre agent déployé, au lieu de l'identité par défaut.

Pour ce faire, spécifiez l'adresse e-mail de votre compte de service personnalisé en tant que service_account lorsque vous créez ou mettez à jour l'instance Agent Engine, par exemple :

# Create a new instance
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

Remarque : Spécifiez uniquement l'adresse e-mail du compte de service, et non l'URI complet de la ressource, par exemple projects/{project_id}/serviceAccounts/{service_account_email}.

Configurer une interface Private Service Connect

Si vous avez configuré une interface Private Service Connect et l'appairage DNS, vous pouvez spécifier votre association de réseau et l'appairage DNS privé lors du déploiement de votre agent :

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },
    },
)

Où :

• NETWORK_ATTACHMENT correspond au nom ou au chemin d'accès complet de votre rattachement réseau. Si le rattachement réseau est créé dans un projet (tel que le projet hôte de VPC partagé) différent de celui dans lequel vous utilisez Agent Engine, vous devez transmettre le chemin d'accès complet de votre rattachement réseau.
• DOMAIN_SUFFIX est le nom DNS de la zone Cloud DNS privée que vous avez créée lors de la configuration de l'appairage DNS privé.
• TARGET_PROJECT est le projet qui héberge le réseau VPC. Il peut être différent du projet d'association au réseau.
• TARGET_NETWORK est le nom du réseau VPC.

Vous pouvez configurer plusieurs agents pour qu'ils utilisent un seul rattachement de réseau partagé ou des rattachements de réseau uniques et dédiés. Pour utiliser un rattachement de réseau partagé, fournissez le même rattachement de réseau dans psc_interface_config pour chaque agent que vous créez.

Configurer des clés de chiffrement gérées par le client

Vous pouvez utiliser une clé personnalisée pour chiffrer les données de votre agent au repos. Pour en savoir plus, consultez Clés de chiffrement gérées par le client (CMEK) dans Agent Engine.

Pour configurer la clé personnalisée (CMEK) de votre agent, vous devez fournir le nom de ressource de la clé au paramètre encryption_spec lorsque vous créez l'instance Agent Engine.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Créer une instance AgentEngine

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.
        "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.
    },
)

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 :

   • *.pkl : fichier pickle correspondant à local_agent.
   • requirements.txt, un fichier texte contenant les conditions requises pour le package.
   • dependencies.tar.gz : fichier tar contenant les éventuels packages supplémentaires.

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. Elle est distincte des instances locales de l'agent.

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.

(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 devrait 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 :

• Agent Development Kit
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Personnalisée

(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

• Utiliser l'agent
• Gérer les agents déployés.
• Résolvez les problèmes de déploiement d'un agent.
• Accédez à l'assistance.