1. Übersicht
Agent Runtime (ehemals Agent Engine) bietet eine verwaltete Laufzeitumgebung, die für die Bereitstellung, Ausführung und Skalierung von KI-Agenten entwickelt wurde. Standardmäßig bündelt die Plattform Ihren Quellcode und Ihre Abhängigkeiten während des Bereitstellungsprozesses automatisch.
Bei Arbeitslasten von Unternehmen ist jedoch oft die vollständige Kontrolle über die Laufzeitumgebung erforderlich. Um dies zu unterstützen, bietet Agent Runtime die Funktion Bring Your Own Container(BYOC), mit der Sie vorgefertigte benutzerdefinierte Container-Images bereitstellen können.
In diesem Codelab wird der End-to-End-Prozess für die Containerisierung eines mit dem Google Agent Development Kit (ADK) erstellten Agenten, die Konfiguration der erforderlichen Google Cloud-Berechtigungen und die Bereitstellung in Agent Runtime mit dem Python SDK oder Terraform beschrieben.
In diesem Codelab erfahren Sie, wie Sie Folgendes tun:
- Einen Python-Agenten mit dem Google Agent Development Kit (ADK) erstellen
- Den Agenten in eine FastAPI -Anwendung einbinden
- Die Anwendung mit Docker containerisieren
- Google Cloud-Berechtigungen konfigurieren
- Den containerisierten Agenten in Agent Runtime bereitstellen und testen
Erstellungs- und Bereitstellungsablauf
Das folgende Diagramm veranschaulicht den Workflow der Erstellungs- und Bereitstellungsschritte, die Sie in diesem Codelab manuell ausführen:

Voraussetzungen
- Google Cloud-Projekt mit aktivierter Abrechnungsfunktion
- Zugriff auf Cloud Shell (empfohlen) oder eine lokale Entwicklungsumgebung mit installierter
gcloudunddocker - Grundlegende Kenntnisse in Python und Docker
2. Umgebung einrichten
Bevor Sie beginnen, müssen Sie die erforderlichen APIs aktivieren und Ihre Umgebung konfigurieren.
Schritt 1: Cloud Shell öffnen
Klicken Sie rechts oben in der Google Cloud Console auf die Schaltfläche Cloud Shell aktivieren.

Schritt 2: Umgebungsvariablen konfigurieren
Legen Sie in Cloud Shell Ihre Projekt-ID fest und definieren Sie wichtige Umgebungsvariablen, die in diesem Codelab verwendet werden. Ersetzen Sie "YOUR_PROJECT_ID" durch Ihre tatsächliche Google Cloud-Projekt-ID:
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"
Mit diesen Variablen werden die Einstellungen für die Zielbereitstellung konfiguriert:
PROJECT_ID: Die eindeutige ID Ihres Google Cloud-Projekts, in dem sich alle Ressourcen der Gemini Enterprise Agent Platform und Artifact Registry befinden.LOCATION: Die geografische Region (z.B.us-central1), in der Ihre Repositories und Laufzeit-Arbeitslasten gehostet werden.MODEL: Die Gemini-Modellversion (z.B.gemini-3.1-flash-lite), die vom Agentenkontext geladen wird.MODEL_REGION: Die Endpunktregion des Modells. Legen Sie hier"global"fest, um das Gemini-Modell über die globalen Endpunkte aufzurufen.
Schritt 3: APIs aktivieren
Aktivieren Sie die erforderlichen Google Cloud APIs:
gcloud services enable \
aiplatform.googleapis.com \
cloudbuild.googleapis.com \
compute.googleapis.com \
artifactregistry.googleapis.com \
storage.googleapis.com
Schritt 4: SDK installieren
Installieren Sie das Vertex AI SDK mit Unterstützung für Agent Engine und ADK:
pip install --upgrade "google-cloud-aiplatform[agent_engines,adk]>=1.144"
3. Quelldateien einrichten
In diesem Schritt erstellen Sie die Struktur und den Code für Ihren Agenten.
Übersicht über die Verzeichnisstruktur
Am Ende dieses Codelabs sind Ihre Dateien in der folgenden Arbeitsbereichshierarchie organisiert:
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
Schritt 1: Verzeichnisse erstellen
Beginnen Sie in Ihrem Basisverzeichnis und erstellen Sie die Arbeitsbereichsstruktur:
cd ~
mkdir -p weather-agent-byoc/weather_agent
cd weather-agent-byoc
Schritt 2: Konfigurationsdatei erstellen
Führen Sie den folgenden Befehl in Cloud Shell aus, um die Konfigurationsparameter direkt in weather_agent/config.json zu schreiben. Mit diesem Befehl werden die Variablen automatisch durch Ihre Umgebungswerte ersetzt:
cat <<EOF > weather_agent/config.json
{
"PROJECT_ID": "${PROJECT_ID}",
"LOCATION": "${LOCATION}",
"MODEL": "${MODEL}",
"MODEL_REGION": "${MODEL_REGION}"
}
EOF
Schritt 3: Agenten definieren
Führen Sie das folgende Skript aus, um die Agentenkonfiguration und die Mock-Tool-Logik in weather_agent/agent.py zu schreiben:
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
Erstellen Sie eine leere __init__.py-Datei, um weather_agent zu einem Python-Paket zu machen:
touch weather_agent/__init__.py
Schritt 4: FastAPI-Wrapper erstellen
Führen Sie das folgende Skript aus, um die Konfiguration des FastAPI-Servereinstiegspunkts in main.py zu schreiben:
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
Schritt 5: Abhängigkeiten definieren
Schreiben Sie die erforderlichen Python-Abhängigkeiten in requirements.txt:
cat << 'EOF' > requirements.txt
fastapi
uvicorn
vertexai
google-cloud-aiplatform[agent_engines,adk]>=1.144
pydantic
EOF
4. Containerisierung
Definieren Sie nun, wie Ihr Agent in einem Container verpackt wird.
Schritt 1: Dockerfile erstellen
Erstellen Sie die Datei Dockerfile im Stammverzeichnis Ihres Projekts, um anzugeben, wie Ihre FastAPI-Anwendung erstellt wird:
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. Artifact Registry und Cloud Build einrichten
Sie benötigen ein Repository, um das Container-Image zu speichern, und Berechtigungen, um es per Push zu übertragen.
Schritt 1: Repository erstellen
Definieren Sie den Repository-Namen und erstellen Sie ein Docker-Repository in Artifact Registry mit den während der Konfiguration definierten Umgebungsvariablen:
export REPOSITORY_NAME="agents-repo"
gcloud artifacts repositories create $REPOSITORY_NAME \
--project=$PROJECT_ID \
--repository-format=docker \
--location=$LOCATION \
--description="Docker repository for Agents"
Schritt 2: Dienstkontoberechtigungen konfigurieren
Gewähren Sie dem Standarddienstkonto von Compute Engine die Berechtigung, Images per Push in Artifact Registry zu übertragen.
Rufen Sie zuerst Ihre Projektnummer ab:
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
Weisen Sie die Rollen zu:
# 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
Schritt 3: Dienst-Agents Berechtigungen gewähren
Gewähren Sie den Dienst-Agents von AI Platform und Reasoning Engine Lesezugriff auf Artifact Registry:
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
Schritt 4: Image erstellen und per Push übertragen
Erstellen Sie mit Cloud Build das Container-Image und übertragen Sie es per Push:
gcloud builds submit \
--project=$PROJECT_ID \
--region=$LOCATION \
--tag $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/weather-agent-image:latest \
.
6. Agenten mit dem SDK bereitstellen
Nachdem die Berechtigungen konfiguriert wurden, können Sie Ihren benutzerdefinierten Container bereitstellen.
Schritt 1: BYOC-Agenten bereitstellen
Erstellen Sie die Python-Datei deploy_byoc.py im Stammverzeichnis Ihres Projekts, um den in der Registry gehosteten Container in Agent Runtime bereitzustellen:
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
Führen Sie das Bereitstellungsskript aus, um den Agenten in Agent Runtime bereitzustellen:
python3 deploy_byoc.py
7. Agenten mit Terraform bereitstellen
Alternativ können Sie denselben containerisierten Agenten mit Terraform bereitstellen. Dies wird für Produktionsumgebungen empfohlen, um die Infrastruktur als Code zu verwalten.
Schritt 1: Terraform-Verzeichnis aufrufen
Erstellen Sie im Stammverzeichnis Ihres Projekts ein Verzeichnis terraform und rufen Sie es auf:
mkdir -p terraform
cd terraform
Schritt 2: Anbieterkonfiguration erstellen
Führen Sie das folgende Skript aus, um die Anbieterzuordnung in providers.tf zu schreiben:
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
Schritt 3: Variablendefinition erstellen
Schreiben Sie den Block mit der Eingabebeschreibung in 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
Schritt 4: Hauptkonfiguration erstellen
Schreiben Sie die Parameter für die Hauptressourcendefinition 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
Schritt 5: Ausgabedefinition erstellen
Schreiben Sie den Ausgabeblock 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
Schritt 6: Datei mit Variablenwerten (tfvars) erstellen
Stellen Sie dynamisch bereit, ohne Platzhalter zu bearbeiten, indem Sie Umgebungsvariablen direkt an terraform.tfvars übergeben:
cat <<EOF > terraform.tfvars
project_id = "${PROJECT_ID}"
location = "${LOCATION}"
repository_name = "agents-repo"
image_tag = "latest"
EOF
Schritt 7: Initialisieren und anwenden
Initialisieren Sie Terraform und wenden Sie die Konfiguration an:
terraform init
terraform apply
Bestätigen Sie die Anwendung, indem Sie bei Aufforderung yes eingeben.
Nach Abschluss gibt Terraform den Ressourcennamen aus. Erfassen Sie ihn programmatisch in agent_resource_name.txt und kehren Sie zum Stammordner zurück:
terraform output -raw reasoning_engine_resource_name > ../agent_resource_name.txt
cd ..
8. Agenten abfragen
Prüfen Sie, ob Ihr Agent ausgeführt wird und antwortet.
Schritt 1: Abfrageskript erstellen
Schreiben Sie das Überprüfungsskript in query_agent.py und verwenden Sie eine dynamische Konfigurationsprüfung, um die Standortkoordinaten abzurufen:
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
Führen Sie das Abfrageskript aus:
python3 query_agent.py
Sie sollten eine Ausgabe vom Agenten sehen, einschließlich der simulierten Temperatur für Tokio.
Schritt 2: Die Console verwenden
- Rufen Sie den bereitgestellten Agenten auf, indem Sie Agent Platform > Agents > Deployments auswählen, um die Liste der Agenten zu filtern.

- Wählen Sie im Dashboard des Agenten Playground aus.

- Erstellen Sie eine neue Sitzung und geben Sie Ihre Abfrage ein, um zu prüfen, ob der Agent wie gezeigt auf Anfragen antwortet.

9. Bereinigen
Löschen Sie die erstellten Ressourcen, um Gebühren zu vermeiden.
Wenn Sie die Bereitstellung mit Terraform vorgenommen haben, wechseln Sie in das terraform Verzeichnis und führen Sie die Aktion zum Löschen aus:
cd ~/weather-agent-byoc/terraform
terraform destroy
cd ..
Wenn Sie die Bereitstellung mit dem SDK vorgenommen haben, erstellen Sie das Skript zum Löschen des bereitgestellten Agenten:
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
Führen Sie das Skript aus, um den Agenten zu löschen:
python3 delete_agent.py
Um die restlichen Ressourcen zu bereinigen, kehren Sie zu Ihrem Basisverzeichnis zurück und führen Sie die folgenden Befehle in Cloud Shell aus:
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. Fazit
Glückwunsch! Sie haben einen KI-Agenten mit BYOC erfolgreich containerisiert und in Agent Runtime bereitgestellt.
Sie haben Folgendes gelernt:
- Mit ADK einen Agenten definieren und ihn mit FastAPI einbinden
- Ein Dockerfile erstellen und Images mit Cloud Build erstellen
- IAM-Berechtigungen für Agent Runtime verwalten
- Ihren benutzerdefinierten Container mit dem Python SDK und Terraform bereitstellen
- Den bereitgestellten Agenten testen und abfragen