Provisionar agentes com o Terraform

É possível usar o Terraform para provisionar e gerenciar instâncias do Agent Runtime de forma declarativa. Ao implantar agentes com o Terraform, você gerencia o google_vertex_ai_reasoning_engine recurso usando o provedor oficial Google Cloud do Terraform (provedor GA ou provedor Beta).

As instruções nesta página correspondem à implementação de agente em contêineres de exemplo descrita no codelab Implantar um agente em contêineres com o Agent Runtime.

Pré-requisitos

Antes de usar o Terraform para implantar um agente, conclua a seguinte configuração:

1. Instale o Terraform (versão 1.5.0 ou mais recente) e consulte a documentação oficial do HashiCorp Terraform Registry para o recurso google_vertex_ai_reasoning_engine (provedor GA e provedor Beta).
2. Configure seu Google Cloud ambiente e ative a API Vertex AI (aiplatform.googleapis.com), a API Artifact Registry (artifactregistry.googleapis.com) e a API Cloud Build (cloudbuild.googleapis.com).

3. Autentique seu ambiente local usando Google Cloud credenciais:

   gcloud auth application-default login

4. Para manter o código do aplicativo separado do gerenciamento de infraestrutura, organize o espaço de trabalho do agente em diretórios dedicados de aplicativos e do 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 outputs
   

   • Arquivos de aplicativos (main.py, requirements.txt, Dockerfile): contêm a lógica do agente, o wrapper da estrutura da Web (como o FastAPI ou o ADK App), as dependências do Python e as instruções de build do contêiner.

   • Diretório do Terraform (terraform/): contém todos os arquivos de configuração do Terraform usados para provisionar recursos:

     • variables.tf: declara variáveis de entrada, como project_id, location, repository_name e image_tag.
     • main.tf: declara configurações do provedor, variáveis locais, vinculações de papéis do IAM e especificações de recursos google_vertex_ai_reasoning_engine.
     • outputs.tf: exporta atributos de recursos provisionados, como o ID do Agent Runtime e o nome completo do recurso, após a implantação.

5. Conceda os papéis do IAM apropriados, dependendo de quem está executando a implantação:

   • Desenvolvedor humano ou conta de serviço de CI/CD que executa comandos terraform apply e de build local.

     Clique para ver as permissões necessárias

     • Usuário da Vertex AI (roles/aiplatform.user) ou Administrador da Vertex AI (roles/aiplatform.admin): autoriza o implantador a executar operações RPC do plano de controle do Agent Runtime (CreateReasoningEngine, UpdateReasoningEngine, DeleteReasoningEngine).
     • Usuário da conta de serviço (roles/iam.serviceAccountUser): concedido na conta de serviço de ambiente de execução personalizada (google_service_account.agent_runtime_sa) anexada ao agente. Autoriza o implantador a anexar a identidade da conta de serviço ao recurso google_vertex_ai_reasoning_engine provisionado.
     • Administrador de objetos do Storage (roles/storage.objectAdmin) ou Leitor de objetos do Storage (roles/storage.objectViewer): necessário ao usar o preparo de pacotes do Python (package_spec) para fazer upload ou ler pickles de agentes serializados (agent.pkl) e manifestos de dependência no Cloud Storage.
     • Gravador do Artifact Registry (roles/artifactregistry.writer): necessário ao pré-criar e enviar imagens de contêiner personalizadas (docker push) para repositórios do Artifact Registry.

   • Agente de serviço do Agent Runtime gerenciado pelo sistema (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

     Clique para ver as permissões necessárias

     • Leitor do Artifact Registry (roles/artifactregistry.reader): concede à infraestrutura da plataforma do Agent Runtime em segundo plano permissão para autenticar com o Artifact Registry e extrair a imagem de contêiner personalizada durante a implantação do pod e as inicializações a frio do contêiner.

     Importante:no Terraform, é necessário gerenciar explicitamente a vinculação do IAM para o agente de serviço e garantir que o recurso google_vertex_ai_reasoning_engine inclua uma referência depends_on à vinculação do IAM. Caso contrário, o provisionamento do pod poderá falhar com IMAGE_PULL_BACKOFF devido a uma disputa.

Preparar para a implantação

O Terraform oferece suporte aos seguintes caminhos de implantação para o Agent Runtime:

• Implantar de uma imagem de contêiner pré-criada: pré-crie e envie uma imagem de contêiner para o Artifact Registry ({region}-docker.pkg.dev/...) e implante-a usando container_spec. Use esse método quando precisar de controle total sobre o processo de build do contêiner, imagens de base personalizadas ou menor latência de implantação.
• Implantar de arquivos de origem ou Dockerfile: implante o agente diretamente de arquivos de origem locais ou de um Dockerfile. O Agent Runtime cria e provisiona a imagem do contêiner automaticamente, sem exigir o gerenciamento manual de imagens.
• Implantar usando especificações de pacote do Python : implante usando (package_spec) preparado no Cloud Storage. O Agent Runtime cria e provisiona a imagem do contêiner automaticamente, sem exigir o gerenciamento manual de imagens.

Implantar de uma imagem do contêiner pré-criada

Se você pré-criar e enviar imagens de contêiner para o Artifact Registry (por exemplo, para incluir bibliotecas de sistema personalizadas, otimizar o desempenho de inicialização a frio ou aplicar controles de build de imagem organizacional), poderá implantar usando container_spec. Para detalhes sobre os requisitos de imagem, consulte Implantar de uma imagem de contêiner.

As imagens de contêiner precisam ser armazenadas no Artifact Registry ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}), ouvir na porta 8080 (ou uma porta personalizada especificada em container_spec) e estar em conformidade com o contrato de ambiente de execução.

1. Crie a imagem do contêiner localmente e envie-a para o repositório do 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. Configure a imagem de contêiner pré-criada para implantação do Terraform. A configuração a seguir demonstra a implantação de uma imagem de contêiner pré-criada hospedada no Artifact Registry criando os arquivos variables.tf, main.tf e outputs.tf no diretório terraform/:

   Variáveis de entrada (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"
   }
   

   Especificações de recursos (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]
   }
   

   Saídas de recursos (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"
   }
   

Implantar do Dockerfile ou do repositório de origem

Ao implantar de um Dockerfile, especifique o arquivo de origem em source_code_spec e defina um bloco image_spec {} vazio para instruir o Agent Runtime a criar a imagem do contêiner usando o Dockerfile. O contêiner criado no Dockerfile precisa aderir ao contrato de ambiente de execução.

Para mais detalhes sobre como a implantação funciona, consulte Implantar do Dockerfile ou Implantar de arquivos de origem.

1. Compacte o código do aplicativo (main.py), o manifesto de dependência do Python (requirements.txt) e as instruções de build do contêiner (Dockerfile) em um arquivo tar compactado.

2. Execute o seguinte comando no diretório raiz do aplicativo. O exemplo usa o diretório raiz weather-agent-byoc/ e o arquivo tar weather_agent_source.tar.gz:

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

   Observação: Os arquivos main.py, requirements.txt e Dockerfile precisam residir diretamente no nível raiz do arquivo tar (não aninhados em um diretório pai como weather-agent-byoc/main.py). Quando o Agent Runtime provisiona o contêiner de build, a API Cloud Build descompacta weather_agent_source.tar.gz diretamente na raiz do espaço de trabalho de build e espera que Dockerfile esteja presente em ./Dockerfile durante a compilação.

3. Crie os arquivos variables.tf, main.tf e outputs.tf no diretório terraform/:

   Variáveis de entrada (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"
   }
   

   Especificações de recursos (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" }
       ])
     }
   }
   

   Saídas de recursos (terraform/outputs.tf)

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

Implantar usando a especificação de pacote do Python

Se o agente for criado usando objetos do SDK do Python ou aplicativos em pickle (como ADK, LangChain ou agentes personalizados do Python), você poderá preparar o agente serializado (.pkl) e a configuração de dependência (requirements.txt) em um bucket do Cloud Storage e referenciá-los usando package_spec.

Para mais detalhes sobre como a implantação funciona, consulte Implantar de um objeto Python.

1. Execute o script Python a seguir para serializar o agente e preparar os artefatos de implantação no 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. Crie os arquivos variables.tf, main.tf e outputs.tf no diretório terraform/ referenciando os URIs preparados do Cloud Storage:

   Variáveis de entrada (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"
   }
   

   Especificações de recursos (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"
       }
     }
   }
   

   Saídas de recursos (terraform/outputs.tf)

   output "package_agent_id" {
     value       = google_vertex_ai_reasoning_engine.package_agent.id
     description = "Resource ID of the deployed package agent"
   }
   

Configurar variáveis de ambiente e secrets

Antes da implantação, é possível anexar uma conta de serviço de ambiente de execução personalizada ao agente e transmitir variáveis de ambiente (env) ou referências do Secret Manager (secret_env).

O exemplo a seguir configura variáveis de ambiente (LOCATION, MODEL, MODEL_REGION) e transmite uma chave de API com segurança do Secret Manager para a conta de serviço de ambiente de execução pelo arquivo 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.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
  ]
}

Execução e ciclo de vida

Execute o ciclo de vida padrão do Terraform para planejar, implantar, invocar e destruir os recursos do agente.

Aplicar a configuração do Terraform

Implante o agente aplicando a configuração do Terraform:

1. Mude para o diretório do Terraform (por exemplo, cd weather-agent-byoc/terraform):

   cd weather-agent-byoc/terraform

2. Inicialize o diretório de trabalho:

   terraform init

3. Visualize o plano de implantação:

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

4. Aplique a configuração para provisionar o agente:

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

consultar o agente implantado

Depois que o Terraform provisionar o recurso google_vertex_ai_reasoning_engine, envie uma solicitação HTTP POST para o endpoint :streamQuery?alt=sse para transmitir eventos de resposta em tempo real usando eventos enviados pelo servidor (SSE):

Observação: Para outros métodos de consulta, consulte Usar um agente do 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"

• Token de acesso OAuth: Authorization: Bearer $(gcloud auth print-access-token) gera um token de acesso OAuth 2.0 de curta duração usando suas credenciais locais Google Cloud .
• Envelope JSON input: o corpo da solicitação exige um payload JSON que contenha um objeto input. Ao chamar métodos de classe explícitos (como async_stream_query), inclua o parâmetro "class_method" junto com "input".
• Payload de resposta: as respostas são entregues continuamente como blocos de eventos enviados pelo servidor (SSE) data: { ... }.

Destruir recursos do agente

Para limpar os recursos e evitar cobranças inesperadas, mude para o diretório terraform/ (por exemplo, cd weather-agent-byoc/terraform) e execute terraform destroy:

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

A seguir

• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (GA) (em inglês)
• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (Beta) (em inglês)
• Google Cloud IA generativa — Tutorial de implantação do Agent Runtime do Terraform (GitHub)
• Fórum de desenvolvedores do Google — Implante o Agent Runtime com o Terraform da maneira empresarial (em inglês)