Vous pouvez utiliser Terraform pour provisionner et gérer des instances Agent Runtime de manière déclarative. Lorsque vous déployez des agents avec Terraform, vous gérez la ressource google_vertex_ai_reasoning_engine à l'aide du fournisseur Terraform Cloud de Confiance by S3NS officiel (fournisseur GA ou fournisseur bêta).
Les instructions de cette page correspondent à l'exemple d'implémentation d'agent conteneurisé décrit dans l'atelier de programmation Déployer un agent conteneurisé avec Agent Runtime.
Prérequis
Avant d'utiliser Terraform pour déployer un agent, assurez-vous d'avoir effectué la configuration suivante :
- Installez Terraform (version 1.5.0 ou ultérieure) et consultez la documentation officielle du registre HashiCorp Terraform pour la ressource
google_vertex_ai_reasoning_engine(fournisseur en disponibilité générale et fournisseur bêta). - Configurez votre environnement Cloud de Confiance by S3NS et activez l'API Vertex AI (
aiplatform.googleapis.com), l'API Artifact Registry (artifactregistry.googleapis.com) et l'API Cloud Build (cloudbuild.googleapis.com). Authentifiez votre environnement local à l'aide des identifiants Cloud de Confiance by S3NS :
gcloud auth application-default loginPour séparer le code de votre application de la gestion de l'infrastructure, organisez l'espace de travail de votre agent en répertoires dédiés à l'application et à Terraform :
weather-agent-byoc/ ├── main.py # Python ADK agent entrypoint ├── requirements.txt # Python dependencies ├── Dockerfile # Container build definition └── terraform/ # Terraform configuration directory ├── main.tf # Agent Runtime resources and specifications ├── variables.tf # Project, region, and container variables └── outputs.tf # Resource name outputsFichiers d'application (
main.py,requirements.txt,Dockerfile) : contiennent la logique de votre agent, le wrapper du framework Web (comme FastAPI ou l'application ADK), les dépendances Python et les instructions de compilation du conteneur.Répertoire Terraform (
terraform/) : contient tous les fichiers de configuration Terraform utilisés pour provisionner les ressources :variables.tf: déclare les variables d'entrée telles queproject_id,location,repository_nameetimage_tag.main.tf: déclare les paramètres du fournisseur, les variables locales, les liaisons de rôles IAM et les spécifications de ressourcesgoogle_vertex_ai_reasoning_engine.outputs.tf: exporte les attributs de ressources provisionnés, tels que l'ID d'Agent Runtime et le nom complet de la ressource, après le déploiement.
Attribuez les rôles IAM appropriés en fonction de la personne qui exécute le déploiement :
Développeur humain ou compte de service CI/CD exécutant
terraform applyet les commandes de compilation locales.Agent de service Agent Runtime géré par le système (
service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com).
Préparer le déploiement
Terraform accepte les chemins de déploiement suivants pour Agent Runtime :
- Déployer à partir d'une image de conteneur prédéfinie : précompilez et transférez une image de conteneur vers Artifact Registry (
{region}-docker.pkg.dev/...), puis déployez-la à l'aide decontainer_spec. Utilisez cette méthode lorsque vous avez besoin d'un contrôle total sur le processus de compilation du conteneur, sur les images de base personnalisées ou sur une latence de déploiement plus faible. - Déployer à partir de fichiers sources ou d'un Dockerfile : déployez votre agent directement à partir de fichiers sources locaux ou d'un Dockerfile. Agent Runtime crée et provisionne automatiquement l'image de conteneur, sans nécessiter de gestion manuelle des images.
- Déployer à l'aide des spécifications du package Python Déployer à l'aide de (
package_spec) préproduit dans Cloud Storage. Agent Runtime crée et provisionne automatiquement l'image de conteneur, sans nécessiter de gestion manuelle des images.
Déployer à partir d'une image de conteneur prédéfinie
Si vous précompilez et transférez des images de conteneurs vers Artifact Registry (par exemple, pour inclure des bibliothèques système personnalisées, optimiser les performances de démarrage à froid ou appliquer des contrôles de compilation d'images organisationnelles), vous pouvez effectuer le déploiement à l'aide de container_spec. Pour en savoir plus sur les exigences concernant les images, consultez Déployer à partir d'une image de conteneur.
Les images de conteneurs doivent être stockées dans Artifact Registry ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}), écouter sur le port 8080 (ou un port personnalisé spécifié dans container_spec) et respecter le contrat d'exécution.
Créez votre image de conteneur localement et transférez-la vers votre dépôt Artifact Registry :
# 1. Authenticate Docker with your Artifact Registry region gcloud auth configure-docker us-central1-docker.pkg.dev# 2. Build the container image from your application root directory cd weather-agent-byoc docker build -t us-central1-docker.pkg.dev/PROJECT_ID/agents-repo/weather-agent-image:latest .# 3. Push the container image to Artifact Registry docker push us-central1-docker.pkg.dev/PROJECT_ID/agents-repo/weather-agent-image:latestConfigurez votre image de conteneur prédéfinie pour le déploiement Terraform. La configuration suivante illustre le déploiement d'une image de conteneur prédéfinie hébergée dans Artifact Registry en créant les fichiers
variables.tf,main.tfetoutputs.tfdans votre répertoireterraform/:Variables d'entrée (
terraform/variables.tf)variable "project_id" { type = string description = "The Google Cloud Project ID" } variable "project_number" { type = string description = "The Google Cloud Project Number" } variable "location" { type = string default = "us-central1" description = "The region to deploy Agent Runtime" } variable "repository_name" { type = string default = "agents-repo" description = "The Artifact Registry repository name" } variable "image_tag" { type = string default = "latest" description = "The tag of the container image to deploy" }Spécifications de ressource (
terraform/main.tf)terraform { required_providers { google = { source = "hashicorp/google" version = ">= 5.28.0" } } } provider "google" { project = var.project_id region = var.location } locals { class_methods = [ { "name" = "get_session", "api_mode" = "" }, { "name" = "list_sessions", "api_mode" = "" }, { "name" = "create_session", "api_mode" = "" }, { "name" = "delete_session", "api_mode" = "" }, { "name" = "async_get_session", "api_mode" = "async" }, { "name" = "async_list_sessions", "api_mode" = "async" }, { "name" = "async_create_session", "api_mode" = "async" }, { "name" = "async_delete_session", "api_mode" = "async" }, { "name" = "async_add_session_to_memory", "api_mode" = "async" }, { "name" = "async_search_memory", "api_mode" = "async" }, { "name" = "stream_query", "api_mode" = "stream" }, { "name" = "async_stream_query", "api_mode" = "async_stream" }, { "name" = "streaming_agent_run_with_events", "api_mode" = "async_stream" } ] } # Grant Artifact Registry Reader permission to the Agent Runtime Service Agent resource "google_project_iam_member" "re_service_agent_ar_reader" { project = var.project_id role = "roles/artifactregistry.reader" member = "serviceAccount:service-${var.project_number}@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com" } # Define the Agent Runtime resource with BYOC container configuration resource "google_vertex_ai_reasoning_engine" "byoc_weather_agent" { display_name = "byoc_weather_agent_tf" description = "BYOC weather agent deployed using Terraform" project = var.project_id region = var.location spec { agent_framework = "google-adk" container_spec { image_uri = "${var.location}-docker.pkg.dev/${var.project_id}/${var.repository_name}/weather-agent-image:${var.image_tag}" } class_methods = jsonencode(local.class_methods) } # Ensure service agent permission exists before provisioning to prevent IMAGE_PULL_BACKOFF depends_on = [google_project_iam_member.re_service_agent_ar_reader] }Sorties de ressources (
terraform/outputs.tf)output "reasoning_engine_id" { value = google_vertex_ai_reasoning_engine.byoc_weather_agent.id description = "The ID of the deployed Agent Runtime instance" } output "reasoning_engine_resource_name" { value = google_vertex_ai_reasoning_engine.byoc_weather_agent.name description = "The resource name of the deployed Agent Runtime instance" }
Déployer à partir d'un Dockerfile ou d'un dépôt source
Lorsque vous déployez à partir d'un Dockerfile, spécifiez votre archive source dans source_code_spec et définissez un bloc image_spec {} vide pour indiquer à Agent Runtime de créer l'image de conteneur à l'aide de votre Dockerfile. Le conteneur créé à partir de votre Dockerfile doit respecter le contrat d'exécution.
Pour en savoir plus sur le fonctionnement du déploiement, consultez Déployer à partir d'un Dockerfile ou Déployer à partir de fichiers sources.
Compressez le code de votre application (
main.py), le fichier manifeste des dépendances Python (requirements.txt) et les instructions de compilation du conteneur (Dockerfile) dans une archive de fichier tar compressée au format gzip.Exécutez la commande suivante à partir du répertoire racine de votre application (l'exemple utilise le répertoire racine
weather-agent-byoc/et l'archive de fichier tarweather_agent_source.tar.gz) :cd weather-agent-byoc tar -czvf terraform/weather_agent_source.tar.gz main.py requirements.txt DockerfileCréez les fichiers
variables.tf,main.tfetoutputs.tfdans votre répertoireterraform/:Variables d'entrée (
terraform/variables.tf)variable "project_id" { type = string description = "The Google Cloud Project ID" } variable "location" { type = string default = "us-central1" description = "The region to deploy Agent Runtime" }Spécifications de ressource (
terraform/main.tf)terraform { required_providers { google = { source = "hashicorp/google" version = ">= 5.28.0" } } } provider "google" { project = var.project_id region = var.location } resource "google_vertex_ai_reasoning_engine" "dockerfile_agent" { display_name = "dockerfile_weather_agent_tf" description = "BYOC weather agent deployed using Dockerfile" project = var.project_id region = var.location spec { agent_framework = "google-adk" source_code_spec { inline_source { source_archive = filebase64("weather_agent_source.tar.gz") } # Empty image_spec instructs the runtime to build using the Dockerfile image_spec {} } class_methods = jsonencode([ { "name" = "get_session", "api_mode" = "" }, { "name" = "list_sessions", "api_mode" = "" }, { "name" = "create_session", "api_mode" = "" }, { "name" = "delete_session", "api_mode" = "" }, { "name" = "async_get_session", "api_mode" = "async" }, { "name" = "async_list_sessions", "api_mode" = "async" }, { "name" = "async_create_session", "api_mode" = "async" }, { "name" = "async_delete_session", "api_mode" = "async" }, { "name" = "async_add_session_to_memory", "api_mode" = "async" }, { "name" = "async_search_memory", "api_mode" = "async" }, { "name" = "stream_query", "api_mode" = "stream" }, { "name" = "async_stream_query", "api_mode" = "async_stream" }, { "name" = "streaming_agent_run_with_events", "api_mode" = "async_stream" } ]) } }Sorties de ressources (
terraform/outputs.tf)output "dockerfile_agent_id" { value = google_vertex_ai_reasoning_engine.dockerfile_agent.id description = "Resource ID of the deployed Dockerfile agent" }
Déployer à l'aide de la spécification du package Python
Si votre agent est créé à l'aide d'objets du SDK Python ou d'applications sérialisées (comme ADK, LangChain ou des agents Python personnalisés), vous pouvez stocker votre agent sérialisé (.pkl) et votre configuration de dépendance (requirements.txt) dans un bucket Cloud Storage et les référencer à l'aide de package_spec.
Pour en savoir plus sur le fonctionnement du déploiement, consultez Déployer à partir d'un objet Python.
Exécutez le script Python suivant pour sérialiser votre agent et préparer les artefacts de déploiement dans Cloud Storage :
import cloudpickle from google.adk.agents import Agent from google.cloud import storage from vertexai.agent_engines import AdkApp PROJECT_ID = "PROJECT_ID" BUCKET_NAME = "BUCKET_NAME" GCS_DIR = "agents/weather_agent" # 1. Define agent logic root_agent = Agent( model="gemini-3.1-flash-lite", name="weather_agent", description="Agent deployed using Terraform package_spec.", ) local_app = AdkApp(agent=root_agent) # 2. Upload pickle to Cloud Storage storage_client = storage.Client(project=PROJECT_ID) bucket = storage_client.bucket(BUCKET_NAME) pkl_blob = bucket.blob(f"{GCS_DIR}/agent.pkl") with pkl_blob.open("wb") as f: cloudpickle.dump(local_app, f) # 3. Upload requirements.txt requirements_content = """google-cloud-aiplatform[agent_engines,adk]>=1.144 cloudpickle==3.0.0 """ req_blob = bucket.blob(f"{GCS_DIR}/requirements.txt") req_blob.upload_from_string(requirements_content) print(f"Artifacts uploaded to gs://{BUCKET_NAME}/{GCS_DIR}/")Créez les fichiers
variables.tf,main.tfetoutputs.tfdans votre répertoireterraform/en référençant les URI Cloud Storage de préproduction :Variables d'entrée (
terraform/variables.tf)variable "project_id" { type = string description = "The Google Cloud Project ID" } variable "location" { type = string default = "us-central1" description = "The region to deploy Agent Runtime" } variable "bucket_name" { type = string description = "Cloud Storage bucket name containing agent artifacts" }Spécifications de ressource (
terraform/main.tf)terraform { required_providers { google = { source = "hashicorp/google" version = ">= 5.28.0" } } } provider "google" { project = var.project_id region = var.location } resource "google_vertex_ai_reasoning_engine" "package_agent" { display_name = "weather_agent_package_tf" description = "Agent Runtime instance deployed using package_spec" project = var.project_id region = var.location spec { agent_framework = "google-adk" package_spec { python_version = "3.11" pickle_object_gcs_uri = "gs://${var.bucket_name}/agents/weather_agent/agent.pkl" requirements_gcs_uri = "gs://${var.bucket_name}/agents/weather_agent/requirements.txt" } } }Sorties de ressources (
terraform/outputs.tf)output "package_agent_id" { value = google_vertex_ai_reasoning_engine.package_agent.id description = "Resource ID of the deployed package agent" }
Configurer des variables d'environnement et des secrets
Avant le déploiement, vous pouvez associer un compte de service d'exécution personnalisé à votre agent et transmettre des variables d'environnement (env) ou des références Secret Manager (secret_env).
L'exemple suivant configure des variables d'environnement (LOCATION, MODEL, MODEL_REGION) et transmet de manière sécurisée une clé API de Secret Manager au compte de service d'exécution via le fichier terraform/main.tf :
# 1. Dedicated Runtime Service Account
resource "google_service_account" "agent_runtime_sa" {
account_id = "agent-runtime-sa"
display_name = "Agent Runtime Identity"
project = var.project_id
}
# 2. Secret Manager Secret for Agent Credentials
resource "google_secret_manager_secret" "api_key_secret" {
secret_id = "agent-api-key"
project = var.project_id
replication {
auto {}
}
}
resource "google_secret_manager_secret_version" "api_key_version" {
secret = google_secret_manager_secret.api_key_secret.id
secret_data = var.api_key_value
}
# Grant Secret Accessor role to Runtime Service Account
resource "google_secret_manager_secret_iam_member" "secret_accessor" {
secret_id = google_secret_manager_secret.api_key_secret.id
role = "roles/secretmanager.secretAccessor"
member = "serviceAccount:${google_service_account.agent_runtime_sa.email}"
}
# Grant Artifact Registry Reader permission to the Agent Runtime Service Agent
resource "google_project_iam_member" "re_service_agent_ar_reader" {
project = var.project_id
role = "roles/artifactregistry.reader"
member = "serviceAccount:service-${var.project_number}@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com"
}
# 3. Agent Runtime Resource with Environment Variables and Secret References
resource "google_vertex_ai_reasoning_engine" "advanced_weather_agent" {
display_name = "byoc_weather_agent_advanced_tf"
description = "BYOC weather agent with custom service account and secrets"
project = var.project_id
location = var.location
spec {
agent_framework = "google-adk"
service_account = google_service_account.agent_runtime_sa.email
container_spec {
image_uri = "${var.location}-docker.pkg.dev/${var.project_id}/${var.repository_name}/weather-agent-image:${var.image_tag}"
}
deployment_spec {
env {
name = "LOCATION"
value = var.location
}
env {
name = "MODEL"
value = "gemini-3.1-flash-lite"
}
env {
name = "MODEL_REGION"
value = "global"
}
secret_env {
name = "API_KEY"
secret_ref {
secret = google_secret_manager_secret.api_key_secret.secret_id
version = "latest"
}
}
}
class_methods = jsonencode([
{ "name" = "get_session", "api_mode" = "" },
{ "name" = "create_session", "api_mode" = "" },
{ "name" = "stream_query", "api_mode" = "stream" },
{ "name" = "async_stream_query", "api_mode" = "async_stream" }
])
}
depends_on = [
google_secret_manager_secret_iam_member.secret_accessor,
google_project_iam_member.re_service_agent_ar_reader
]
}
Configurer Agent Gateway
Pour acheminer le trafic entre Agent Runtime et des API ou des clients externes via Agent Gateway, configurez le bloc agent_gateway_config dans deployment_spec à l'aide du fournisseur google-beta.
Pour obtenir des exemples de déploiement complets et des détails sur les paramètres pour le routage Agent-to-Anywhere (sortie) et Client-to-Agent (entrée), consultez Router le trafic d'exécution via Agent Gateway.
Gouvernance de passerelle centrale multiprojet
Dans les architectures d'entreprise multiprojets, vous pouvez gérer un projet de gouvernance central hébergeant Agent Gateway, Agent Registry et Model Armor tout en déployant des charges de travail d'exécution dans des dossiers de projet distincts au sein de votre organisation à l'aide de Terraform :
- Agent Gateway central et règles d'autorisation : provisionnez
google_network_services_agent_gateway,google_network_services_authz_extensionetgoogle_network_security_authz_policydans le projet de gouvernance central. Consultez Configurer Agent Gateway. - Accès de l'agent de service inter-projets : accordez le rôle
ar_agw_cross_project_sa(google_project_iam_custom_role) dans le projet de passerelle central à l'agent de service d'exécution de chaque projet de charge de travail à l'aide degoogle_project_iam_member. Consultez Acheminer le trafic d'exécution via Agent Gateway. - Registre central et règles de sortie : enregistrez les agents et les outils multiprojets dans le registre du projet central à l'aide de
google_agent_registry_serviceet accordezroles/iap.egressoravec les ressourcesgoogle_iap_agent_registry_*. Consultez Créer des règles d'agent IAM. - Modèles et paramètres de plancher Model Armor : appliquez des seuils de sécurité dans votre organisation ou vos dossiers avec
google_model_armor_floorsettingetgoogle_model_armor_template. Consultez Déléguer l'autorisation à Model Armor.
Exécution et cycle de vie
Exécutez le cycle de vie Terraform standard pour planifier, déployer, appeler et détruire vos ressources d'agent.
Appliquer la configuration Terraform
Déployez votre agent en appliquant votre configuration Terraform :
Accédez à votre répertoire Terraform (par exemple,
cd weather-agent-byoc/terraform) :cd weather-agent-byoc/terraformInitialisez le répertoire de travail :
terraform initPrévisualisez le plan de déploiement :
terraform plan -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"Appliquez la configuration pour provisionner l'agent :
terraform apply -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"
Interroger l'agent déployé
Une fois que Terraform a provisionné la ressource google_vertex_ai_reasoning_engine, envoyez une requête HTTP POST au point de terminaison :streamQuery?alt=sse pour diffuser les événements de réponse en temps réel à l'aide des événements envoyés par le serveur (SSE) :
LOCATION="LOCATION" PROJECT_ID="PROJECT_ID" REASONING_ENGINE_ID="REASONING_ENGINE_ID"curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "class_method": "async_stream_query", "input": { "user_id": "terraform_test_user", "message": "What is the temperature in Seattle?" } }' \ "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse"
- Jeton d'accès OAuth :
Authorization: Bearer $(gcloud auth print-access-token)génère un jeton d'accès OAuth 2.0 de courte durée à l'aide de vos identifiants Cloud de Confiance by S3NS locaux. - Enveloppe JSON
input: le corps de la requête nécessite une charge utile JSON contenant un objetinput. Lorsque vous appelez des méthodes de classe explicites (commeasync_stream_query), incluez le paramètre"class_method"en plus de"input". - Charge utile de la réponse : les réponses sont diffusées en continu sous forme de fragments d'événements envoyés par le serveur (SSE)
data: { ... }.
Détruire les ressources de l'agent
Pour nettoyer les ressources et éviter des frais de facturation inattendus, accédez à votre répertoire terraform/ (par exemple, cd weather-agent-byoc/terraform) et exécutez terraform destroy :
cd weather-agent-byoc/terraform
terraform destroy -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"Étapes suivantes
- Acheminer le trafic de l'environnement d'exécution via Agent Gateway
- Registre HashiCorp Terraform —
google_vertex_ai_reasoning_engine(DG) - Registre HashiCorp Terraform —
google_vertex_ai_reasoning_engine(bêta) - Google Cloud Generative AI — Agent Runtime Terraform Deployment Tutorial (GitHub)
- Google Developer Forum — Deploy Your Agent Runtime with Terraform the Enterprise Way