Cette page a été traduite par l'API Cloud Translation.

Déployer un agent

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

Configurez votre agent pour le déploiement.
Créez une instance AgentEngine.
Accordez les autorisations à l'agent déployé.
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 :

Configurer votre agent pour le déploiement

Vous pouvez effectuer les configurations facultatives suivantes :

Exigences concernant les packages
Packages supplémentaires
Variables d'environnement
Options de compilation
Dossier Cloud Storage
Métadonnées des ressources

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 :

É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.
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 respecte le format du fichier d'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 la 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 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.

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

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.

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

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

Un bundle des artefacts suivants est généré localement :
- *.pkl : fichier pickle correspondant à local_agent.
- requirements.txt : fichier texte contenant les conditions requises pour le package.
- dependencies.tar.gz : fichier tar contenant les packages supplémentaires.
Le bundle est importé dans Cloud Storage (sous le dossier correspondant) pour la mise en préproduction des artefacts.
Les URI Cloud Storage pour les artefacts respectifs sont spécifiés dans PackageSpec.
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 les autorisations de l'agent de service.

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"