Déployer un agent

Pour déployer un agent sur Vertex AI Agent Engine, procédez comme suit :

  1. Configurez votre agent pour le déploiement.
  2. Créez une instance AgentEngine.
  3. Accordez les autorisations à l'agent déployé.
  4. Obtenez l'ID de ressource de l'agent.

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

Avant de commencer

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

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

Configurer votre agent pour le déploiement

Vous pouvez effectuer les configurations facultatives suivantes :

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.77.0) lors du développement de l'agent.

ADK 

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # 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

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.88.0",
]

  • Ajoutez des packages et des contraintes supplémentaires :

    requirements = [
    "google-cloud-aiplatform[agent_engines,adk]==1.88.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
    "cloudpickle==3.0",
]

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

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 d'environnement (par exemple, CLOUD_SQL_CREDENTIALS_SECRET), suivez d'abord 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 secrète.
  • SECRET_ID est l'ID du secret.

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 

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"],
#   }

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

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.

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

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

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

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

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 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())

Configurer les métadonnées de ressources

Vous pouvez définir des métadonnées sur la ressource ReasoningEngine :

display_name = "Currency Exchange Rate Agent (Staging)"

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

Pour obtenir l'ensemble complet des paramètres, consultez la documentation de référence de l'API.

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
agent_engines.create(
  local_agent=<my-agent>,
  service_account="my-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
  resource_name,
  service_account="my-new-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

Configurer une interface Private Service Connect

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

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

Où :

  • NETWORK_ATTACHMENT est le nom ou 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 correspond au projet qui héberge le réseau VPC.
  • 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é, indiquez 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 lors de la création de 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 = agent_engines.create(
    local_agent,
    # ... other parameters
    encryption_spec={"kms_key_name": kms_key_name},
)

Créer une instance AgentEngine

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

remote_agent = agent_engines.create(
    local_agent,                     # Optional.
    requirements=requirements,       # Optional.
    extra_packages=extra_packages,   # Optional.
    gcs_dir_name=gcs_dir_name,       # Optional.
    display_name=display_name,       # Optional.
    description=description,         # 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 bundle des artefacts suivants est généré localement :

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

  3. Les URI Cloud Storage pour les 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.

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.

Si vous avez défini des secrets en tant que variables d'environnement, vous devez accorder l'autorisation suivante :

  • Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor)

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 l'identifiant resource_name de votre agent déployé :

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

Étapes suivantes