1. Panoramica
Agent Runtime (in precedenza Agent Engine) offre un ambiente di runtime gestito progettato per eseguire il deployment, l'esecuzione e lo scaling degli agenti AI in modo efficace. Per impostazione predefinita, la piattaforma raggruppa automaticamente il codice sorgente e le dipendenze durante il processo di deployment.
Tuttavia, i carichi di lavoro aziendali spesso richiedono la proprietà completa dell'ambiente di runtime. Per supportare questa funzionalità, Agent Runtime fornisce la funzionalità Bring Your Own Container(BYOC), che ti consente di eseguire il deployment di immagini container personalizzate predefinite.
Questo codelab descrive il processo end-to-end per il containerizzazione di un agente creato con Google Agent Development Kit (ADK), la configurazione delle autorizzazioni Google Cloud necessarie e il deployment in Agent Runtime utilizzando l'SDK Python o Terraform.
Questo codelab ti guiderà attraverso:
- Creazione di un agente Python utilizzando Google Agent Development Kit (ADK).
- Inserimento dell'agente in un'applicazione FastAPI.
- Containerizzazione dell'applicazione con Docker.
- Configurazione delle autorizzazioni Google Cloud.
- Deployment e test dell'agente containerizzato su Agent Runtime.
Flusso di creazione e deployment
Il seguente diagramma illustra il flusso di lavoro dei passaggi di build e deployment che eseguirai manualmente in questo codelab:
Cosa ti serve
- Un progetto Google Cloud con la fatturazione abilitata.
- Accesso a Cloud Shell (consigliato) o a un ambiente di sviluppo locale con
gcloudedockerinstallati. - Conoscenza di base di Python e Docker.
2. Configurazione dell'ambiente
Prima di iniziare, devi abilitare le API necessarie e configurare l'ambiente.
Passaggio 1: apri Cloud Shell
Fai clic sul pulsante Attiva Cloud Shell in alto a destra nella console Google Cloud.
Passaggio 2: configura le variabili di ambiente
In Cloud Shell, imposta l'ID progetto e definisci le variabili di ambiente chiave utilizzate in questo codelab. Sostituisci "YOUR_PROJECT_ID" con l'ID del tuo progetto Google Cloud effettivo:
gcloud config set project "YOUR_PROJECT_ID"
export PROJECT_ID=$(gcloud config get-value project)
export LOCATION="us-central1"
export MODEL="gemini-3.1-flash-lite"
export MODEL_REGION="global"
Queste variabili configurano le impostazioni di deployment di destinazione:
PROJECT_ID: l'identificatore univoco del tuo progetto Google Cloud in cui risiederanno tutte le risorse di Gemini Enterprise Agent Platform e Artifact Registry.LOCATION: la regione geografica (ad es.us-central1) che ospita i repository e i carichi di lavoro di runtime.MODEL: La versione del modello Gemini (ad es.gemini-3.1-flash-lite) caricata dal contesto dell'agente.MODEL_REGION: la regione dell'endpoint del modello. Imposta questo valore su"global"per richiamare il modello Gemini dagli endpoint globali.
Passaggio 3: attivazione delle API
Abilita le API Google Cloud richieste:
gcloud services enable \
aiplatform.googleapis.com \
cloudbuild.googleapis.com \
compute.googleapis.com \
artifactregistry.googleapis.com \
storage.googleapis.com
Passaggio 4: installa l'SDK
Installa l'SDK Vertex AI con il supporto di Agent Engine e ADK:
pip install --upgrade "google-cloud-aiplatform[agent_engines,adk]>=1.144"
3. Configurazione dei file di origine
In questo passaggio creerai la struttura e il codice per il tuo agente.
Panoramica della struttura delle directory
Al termine di questo codelab, i tuoi file saranno organizzati nella seguente gerarchia del workspace:
weather-agent-byoc/
├── Dockerfile # Container definition
├── deploy_byoc.py # Python SDK deployment script
├── main.py # FastAPI server wrapper
├── query_agent.py # Verify / query script
├── requirements.txt # Python dependencies
│
├── weather_agent/ # Agent source module
│ ├── __init__.py # Package declaration
│ ├── agent.py # Agent & mock tools logic
│ └── config.json # Environment config variables
│
└── terraform/ # Terraform configuration files
├── main.tf
├── outputs.tf
├── providers.tf
├── terraform.tfvars
└── variables.tf
Passaggio 1: crea le directory
Inizia dalla home directory e crea la struttura dello spazio di lavoro:
cd ~
mkdir -p weather-agent-byoc/weather_agent
cd weather-agent-byoc
Passaggio 2: crea il file di configurazione
Esegui questo comando in Cloud Shell per scrivere i parametri di configurazione direttamente in weather_agent/config.json. Questo comando sostituisce automaticamente le variabili con i valori dell'ambiente:
cat <<EOF > weather_agent/config.json
{
"PROJECT_ID": "${PROJECT_ID}",
"LOCATION": "${LOCATION}",
"MODEL": "${MODEL}",
"MODEL_REGION": "${MODEL_REGION}"
}
EOF
Passaggio 3: definisci l'agente
Esegui il seguente script per scrivere la configurazione dell'agente e la logica dello strumento di simulazione in weather_agent/agent.py:
cat << 'EOF' > weather_agent/agent.py
import json
import random
from google.adk.agents import Agent
from google.adk.models.google_llm import Gemini
from functools import cached_property
from google.genai import Client
# Load config
llm_config = json.load(open("weather_agent/config.json"))
PROJECT_ID = llm_config["PROJECT_ID"]
MODEL = llm_config["MODEL"]
MODEL_REGION = llm_config["MODEL_REGION"]
# Override Gemini class for global endpoint compatibility
class GlobalGemini(Gemini):
@cached_property
def api_client(self) -> Client:
return Client(vertexai=True, location="global")
# Define Tool
def get_temperature(place: str) -> str:
'''Returns the current temperature of a given place.
Args:
place: The name of the city or location.
Returns:
str: A string describing the temperature.
'''
temp = random.randint(-10, 40)
return f"The current temperature in {place} is {temp}°C."
# Initialize LLM
llm_model = GlobalGemini(model=MODEL) if MODEL_REGION == "global" else Gemini(model=MODEL)
# Initialize Agent
root_agent = Agent(
model=llm_model,
name='weather_agent',
description='An agent that provides temperature information for locations.',
instruction='You are a helpful assistant that can provide the current temperature for any given place using the get_temperature tool.',
tools=[get_temperature],
)
EOF
Crea un file __init__.py vuoto per trasformare weather_agent in un pacchetto Python:
touch weather_agent/__init__.py
Passaggio 4: crea il wrapper FastAPI
Esegui questo script per scrivere la configurazione del punto di ingresso del server FastAPI in main.py:
cat << 'EOF' > main.py
import inspect
import json
import logging
import os
from typing import Any, Dict, Optional
import uvicorn
import vertexai
from weather_agent.agent import root_agent
from fastapi import FastAPI, encoders, responses
from pydantic import BaseModel
from vertexai import agent_engines
app = FastAPI()
config_json = json.load(open("weather_agent/config.json"))
PROJECT_ID = config_json["PROJECT_ID"]
LOCATION = config_json["LOCATION"]
MODEL_REGION = config_json["MODEL_REGION"]
class QueryRequest(BaseModel):
input: Optional[Dict[str, Any]] = None
class_method: Optional[str] = None
vertexai.init(project=PROJECT_ID, location=MODEL_REGION)
adk_app = agent_engines.AdkApp(agent=root_agent)
def _encode_chunk_to_json(chunk):
try:
json_chunk = encoders.jsonable_encoder(chunk)
return json.dumps(json_chunk) + "\n"
except Exception:
logging.exception("Failed to encode chunk")
return None
async def json_generator(output):
async for chunk in output:
encoded_chunk = _encode_chunk_to_json(chunk)
if encoded_chunk is None:
break
yield encoded_chunk
async def _invoke_callable_or_raise(invocation_callable, invocation_payload):
if inspect.iscoroutinefunction(invocation_callable):
return await invocation_callable(**invocation_payload)
else:
return invocation_callable(**invocation_payload)
@app.post("/api/reasoning_engine")
async def query(request: QueryRequest) -> responses.JSONResponse:
method = getattr(adk_app, request.class_method)
output = await _invoke_callable_or_raise(method, request.input or {})
try:
json_serialized_content = encoders.jsonable_encoder({"output": output})
except ValueError as encoding_error:
logging.exception("Failed to encode response")
raise encoding_error
return responses.JSONResponse(content=json_serialized_content)
@app.post("/api/stream_reasoning_engine")
async def stream_query(request: QueryRequest) -> responses.StreamingResponse:
method = getattr(adk_app, request.class_method)
output = await _invoke_callable_or_raise(method, request.input or {})
return responses.StreamingResponse(
content=json_generator(output),
media_type="application/json",
)
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF
Passaggio 5: definisci le dipendenze
Scrivi le dipendenze Python richieste in requirements.txt:
cat << 'EOF' > requirements.txt
fastapi
uvicorn
vertexai
google-cloud-aiplatform[agent_engines,adk]>=1.144
pydantic
EOF
4. Containerizzazione
Ora definisci come verrà creato il pacchetto dell'agente in un container.
Passaggio 1: crea Dockerfile
Crea il file Dockerfile nella directory radice del progetto per specificare come viene creata l'applicazione FastAPI:
cat << 'EOF' > Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY weather_agent/ /app/weather_agent/
COPY main.py .
COPY requirements.txt .
RUN pip install -r requirements.txt
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"]
EOF
5. Configura Artifact Registry e Cloud Build
Hai bisogno di un repository per archiviare l'immagine container e delle autorizzazioni per eseguirne il push.
Passaggio 1: crea il repository
Definisci il nome del repository e crea un repository Docker all'interno di Artifact Registry utilizzando le variabili di ambiente definite durante la configurazione:
export REPOSITORY_NAME="agents-repo"
gcloud artifacts repositories create $REPOSITORY_NAME \
--project=$PROJECT_ID \
--repository-format=docker \
--location=$LOCATION \
--description="Docker repository for Agents"
Passaggio 2: configura le autorizzazioni dell'account di servizio
Concedi al service account Compute predefinito l'autorizzazione per eseguire il push delle immagini in Artifact Registry.
Innanzitutto, recupera il numero di progetto:
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
Concedi i ruoli:
# Allow pushing to Artifact Registry
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer" \
--condition=None
# Allow Cloud Build to read storage objects
gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.objectViewer" \
--condition=None
Passaggio 3: concedi le autorizzazioni agli agenti di servizio
Concedi l'accesso in lettura ad Artifact Registry agli agenti di servizio AI Platform e Reasoning Engine:
gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
--role="roles/artifactregistry.reader" --condition=None
gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
--role="roles/artifactregistry.reader" --condition=None
Passaggio 4: crea e invia l'immagine
Utilizza Cloud Build per creare ed eseguire il push dell'immagine container:
gcloud builds submit \
--project=$PROJECT_ID \
--region=$LOCATION \
--tag $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/weather-agent-image:latest \
.
6. Esegui il deployment dell'agente con l'SDK
Ora che le autorizzazioni sono configurate, puoi eseguire il deployment del container personalizzato.
Passaggio 1: esegui il deployment dell'agente BYOC
Crea il file Python deploy_byoc.py nella directory radice del progetto per eseguire il deployment del container ospitato nel registro in Agent Runtime:
cat << 'EOF' > deploy_byoc.py
import json
import os
import vertexai
from google.cloud import aiplatform
config = json.load(open("weather_agent/config.json"))
PROJECT_ID = config["PROJECT_ID"]
LOCATION = config["LOCATION"]
REPOSITORY_NAME = "agents-repo"
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
image_uri = f"{LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY_NAME}/weather-agent-image:latest"
print(f"Deploying custom container agent from {image_uri}...")
remote_agent = client.agent_engines.create(
config={
"display_name": "byoc_weather_agent",
"description": "BYOC weather agent from custom container",
"container_spec": {
"image_uri": image_uri
},
"class_methods": [
# For convenience to interact with the agent through the Python SDK
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/use-an-adk-agent#supported-operations
{"api_mode": "", "name": "get_session"},
{"api_mode": "", "name": "list_sessions"},
{"api_mode": "", "name": "create_session"},
{"api_mode": "", "name": "delete_session"},
{"api_mode": "async", "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": "stream", "name": "stream_query"},
{"api_mode": "async_stream", "name": "async_stream_query"},
{"api_mode": "async_stream", "name": "streaming_agent_run_with_events"},
],
"agent_framework": "google-adk",
},
)
print(f"Agent successfully deployed!")
print(f"Resource Name: {remote_agent.api_resource.name}")
# Save resource name for testing
with open("agent_resource_name.txt", "w") as f:
f.write(remote_agent.api_resource.name)
EOF
Esegui lo script di deployment per eseguire il deployment dell'agente su Agent Runtime:
python3 deploy_byoc.py
7. Esegui il deployment dell'agente con Terraform
In alternativa, puoi eseguire il deployment dello stesso agente containerizzato utilizzando Terraform. Questa opzione è consigliata per gli ambienti di produzione per gestire l'infrastruttura come codice.
Passaggio 1: vai alla directory Terraform
Crea una directory terraform nella directory root del progetto e vai alla directory:
mkdir -p terraform
cd terraform
Passaggio 2: crea la configurazione dei fornitori
Esegui lo script seguente per scrivere il mapping dei provider in providers.tf:
cat << 'EOF' > providers.tf
terraform {
required_providers {
google = {
source = "hashicorp/google"
version = ">= 5.28.0"
}
}
}
provider "google" {
project = var.project_id
region = var.location
}
EOF
Passaggio 3: crea la definizione delle variabili
Scrivi il blocco di descrizione degli input per variables.tf:
cat << 'EOF' > variables.tf
variable "project_id" {
type = string
description = "The Google Cloud Project ID"
}
variable "location" {
type = string
description = "The region to deploy the reasoning engine"
default = "us-central1"
}
variable "repository_name" {
type = string
description = "The Artifact Registry repository name"
default = "agents-repo"
}
variable "image_tag" {
type = string
description = "The tag of the container image to deploy"
default = "latest"
}
EOF
Passaggio 4: crea la configurazione principale
Scrivi i parametri principali di definizione delle risorse in main.tf:
cat << 'EOF' > main.tf
locals {
class_methods = [
{"api_mode" = "", "name" = "get_session"},
{"api_mode" = "", "name" = "list_sessions"},
{"api_mode" = "", "name" = "create_session"},
{"api_mode" = "", "name" = "delete_session"},
{"api_mode" = "async", "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" = "stream", "name" = "stream_query"},
{"api_mode" = "async_stream", "name" = "async_stream_query"},
{"api_mode" = "async_stream", "name" = "streaming_agent_run_with_events"}
]
}
# define the resource with the BYOC configuration, set agent_framework to "google-adk" to enable interactive features on the console.
resource "google_vertex_ai_reasoning_engine" "byoc_weather_agent" {
display_name = "byoc_weather_agent_tf"
description = "BYOC weather agent deployed via Terraform"
project = var.project_id
location = var.location
spec {
class_methods = jsonencode(local.class_methods)
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}"
}
}
}
EOF
Passaggio 5: crea la definizione degli output
Scrivi il blocco di output in outputs.tf:
cat << 'EOF' > outputs.tf
output "reasoning_engine_id" {
value = google_vertex_ai_reasoning_engine.byoc_weather_agent.id
description = "The ID of the deployed reasoning engine"
}
output "reasoning_engine_resource_name" {
value = google_vertex_ai_reasoning_engine.byoc_weather_agent.id
description = "The resource name of the deployed reasoning engine"
}
EOF
Passaggio 6: crea il file dei valori delle variabili (tfvars)
Esegui il deployment in modo dinamico senza modificare i segnaposto inserendo le variabili di ambiente direttamente in terraform.tfvars:
cat <<EOF > terraform.tfvars
project_id = "${PROJECT_ID}"
location = "${LOCATION}"
repository_name = "agents-repo"
image_tag = "latest"
EOF
Passaggio 7: inizializza e applica
Inizializza Terraform e applica la configurazione:
terraform init
terraform apply
Conferma l'applicazione digitando yes quando ti viene richiesto.
Una volta completata, Terraform restituisce il nome della risorsa. Acquisiscilo in modo programmatico in agent_resource_name.txt e torna alla cartella radice:
terraform output -raw reasoning_engine_resource_name > ../agent_resource_name.txt
cd ..
8. Interrogare l'agente
Verifica che l'agente sia in esecuzione e risponda.
Passaggio 1: crea lo script di query
Scrivi lo script di verifica per query_agent.py utilizzando un controllo della configurazione dell'installazione dinamica per recuperare le coordinate della posizione:
cat << 'EOF' > query_agent.py
import json
import os
import requests
from google import auth as google_auth
from google.auth.transport import requests as google_requests
# Load config coordinates directly
config_json = json.load(open("weather_agent/config.json"))
LOCATION = config_json["LOCATION"]
PROJECT_ID = config_json["PROJECT_ID"]
# Load agent resource name
with open("agent_resource_name.txt", "r") as f:
agent_resource_name = f.read().strip()
def get_identity_token():
credentials, _ = google_auth.default()
auth_request = google_requests.Request()
credentials.refresh(auth_request)
return credentials.token
# Access the agent at the fastapi endpoint that was specified in main.py
url = f"https://{LOCATION}-aiplatform.googleapis.com/v1/{agent_resource_name}/api/stream_reasoning_engine"
payload = {
"class_method": "async_stream_query",
"input": {
"user_id": "codelab_test_user",
"message": "What is the temperature in Tokyo?",
},
}
print(f"Sending query to {url}...")
response = requests.post(
url,
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {get_identity_token()}",
},
data=json.dumps(payload),
stream=True,
)
for chunk in response.iter_content(chunk_size=8192):
if chunk:
print(chunk.decode('utf-8'))
EOF
Esegui lo script della query:
python3 query_agent.py
Dovresti vedere l'output in streaming dall'agente, inclusa la temperatura simulata per Tokyo.
Passaggio 2: utilizza la console
- Vai all'agente di cui è stato eseguito il deployment selezionando Agent Platform > Agenti > Deployment per filtrare l'elenco degli agenti.
- Seleziona Playground dalla dashboard dell'agente.
- Crea una nuova sessione e digita la query per verificare se l'agente risponde alle richieste come mostrato.
9. Esegui la pulizia
Per evitare addebiti, libera spazio dalle risorse che hai creato.
Se hai eseguito il deployment utilizzando Terraform, passa alla directory terraform ed esegui l'azione di eliminazione:
cd ~/weather-agent-byoc/terraform
terraform destroy
cd ..
Se hai eseguito il deployment utilizzando l'SDK, crea lo script per eliminare l'agente di cui è stato eseguito il deployment:
cat << 'EOF' > delete_agent.py
import json
import os
import vertexai
from google.cloud import aiplatform
config = json.load(open("weather_agent/config.json"))
PROJECT_ID = config["PROJECT_ID"]
LOCATION = config["LOCATION"]
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
with open("agent_resource_name.txt", "r") as f:
agent_resource_name = f.read().strip()
# 1. Delete the Agent
# Note: We retrieve the list first to ensure we delete the ones created in this session
try:
page_size = 100
reasoning_engines = client.agent_engines.list()
for engine in reasoning_engines:
if agent_resource_name in engine.api_resource.name:
print(f"Deleting Reasoning Engine: {engine.api_resource.name}")
engine.delete(force=True)
except Exception as e:
print(f"Error deleting reasoning engines: {e}")
EOF
Esegui lo script per eliminare l'agente:
python3 delete_agent.py
Per pulire il resto delle risorse, torna alla directory home ed esegui questi comandi in Cloud Shell:
cd ~
# 1. Delete the Artifact Registry Repository
gcloud artifacts repositories delete $REPOSITORY_NAME --location=$LOCATION --quiet
# 2. Clean up files (Optional)
rm -rf ~/weather-agent-byoc
10. Conclusione
Complimenti! Hai eseguito correttamente la containerizzazione e il deployment di un agente AI su Agent Runtime utilizzando BYOC.
Hai imparato a:
- Utilizza ADK per definire un agente e eseguirne il wrapping utilizzando FastAPI.
- Crea un Dockerfile e crea immagini utilizzando Cloud Build.
- Gestisci le autorizzazioni IAM per Agent Runtime.
- Esegui il deployment del container personalizzato utilizzando sia l'SDK Python sia Terraform.
- Testa ed esegui query sull'agente di cui hai eseguito il deployment.