Cloud Run'da ADK aracısını dağıtma, yönetme ve gözlemleme

1. Giriş

Bu eğitimde, Google Cloud Run'da Agent Development Kit (ADK) ile oluşturulmuş güçlü bir aracı dağıtma, yönetme ve izleme konusunda size yol gösterilecektir. ADK, karmaşık ve çok aracılı iş akışları oluşturabilen aracılar oluşturmanıza olanak tanır. Tümüyle yönetilen bir sunucusuz platform olan Cloud Run'dan yararlanarak, temel altyapı konusunda endişelenmeden aracılarınızı ölçeklenebilir, container mimarisine alınmış uygulamalar olarak dağıtabilirsiniz. Bu güçlü kombinasyon, Google Cloud'un sağlam ve ölçeklenebilir ortamından yararlanırken aracınızın temel mantığına odaklanmanızı sağlar.

Bu eğitimin tamamında ADK'nın Cloud Run ile sorunsuz entegrasyonunu inceleyeceğiz. Aracınızı nasıl dağıtacağınızı öğrenecek ve ardından uygulamanızı üretime benzer bir ortamda yönetmenin pratik yönlerini inceleyeceksiniz. Trafiği yöneterek aracınızın yeni sürümlerini güvenli bir şekilde kullanıma sunacağınız ve yeni özellikleri tam sürümden önce bir kullanıcı alt kümesiyle test etmenizi sağlayacak yöntemleri ele alacağız.

Ayrıca, temsilcinizin performansını izleme konusunda uygulamalı deneyim kazanacaksınız. Cloud Run'ın otomatik ölçeklendirme özelliklerini uygulamada gözlemlemek için bir yük testi yaparak gerçek hayattaki bir senaryoyu simüle edeceğiz. Aracınızın davranışı ve performansı hakkında daha ayrıntılı analizler elde etmek için Cloud Trace ile izlemeyi etkinleştireceğiz. Bu sayede, istekler aracınızda ilerlerken uçtan uca ayrıntılı bir görünüm elde edebilir, performansla ilgili darboğazları belirleyip giderebilirsiniz. Bu eğitimin sonunda, Cloud Run'da ADK destekli aracılarınızı nasıl etkili bir şekilde dağıtacağınız, yöneteceğiniz ve izleyeceğiniz konusunda kapsamlı bir bilgiye sahip olacaksınız.

Bu codelab'de aşağıdaki gibi adım adım bir yaklaşım kullanacaksınız:

ADK Agent veritabanı oturum hizmeti için kullanılacak Cloud SQL'de bir PostgreSQL veritabanı oluşturun.
Temel bir ADK aracısı ayarlama
ADK çalıştırıcısı tarafından kullanılacak veritabanı oturumu hizmetini ayarlama
Aracıyı Cloud Run'a ilk kez dağıtma
Yük testi yapma ve Cloud Run otomatik ölçeklendirmesini inceleme
Yeni aracı düzeltmesini dağıtma ve yeni düzeltmelere yönelik trafiği kademeli olarak artırma
Bulut izlemeyi ayarlama ve aracı çalıştırma izlemeyi inceleme

Mimariye Genel Bakış

Ön koşullar

Python ile rahatça çalışabilme
HTTP hizmetini kullanan temel tam yığın mimarisi hakkında bilgi sahibi olmak

Neler öğreneceksiniz?

ADK yapısı ve yerel yardımcı programlar
Veritabanı oturumu hizmetiyle ADK aracısını kurma
Veritabanı oturumu hizmeti tarafından kullanılmak üzere Cloud SQL'de PostgreSQL'i ayarlama
Dockerfile kullanarak uygulamayı Cloud Run'a dağıtma ve ilk ortam değişkenlerini ayarlama
Yük testiyle Cloud Run otomatik ölçeklendirmeyi yapılandırma ve test etme
Cloud Run ile kademeli yayın stratejisi
ADK aracısı izlemeyi Cloud Trace'e yönlendirme

Gerekenler

Chrome web tarayıcısı
Gmail hesabı
Faturalandırmanın etkin olduğu bir Cloud projesi

Her seviyeden geliştirici (yeni başlayanlar dahil) için tasarlanan bu codelab'de örnek uygulamada Python kullanılmaktadır. Ancak sunulan kavramları anlamak için Python bilgisi gerekmez.

2. 🚀 Atölye kurulumuna hazırlanma

Bu eğitimde Cloud Shell IDE'yi kullanacağız. Buraya gitmek için aşağıdaki düğmeyi tıklayın.

Cloud Shell'e girdikten sonra, bu codelab için şablon çalışma dizinini GitHub'dan klonlamak üzere aşağıdaki komutu çalıştırın. Çalışma dizini, deploy_and_manage_adk dizininde oluşturulur.

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

Ardından, klonlanan depoyu çalışma dizininiz olarak açmak için terminalde aşağıdaki komutu çalıştırın.

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

Ardından arayüzünüz aşağıdaki gibi görünmelidir.

Bu, ana arayüzümüz olacak. Üstte IDE, altta terminal yer alacak. Şimdi, daha önce talep edilen deneme faturalandırma hesabına bağlanacak Google Cloud projemizi oluşturup etkinleştirmek için terminalimizi hazırlamamız gerekiyor. Terminal oturumunuzun her zaman hazır olmasını sağlamak için bir komut dosyası hazırladık. Aşağıdaki komutu çalıştırın ( deploy_and_manage_adk çalışma alanında olduğunuzdan emin olun):

bash setup_trial_project.sh && source .env

Bu komutu çalıştırdığınızda proje kimliği adı önerisiyle karşılaşacaksınız. Devam etmek için Enter tuşuna basabilirsiniz.

Bir süre bekledikten sonra konsolunuzda bu çıktıyı görürseniz bir sonraki adıma geçebilirsiniz.

Bu, terminalinizin kimliğinin zaten doğrulandığını ve doğru proje kimliğine ( mevcut dizin yolunun yanındaki sarı renk) ayarlandığını gösterir. Bu komut, yeni bir proje oluşturmanıza, projeyi bulup deneme faturalandırma hesabına bağlamanıza, .env dosyasını ortam değişkeni yapılandırması için hazırlamanıza ve terminalde doğru proje kimliğini etkinleştirmenize yardımcı olur.

Şimdi bir sonraki adıma geçmeye hazırız.

3. 🚀 API'leri etkinleştirme

Bu eğitimde Cloud SQL veritabanı, Gemini modeli ve Cloud Run ile etkileşim kuracağız. Bu ürünlerin etkinleştirilmesi için aşağıdaki API'nin etkinleştirilmesi gerekir. Bu API'yi etkinleştirmek için aşağıdaki komutları çalıştırın.

Bu işlem biraz zaman alabilir.

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

Komut başarıyla yürütüldüğünde aşağıda gösterilene benzer bir mesaj görürsünüz:

Operation "operations/..." finished successfully.

4. 🚀 Python Ortamını Kurma ve Ortam Değişkenleri

Bu codelab'de Python 3.12'yi kullanacağız. Python sürümü ve sanal ortam oluşturma ve yönetme ihtiyacını basitleştirmek için uv python proje yöneticisini kullanacağız. Bu uv paketi, Cloud Shell'e önceden yüklenmiştir.

.venv dizinindeki sanal ortama gerekli bağımlılıkları yüklemek için bu komutu çalıştırın.

uv sync --frozen

Ardından, bu proje için gerekli ortam değişkeni dosyalarını inceleyeceğiz. Bu dosya daha önce setup_trial_project.sh komut dosyası tarafından ayarlanıyordu. .env dosyasını düzenleyicide açmak için aşağıdaki komutu çalıştırın:

cloudshell open .env

.env dosyasında aşağıdaki yapılandırmaların zaten uygulandığını görürsünüz.

# .env

# 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
# DB_CONNECTION_NAME=your-db-connection-name

Bu codelab'de GOOGLE_CLOUD_LOCATION ve GOOGLE_GENAI_USE_VERTEXAI. için önceden yapılandırılmış değerleri kullanacağız.

Şimdi bir sonraki adıma geçebiliriz: Temsilcimizin durum ve oturum kalıcılığı için kullanacağı veritabanını oluşturma.

5. 🚀 Cloud SQL veritabanını hazırlama

ADK aracısı tarafından daha sonra kullanılacak bir veritabanına ihtiyacımız olacak. Cloud SQL'de PostgreSQL veritabanı oluşturalım. Önce veritabanı örneğini oluşturmak için aşağıdaki komutu çalıştırın. Varsayılan postgres veritabanı adını kullanacağımız için burada veritabanı oluşturma adımını atlayacağız. Ayrıca, varsayılan veritabanı kullanıcı adımızı da (postgres) yapılandırmamız gerekiyor. Eğitimin devamı için şifremiz olarak ADK-deployment123'ü kullanalım.

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

Yukarıdaki komutta, ilk ortak gcloud sql instances create adk-deployment, veritabanı örneğini oluşturmak için kullandığımız bir komuttur. Bu eğitimde, sandbox için minimum spesifikasyon kullanıyoruz. Varsayılan postgres kullanıcı adı şifresini değiştirmek için kullanılan ikinci komut gcloud sql users set-password postgres

Veritabanı örneği adı olarak adk-deployment'ı kullandığımızı unutmayın. İşlem tamamlandığında, terminalde aşağıdaki gibi bir çıkış görürsünüz. Bu çıkış, örneğin hazır olduğunu ve varsayılan kullanıcı şifresinin güncellendiğini gösterir.

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done.

Bu veritabanının dağıtılması biraz zaman alacağından CloudSQL veritabanı dağıtımının hazır olmasını beklerken bir sonraki bölüme geçelim.

6. 🚀 ADK ve Gemini 2.5 ile Hava Durumu Temsilcisi'ni oluşturma

ADK dizin yapısına giriş

ADK'nın sunduğu özelliklere ve temsilci oluşturma sürecine göz atarak başlayalım. ADK'nın tam dokümanına bu URL'den erişebilirsiniz . ADK, KSA komut yürütme özelliğiyle birçok yardımcı program sunar. Bunlardan bazıları şunlardır :

Aracı dizin yapısını ayarlama
KSA giriş çıkışı üzerinden etkileşimi hızlıca deneyin
Yerel geliştirme kullanıcı arayüzü web arayüzünü hızlıca kurma

Şimdi weather_agent dizinindeki aracı yapısını kontrol edelim.

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

Ayrıca init.py ve agent.py dosyalarını incelerseniz bu kodu görürsünüz.

# __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 weather_agent.tool import get_weather

# 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")

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],
)

ADK Kod Açıklaması

Bu komut dosyası, aşağıdaki öğeleri başlattığımız aracı başlatma kodumuzu içerir:

Kullanılacak modeli gemini-2.5-flash olarak ayarlayın.
Hava durumu aracısı olarak aracının işlevselliğini desteklemek için araç get_weather'ı sağlama

Web kullanıcı arayüzünü yerel olarak çalıştırma

Artık temsilciyle etkileşim kurabilir ve davranışını yerel olarak inceleyebiliriz. ADK, etkileşim sırasında neler olduğunu incelemek ve etkileşimde bulunmak için bir geliştirme web kullanıcı arayüzü kullanmamıza olanak tanır. Yerel geliştirme kullanıcı arayüzü sunucusunu başlatmak için aşağıdaki komutu çalıştırın:

uv run adk web --port 8080

Aşağıdaki örnekteki gibi bir çıkış oluşturur. Bu, web arayüzüne erişebildiğimiz anlamına gelir.

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)

Şimdi bunu kontrol etmek için Cloud Shell Düzenleyicinizin üst kısmındaki Web Önizlemesi düğmesini tıklayın ve 8080 bağlantı noktasında önizle'yi seçin.

Sol üstteki açılır düğmeden ( bizim durumumuzda weather_agent olmalıdır) kullanılabilir aracıları seçebileceğiniz ve bot ile etkileşim kurabileceğiniz aşağıdaki web sayfasını görürsünüz. Sol pencerede, temsilci çalışma zamanı sırasında günlük ayrıntılarıyla ilgili birçok bilgi görürsünüz.

Şimdi onunla etkileşim kurmayı deneyin. Sol çubukta, her girişin izini inceleyebiliriz. Böylece, nihai yanıtı oluşturmadan önce aracının gerçekleştirdiği her işlem için ne kadar süre gerektiğini anlayabiliriz.

Bu, ADK'ya yerleştirilmiş gözlemlenebilirlik özelliklerinden biridir. Şu anda yerel olarak incelenmektedir. Daha sonra, tüm isteklerin merkezi izine sahip olmak için bu entegrasyonun Cloud Trace ile nasıl yapıldığını göreceğiz.

7. 🚀 Cloud Run'a dağıtma

Şimdi bu aracı hizmetini Cloud Run'a dağıtalım. Bu demoda, bu hizmet başkalarının erişebileceği herkese açık bir hizmet olarak sunulacaktır. Ancak güvenli olmadığı için bunun en iyi uygulama olmadığını unutmayın.

Bu dağıtım senaryosu, aracı arka uç hizmetinizi özelleştirmenize olanak tanır. Aracımızı Cloud Run'a dağıtmak için Dockerfile kullanacağız. Bu noktada, uygulamalarımızı Cloud Run'a dağıtmak için gereken tüm dosyalara ( Dockerfile ve server.py) sahibiz. Bu iki öğeye sahip olarak aracı dağıtımınızı esnek bir şekilde özelleştirebilirsiniz ( ör. özel arka uç rotaları ekleme ve/veya izleme amacıyla ek bir yardımcı hizmet ekleme). Bu konuyu daha sonra ayrıntılı olarak ele alacağız.

Şimdi önce hizmeti dağıtalım, Cloud Shell Terminal'e gidelim ve mevcut projenin etkin projeniz için yapılandırıldığından emin olalım. Kurulum komut dosyasını tekrar çalıştıralım. İsteğe bağlı olarak, etkin projenizi yapılandırmak için gcloud config set project [PROJECT_ID] komutunu da kullanabilirsiniz.

bash setup_trial_project.sh && source .env

Şimdi .env dosyasını tekrar ziyaret etmemiz, açmamız ve DB_CONNECTION_NAME değişkeninin yorumdan çıkarılması ve doğru değerle doldurulması gerektiğini görmemiz gerekiyor.

# 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
DB_CONNECTION_NAME=your-db-connection-name

DB_CONNECTION_NAME değerini almak için Cloud SQL kontrol panelini ziyaret edelim.

ardından oluşturduğunuz örneği tıklayın. Cloud Console'un üst bölümündeki arama çubuğuna gidip "cloud sql" yazın. Ardından Cloud SQL ürününü tıklayın.

Daha önce oluşturulan örneği görürsünüz, bu örneği tıklayın.

Örnek sayfasında "Bu örneğe bağlanın" bölümüne gidin ve DB_CONNECTION_NAME değerinin yerine kullanmak üzere Bağlantı Adı'nı kopyalayabilirsiniz.

Ardından, .env dosyasını aşağıdaki komutla açın.

cloudshell edit .env

ve .env dosyasındaki DB_CONNECTION_NAME değişkenini değiştirin. .env dosyanız aşağıdaki örneğe benzer olmalıdır.

# 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
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

Ardından dağıtım komut dosyasını çalıştırın.

bash deploy_to_cloudrun.sh

Docker deposu için bir Artifact Registry oluşturmayı onaylamanız istenirse Y yanıtını verin.

Dağıtım sürecini beklerken deploy_to_cloudrun.sh dosyasına göz atalım.

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

Bu komut dosyası, .env değişkeninizi yükler ve ardından dağıtım komutunu çalıştırır.

Daha yakından bakarsanız bir hizmeti dağıtmak istediğinizde yapılması gereken tüm işlemleri (ör. resmi oluşturma, kayıt defterine gönderme, hizmeti dağıtma, IAM politikasını ayarlama, revizyon oluşturma ve hatta trafiği yönlendirme) yapmak için yalnızca bir gcloud run deploy komutuna ihtiyacımız olduğunu görürsünüz. Bu örnekte Dockerfile'ı zaten sağladığımız için bu komut, uygulamayı oluşturmak için Dockerfile'ı kullanır.

Dağıtım tamamlandığında aşağıdakine benzer bir bağlantı alırsınız:

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

Bu URL'yi aldıktan sonra, uygulamanızı gizli pencereden veya mobil cihazınızdan kullanabilir ve aracı geliştirici kullanıcı arayüzüne erişebilirsiniz. Dağıtımın tamamlanmasını beklerken, bir sonraki bölümde dağıttığımız ayrıntılı hizmeti inceleyelim.

8. 💡 Dockerfile ve arka uç sunucu komut dosyası

Aracıyı hizmet olarak erişilebilir hale getirmek için aracı, Dockerfile komutunda çalıştırılacak bir FastAPI uygulamasının içine yerleştiririz. Aşağıda Dockerfile'ın içeriği yer almaktadır.

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"]

Burada, Oturum, Bellek veya Yapı hizmetini üretime hazırlama gibi gerekli hizmetleri aracıyı destekleyecek şekilde yapılandırabiliriz. Kullanılacak server.py kodunu aşağıda bulabilirsiniz.

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


# 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, "trace_to_cloud": 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",
    )

# 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 = ""


# Example if you want to add your custom endpoint
@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)

Sunucu Kodu Açıklaması

server.py komut dosyasında tanımlananlar:

get_fast_api_app yöntemini kullanarak aracımızı FastAPI uygulamasına dönüştürün. Bu sayede, web geliştirme kullanıcı arayüzü için kullanılan aynı rota tanımını devralırız.
Anahtar kelime bağımsız değişkenlerini get_fast_api_app yöntemine ekleyerek gerekli oturum, bellek veya yapay ürün hizmetini yapılandırın. Bu eğitimde, SESSION_SERVICE_URI ortam değişkenini yapılandırırsak oturum hizmeti bunu kullanır, aksi takdirde bellek içi oturumu kullanır.
Diğer arka uç iş mantığını desteklemek için özel rota ekleyebiliriz. Komut dosyasına geri bildirim işlevselliği rota örneği ekliyoruz.
İzlemeyi Google Cloud Trace'e göndermek için get_fast_api_app arg parametrelerinde bulut izlemeyi etkinleştirin.
uvicorn kullanarak FastAPI hizmetini çalıştırma

Dağıtımınız tamamlandıysa lütfen Cloud Run URL'sine erişerek web geliştirici kullanıcı arayüzünden temsilciyle etkileşim kurmayı deneyin.

9. 🚀 Yük testi ile Cloud Run otomatik ölçeklendirmesini inceleme

Şimdi Cloud Run'ın otomatik ölçeklendirme özelliklerini inceleyeceğiz. Bu senaryoda, örnek başına maksimum eşzamanlılık sayısını etkinleştirirken yeni düzeltmeyi dağıtalım. Önceki bölümde, maksimum eşzamanlılık değerini 10 olarak ayarladık ( --concurrency 10 işareti). Bu nedenle, bu sayıyı aşan bir yük testi yaptığımızda Cloud Run'ın örneğini ölçeklendirmeye çalışmasını bekleyebiliriz.

load_test.py dosyasını inceleyelim. Bu, locust çerçevesini kullanarak yük testi yapmak için kullanacağımız komut dosyasıdır. Bu komut dosyası aşağıdaki işlemleri yapar :

Rastgele oluşturulmuş user_id ve session_id
user_id için session_id oluşturma
Oluşturulan user_id ve session_id ile "/run_sse" uç noktasına isabet edin.

Dağıtılan hizmet URL'mizi kaçırdıysanız bize bildirmeniz gerekir. Cloud Run konsoluna gidebiliriz.

Ardından, weather-agent hizmetinizi bulup tıklayın.

Hizmet URL'si, Bölge bilgisinin hemen yanında gösterilir. Ör.

İşinizi kolaylaştırmak için, yakın zamanda dağıtılan hizmet URL'nizi almak ve SERVICE_URL ortam değişkeninde depolamak üzere aşağıdaki komut dosyasını çalıştıralım.

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

Ardından, aracı uygulamamızı yükleme testine tabi tutmak için aşağıdaki komutu çalıştırın.

uv run locust -f load_test.py \
              -H $SERVICE_URL \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

Bu komutu çalıştırdığınızda aşağıdaki gibi metrikler gösterilir. ( Bu örnekte tüm istekler başarılıdır.)

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

Ardından Cloud Run'da neler olduğunu görmek için dağıtılan hizmetinize tekrar gidin ve kontrol paneline bakın. Bu işlem, gelen istekleri işlemek için örneğin otomatik olarak nasıl ölçeklendirildiğini gösterir. Eşzamanlılık sınırını örnek başına 10 ile sınırlandırdığımız için Cloud Run örneği, bu koşulu otomatik olarak karşılamak üzere kapsayıcı sayısını ayarlamaya çalışır.

10. 🚀 Yeni düzeltmeleri aşamalı olarak kullanıma sunma

Şimdi de aşağıdaki senaryoyu ele alalım. Temsilcinin istemini güncellemek istiyoruz. Aşağıdaki komutla weather_agent/agent.py dosyasını açın.

cloudshell edit weather_agent/agent.py

ve aşağıdaki kodla üzerine yazın:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# 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")

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.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

Ardından, yeni düzeltmeler yayınlamak istiyorsunuz ancak tüm istek trafiğinin doğrudan yeni sürüme gitmesini istemiyorsunuz. Cloud Run ile kademeli yayın yapabiliriz. Öncelikle –no-traffic işaretini kullanarak yeni bir revizyon dağıtmamız gerekir. Önceki aracı komut dosyasını kaydedin ve aşağıdaki komutu çalıştırın

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project $GOOGLE_CLOUD_PROJECT \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

İşlem tamamlandıktan sonra, sunulan trafik sayısı dışında önceki dağıtım sürecine benzer bir günlük alırsınız. %0 trafik yayınlandığı gösterilir.

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

Şimdi Cloud Run kontrol paneline gidelim.

Ardından, weather-agent hizmetinizi bulup tıklayın.

Düzeltmeler sekmesine gidin. Burada, dağıtılan düzeltmelerin listesini görürsünüz.

Yeni dağıtılan düzeltmelerin %0 oranında yayınlandığını görürsünüz. Buradan üç noktalı düğmeyi (⋮) tıklayıp Trafiği Yönet'i seçebilirsiniz.

Yeni açılan pencerede, hangi revizyonlara gidecek trafiğin yüzdesini düzenleyebilirsiniz.

Bir süre bekledikten sonra trafik, yüzde yapılandırmalarına göre orantılı olarak yönlendirilir. Bu sayede, yeni sürümde bir sorun yaşanırsa önceki düzeltmelere kolayca geri çekebiliriz.

11. 🚀 ADK İzleme

ADK ile oluşturulan aracıların izleme özelliği, açık telemetri yerleştirme kullanılarak desteklenir. Bu izlemeyi yakalayıp görselleştirmek için Cloud Trace'i kullanırız. Daha önce dağıtılan hizmetimizde nasıl etkinleştirdiğimizi görmek için server.py dosyasını inceleyelim.

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

Burada, trace_to_cloud bağımsız değişkenini True olarak iletiyoruz. Diğer seçeneklerle dağıtım yapıyorsanız çeşitli dağıtım seçeneklerinden Cloud Trace'e izlemeyi etkinleştirme hakkında daha fazla bilgi için bu dokümanı inceleyebilirsiniz.

Hizmetinizin web geliştirme kullanıcı arayüzüne erişmeyi deneyin ve temsilciyle sohbet edin. Ardından Trace Explorer sayfasına gidelim.

İzleme gezgini sayfasında, temsilci iziyle olan görüşmemizin gönderildiğini görürsünüz. Span adı bölümünden görebilir ve temsilcimize özgü span'i ( agent_run [weather_agent] olarak adlandırılır) filtreleyebilirsiniz.

Aralıklar zaten filtrelenmişse her izlemeyi doğrudan da inceleyebilirsiniz. Temsilcinin yaptığı her işlemle ilgili ayrıntılı süre gösterilir. Örneğin, aşağıdaki resimlere bakın.

Her bölümde, aşağıdaki örnekte gösterildiği gibi özelliklerdeki ayrıntıları inceleyebilirsiniz.

Artık sorunları ayıklamaya yardımcı olmak için temsilcimizin kullanıcıyla her etkileşimi hakkında iyi bir gözlemlenebilirlik ve bilgiye sahibiz. Çeşitli araçları veya iş akışlarını denemekten çekinmeyin.

12. 🎯 Hedef

Yük altında nasıl performans gösterdiklerini ve izlemenin nasıl göründüğünü görmek için çoklu aracı veya aracı tabanlı iş akışlarını deneyin.

13. 🧹 Temizleme

Bu codelab'de kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.
Alternatif olarak, konsolda Cloud Run'a gidebilir, yeni dağıttığınız hizmeti seçip silebilirsiniz.