Provisionner des agents avec Terraform

Vous pouvez utiliser Terraform pour provisionner et gérer les 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 officiel (fournisseur GA ou fournisseur bêta). Google Cloud

Les instructions de cette page correspondent à l'implémentation d'agent conteneurisé exemple décrite 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 :

1. Installez Terraform (version 1.5.0 ou ultérieure) et consultez la documentation officielle du registre Terraform HashiCorp pour la ressource google_vertex_ai_reasoning_engine (fournisseur GA et fournisseur bêta).
2. Configurez votre Google Cloud environnement et activez l'API Vertex AI (aiplatform.googleapis.com), l'API Artifact Registry (artifactregistry.googleapis.com) et l'API Cloud Build (cloudbuild.googleapis.com).

3. Authentifiez votre environnement local à l'aide d' Google Cloud identifiants :

   gcloud auth application-default login

4. Pour séparer le code de votre application de la gestion de l'infrastructure, organisez votre espace de travail d'agent dans des répertoires d'application et Terraform dédiés :

   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 outputs
   

   • Fichiers d'application (main.py, requirements.txt, Dockerfile) : contiennent la logique de votre agent, le wrapper de framework Web (tel que FastAPI ou ADK App), 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 des ressources :

     • variables.tf : déclare des variables d'entrée telles que project_id, location, repository_name et image_tag.
     • main.tf : déclare les paramètres du fournisseur, les variables locales, les liaisons de rôles IAM et les spécifications de ressources google_vertex_ai_reasoning_engine.
     • outputs.tf : exporte les attributs de ressources provisionnés, tels que l'ID Agent Runtime et le nom complet de la ressource, après le déploiement.

5. 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 les commandes terraform apply et de compilation locale.

     Cliquez pour afficher les autorisations requises

     • Utilisateur Vertex AI (roles/aiplatform.user) ou Administrateur Vertex AI (roles/aiplatform.admin) : autorise le déployeur à exécuter les opérations RPC du plan de contrôle Agent Runtime (CreateReasoningEngine, UpdateReasoningEngine, DeleteReasoningEngine).
     • Utilisateur du compte de service (roles/iam.serviceAccountUser) : accordé sur le compte de service d'exécution personnalisé (google_service_account.agent_runtime_sa) associé à l'agent. Autorise le déployeur à associer cette identité de compte de service à la ressource google_vertex_ai_reasoning_engine provisionnée.
     • Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) ou Lecteur des objets de l'espace de stockage (roles/storage.objectViewer) : requis lors de l'utilisation de la préproduction de packages Python (package_spec) pour importer ou lire des pickles d'agent sérialisés (agent.pkl) et des manifestes de dépendances dans Cloud Storage.
     • Rédacteur Artifact Registry (roles/artifactregistry.writer) : requis lors de la précompilation et de l'envoi d'images de conteneurs personnalisées (docker push) vers des dépôts Artifact Registry.

   • Agent de service Agent Runtime géré par le système (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

     Cliquez pour afficher les autorisations requises

     • Lecteur Artifact Registry (roles/artifactregistry.reader) : accorde à l'infrastructure de la plate-forme Agent Runtime en arrière-plan l'autorisation de s'authentifier auprès d'Artifact Registry et d'extraire votre image de conteneur personnalisée lors du déploiement du pod et des démarrages à froid du conteneur.

     Important : Dans Terraform, vous devez gérer explicitement la liaison IAM pour l'agent de service et vous assurer que la ressource google_vertex_ai_reasoning_engine inclut une référence depends_on à la liaison IAM. Sinon, le provisionnement du pod peut échouer avec IMAGE_PULL_BACKOFF en raison d'une condition de concurrence.

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éconfigurée : précompilez et transférez une image de conteneur vers Artifact Registry ({region}-docker.pkg.dev/...) et déployez-la à l'aide de container_spec. Utilisez cette méthode lorsque vous avez besoin d'un contrôle total sur le processus de compilation du conteneur, des images de base personnalisées ou 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 compile et provisionne automatiquement l'image de conteneur sans nécessiter de gestion manuelle des images.
• Déployer à l'aide de spécifications de package Python : déployez à l'aide de (package_spec) préproduit dans Cloud Storage. Agent Runtime compile et provisionne automatiquement l'image de conteneur sans nécessiter de gestion manuelle des images.

Déployer à partir d'une image de conteneur préconfigurée

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 organisationnels), vous pouvez déployer à l'aide de container_spec. Pour en savoir plus sur les exigences concernant les images, consultez la section 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 être conformes au contrat d'exécution.

1. Compilez 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:latest

2. Configurez votre image de conteneur préconfigurée pour le déploiement Terraform. La configuration suivante montre comment déployer une image de conteneur préconfigurée hébergée dans Artifact Registry en créant les fichiers variables.tf, main.tf et outputs.tf dans votre répertoire terraform/ :

   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.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
     location     = 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 demander à Agent Runtime de compiler 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 la section Déployer à partir d'un Dockerfile ou Déployer à partir de fichiers sources.

1. Compressez le code de votre application (main.py), le manifeste de dépendances Python (requirements.txt) et les instructions de compilation du conteneur (Dockerfile) dans une archive de fichier tar compressée au format gzip.

2. 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 tar weather_agent_source.tar.gz) :

   cd weather-agent-byoc
   tar -czvf terraform/weather_agent_source.tar.gz main.py requirements.txt Dockerfile

   Remarque : Les fichiers main.py, requirements.txt et Dockerfile doivent se trouver directement au niveau racine de l'archive de fichier tar (et non imbriqués dans un répertoire parent tel que weather-agent-byoc/main.py). Lorsque Agent Runtime provisionne le conteneur de compilation, l'API Cloud Build décompresse weather_agent_source.tar.gz directement dans la racine de l'espace de travail de compilation et s'attend à ce que Dockerfile soit présent dans ./Dockerfile lors de la compilation.

3. Créez les fichiers variables.tf, main.tf et outputs.tf dans votre répertoire terraform/ :

   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
     location     = 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 d'une spécification de package Python

Si votre agent est créé à l'aide d'objets du SDK Python ou d'applications pickle (telles qu'ADK, LangChain ou des agents Python personnalisés), vous pouvez préproduire votre agent sérialisé (.pkl) et la configuration des dépendances (requirements.txt) dans un bucket Cloud Storage et y faire référence à l'aide de package_spec.

Pour en savoir plus sur le fonctionnement du déploiement, consultez la section Déployer à partir d'un objet Python.

1. Exécutez le script Python suivant pour sérialiser votre agent et préproduire 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}/")
   

2. Créez les fichiers variables.tf, main.tf et outputs.tf dans votre répertoire terraform/ en faisant référence aux URI Cloud Storage préproduits :

   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
     location     = 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 les variables d'environnement et les 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 les variables d'environnement (LOCATION, MODEL, MODEL_REGION) et transmet une clé API de manière sécurisée de Secret Manager au compte de service d'exécution via le terraform/main.tf file :

# 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.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
  ]
}

Exécution et cycle de vie

Exécutez le cycle de vie Terraform standard pour planifier, déployer, appeler et détruire les ressources de votre agent.

Appliquer la configuration Terraform

Déployez votre agent en appliquant votre configuration Terraform :

1. Accédez à votre répertoire Terraform (par exemple, cd weather-agent-byoc/terraform) :

   cd weather-agent-byoc/terraform

2. Initialisez le répertoire de travail :

   terraform init

3. Prévisualisez le plan de déploiement :

   terraform plan -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"

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

Remarque : Pour connaître les autres méthodes de requête, consultez la section Utiliser un agent ADK.

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 à courte durée de vie à l'aide de vos identifiants locaux. Google Cloud
• Enveloppe JSON input : le corps de la requête nécessite une charge utile JSON contenant un objet input. Lorsque vous appelez des méthodes de classe explicites (telles que async_stream_query), incluez le paramètre "class_method" à côté de "input".
• Charge utile de réponse : les réponses sont fournies en continu sous forme de blocs 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"

Étape suivante

• Registre Terraform HashiCorp : google_vertex_ai_reasoning_engine (GA)
• Registre Terraform HashiCorp : google_vertex_ai_reasoning_engine (bêta)
• Google Cloud IA générative : tutoriel de déploiement Terraform Agent Runtime (GitHub)
• Forum des développeurs Google : Déployer votre Agent Runtime avec Terraform pour les entreprises