Agents mit Terraform bereitstellen

Mit Terraform können Sie Agent Runtime-Instanzen deklarativ bereitstellen und verwalten. Wenn Sie Agenten mit Terraform bereitstellen, verwalten Sie die google_vertex_ai_reasoning_engine-Ressource mit dem offiziellen Cloud de Confiance by S3NS -Terraform-Anbieter (GA-Anbieter oder Beta-Anbieter).

Die Anleitung auf dieser Seite entspricht der Beispielimplementierung eines containerisierten Agenten, die im Codelab Containerisierten Agenten mit Agent Runtime bereitstellen beschrieben wird.

Vorbereitung

Bevor Sie einen Agent mit Terraform bereitstellen, müssen Sie die folgende Einrichtung abgeschlossen haben:

  1. Installieren Sie Terraform (Version 1.5.0 oder höher) und lesen Sie die offizielle HashiCorp Terraform Registry-Dokumentation für die Ressource google_vertex_ai_reasoning_engine (GA-Anbieter und Beta-Anbieter).
  2. Richten Sie Ihre Cloud de Confiance by S3NS -Umgebung ein und aktivieren Sie die Vertex AI API (aiplatform.googleapis.com), die Artifact Registry API (artifactregistry.googleapis.com) und die Cloud Build API (cloudbuild.googleapis.com).

  3. Authentifizieren Sie Ihre lokale Umgebung mit den Anmeldedaten von Cloud de Confiance by S3NS :

    gcloud auth application-default login

  4. Damit Ihr Anwendungscode von der Infrastrukturverwaltung getrennt bleibt, sollten Sie Ihren Agenten-Arbeitsbereich in separate Anwendungs- und Terraform-Verzeichnisse aufteilen:

    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

    • Anwendungsdateien (main.py, requirements.txt, Dockerfile): Enthalten die Agentenlogik, den Web-Framework-Wrapper (z. B. FastAPI oder ADK App), Python-Abhängigkeiten und Anweisungen zum Erstellen des Containers.

    • Terraform-Verzeichnis (terraform/): Enthält alle Terraform-Konfigurationsdateien, die zum Bereitstellen von Ressourcen verwendet werden:

      • variables.tf: Deklariert Eingabevariablen wie project_id, location, repository_name und image_tag.
      • main.tf: Deklariert Anbieter-Einstellungen, lokale Variablen, IAM-Rollenbindungen und google_vertex_ai_reasoning_engine-Ressourcenspezifikationen.
      • outputs.tf: Exportiert nach der Bereitstellung bereitgestellte Ressourcenattribute wie die Agent Runtime-ID und den vollständigen Ressourcennamen.

  5. Weisen Sie die entsprechenden IAM-Rollen zu, je nachdem, wer die Bereitstellung ausführt:

    • Entwickler oder CI/CD-Dienstkonto, der bzw. das terraform apply und lokale Build-Befehle ausführt.

    • Vom System verwalteter Agent Runtime-Dienst-Agent (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com).

Bereitstellung vorbereiten

Terraform unterstützt die folgenden Bereitstellungspfade für Agent Runtime:

  • Aus vordefiniertem Container-Image bereitstellen: Erstellen Sie ein Container-Image vorab, übertragen Sie es per Push an Artifact Registry ({region}-docker.pkg.dev/...) und stellen Sie es mit container_spec bereit. Verwenden Sie diese Methode, wenn Sie die volle Kontrolle über den Container-Build-Prozess, benutzerdefinierte Basis-Images oder eine geringere Bereitstellungslatenz benötigen.
  • Aus Quelldateien oder Dockerfile bereitstellen: Stellen Sie Ihren Agenten direkt aus lokalen Quelldateien oder einem Dockerfile bereit. Die Agent Runtime erstellt und stellt das Container-Image automatisch bereit, ohne dass eine manuelle Image-Verwaltung erforderlich ist.
  • Mit Python-Paketspezifikationen bereitstellen: Mit (package_spec) bereitstellen, das in Cloud Storage bereitgestellt wird. Die Agent Runtime erstellt und stellt das Container-Image automatisch bereit, ohne dass eine manuelle Image-Verwaltung erforderlich ist.

Aus einem vordefinierten Container-Image bereitstellen

Wenn Sie Container-Images vorab erstellen und per Push in Artifact Registry übertragen (z. B. um benutzerdefinierte Systembibliotheken einzubinden, die Kaltstartleistung zu optimieren oder Kontrollen für die Image-Erstellung in der Organisation zu erzwingen), können Sie die Bereitstellung mit container_spec durchführen. Weitere Informationen zu den Image-Anforderungen finden Sie unter Aus Container-Image bereitstellen.

Container-Images müssen in Artifact Registry ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}) gespeichert werden, Port 8080 (oder einen in container_spec angegebenen benutzerdefinierten Port) überwachen und dem Laufzeitvertrag entsprechen.

  1. Erstellen Sie das Container-Image lokal und übertragen Sie es per Push in Ihr Artifact Registry-Repository:

    # 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. Konfigurieren Sie Ihr vordefiniertes Container-Image für die Terraform-Bereitstellung. In der folgenden Konfiguration wird gezeigt, wie Sie ein vordefiniertes Container-Image bereitstellen, das in Artifact Registry gehostet wird. Dazu erstellen Sie die Dateien variables.tf, main.tf und outputs.tf in Ihrem Verzeichnis terraform/:

    Eingabevariablen (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"
}

    Ressourcenspezifikationen (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]
}

    Ressourcenausgaben (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"
}

Aus Dockerfile oder Quell-Repository bereitstellen

Wenn Sie die Bereitstellung über ein Dockerfile vornehmen, geben Sie Ihr Quellarchiv in source_code_spec an und legen Sie einen leeren image_spec {}-Block fest, um Agent Runtime anzuweisen, das Container-Image mit Ihrem Dockerfile zu erstellen. Der aus Ihrem Dockerfile erstellte Container muss dem Laufzeitvertrag entsprechen.

Weitere Informationen zur Funktionsweise der Bereitstellung finden Sie unter Aus Dockerfile bereitstellen oder Aus Quelldateien bereitstellen.

  1. Komprimieren Sie Ihren Anwendungscode (main.py), das Python-Abhängigkeitsmanifest (requirements.txt) und die Container-Build-Anweisungen (Dockerfile) in ein gzipptes TAR-Dateiarchiv.

  2. Führen Sie den folgenden Befehl im Stammverzeichnis Ihrer Anwendung aus. Im Beispiel wird das Stammverzeichnis weather-agent-byoc/ und das TAR-Dateiarchiv weather_agent_source.tar.gz verwendet:

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

  3. Erstellen Sie die Dateien variables.tf, main.tf und outputs.tf in Ihrem terraform/-Verzeichnis:

    Eingabevariablen (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"
}

    Ressourcenspezifikationen (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" }
    ])
  }
}

    Ressourcenausgaben (terraform/outputs.tf)

    output "dockerfile_agent_id" {
  value       = google_vertex_ai_reasoning_engine.dockerfile_agent.id
  description = "Resource ID of the deployed Dockerfile agent"
}

Mit Python-Paketspezifikation bereitstellen

Wenn Ihr Agent mit Python SDK-Objekten oder gepickelten Anwendungen (z. B. ADK, LangChain oder benutzerdefinierten Python-Agenten) erstellt wurde, können Sie Ihren serialisierten Agenten (.pkl) und die Abhängigkeitskonfiguration (requirements.txt) in einem Cloud Storage-Bucket bereitstellen und mit package_spec darauf verweisen.

Weitere Informationen zur Funktionsweise der Bereitstellung finden Sie unter Über Python-Objekt bereitstellen.

  1. Führen Sie das folgende Python-Skript aus, um Ihren Agenten zu serialisieren und die Bereitstellungsartefakte in Cloud Storage bereitzustellen:

    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. Erstellen Sie die Dateien variables.tf, main.tf und outputs.tf in Ihrem Verzeichnis terraform/, die auf die bereitgestellten Cloud Storage-URIs verweisen:

    Eingabevariablen (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"
}
    Ressourcenspezifikationen (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"
    }
  }
}
    Ressourcenausgaben (terraform/outputs.tf)
    output "package_agent_id" {
  value       = google_vertex_ai_reasoning_engine.package_agent.id
  description = "Resource ID of the deployed package agent"
}

Umgebungsvariablen und Secrets konfigurieren

Vor der Bereitstellung können Sie ein benutzerdefiniertes Laufzeitdienstkonto an Ihren Agenten anhängen und Umgebungsvariablen (env) oder Secret Manager-Referenzen (secret_env) übergeben.

Im folgenden Beispiel werden Umgebungsvariablen (LOCATION, MODEL, MODEL_REGION) konfiguriert und ein API-Schlüssel wird über die Datei terraform/main.tf sicher von Secret Manager an das Laufzeitdienstkonto übergeben:

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

KI-Agenten-Gateway konfigurieren

Wenn Sie Traffic zwischen Agent Runtime und externen APIs oder Clients über Agent Gateway weiterleiten möchten, konfigurieren Sie den Block agent_gateway_config in deployment_spec mit dem Anbieter google-beta.

Vollständige Bereitstellungsbeispiele und Parameterdetails für das Routing von Agent-to-Anywhere (ausgehend) und Client-to-Agent (eingehend) finden Sie unter Laufzeittraffic über Agent Gateway weiterleiten.

Zentrale Gateway-Governance für mehrere Projekte

In Multi-Projekt-Architekturen für Unternehmen können Sie ein zentrales Governance-Projekt verwalten, in dem Agent Gateway, Agent Registry und Model Armor gehostet werden. Gleichzeitig können Sie Runtime-Arbeitslasten in separaten Projektordnern in Ihrer Organisation mit Terraform bereitstellen:

  • Zentrales Agent Gateway und Autorisierungsrichtlinien: Stellen Sie google_network_services_agent_gateway, google_network_services_authz_extension und google_network_security_authz_policy im zentralen Governance-Projekt bereit. Weitere Informationen finden Sie unter Agent Gateway einrichten.
  • Projektübergreifender Dienst-Agent-Zugriff: Gewähren Sie ar_agw_cross_project_sa (google_project_iam_custom_role) im zentralen Gateway-Projekt dem Laufzeit-Dienst-Agent jedes Arbeitslastprojekts mit google_project_iam_member. Laufzeit-Traffic über das Agent Gateway weiterleiten
  • Zentrale Registry und Richtlinien für ausgehenden Traffic: Registrieren Sie projektübergreifende Agenten und Tools in der Registry des zentralen Projekts mit google_agent_registry_service und gewähren Sie roles/iap.egressor mit google_iap_agent_registry_*-Ressourcen. Siehe IAM-Agent-Richtlinien erstellen.
  • Model Armor-Vorlagen und Mindesteinstellungen: Erzwingen Sie Sicherheitsschwellenwerte in Ihrer Organisation oder in Ordnern mit google_model_armor_floorsetting und google_model_armor_template. Weitere Informationen finden Sie unter Autorisierung an Model Armor delegieren.

Ausführung und Lebenszyklus

Führen Sie den Standard-Terraform-Lebenszyklus aus, um Ihre Agentenressourcen zu planen, bereitzustellen, aufzurufen und zu löschen.

Terraform-Konfiguration anwenden

Stellen Sie den Agenten bereit, indem Sie die Terraform-Konfiguration anwenden:

  1. Wechseln Sie in Ihr Terraform-Verzeichnis (z. B. cd weather-agent-byoc/terraform):

    cd weather-agent-byoc/terraform

  2. Initialisieren Sie das Arbeitsverzeichnis:

    terraform init

  3. Sehen Sie sich eine Vorschau des Bereitstellungsplans an:

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

  4. Wenden Sie die Konfiguration an, um den Agenten bereitzustellen:

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

Bereitgestellten KI-Agenten abfragen

Nachdem Terraform die google_vertex_ai_reasoning_engine-Ressource bereitgestellt hat, senden Sie eine HTTP-POST-Anfrage an den :streamQuery?alt=sse-Endpunkt, um Antwortereignisse in Echtzeit mithilfe von Server-Sent Events (SSE) zu streamen:

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"
  • OAuth-Zugriffstoken: Authorization: Bearer $(gcloud auth print-access-token) generiert ein kurzlebiges OAuth 2.0-Zugriffstoken mit Ihren lokalen Cloud de Confiance by S3NS -Anmeldedaten.
  • JSON-input-Envelope: Der Anfragetext erfordert eine JSON-Nutzlast, die ein input-Objekt enthält. Wenn Sie explizite Klassenmethoden wie async_stream_query aufrufen, geben Sie den Parameter "class_method" zusammen mit "input" an.
  • Antwortnutzlast: Antworten werden kontinuierlich als data: { ... }-SSE-Blöcke (Server-Sent Event) bereitgestellt.

Agentenressourcen löschen

Wenn Sie Ressourcen bereinigen und unerwartete Abrechnungsgebühren vermeiden möchten, wechseln Sie in Ihr terraform/-Verzeichnis (z. B. cd weather-agent-byoc/terraform) und führen Sie terraform destroy aus:

cd weather-agent-byoc/terraform
terraform destroy -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"

Nächste Schritte