Menyebarkan agen ADK ke Google Kubernetes Engine (GKE)

1. Pengantar

Ringkasan

Lab ini menjembatani kesenjangan penting antara pengembangan sistem multiagen yang canggih dan men-deploy-nya untuk penggunaan di dunia nyata. Meskipun membangun agen secara lokal adalah langkah awal yang baik, aplikasi produksi memerlukan platform yang skalabel, andal, dan aman.

Di lab ini, Anda akan mengambil sistem multiagen yang dibangun dengan Google Agent Development Kit (ADK) dan men-deploy-nya ke lingkungan tingkat produksi di Google Kubernetes Engine (GKE).

Agen tim konsep film

Aplikasi contoh yang digunakan dalam lab ini adalah "tim konsep film" yang terdiri dari beberapa agen kolaboratif: peneliti, penulis naskah, dan penulis file. Agen ini bekerja sama untuk membantu pengguna bertukar pikiran dan membuat garis besar ide film tentang tokoh sejarah.

diagram alur agen

Mengapa men-deploy ke GKE?

Untuk menyiapkan agen Anda menghadapi tuntutan lingkungan produksi, Anda memerlukan platform yang dibangun untuk skalabilitas, keamanan, dan efisiensi biaya. Google Kubernetes Engine (GKE) menyediakan fondasi yang canggih dan fleksibel ini untuk menjalankan aplikasi dalam container Anda.

Hal ini memberikan beberapa keuntungan untuk workload produksi Anda:

  • Penskalaan & performa otomatis: Tangani traffic yang tidak dapat diprediksi dengan HorizontalPodAutoscaler (HPA), yang secara otomatis menambahkan atau menghapus replika agen berdasarkan beban. Untuk workload AI yang lebih berat, Anda dapat melampirkan akselerator hardware seperti GPU dan TPU.
  • Pengelolaan resource yang hemat biaya: Optimalkan biaya dengan GKE Autopilot, yang otomatis mengelola infrastruktur yang mendasarinya sehingga Anda hanya membayar resource yang diminta aplikasi Anda.
  • Keamanan & kemampuan observasi terintegrasi: Terhubung secara aman ke layanan Google Cloud lainnya menggunakan Workload Identity, sehingga tidak perlu mengelola dan menyimpan kunci akun layanan. Semua log aplikasi otomatis di-streaming ke Cloud Logging untuk pemantauan dan proses debug terpusat.
  • Kontrol & portabilitas: Hindari ketergantungan pada vendor dengan Kubernetes open source. Aplikasi Anda bersifat portabel dan dapat berjalan di cluster Kubernetes mana pun, baik di infrastruktur lokal maupun di cloud lain.

Yang akan Anda pelajari

Di lab ini, Anda akan mempelajari cara melakukan tugas berikut:

  • Sediakan cluster GKE Autopilot.
  • Masukkan aplikasi ke dalam container dengan Dockerfile dan kirim image ke Artifact Registry.
  • Hubungkan aplikasi Anda ke Google Cloud API secara aman menggunakan Workload Identity.
  • Tulis dan terapkan manifes Kubernetes untuk Deployment dan Service.
  • Mengekspos aplikasi ke internet dengan LoadBalancer.
  • Konfigurasi penskalaan otomatis dengan HorizontalPodAutoscaler (HPA).

2. Penyiapan project

Akun Google

Jika belum memiliki Akun Google pribadi, Anda harus membuat Akun Google.

Gunakan akun pribadi, bukan akun kantor atau sekolah.

Login ke Konsol Google Cloud

Login ke Konsol Google Cloud menggunakan Akun Google pribadi.

Aktifkan Penagihan

Menyiapkan akun penagihan pribadi

Jika menyiapkan penagihan menggunakan kredit Google Cloud, Anda dapat melewati langkah ini.

Untuk menyiapkan akun penagihan pribadi, buka di sini untuk mengaktifkan penagihan di Cloud Console.

Beberapa Catatan:

  • Menyelesaikan lab ini akan dikenai biaya kurang dari $1 USD untuk resource Cloud.
  • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
  • Pengguna baru memenuhi syarat untuk mengikuti Uji Coba Gratis senilai$300 USD.

Membuat project (opsional)

Jika Anda tidak memiliki project saat ini yang ingin digunakan untuk lab ini, buat project baru di sini.

3. Buka Cloud Shell Editor

  1. Klik link ini untuk langsung membuka Cloud Shell Editor
  2. Jika diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan.Klik untuk memberikan otorisasi pada Cloud Shell
  3. Jika terminal tidak muncul di bagian bawah layar, buka terminal:
    • Klik Lihat
    • Klik TerminalMembuka terminal baru di Cloud Shell Editor
  4. Di terminal, tetapkan project Anda dengan perintah ini:
    gcloud config set project [PROJECT_ID]
    • Contoh:
      gcloud config set project lab-project-id-example
    • Jika tidak ingat project ID, Anda dapat mencantumkan semua project ID dengan:
      gcloud projects list
      Menetapkan project ID di terminal Cloud Shell Editor
  5. Anda akan melihat pesan ini:
    Updated property [core/project].

4. Mengaktifkan API

Untuk menggunakan GKE, Artifact Registry, Cloud Build, dan Vertex AI, Anda harus mengaktifkan API masing-masing di project Google Cloud Anda.

  • Di terminal, aktifkan API:
    gcloud services enable \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com
    Setelah selesai dijalankan, Anda akan melihat output seperti berikut: 
    Operation "operations/acf.p2-176675280136-b03ab5e4-3483-4ebf-9655-43dc3b345c63" finished successfully.

Memperkenalkan API

  • Google Kubernetes Engine API (container.googleapis.com) memungkinkan Anda membuat dan mengelola cluster GKE yang menjalankan agen Anda. GKE menyediakan lingkungan terkelola untuk men-deploy, mengelola, dan menskalakan aplikasi dalam container menggunakan infrastruktur Google.
  • Artifact Registry API (artifactregistry.googleapis.com) menyediakan repositori pribadi yang aman untuk menyimpan image container agen Anda. Artifact Registry adalah evolusi Container Registry dan terintegrasi secara lancar dengan GKE dan Cloud Build.
  • Cloud Build API (cloudbuild.googleapis.com) digunakan oleh perintah gcloud builds submit untuk membangun image container Anda di cloud dari Dockerfile Anda. Cloud Build adalah platform CI/CD serverless yang mengeksekusi build Anda di infrastruktur Google Cloud.
  • Vertex AI API (aiplatform.googleapis.com) memungkinkan agen yang di-deploy berkomunikasi dengan model Gemini untuk melakukan tugas intinya. API ini menyediakan API terpadu untuk semua layanan AI Google Cloud.

5. Menyiapkan lingkungan pengembangan

Buat struktur direktori

  1. Di terminal, buat direktori project dan subdirektori yang diperlukan:
    mkdir -p ~/adk_multiagent_system_gke/workflow_agents
cd ~/adk_multiagent_system_gke
  2. Di terminal, jalankan perintah berikut untuk membuka direktori di penjelajah Cloud Shell Editor.
    cloudshell open-workspace ~/adk_multiagent_systems
  3. Panel explorer di sebelah kiri akan dimuat ulang. Sekarang Anda akan melihat direktori yang Anda buat.
    screenshot struktur file saat ini
    Saat Anda membuat file di langkah-langkah berikut, Anda akan melihat file tersebut muncul di direktori ini.

Membuat file awal

Sekarang Anda akan membuat file awal yang diperlukan untuk aplikasi.

  1. Buat callback_logging.py dengan menjalankan perintah berikut di terminal. File ini menangani logging untuk kemampuan pengamatan.
    cat <<EOF > ~/adk_multiagent_systems/callback_logging.py
"""
Provides helper functions for observability. Handles formatting and sending 
agent queries, responses, and tool calls to Google Cloud Logging to aid 
in monitoring and debugging.
"""
import logging
import google.cloud.logging

from google.adk.agents.callback_context import CallbackContext
from google.adk.models import LlmResponse, LlmRequest


def log_query_to_model(callback_context: CallbackContext, llm_request: LlmRequest):
    cloud_logging_client = google.cloud.logging.Client()
    cloud_logging_client.setup_logging()
    if llm_request.contents and llm_request.contents[-1].role == 'user':
         if llm_request.contents[-1].parts and "text" in llm_request.contents[-1].parts:
            last_user_message = llm_request.contents[-1].parts[0].text
            logging.info(f"[query to {callback_context.agent_name}]: " + last_user_message)

def log_model_response(callback_context: CallbackContext, llm_response: LlmResponse):
    cloud_logging_client = google.cloud.logging.Client()
    cloud_logging_client.setup_logging()
    if llm_response.content and llm_response.content.parts:
        for part in llm_response.content.parts:
            if part.text:
                logging.info(f"[response from {callback_context.agent_name}]: " + part.text)
            elif part.function_call:
                logging.info(f"[function call from {callback_context.agent_name}]: " + part.function_call.name)
EOF
  2. Buat workflow_agents/__init__.py dengan menjalankan perintah berikut di terminal. Tindakan ini menandai direktori sebagai paket Python.
    cat <<EOF > ~/adk_multiagent_systems/workflow_agents/__init__.py
"""
Marks the directory as a Python package and exposes the agent module, 
allowing the ADK to discover and register the agents defined within.
"""
from . import agent
EOF
  3. Buat workflow_agents/agent.py dengan menjalankan perintah berikut di terminal. File ini berisi logika inti untuk tim multi-agen Anda.
    cat <<EOF > ~/adk_multiagent_systems/workflow_agents/agent.py
"""
Defines the core multi-agent workflow. Configures individual agents (Researcher, 
Screenwriter, File Writer), assigns their specific tools, and orchestrates 
their collaboration using the ADK's SequentialAgent pattern.
"""
import os
import logging
import google.cloud.logging

from callback_logging import log_query_to_model, log_model_response
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent, LoopAgent, ParallelAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool  # import
from google.genai import types

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper


cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
print(model_name)

# Tools


def append_to_state(
    tool_context: ToolContext, field: str, response: str
) -> dict[str, str]:
    """Append new output to an existing state key.

    Args:
        field (str): a field name to append to
        response (str): a string to append to the field

    Returns:
        dict[str, str]: {"status": "success"}
    """
    existing_state = tool_context.state.get(field, [])
    tool_context.state[field] = existing_state + [response]
    logging.info(f"[Added to {field}] {response}")
    return {"status": "success"}


def write_file(
    tool_context: ToolContext,
    directory: str,
    filename: str,
    content: str
) -> dict[str, str]:
    target_path = os.path.join(directory, filename)
    os.makedirs(os.path.dirname(target_path), exist_ok=True)
    with open(target_path, "w") as f:
        f.write(content)
    return {"status": "success"}


# Agents

file_writer = Agent(
    name="file_writer",
    model=model_name,
    description="Creates marketing details and saves a pitch document.",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE. If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
    - Use your 'write_file' tool to create a new txt file with the following arguments:
        - for a filename, use the movie title
        - Write to the 'movie_pitches' directory.
        - For the 'content' to write, extract the following from the PLOT_OUTLINE:
            - A logline
            - Synopsis or plot outline
    """,
    generate_content_config=types.GenerateContentConfig(
        temperature=0,
    ),
    tools=[write_file],
)

screenwriter = Agent(
    name="screenwriter",
    model=model_name,
    description="As a screenwriter, write a logline and plot outline for a biopic about a historical character.",
    instruction="""
    INSTRUCTIONS:
    Your goal is to write a logline and three-act plot outline for an inspiring movie about a historical character(s) described by the PROMPT: { PROMPT? }

    - If there is CRITICAL_FEEDBACK, use those thoughts to improve upon the outline.
    - If there is RESEARCH provided, feel free to use details from it, but you are not required to use it all.
    - If there is a PLOT_OUTLINE, improve upon it.
    - Use the 'append_to_state' tool to write your logline and three-act plot outline to the field 'PLOT_OUTLINE'.
    - Summarize what you focused on in this pass.

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    RESEARCH:
    { research? }

    CRITICAL_FEEDBACK:
    { CRITICAL_FEEDBACK? }
    """,
    generate_content_config=types.GenerateContentConfig(
        temperature=0,
    ),
    tools=[append_to_state],
)

researcher = Agent(
    name="researcher",
    model=model_name,
    description="Answer research questions using Wikipedia.",
    instruction="""
    PROMPT:
    { PROMPT? }

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    CRITICAL_FEEDBACK:
    { CRITICAL_FEEDBACK? }

    INSTRUCTIONS:
    - If there is a CRITICAL_FEEDBACK, use your wikipedia tool to do research to solve those suggestions
    - If there is a PLOT_OUTLINE, use your wikipedia tool to do research to add more historical detail
    - If these are empty, use your Wikipedia tool to gather facts about the person in the PROMPT
    - Use the 'append_to_state' tool to add your research to the field 'research'.
    - Summarize what you have learned.
    Now, use your Wikipedia tool to do research.
    """,
    generate_content_config=types.GenerateContentConfig(
        temperature=0,
    ),
    tools=[
        LangchainTool(tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())),
        append_to_state,
    ],
)

film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        researcher,
        screenwriter,
        file_writer
    ],
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="Guides the user in crafting a movie plot.",
    instruction="""
    - Let the user know you will help them write a pitch for a hit movie. Ask them for   
      a historical figure to create a movie about.
    - When they respond, use the 'append_to_state' tool to store the user's response
      in the 'PROMPT' state key and transfer to the 'film_concept_team' agent
    """,
    generate_content_config=types.GenerateContentConfig(
        temperature=0,
    ),
    tools=[append_to_state],
    sub_agents=[film_concept_team],
)
EOF

Struktur file Anda sekarang akan terlihat seperti ini:
screenshot struktur file saat ini

Menyiapkan lingkungan virtual

  • Di terminal, buat dan aktifkan lingkungan virtual menggunakan uv. Tindakan ini memastikan dependensi project Anda tidak bertentangan dengan Python sistem.
    uv venv
source .venv/bin/activate

Persyaratan penginstalan

  1. Jalankan perintah berikut di terminal untuk membuat file requirements.txt.
    cat <<EOF > ~/adk_multiagent_systems/requirements.txt
# Lists all Python dependencies required to run the multi-agent system,
# including the Google ADK, LangChain community tools, and web server libraries.
langchain-community==0.3.20
wikipedia==1.4.0
google-adk==1.8.0
fastapi==0.121.2
uvicorn==0.38.0
EOF
  2. Instal paket yang diperlukan ke lingkungan virtual Anda di terminal.
    uv pip install -r requirements.txt

Menyiapkan variabel lingkungan

  1. Gunakan perintah berikut di terminal untuk membuat file .env, dengan otomatis menyisipkan project ID dan region Anda.
    cat <<EOF > ~/adk_multiagent_systems/.env
GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)"
GOOGLE_CLOUD_PROJECT_NUMBER="$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')"
GOOGLE_CLOUD_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=true
MODEL="gemini-2.5-flash"
EOF
  2. Di terminal, muat variabel ke sesi shell Anda.
    source .env

Rekap

Di bagian ini, Anda telah membangun fondasi lokal untuk project Anda:

  • Membuat struktur direktori dan file awal agen yang diperlukan (agent.py, callback_logging.py, requirements.txt).
  • Mengisolasi dependensi Anda menggunakan lingkungan virtual (uv).
  • Variabel lingkungan yang dikonfigurasi (.env) untuk menyimpan detail khusus project seperti Project ID dan Region Anda.

6. Mempelajari file agen

Anda telah menyiapkan kode sumber untuk lab, termasuk sistem multiagen yang telah ditulis sebelumnya. Sebelum men-deploy aplikasi, sebaiknya pahami cara agen ditentukan. Logika agen inti berada di workflow_agents/agent.py.

  1. Di Cloud Shell Editor, gunakan file explorer di sebelah kiri untuk membuka adk_multiagent_system_gke/workflow_agents/, lalu buka file agent.py.
  2. Luangkan waktu sejenak untuk melihat-lihat file. Anda tidak perlu memahami setiap baris, tetapi perhatikan struktur tingkat tinggi:
    • Agen individual: File menentukan tiga objek Agent yang berbeda: researcher, screenwriter, dan file_writer. Setiap agen diberi instruction tertentu (perintahnya) dan daftar tools yang diizinkan untuk digunakan (seperti alat WikipediaQueryRun atau alat write_file kustom).
    • Komposisi agen: Setiap agen dihubungkan menjadi SequentialAgent yang disebut film_concept_team. Hal ini memberi tahu ADK untuk menjalankan agen ini satu demi satu, meneruskan status dari satu agen ke agen berikutnya.
    • Agen root: root_agent (bernama "greeter") ditentukan untuk menangani interaksi awal pengguna. Saat pengguna memberikan perintah, agen ini akan menyimpannya ke status aplikasi, lalu mentransfer kontrol ke alur kerja film_concept_team.

Memahami struktur ini membantu memperjelas apa yang akan Anda deploy: bukan hanya satu agen, tetapi tim agen khusus yang terkoordinasi yang diatur oleh ADK.

7. Membuat cluster GKE Autopilot

Setelah lingkungan Anda siap, langkah selanjutnya adalah menyediakan infrastruktur tempat aplikasi agen Anda akan berjalan. Anda akan membuat cluster GKE Autopilot, yang berfungsi sebagai dasar untuk deployment Anda. Kami menggunakan mode Autopilot karena mode ini menangani pengelolaan kompleks node, penskalaan, dan keamanan dasar cluster, sehingga Anda dapat berfokus sepenuhnya pada deployment aplikasi.

  1. Di terminal, buat cluster GKE Autopilot baru bernama adk-cluster.
    gcloud container clusters create-auto adk-cluster \
  --location=$GOOGLE_CLOUD_LOCATION \
  --project=$GOOGLE_CLOUD_PROJECT
    Perintah ini menyediakan cluster Kubernetes yang terkelola sepenuhnya. GKE Autopilot secara otomatis mengonfigurasi node, penskalaan, dan keamanan, sehingga menyederhanakan operasi cluster.
  2. Setelah cluster dibuat, konfigurasi kubectl untuk terhubung ke cluster dengan menjalankan perintah ini di terminal:
    gcloud container clusters get-credentials adk-cluster \
  --location=$GOOGLE_CLOUD_LOCATION \
  --project=$GOOGLE_CLOUD_PROJECT
    Perintah ini menghubungkan lingkungan lokal Anda ke cluster GKE baru. Alat ini secara otomatis mengambil endpoint dan kredensial autentikasi cluster, lalu memperbarui file konfigurasi lokal (~/.kube/config). Mulai saat ini, alat command line kubectl akan diautentikasi dan diarahkan untuk berkomunikasi dengan adk-cluster Anda.

Rekap

Di bagian ini, Anda telah menyediakan infrastruktur:

  • Membuat cluster GKE Autopilot yang terkelola sepenuhnya menggunakan gcloud.
  • Mengonfigurasi alat kubectl lokal Anda untuk mengautentikasi dan berkomunikasi dengan cluster baru.

8. Membuat container dan mengirim aplikasi

Kode agen Anda saat ini hanya ada di lingkungan Cloud Shell Anda. Untuk menjalankannya di GKE, Anda harus memaketkannya terlebih dahulu ke dalam image container. Image container adalah file statis dan portabel yang menggabungkan kode aplikasi Anda dengan semua dependensinya. Saat Anda menjalankan image ini, image tersebut akan menjadi container aktif.

Proses ini melibatkan tiga langkah utama:

  • Buat titik entri: Tentukan file main.py untuk mengubah logika agen Anda menjadi server web yang dapat dijalankan.
  • Tentukan image container: Buat Dockerfile yang berfungsi sebagai cetak biru untuk membangun image container Anda.
  • Bangun dan kirim: Gunakan Cloud Build untuk mengeksekusi Dockerfile, membuat image container, dan mengirimkannya ke Google Artifact Registry, repositori yang aman untuk image Anda.

Menyiapkan aplikasi untuk deployment

Agen ADK Anda memerlukan server web untuk menerima permintaan. File main.py akan berfungsi sebagai titik entri ini, menggunakan framework FastAPI untuk mengekspos fungsi agen Anda melalui HTTP.

  1. Di root direktori adk_multiagent_system_gke di terminal, buat file baru bernama main.py.
    cat <<EOF > ~/adk_multiagent_systems/main.py
"""
Serves as the application entry point. Initializes the FastAPI web server, 
discovers the agents defined in the workflow directory, and exposes them 
via HTTP endpoints for interaction.
"""

import os

import uvicorn
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app

# Get the directory where main.py is located
AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Configure the session service (e.g., SQLite for local storage)
SESSION_SERVICE_URI = "sqlite:///./sessions.db"

# Configure CORS to allow requests from various origins for this lab
ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]

# Enable the ADK's built-in web interface
SERVE_WEB_INTERFACE = True

# Call the ADK function to discover agents and create the FastAPI app
app: FastAPI = get_fast_api_app(
    agents_dir=AGENT_DIR,
    session_service_uri=SESSION_SERVICE_URI,
    allow_origins=ALLOWED_ORIGINS,
    web=SERVE_WEB_INTERFACE,
)

# You can add more FastAPI routes or configurations below if needed
# Example:
# @app.get("/hello")
# async def read_root():
#     return {"Hello": "World"}

if __name__ == "__main__":
    # Get the port from the PORT environment variable provided by the container runtime
    # Run the Uvicorn server, listening on all available network interfaces (0.0.0.0)
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF
    File ini menggunakan library ADK untuk menemukan agen di project Anda dan membungkusnya dalam aplikasi web FastAPI. Server uvicorn menjalankan aplikasi ini, memproses host 0.0.0.0 untuk menerima koneksi dari alamat IP mana pun dan pada port yang ditentukan oleh variabel lingkungan PORT, yang akan kita tetapkan nanti dalam manifes Kubernetes.

    Pada tahap ini, struktur file Anda seperti yang terlihat di panel explorer di Cloud Shell Editor akan terlihat seperti ini: screenshot struktur file saat ini

Mem-build agen ADK dalam container dengan Docker

Untuk men-deploy aplikasi ke GKE, pertama-tama kita perlu mengemasnya ke dalam image container, yang menggabungkan kode aplikasi kita dengan semua library dan dependensi yang diperlukan untuk menjalankannya. Kita akan menggunakan Docker untuk membuat image container ini.

  1. Di root direktori adk_multiagent_system_gke di terminal, buat file baru bernama Dockerfile.
    cat <<'EOF' > ~/adk_multiagent_systems/Dockerfile
# Defines the blueprint for the container image. Installs dependencies,
# sets up a secure non-root user, and specifies the startup command to run the 
# agent web server.

# Use an official lightweight Python image as the base
FROM python:3.13-slim

# Set the working directory inside the container
WORKDIR /app

# Create a non-root user for security best practices
RUN adduser --disabled-password --gecos "" myuser

# Copy and install dependencies first to leverage Docker's layer caching
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy all application code into the container
COPY . .

# Create the directory where the agent will write files at runtime
# The -p flag ensures the command doesn't fail if the directory already exists
RUN mkdir -p movie_pitches

# Change ownership of EVERYTHING in /app to the non-root user
# Without this, the running agent would be denied permission to write files.
RUN chown -R myuser:myuser /app

# Switch the active user from root to the non-root user
USER myuser

# Add the user's local binary directory to the system's PATH
ENV PATH="/home/myuser/.local/bin:$PATH"

# Define the command to run when the container starts
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"]
EOF
    Pada tahap ini, struktur file Anda seperti yang terlihat di panel explorer di Cloud Shell Editor akan terlihat seperti ini: screenshot struktur file saat ini

Bangun dan kirim image container ke Artifact Registry

Setelah memiliki Dockerfile, Anda akan menggunakan Cloud Build untuk membangun image dan mengirimkannya ke Artifact Registry, registry pribadi yang aman dan terintegrasi dengan layanan Google Cloud. GKE akan menarik image dari registry ini untuk menjalankan aplikasi Anda.

  1. Di terminal, buat repositori Artifact Registry baru untuk menyimpan image container Anda.
    gcloud artifacts repositories create adk-repo \
  --repository-format=docker \
  --location=$GOOGLE_CLOUD_LOCATION \
  --description="ADK repository"
  2. Di terminal, gunakan gcloud builds submit untuk membangun image container dan mengirimkannya ke repositori.
    gcloud builds submit \
  --tag $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest \
  --project=$GOOGLE_CLOUD_PROJECT \
  .
    Satu perintah ini menggunakan Cloud Build, platform CI/CD serverless, untuk menjalankan langkah-langkah di Dockerfile Anda. Cloud Build akan membangun image di cloud, memberi tag dengan alamat repositori Artifact Registry Anda, dan mengirimkannya ke sana secara otomatis.
  3. Dari terminal, verifikasi bahwa image telah dibuat:
    gcloud artifacts docker images list \
  $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo \
  --project=$GOOGLE_CLOUD_PROJECT

Rekap

Di bagian ini, Anda mengemas kode untuk deployment:

  • Membuat titik entri main.py untuk membungkus agen Anda di server web FastAPI.
  • Menentukan Dockerfile untuk memaketkan kode dan dependensi Anda ke dalam image portabel.
  • Menggunakan Cloud Build untuk membangun image dan mengirimkannya ke repositori Artifact Registry yang aman.

9. Membuat manifes Kubernetes

Setelah image container Anda dibuat dan disimpan di Artifact Registry, Anda perlu menginstruksikan GKE tentang cara menjalankannya. Hal ini melibatkan dua aktivitas utama:

  • Mengonfigurasi izin: Anda akan membuat identitas khusus untuk agen dalam cluster dan memberikan akses yang aman ke Google Cloud API yang diperlukan (khususnya, Vertex AI).
  • Menentukan status aplikasi: Anda akan menulis file manifes Kubernetes, dokumen YAML yang secara deklaratif menentukan semua yang dibutuhkan aplikasi Anda untuk berjalan, termasuk image container, variabel lingkungan, dan cara aplikasi harus diekspos ke jaringan.

Mengonfigurasi Akun Layanan Kubernetes untuk Vertex AI

Agen Anda memerlukan izin untuk berkomunikasi dengan Vertex AI API guna mengakses model Gemini. Metode yang paling aman dan direkomendasikan untuk memberikan izin ini di GKE adalah Workload Identity. Dengan Workload Identity, Anda dapat menautkan identitas native Kubernetes (Akun Layanan Kubernetes) dengan identitas Google Cloud (Akun Layanan IAM), sehingga Anda tidak perlu mendownload, mengelola, dan menyimpan kunci JSON statis.

  1. Di terminal, buat Akun Layanan Kubernetes (adk-agent-sa). Tindakan ini akan membuat identitas untuk agen Anda di dalam cluster GKE yang dapat digunakan oleh pod Anda.
    kubectl create serviceaccount adk-agent-sa
  2. Di terminal, tautkan Akun Layanan Kubernetes Anda ke IAM Google Cloud dengan membuat binding kebijakan. Perintah ini memberikan peran aiplatform.user ke adk-agent-sa Anda, sehingga adk-agent-sa dapat memanggil Vertex AI API dengan aman.
    gcloud projects add-iam-policy-binding projects/${GOOGLE_CLOUD_PROJECT} \
    --role=roles/aiplatform.user \
    --member=principal://iam.googleapis.com/projects/${GOOGLE_CLOUD_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GOOGLE_CLOUD_PROJECT}.svc.id.goog/subject/ns/default/sa/adk-agent-sa \
    --condition=None

Buat file manifes Kubernetes

Kubernetes menggunakan file manifes YAML untuk menentukan status aplikasi yang diinginkan. Anda akan membuat file deployment.yaml yang berisi dua objek Kubernetes penting: Deployment dan Service.

  1. Dari terminal, buat file deployment.yaml. 
    cat <<EOF > ~/adk_multiagent_systems/deployment.yaml
# Defines the Kubernetes resources required to deploy the application to GKE. 
# Includes the Deployment (to run the container pods) and the Service 
# (to expose the application via a Load Balancer).
apiVersion: apps/v1
kind: Deployment
metadata:
  name: adk-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: adk-agent
  template:
    metadata:
      labels:
        app: adk-agent
    spec:
      # Assign the Kubernetes Service Account for Workload Identity
      serviceAccountName: adk-agent-sa
      containers:
      - name: adk-agent
        imagePullPolicy: Always
        # The path to the container image in Artifact Registry
        image: ${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${GOOGLE_CLOUD_PROJECT}/adk-repo/adk-agent:latest
        # Define the resources for GKE Autopilot to provision
        resources:
          limits:
            memory: "1Gi"
            cpu: "1000m"
            ephemeral-storage: "512Mi"
          requests:
            memory: "1Gi"
            cpu: "1000m"
            ephemeral-storage: "512Mi"
        ports:
        - containerPort: 8080
        # Environment variables passed to the application
        env:
        - name: PORT
          value: "8080"
        - name: GOOGLE_CLOUD_PROJECT
          value: ${GOOGLE_CLOUD_PROJECT}
        - name: GOOGLE_CLOUD_LOCATION
          value: ${GOOGLE_CLOUD_LOCATION}
        - name: GOOGLE_GENAI_USE_VERTEXAI
          value: "true"
        - name: MODEL
          value: "gemini-2.5-flash"
---
apiVersion: v1
kind: Service
metadata:
  name: adk-agent
spec:
  # Create a public-facing Network Load Balancer with an external IP
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app: adk-agent
EOF
    Pada tahap ini, struktur file Anda seperti yang terlihat di panel explorer di Cloud Shell Editor akan terlihat seperti ini:screenshot struktur file saat ini

Rekap

Di bagian ini, Anda menentukan konfigurasi keamanan dan deployment:

  • Membuat Akun Layanan Kubernetes dan menautkannya ke IAM Google Cloud menggunakan Workload Identity, sehingga pod Anda dapat mengakses Vertex AI secara aman tanpa mengelola kunci.
  • Membuat file deployment.yaml yang menentukan Deployment (cara menjalankan pod) dan Layanan (cara mengeksposnya melalui Load Balancer).

10. Deploy aplikasi ke GKE

Setelah file manifes ditentukan dan image container dikirim ke Artifact Registry, Anda kini siap men-deploy aplikasi. Dalam tugas ini, Anda akan menggunakan kubectl untuk menerapkan konfigurasi ke cluster GKE, lalu memantau statusnya untuk memastikan agen Anda dimulai dengan benar.

  1. Di terminal, terapkan manifes deployment.yaml ke cluster Anda.
    kubectl apply -f deployment.yaml
    Perintah kubectl apply mengirimkan file deployment.yaml Anda ke server Kubernetes API. Kemudian, server akan membaca konfigurasi Anda dan mengatur pembuatan objek Deployment dan Service.
  2. Di terminal, periksa status deployment Anda secara real time. Tunggu hingga pod berada dalam status Running.
    kubectl get pods -l=app=adk-agent --watch
    Anda akan melihat pod berpindah melalui beberapa fase:
    • Tertunda: Pod telah diterima oleh cluster, tetapi penampung belum dibuat.
    • Pembuatan container: GKE mengambil image container Anda dari Artifact Registry dan memulai container.
    • Lari: Berhasil! Container sedang berjalan, dan aplikasi agen Anda sudah aktif.
  3. Setelah status menunjukkan Running, tekan CTRL+C di terminal untuk menghentikan perintah watch dan kembali ke command prompt.

Rekap

Di bagian ini, Anda meluncurkan beban kerja:

  • Gunakan penerapan kubectl untuk mengirim manifes Anda ke cluster.
  • Memantau siklus proses Pod (Tertunda -> ContainerCreating -> Berjalan) untuk memastikan aplikasi berhasil dimulai.

11. Berinteraksi dengan agen

Agen ADK Anda kini berjalan secara live di GKE dan diekspos ke internet melalui Load Balancer publik. Anda akan terhubung ke antarmuka web agen untuk berinteraksi dengannya dan memverifikasi bahwa seluruh sistem berfungsi dengan benar.

Menemukan Alamat IP eksternal layanan Anda

Untuk mengakses agen, Anda harus mendapatkan alamat IP publik yang disediakan GKE untuk Layanan Anda terlebih dahulu.

  1. Di terminal, jalankan perintah berikut untuk mendapatkan detail layanan Anda.
    kubectl get service adk-agent
  2. Cari nilai di kolom EXTERNAL-IP. Mungkin perlu waktu satu atau dua menit agar alamat IP ditetapkan setelah Anda men-deploy layanan untuk pertama kalinya. Jika ditampilkan sebagai pending, tunggu sebentar dan jalankan kembali perintah. Outputnya akan terlihat seperti ini:
    NAME                TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)        AGE
adk-agent-service   LoadBalancer   10.120.12.234   34.123.45.67    80:31234/TCP   5m
    Alamat yang tercantum di bagian EXTERNAL-IP (misalnya, 34.123.45.67) adalah titik masuk publik ke agen Anda.

Menguji agen yang di-deploy

Sekarang Anda dapat menggunakan alamat IP publik untuk mengakses UI web bawaan ADK langsung dari browser Anda.

  1. Salin alamat IP eksternal (EXTERNAL-IP) dari terminal.
  2. Buka tab baru di browser web Anda dan ketik http://[EXTERNAL-IP], dengan mengganti [EXTERNAL-IP] dengan alamat IP yang Anda salin.
  3. Sekarang Anda akan melihat antarmuka web ADK.
  4. Pastikan workflow_agents dipilih di menu drop-down agen.
  5. Aktifkan Token Streaming.
  6. Ketik hello, lalu tekan enter untuk memulai percakapan baru.
  7. Amati hasilnya. Agen akan merespons dengan cepat dengan sapaannya: "Saya dapat membantu Anda menulis saran untuk film populer. Tokoh sejarah mana yang ingin Anda jadikan film?"
  8. Saat diminta untuk memilih karakter historis, pilih salah satu yang Anda minati. Beberapa ide mencakup:
    • the most successful female pirate in history
    • the woman who invented the first computer compiler
    • a legendary lawman of the American Wild West

Rekap

Di bagian ini, Anda telah memverifikasi deployment:

  • Mengambil alamat IP Eksternal yang dialokasikan oleh LoadBalancer.
  • Mengakses UI Web ADK melalui browser untuk mengonfirmasi bahwa sistem multi-agen responsif dan berfungsi.

12. Konfigurasi penskalaan otomatis

Tantangan utama dalam produksi adalah menangani traffic pengguna yang tidak dapat diprediksi. Mengodekan secara permanen jumlah replika yang tetap, seperti yang Anda lakukan pada tugas sebelumnya, berarti Anda membayar lebih untuk resource yang tidak digunakan atau berisiko mengalami performa yang buruk selama lonjakan traffic. GKE mengatasi masalah ini dengan penskalaan otomatis.

Anda akan mengonfigurasi HorizontalPodAutoscaler (HPA), pengontrol Kubernetes yang secara otomatis menyesuaikan jumlah pod yang berjalan di Deployment Anda berdasarkan penggunaan CPU real-time.

  1. Di terminal Cloud Shell Editor, buat file hpa.yaml baru di root direktori adk_multiagent_system_gke.
    cloudshell edit ~/adk_multiagent_systems/hpa.yaml
  2. Tambahkan konten berikut ke file hpa.yaml baru:
    # Configures the HorizontalPodAutoscaler (HPA) to automatically scale 
# the number of running agent pods up or down based on CPU utilization 
# to handle varying traffic loads.

apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: adk-agent-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: adk-agent
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilizationPercentage: 50
    Objek HPA ini menargetkan Deployment adk-agent kita. Hal ini memastikan selalu ada minimal 1 pod yang berjalan, menetapkan maksimum 5 pod, dan akan menambahkan/menghapus replika untuk menjaga penggunaan CPU rata-rata sekitar 50%.Pada tahap ini, struktur file Anda seperti yang terlihat di panel explorer di Cloud Shell Editor akan terlihat seperti ini: screenshot struktur file saat ini
  3. Terapkan HPA ke cluster Anda dengan menempelkannya ke terminal.
    kubectl apply -f hpa.yaml

Memverifikasi autoscaler

HPA kini aktif dan memantau deployment Anda. Anda dapat memeriksa statusnya untuk melihatnya beraksi.

  1. Jalankan perintah berikut di terminal untuk mendapatkan status HPA Anda. 
    kubectl get hpa adk-agent-hpa
    Outputnya akan terlihat seperti ini:
    NAME            REFERENCE          TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
adk-agent-hpa   Deployment/adk-agent   0%/50%    1         5         1          30s
    Agen Anda kini akan otomatis diskalakan sebagai respons terhadap traffic.

Rekap

Di bagian ini, Anda mengoptimalkan traffic produksi:

  • Membuat manifes hpa.yaml untuk menentukan aturan penskalaan.
  • Men-deploy HorizontalPodAutoscaler (HPA) untuk menyesuaikan jumlah replika pod secara otomatis berdasarkan pemakaian CPU.

13. Menyiapkan produksi

Catatan: Bagian berikut hanya untuk tujuan informasi dan tidak berisi langkah-langkah lebih lanjut yang harus dilakukan. Bagian ini dirancang untuk memberikan konteks dan praktik terbaik dalam membawa aplikasi Anda ke produksi.

Menyesuaikan performa dengan alokasi resource

Di GKE Autopilot, Anda mengontrol jumlah CPU dan memori yang disediakan untuk aplikasi dengan menentukan requests resource di deployment.yaml.

Jika mendapati bahwa agen Anda lambat atau mengalami error karena kurangnya memori, Anda dapat meningkatkan alokasi sumber dayanya dengan mengedit blok resources di deployment.yaml dan menerapkan kembali file dengan kubectl apply.

Misalnya, untuk menggandakan memori:

# In deployment.yaml
# ...
        resources:
          requests:
            memory: "2Gi"  # Increased from 1Gi
            cpu: "1000m"
# ...

Mengotomatiskan alur kerja dengan CI/CD

Di lab ini, Anda menjalankan perintah secara manual. Praktik profesionalnya adalah membuat pipeline CI/CD (Continuous Integration/Continuous Deployment). Dengan menghubungkan repositori kode sumber (seperti GitHub) ke pemicu Cloud Build, Anda dapat mengotomatiskan seluruh deployment.

Dengan pipeline, setiap kali Anda mengirim perubahan kode, Cloud Build dapat otomatis:

  1. Buat image container baru.
  2. Kirim image ke Artifact Registry.
  3. Terapkan manifes Kubernetes yang telah diupdate ke cluster GKE Anda.

Mengelola secret secara aman

Dalam lab ini, Anda menyimpan konfigurasi dalam file .env dan meneruskannya ke aplikasi. Cara ini nyaman untuk pengembangan, tetapi tidak aman untuk data sensitif seperti kunci API. Praktik terbaik yang direkomendasikan adalah menggunakan Secret Manager untuk menyimpan secret dengan aman.

GKE memiliki integrasi native dengan Secret Manager yang memungkinkan Anda memasang secret langsung ke pod sebagai variabel lingkungan atau file, tanpa pernah diperiksa ke kode sumber Anda.

Berikut bagian Membersihkan resource yang Anda minta, yang disisipkan tepat sebelum bagian Kesimpulan.

14. Membersihkan resource

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus cluster GKE

Cluster GKE adalah pendorong biaya utama dalam lab ini. Menghapusnya akan menghentikan biaya komputasi.

  1. Di terminal, jalankan perintah berikut:
    gcloud container clusters delete adk-cluster \
  --location=$GOOGLE_CLOUD_LOCATION \
  --quiet

Hapus repositori Artifact Registry

Image container yang disimpan di Artifact Registry dikenai biaya penyimpanan.

  1. Di terminal, jalankan perintah berikut:
    gcloud artifacts repositories delete adk-repo \
  --location=$GOOGLE_CLOUD_LOCATION \
  --quiet

Menghapus project (Opsional)

Jika Anda membuat project baru khusus untuk lab ini dan tidak berencana menggunakannya lagi, cara termudah untuk membersihkannya adalah dengan menghapus seluruh project.

  1. Di terminal, jalankan perintah berikut (ganti [YOUR_PROJECT_ID] dengan project ID Anda yang sebenarnya):
    gcloud projects delete [YOUR_PROJECT_ID]

15. Kesimpulan

Selamat! Anda telah berhasil men-deploy aplikasi ADK multi-agen ke cluster GKE tingkat produksi. Ini adalah pencapaian signifikan yang mencakup siklus proses inti aplikasi modern berbasis cloud, sehingga memberi Anda fondasi yang kuat untuk men-deploy sistem agentik kompleks Anda sendiri.

Rekap

Di lab ini, Anda telah mempelajari cara:

Referensi yang berguna