Men-deploy, Mengelola, dan Mengamati Agen ADK di Cloud Run

1. Pengantar

CATATAN PENTING:

Tutorial ini memerlukan Project Google Cloud dengan akun penagihan yang aktif. Jika Anda belum memilikinya, ikuti langkah-langkah di bawah untuk mendapatkan akun penagihan uji coba yang dapat digunakan untuk tutorial ini:

1. Buka jendela samaran
2. Buka portal penukaran akun penagihan uji coba ini
3. Login menggunakan akun Gmail pribadi Anda ( email Google Workspace / lainnya tidak akan berfungsi! )
4. Ikuti petunjuk langkah demi langkah

Tutorial ini akan memandu Anda men-deploy, mengelola, dan memantau agen canggih yang dibangun dengan Agent Development Kit (ADK) di Google Cloud Run. ADK memungkinkan Anda membuat agen yang mampu melakukan alur kerja multi-agen yang kompleks. Dengan memanfaatkan Cloud Run, platform serverless yang terkelola sepenuhnya, Anda dapat men-deploy agen sebagai aplikasi dalam container yang skalabel tanpa mengkhawatirkan infrastruktur yang mendasarinya. Kombinasi yang efektif ini memungkinkan Anda berfokus pada logika inti agen sambil memanfaatkan lingkungan Google Cloud yang andal dan skalabel.

Sepanjang tutorial ini, kita akan mempelajari integrasi ADK yang lancar dengan Cloud Run. Anda akan mempelajari cara men-deploy agen, lalu mempelajari aspek praktis pengelolaan aplikasi dalam setelan seperti produksi. Kita akan membahas cara meluncurkan versi baru agen Anda dengan aman melalui pengelolaan traffic, sehingga Anda dapat menguji fitur baru dengan sebagian kecil pengguna sebelum rilis penuh.

Selain itu, Anda akan mendapatkan pengalaman langsung dalam memantau performa agen Anda. Kita akan menyimulasikan skenario dunia nyata dengan melakukan uji beban untuk mengamati kemampuan penskalaan otomatis Cloud Run dalam tindakan. Untuk mendapatkan insight yang lebih mendalam tentang perilaku dan performa agen Anda, kami akan mengaktifkan tracing dengan Cloud Trace. Hal ini akan memberikan tampilan permintaan end-to-end yang mendetail saat permintaan tersebut melewati agen Anda, sehingga Anda dapat mengidentifikasi dan mengatasi hambatan performa. Setelah menyelesaikan tutorial ini, Anda akan memiliki pemahaman yang komprehensif tentang cara men-deploy, mengelola, dan memantau agen yang didukung ADK secara efektif di Cloud Run.

Selama mengikuti codelab, Anda akan menggunakan pendekatan langkah demi langkah sebagai berikut:

1. Buat database PostgreSQL di CloudSQL untuk digunakan bagi layanan sesi database ADK Agent
2. Menyiapkan agen ADK dasar
3. Menyiapkan layanan sesi database untuk digunakan oleh peluncur ADK
4. Men-deploy agen ke Cloud Run untuk pertama kalinya
5. Pengujian beban dan memeriksa penskalaan otomatis Cloud Run
6. Men-deploy revisi agen baru dan secara bertahap meningkatkan traffic ke revisi baru
7. Menyiapkan cloud tracing dan memeriksa tracing eksekusi agen

Ringkasan Arsitektur

Prasyarat

• Nyaman bekerja dengan Python
• Pemahaman tentang arsitektur full-stack dasar menggunakan layanan HTTP

Yang akan Anda pelajari

• Struktur ADK dan utilitas lokal
• Menyiapkan agen ADK dengan layanan sesi Database
• Menyiapkan PostgreSQL di CloudSQL untuk digunakan oleh layanan sesi Database
• Men-deploy aplikasi ke Cloud Run menggunakan Dockerfile dan menyiapkan variabel lingkungan awal
• Mengonfigurasi dan Menguji penskalaan otomatis Cloud Run dengan pengujian beban
• Strategi untuk rilis bertahap dengan Cloud Run
• Menyiapkan pelacakan Agen ADK ke Cloud Trace

Yang Anda butuhkan

• Browser web Chrome
• Akun Gmail
• Project Cloud dengan penagihan diaktifkan

Codelab ini, yang dirancang untuk developer dari semua level (termasuk pemula), menggunakan Python dalam aplikasi contohnya. Namun, pengetahuan Python tidak diperlukan untuk memahami konsep yang disajikan.

2. Sebelum memulai

Pilih Project Aktif di Konsol Cloud

Codelab ini mengasumsikan bahwa Anda sudah memiliki project Google Cloud dengan penagihan yang diaktifkan. Jika belum memilikinya, Anda dapat mengikuti petunjuk di bawah untuk memulai.

1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Siapkan Database Cloud SQL

Kita akan memerlukan database yang akan digunakan oleh agen ADK nanti. Mari kita buat database PostgreSQL di Cloud SQL. Pertama, buka kotak penelusuran di bagian atas konsol cloud, lalu ketik "cloud sql". Kemudian, klik produk Cloud SQL

Setelah itu, kita perlu membuat instance database baru, mengklik Create Instance, lalu memilih PostgreSQL

Anda mungkin juga perlu mengaktifkan Compute Engine API jika memulai dengan project baru. Cukup klik Enable API jika perintah ini muncul

Selanjutnya, kita akan memilih spesifikasi database, memilih edisi Enterprise dengan preset Edisi Sandbox

Setelah itu, tetapkan nama instance dan sandi default untuk pengguna postgres di sini. Anda dapat menyiapkannya dengan kredensial apa pun yang Anda inginkan, tetapi untuk tutorial ini, kita akan menggunakan "adk-deployment" untuk nama instance dan sandi di sini

Penting! Nama pengguna dan sandi adalah data sensitif, pastikan Anda merahasiakan nilai ini dari orang lain.

Mari kita gunakan us-central1 dengan zona tunggal untuk tutorial ini. Kita dapat menyelesaikan pembuatan database, lalu membiarkannya menyelesaikan semua penyiapan yang diperlukan dengan mengklik tombol Create Instance

Bersabarlah, pembuatan database akan selesai dalam waktu sekitar 5-10 menit

Sambil menunggu proses ini selesai, kita dapat melanjutkan ke bagian berikutnya

Menyiapkan Project Cloud di Terminal Cloud Shell

1. Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.

2. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:

gcloud auth list

3. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.

gcloud config list project

4. Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:

gcloud config set project <YOUR_PROJECT_ID>

Atau, Anda juga dapat melihat ID PROJECT_ID di konsol

Klik project tersebut dan Anda akan melihat semua project dan project ID di sisi kanan

5. Aktifkan API yang diperlukan melalui perintah yang ditampilkan di bawah. Proses ini mungkin memerlukan waktu beberapa menit, jadi harap bersabar.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

Jika perintah berhasil dieksekusi, Anda akan melihat pesan yang mirip dengan yang ditampilkan di bawah:

Operation "operations/..." finished successfully.

Alternatif untuk perintah gcloud adalah melalui konsol dengan menelusuri setiap produk atau menggunakan link ini.

Jika ada API yang terlewat, Anda dapat mengaktifkannya kapan saja selama pelaksanaan.

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.

Buka Cloud Shell Editor dan Siapkan Direktori Kerja Aplikasi

Sekarang, kita dapat menyiapkan editor kode untuk melakukan beberapa hal terkait coding. Kita akan menggunakan Cloud Shell Editor untuk melakukannya

1. Klik tombol Open Editor, yang akan membuka Cloud Shell Editor, kita dapat menulis kode di sini
2. Pastikan project Cloud Code ditetapkan di pojok kiri bawah (status bar) editor Cloud Shell, seperti yang ditandai dalam gambar di bawah dan ditetapkan ke project Google Cloud aktif tempat Anda mengaktifkan penagihan. Authorize jika diminta. Jika Anda sudah mengikuti perintah sebelumnya, tombol tersebut juga dapat mengarah langsung ke project yang Anda aktifkan, bukan tombol login

Bersabarlah. Mungkin perlu waktu beberapa saat setelah menginisialisasi Editor Cloud Shell agar tombol Cloud Code - Sign In muncul

3. Selanjutnya, clone direktori kerja template untuk codelab ini dari GitHub dengan menjalankan perintah berikut. Perintah ini akan membuat direktori kerja di direktori deploy_and_manage_adk

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

4. Setelah itu, buka bagian atas Editor Cloud Shell, klik File->Open Folder, temukan direktori username Anda, lalu temukan direktori deploy_and_manage_adk, lalu klik tombol OK. Tindakan ini akan menjadikan direktori yang dipilih sebagai direktori kerja utama. Dalam contoh ini, nama penggunanya adalah alvinprayuda, sehingga jalur direktori ditampilkan di bawah

Sekarang, Cloud Shell Editor Anda akan terlihat seperti ini

Selanjutnya, kita dapat mengonfigurasi penyiapan lingkungan Python

Penyiapan Lingkungan

Siapkan Lingkungan Virtual Python

Langkah selanjutnya adalah menyiapkan lingkungan pengembangan. Direktori kerja terminal aktif Anda saat ini harus berada di dalam direktori kerja deploy_and_manage_adk. Kita akan menggunakan Python 3.12 dalam codelab ini dan kita akan menggunakan pengelola project python uv untuk menyederhanakan kebutuhan pembuatan dan pengelolaan versi python serta lingkungan virtual

1. Jika Anda belum membuka terminal, buka dengan mengklik Terminal -> New Terminal , atau gunakan Ctrl + Shift + C , yang akan membuka jendela terminal di bagian bawah browser

2. Download uv dan instal python 3.12 dengan perintah berikut

curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

3. Sekarang kita akan melakukan inisialisasi lingkungan virtual menggunakan uv. Jalankan perintah ini

uv sync --frozen

Tindakan ini akan membuat direktori .venv dan menginstal dependensi. Pratinjau cepat di pyproject.toml akan memberi Anda informasi tentang dependensi yang ditampilkan seperti ini

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]

Catatan: Dependensi Python dideklarasikan di dalam pyproject.toml dan dikunci versinya di dalam file uv.lock

4. Untuk menguji lingkungan virtual, buat file main.py baru dan salin kode berikut

def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()

5. Kemudian, jalankan perintah berikut

uv run main.py

Anda akan mendapatkan output seperti yang ditunjukkan di bawah

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

Ini menunjukkan bahwa project python sedang disiapkan dengan benar.

Catatan: Kita tidak perlu membuat lingkungan virtual secara manual atau mengaktifkannya karena uv sudah menanganinya. Mulai dari titik ini, perintah python standar (misalnya, python main.py) akan digantikan dengan uv run (misalnya, uv run main.py).

Menyiapkan File Konfigurasi

Sekarang kita perlu menyiapkan file konfigurasi untuk project ini.

Ganti nama file .env.example menjadi .env dan file tersebut akan menampilkan nilai di bawah. Perbarui nilai GOOGLE_CLOUD_PROJECT ke project-id Anda

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

Catatan Penting: Perbarui nilai GOOGLE_CLOUD_PROJECT dengan Project ID Anda

Untuk codelab ini, kita akan menggunakan nilai yang telah dikonfigurasi sebelumnya untuk GOOGLE_CLOUD_LOCATION dan GOOGLE_GENAI_USE_VERTEXAI. Untuk saat ini, kita akan membiarkan SESSION_SERVICE_URI dikomentari.

Sekarang kita dapat melanjutkan ke langkah berikutnya, yaitu memeriksa logika agen dan men-deploy-nya

3. Membangun Agen Cuaca dengan ADK dan Gemini 2.5

Pengantar Struktur Direktori ADK

Mari kita mulai dengan mempelajari apa yang ditawarkan ADK dan cara membuat agen. Dokumentasi lengkap ADK dapat diakses di URL ini . ADK menawarkan banyak utilitas dalam eksekusi perintah CLI-nya. Beberapa di antaranya adalah sebagai berikut :

• Menyiapkan struktur direktori agen
• Mencoba interaksi dengan cepat melalui input output CLI
• Menyiapkan antarmuka web UI pengembangan lokal dengan cepat

Sekarang, mari kita periksa struktur agen di direktori weather_agent

weather_agent/
├── __init__.py
├── agent.py

Jika Anda memeriksa init.py dan agent.py, Anda akan melihat kode ini

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.cloud import logging as google_cloud_logging

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)

# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather],
)

Catatan: Struktur direktori, impor agen di dalam init.py , dan deklarasi root_agent di agent.py adalah struktur wajib yang harus dikenali oleh ADK CLI.

Penjelasan Kode ADK

Skrip ini berisi inisiasi agen tempat kita menginisialisasi hal-hal berikut:

• Menetapkan model yang akan digunakan ke gemini-2.5-flash
• Menyediakan alat get_weather untuk mendukung fungsi agen sebagai agen cuaca

Menjalankan UI Web

Sekarang, kita dapat berinteraksi dengan agen dan memeriksa perilakunya secara lokal. ADK memungkinkan kita memiliki UI web pengembangan untuk berinteraksi dan memeriksa apa yang terjadi selama interaksi. Jalankan perintah berikut untuk memulai server UI pengembangan lokal

uv run adk web --port 8080

Perintah ini akan menghasilkan output seperti contoh berikut, yang berarti kita sudah dapat mengakses antarmuka web

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Sekarang, untuk memeriksanya, klik tombol Web Preview di area atas Cloud Shell Editor Anda, lalu pilih Preview on port 8080

Anda akan melihat halaman web berikut tempat Anda dapat memilih agen yang tersedia di tombol drop-down kiri atas ( dalam kasus ini, tombol tersebut adalah weather_agent) dan berinteraksi dengan bot. Anda akan melihat banyak informasi tentang detail log selama runtime agen di jendela kiri

Sekarang, coba berinteraksi dengannya. Di panel kiri, kita dapat memeriksa rekaman aktivitas untuk setiap input, sehingga kita dapat memahami berapa lama waktu yang diperlukan untuk setiap tindakan yang dilakukan oleh agen sebelum membentuk jawaban akhir.

Ini adalah salah satu fitur observasi yang telah dibangun ke dalam ADK, saat ini kami memeriksanya secara lokal. Selanjutnya, kita akan melihat cara mengintegrasikannya ke Cloud Tracing sehingga kita memiliki trace terpusat dari semua permintaan

Pengingat! Mari kita hentikan proses adk web untuk saat ini. Anda dapat menekan CTRL + C untuk menghentikan proses

4. Skrip Server Backend

Untuk membuat agen dapat diakses sebagai layanan, kita akan membungkus agen di dalam aplikasi FastAPI. Kita dapat mengonfigurasi layanan yang diperlukan untuk mendukung agen di sini seperti menyiapkan layanan Session, Memory, atau Artifact untuk tujuan produksi di sini. Berikut adalah kode server.py yang akan digunakan

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

Penjelasan Kode Server

Berikut adalah hal-hal yang ditentukan dalam skrip server.py:

1. Konversi agen kita menjadi aplikasi FastAPI menggunakan metode get_fast_api_app. Dengan cara ini, kita akan mewarisi definisi rute yang sama yang digunakan untuk UI pengembangan web.
2. Konfigurasi layanan Sesi, Memori, atau Artefak yang diperlukan dengan menambahkan argumen kata kunci ke metode get_fast_api_app. Dalam tutorial ini, jika kita mengonfigurasi variabel lingkungan SESSION_SERVICE_URI, layanan sesi akan menggunakannya, atau menggunakan sesi dalam memori
3. Kita dapat menambahkan rute kustom untuk mendukung logika bisnis backend lainnya. Dalam skrip, kita menambahkan contoh rute fungsi masukan
4. Aktifkan pelacakan cloud, untuk mengirim trace ke Google Cloud Trace

5. Men-deploy ke Cloud Run

Sekarang, deploy layanan agen ini ke Cloud Run. Untuk tujuan demo ini, layanan ini akan diekspos sebagai layanan publik yang dapat diakses oleh orang lain. Namun, perlu diingat bahwa ini bukan praktik terbaik karena tidak aman

Dalam codelab ini, kita akan menggunakan Dockerfile untuk men-deploy agen ke Cloud Run. Berikut adalah konten Dockerfile yang akan digunakan

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

Pada tahap ini, kita sudah memiliki semua file yang diperlukan untuk men-deploy aplikasi ke Cloud Run. Mari kita deploy. Buka Terminal Cloud Shell dan pastikan project saat ini dikonfigurasi ke project aktif Anda. Jika tidak, Anda harus menggunakan perintah gcloud configure untuk menyetel project ID:

gcloud config set project [PROJECT_ID]

Kemudian, jalankan perintah berikut untuk men-deploy-nya ke Cloud Run.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

Catatan Penting: Perbarui nilai YOUR_DB_CONNECTION_NAME, YOUR_DEFAULT_USER_PASS, dan YOUR_PROJECT_ID di sini.

Perhatikan juga bahwa kita memberikan SESSION_SERVICE_URI di sini sebagai variabel lingkungan untuk tujuan tutorial. Tindakan ini tidak direkomendasikan karena akan mengekspos nama pengguna dan sandi db. Coba gunakan secret untuk kasus seperti ini

Untuk mendapatkan nilai {YOUR_DB_CONNECTION_NAME}, Anda dapat membuka Cloud SQL lagi dan mengklik instance yang telah Anda buat. Di dalam halaman instance, scroll ke bawah ke bagian "Connect to this instance" dan Anda dapat menyalin Connection Name untuk menggantikan nilai {YOUR_DB_CONNECTION_NAME}. Misalnya, lihat gambar yang ditampilkan di bawah

Catatan: Saat SESSION_SERVICE_URI disiapkan, agen ADK kami akan menggunakan URI untuk layanan guna menyimpan informasi dan status sesi. Dalam tutorial ini, kita akan menggunakan koneksi soket Unix PostgreSQL dengan driver pg8000.

Perhatikan bahwa dalam contoh ini, kita menggunakan pengguna default postgres dan database default postgres . Jika Anda menggunakan nilai yang sama dengan tutorial, SESSION_SERVICE_URI Anda akan terlihat seperti ini

SESSION_SERVICE_URI="postgresql+pg8000://postgres:adk-deployment@postgres/?unix_sock=/cloudsql/{YOUR_PROJECT_ID}:us-central1:adk-deployment/.s.PGSQL.5432"

Oleh karena itu, Anda hanya perlu mengganti project ID di sini

Jika Anda diminta untuk mengonfirmasi pembuatan registry artefak untuk repositori Docker, cukup jawab Y. Perhatikan bahwa kami mengizinkan akses tanpa autentikasi di sini karena ini adalah aplikasi demo. Sebaiknya gunakan autentikasi yang sesuai untuk aplikasi produksi dan perusahaan Anda.

Setelah deployment selesai, Anda akan mendapatkan link yang mirip dengan di bawah ini:

https://weather-agent-*******.us-central1.run.app

Lanjutkan penggunaan aplikasi Anda dari jendela Samaran atau perangkat seluler Anda. Fitur ini seharusnya sudah aktif.

6. Memeriksa Penskalaan Otomatis Cloud Run dengan Pengujian Beban

Sekarang, kita akan memeriksa kemampuan penskalaan otomatis Cloud Run. Untuk skenario ini, mari deploy revisi baru sambil mengaktifkan konkurensi maksimum per instance. Jalankan perintah berikut

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --concurrency 10

Catatan Penting: Perbarui nilai YOUR_PROJECT_ID di sini.

Setelah itu, mari kita periksa file load_test.py. Ini akan menjadi skrip yang kita gunakan untuk melakukan pengujian beban menggunakan framework locust. Skrip ini akan melakukan hal berikut :

1. user_id dan session_id yang diacak
2. Buat session_id untuk user_id
3. Hit endpoint "/run_sse" dengan user_id dan session_id yang dibuat

Kita perlu mengetahui URL layanan yang di-deploy, jika Anda melewatkannya. Buka konsol Cloud Run dan klik layanan weather-agent Anda

Kemudian, temukan layanan weather-agent Anda, lalu klik

URL layanan akan ditampilkan tepat di samping informasi Region. Mis.

Kemudian, jalankan perintah berikut untuk melakukan uji beban

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

Catatan Penting: Perbarui nilai YOUR_SERVICE_URL di sini.

Catatan: ini akan menyimulasikan peningkatan permintaan pengguna paralel dari 0 hingga 60 dengan kecepatan 5 pengguna per detik selama periode 120 detik

Dengan menjalankan ini, Anda akan melihat metrik seperti ini ditampilkan. ( Dalam contoh ini, semua permintaan berhasil )

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00  

Kemudian, mari kita lihat apa yang terjadi di Cloud Run. Buka kembali layanan yang di-deploy, lalu lihat dasbornya. Hal ini akan menunjukkan cara Cloud Run menskalakan instance secara otomatis untuk menangani permintaan yang masuk. Karena kita membatasi konkurensi maksimum hingga 10 per instance, instance Cloud Run akan mencoba menyesuaikan jumlah penampung untuk memenuhi kondisi ini secara otomatis.

Catatan: Anda dapat mengontrol tidak hanya konkurensi maksimum, tetapi juga instance container minimum dan maksimum. Lihat dokumen SDK ini untuk mengetahui detailnya

7. Merilis Revisi Baru Secara Bertahap

Sekarang, mari kita lihat skenario berikut. Kita ingin memperbarui perintah agen menjadi berikut :

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information. You only answer inquiries about the weather. Refuse all other user query",
    tools=[get_weather],
)

Kemudian, Anda ingin merilis revisi baru, tetapi tidak ingin semua traffic permintaan langsung menuju ke versi baru. Kita dapat melakukan rilis bertahap dengan Cloud Run. Pertama, kita perlu men-deploy revisi baru, tetapi dengan tanda –no-traffic. Simpan skrip agen sebelumnya dan jalankan perintah berikut

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

Catatan Penting: Perbarui nilai YOUR_PROJECT_ID di sini

Setelah selesai, Anda akan menerima log yang serupa dengan proses deployment sebelumnya dengan perbedaan jumlah traffic yang ditayangkan. Kampanye ini akan menampilkan 0 persen traffic yang ditayangkan.

Selanjutnya, buka halaman produk Cloud Run dan temukan instance yang di-deploy. Ketik cloud run di kotak penelusuran, lalu klik produk Cloud Run

Kemudian, temukan layanan weather-agent Anda, lalu klik

Buka tab Revisi dan Anda akan melihat daftar revisi yang di-deploy di sana

Anda akan melihat bahwa revisi baru yang di-deploy menyajikan 0%, dari sini Anda dapat mengklik tombol kebab (⋮) dan memilih Kelola Traffic

Di jendela yang baru muncul, Anda dapat mengedit persentase traffic yang masuk ke revisi tertentu.

Setelah menunggu beberapa saat, traffic akan diarahkan secara proporsional berdasarkan konfigurasi persentase. Dengan begitu, kita dapat dengan mudah mengembalikan ke revisi sebelumnya jika terjadi masalah dengan rilis baru

8. Perekaman Aktivitas ADK

Agen yang dibuat dengan ADK sudah mendukung pelacakan menggunakan penyematan telemetri terbuka di dalamnya. Kita memiliki Cloud Trace untuk merekam pelacakan tersebut dan memvisualisasikannya. Mari kita periksa server.py tentang cara mengaktifkannya di layanan yang sebelumnya di-deploy

# server.py

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

Di sini, kita menginisialisasi tracer dan exporter. Detail eksportir dapat diperiksa di tracing.py . Di sini kita membuat pengekspor kustom karena ada batasan pada data rekaman aktivitas yang dapat diekspor ke Cloud Trace. Kami menggunakan penerapan dari https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html untuk kemampuan pelacakan ini.

Coba akses UI pengembangan web layanan Anda dan mulai percakapan dengan agen. Setelah itu, buka kolom penelusuran konsol cloud, ketik "trace explorer", lalu pilih produk Trace Explorer di sana

Di halaman trace explorer, Anda akan melihat percakapan kita dengan trace agen telah dikirimkan. Anda dapat melihat dari bagian Span name dan memfilter rentang khusus untuk agen kami ( bernama agent_run [weather_agent]) di sana

Jika rentang sudah difilter, Anda juga dapat memeriksa setiap rekaman aktivitas secara langsung. Bagian ini akan menampilkan durasi mendetail pada setiap tindakan yang dilakukan oleh agen. Misalnya, lihat gambar di bawah

Di setiap bagian, Anda dapat memeriksa detail dalam atribut seperti yang ditunjukkan di bawah

Sekarang kita memiliki kemampuan pengamatan dan informasi yang baik tentang setiap interaksi agen kita dengan pengguna untuk membantu men-debug masalah. Jangan ragu untuk mencoba berbagai alat atau alur kerja.

9. Tantangan

Coba alur kerja multi-agen atau agen untuk melihat performanya saat beban tinggi dan seperti apa rekaman aktivitasnya

10. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud, buka halaman Manage resources.
2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.
4. Atau, Anda dapat membuka Cloud Run di konsol, memilih layanan yang baru saja Anda deploy, lalu menghapusnya.