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 l'interface Private Service Connect

Vertex AI Agent Engine est compatible avec l'interface Private Service Connect et le peering DNS pour un trafic de sortie privé et sécurisé.

Pourquoi utiliser une interface Private Service Connect ?

Votre agent est déployé dans un réseau sécurisé géré par Google, sans accès à votre réseau de cloud privé virtuel (VPC). Une interface PSC crée un pont privé et sécurisé vers votre réseau. Il s'agit donc de la solution recommandée pour interagir avec des services hébergés de manière privée dans vos environnements VPC, sur site et multicloud.

En plus de fournir un accès privé, cette connexion est également requise pour activer l'accès à Internet lorsque vous utilisez VPC Service Controls. Consultez Accéder à Internet public.

Fonctionnement

Lorsque vous configurez une interface PSC, Agent Engine provisionne une interface dans un projet locataire appartenant à Google, où votre agent s'exécute. Cette interface se connecte directement à un rattachement de réseau dans votre projet. Tout le trafic entre votre agent et votre VPC transite de manière sécurisée sur le réseau de Google, sans jamais traverser l'Internet public.

Accéder à l'Internet public

La capacité de l'agent à accéder à l'Internet public dépend de la configuration de sécurité de votre projet, en particulier si vous utilisez VPC Service Controls.

Comportement par défaut (sans VPC Service Controls)
  • Lorsque vous configurez votre agent avec une interface PSC uniquement, il conserve son accès Internet par défaut. Ce trafic sortant quitte directement l'environnement sécurisé géré par Google dans lequel votre agent s'exécute.
Avec VPC Service Controls
  • Lorsque votre projet fait partie d'un périmètre VPC Service Controls, l'accès Internet par défaut de l'agent est bloqué par le périmètre pour empêcher l'exfiltration de données. Pour permettre à l'agent d'accéder à l'Internet public dans ce scénario, vous devez configurer explicitement un chemin de sortie sécurisé qui achemine le trafic via votre VPC. La méthode recommandée consiste à configurer un serveur proxy dans votre périmètre VPC et à créer une passerelle Cloud NAT pour permettre à la VM du proxy d'accéder à Internet.

Avant de commencer

Pour activer la connectivité privée pour votre agent déployé à l'aide de l'interface Private Service Connect, vous devez configurer un réseau VPC, un sous-réseau et un rattachement de réseau dans votre projet utilisateur.

Exigences concernant les plages d'adresses IP des sous-réseaux

Agent Engine recommande un sous-réseau /28.

Le sous-réseau du rattachement réseau est compatible avec les adresses RFC 1918 et non-RFC 1918, à l'exception des sous-réseaux 100.64.0.0/10 et 240.0.0.0/4. Agent Engine ne peut se connecter qu'aux plages d'adresses IP RFC 1918 routables à partir du réseau spécifié. Agent Engine ne peut pas accéder à une adresse IP publique utilisée en mode privé ni à ces plages non-RFC 1918 :

  • 100.64.0.0/10
  • 192.0.0.0/24
  • 192.0.2.0/24
  • 198.18.0.0/15
  • 198.51.100.0/24
  • 203.0.113.0/24
  • 240.0.0.0/4

Pour en savoir plus sur la configuration, consultez Configurer une interface Private Service Connect.

Utilisation avec un VPC partagé

Vous pouvez utiliser l'interface Private Service Connect avec une architecture de VPC partagé, qui vous permet de créer votre Agent Engine dans un projet de service tout en utilisant un réseau provenant d'un projet hôte central.

Lorsque vous configurez PSC-I dans un environnement VPC partagé, créez le sous-réseau dans le projet hôte, puis créez le rattachement réseau dans le projet de service.

Pour que le projet de service puisse utiliser le réseau du projet hôte, vous devez accorder l'autorisation IAM appropriée. L'agent de service Vertex AI de votre projet de service a besoin du rôle Utilisateur de réseau Compute (roles/compute.networkUser) dans le projet hôte.

Déployer des agents avec l'interface Private Service Connect

Une fois le rattachement de réseau configuré, vous pouvez le spécifier lors de la création de l'instance AgentEngine.

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
    },
)

Où :

  • NETWORK_ATTACHMENT est le nom ou le chemin d'accès complet du rattachement de réseau que vous avez créé.

Utiliser des rattachements de réseau avec plusieurs agents

Vous pouvez décider de la manière dont vos agents partagent les ressources réseau. 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 le psc_interface_config pour chaque agent que vous créez.

Appairage DNS

Alors que l'interface Private Service Connect fournit le chemin réseau sécurisé, l'appairage DNS fournit le mécanisme de détection de services. Avec PSC-I, vous devez toujours connaître l'adresse IP spécifique du service dans le réseau VPC. Bien que vous puissiez vous connecter aux services à l'aide de leurs adresses IP internes, cela n'est pas recommandé pour les systèmes de production où les adresses IP peuvent changer. Avec l'appairage DNS, l'agent déployé peut se connecter aux services de votre réseau VPC à l'aide de noms DNS stables et lisibles au lieu d'adresses IP. L'appairage DNS permet aux agents déployés de résoudre les noms DNS à l'aide des enregistrements d'une zone privée Cloud DNS dans votre VPC. Consultez Configurer un appairage DNS privé.

Une fois le peering DNS privé configuré, vous pouvez le spécifier lors de la création de l'instance AgentEngine.

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 du rattachement de réseau que vous avez créé.
  • 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.

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