Bu sayfa, Cloud Translation API ile çevrilmiştir.

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'a 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ı ve ardından uygulamanızı üretime benzer bir ortamda yönetmenin pratik yönlerini öğreneceksiniz. Trafiği yöneterek aracınızın yeni sürümlerini nasıl güvenli bir şekilde kullanıma sunacağınızı ele alacağız. Bu sayede, yeni özellikleri tam sürüm yayınlanmadan önce bir kullanıcı alt kümesiyle test edebilirsiniz.

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 dünyadaki 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 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 Geliştirme Kurulumuna Hazırlanma

1. adım: Cloud Console'da Etkin Proje'yi seçin

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun (konsolunuzun sol üst bölümüne bakın).

Bu seçeneği tıkladığınızda, örnekteki gibi tüm projelerinizin listesini görürsünüz.

Kırmızı kutuyla belirtilen değer PROJE KİMLİĞİ'dir ve bu değer, eğitim boyunca kullanılacaktır.

Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bunu kontrol etmek için sol üst çubuğunuzdaki hamburger simgesini ☰ tıklayarak gezinme menüsünü gösterin ve Faturalandırma menüsünü bulun.

"Google Cloud Platform Deneme Faturalandırma Hesabı" ifadesini Faturalandırma / Genel Bakış başlığı altında ( Cloud Console'unuzun sol üst bölümü) görüyorsanız projeniz bu eğitimde kullanılmaya hazırdır. Aksi takdirde, bu eğitimin başına dönün ve deneme faturalandırma hesabını kullanın.

2. adım: Cloud SQL veritabanını hazırlayın

ADK aracısı tarafından daha sonra kullanılacak bir veritabanına ihtiyacımız olacak. Cloud SQL'de PostgreSQL veritabanı oluşturalım. Öncelikle 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.

Ardından yeni bir veritabanı örneği oluşturmamız gerekir. Create Instance'ı (Örnek oluştur) tıklayın ve PostgreSQL'i seçin.

Yeni bir projeyle başlıyorsanız Compute Engine API'yi de etkinleştirmeniz gerekebilir. Bu istem gösterilirse API'yi etkinleştir'i tıklayın.

Ardından, veritabanının özelliklerini seçeceğiz. Sandbox Edition ön ayarıyla Enterprise Edition'ı seçin.

Ardından, postgres kullanıcısı için örnek adını ve varsayılan şifreyi buradan ayarlayın. Bu kurulumu istediğiniz kimlik bilgileriyle yapabilirsiniz. Ancak bu eğitimde örnek ad için "adk-deployment", şifre için ise "ADK-deployment123" kullanılacaktır.

Bu eğitimde tek bölgeli us-central1'i kullanalım. Ardından, veritabanı oluşturma işlemimizi tamamlayıp Örnek Oluştur düğmesini tıklayarak gerekli tüm kurulumların tamamlanmasını sağlayabiliriz.

Bu işlemin tamamlanmasını beklerken sonraki bölüme geçebiliriz.

3. adım: Cloud Shell'i tanıyın

Eğitimlerin büyük bir bölümünde Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmındaki Cloud Shell'i Etkinleştir'i tıklayın. Yetkilendirmeniz istenirse Yetkilendir'i tıklayın.

Cloud Shell'e bağlandıktan sonra, kabuğun ( veya terminalin) hesabımızla kimliğinin doğrulanıp doğrulanmadığını kontrol etmemiz gerekir.

gcloud auth list

Aşağıdaki örnek çıktıda olduğu gibi kişisel Gmail'inizi görüyorsanız her şey yolundadır.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Aksi takdirde, tarayıcınızı yenilemeyi deneyin ve istendiğinde Yetkilendir'i tıkladığınızdan emin olun ( bağlantı sorunu nedeniyle kesintiye uğrayabilir).

Ardından, terminalde $simgesinden önce ( ) içinde değer görüyorsanız ( aşağıdaki ekran görüntüsünde değer "adk-cloudrun-deployment-476504") kabuğun doğru PROJE KİMLİĞİ ile yapılandırılıp yapılandırılmadığını da kontrol etmemiz gerekir. Bu değer, etkin kabuk oturumunuz için yapılandırılmış projeyi gösterir.

Gösterilen değer zaten doğruysa sonraki komutu atlayabilirsiniz. Ancak doğru değilse veya eksikse aşağıdaki komutu çalıştırın.

gcloud config set project <YOUR_PROJECT_ID>

Ardından, bu codelab için şablon çalışma dizinini GitHub'dan klonlayın ve 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

4. adım: Cloud Shell Editor ile tanışın ve uygulama çalışma dizinini ayarlayın

Şimdi kod düzenleyicimizi bazı kodlama işlemleri yapacak şekilde ayarlayabiliriz. Bu işlem için Cloud Shell Düzenleyici'yi kullanacağız.

Open Editor (Düzenleyiciyi Aç) düğmesini tıklayın. Bu işlem, Cloud Shell Düzenleyici'yi açar.

Ardından, Cloud Shell Düzenleyici'nin üst bölümüne gidip File->Open Folder'ı (Dosya->Klasör Aç) tıklayın,username (kullanıcı adı) dizininizi ve deploy_and_manage_adk dizinini bulup Tamam düğmesini tıklayın. Bu işlem, seçilen dizini ana çalışma dizini yapar. Bu örnekte, kullanıcı adı alvinprayuda olduğundan dizin yolu aşağıda gösterilmiştir.

Cloud Shell Düzenleyici çalışma dizininiz artık şu şekilde görünmelidir ( deploy_and_manage_adk içinde):

Şimdi düzenleyicinin terminalini açın. Menü çubuğunda Terminal -> New Terminal'ı tıklayarak veya Ctrl + Üst Karakter + C kısayolunu kullanarak yapabilirsiniz. Bu kısayol, tarayıcının alt kısmında bir terminal penceresi açar.

Mevcut etkin terminaliniz deploy_and_manage_adk çalışma dizininde olmalıdır. 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

Şimdi de aşağıdaki komutu kullanarak gerekli API'leri etkinleştirmemiz gerekiyor. Bu işlem biraz zaman alabilir.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.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.

Ardından, bu proje için yapılandırma dosyalarını ayarlamamız gerekir.

.env.example dosyasını .env olarak yeniden adlandırın.

cp .env.example .env

.env dosyasını açın ve GOOGLE_CLOUD_PROJECT değerini proje kimliğinizle güncelleyin.

# .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. Şimdilik DB_CONNECTION_NAME yorum satırı olarak kalacak.

Şimdi bir sonraki adıma geçebilir, aracı mantığını inceleyebilir ve dağıtabiliriz.

3. 🚀 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 temsilcinin nasıl oluşturulacağına göz atarak başlayalım. ADK'nın tüm belgelerine 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ü çalıştırma

Artık aracıyla 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 örneğe benzer bir çıktı oluşturulur. Bu, web arayüzüne erişebileceğ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şime geçmeyi deneyin. Sol çubukta, her giriş için izlemeyi inceleyebiliriz. Böylece, nihai yanıtı oluşturmadan önce aracı tarafından gerçekleştirilen her işlem için ne kadar süre gerektiğini anlayabiliriz.

Bu, ADK'ya yerleştirilmiş gözlemlenebilirlik özelliklerinden biridir ve ş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.

4. 🚀 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 codelab'de, 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 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. Yapılandırılmamışsa proje kimliğini ayarlamak için gcloud configure komutunu kullanmanız gerekir:

gcloud config set project [PROJECT_ID]

Ş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'e tekrar gidip oluşturduğunuz örneği tıklayabilirsiniz. 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çın ve 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.

5. 💡 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 aracıyı desteklemek için gerekli hizmetleri 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ünde 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.

6. 🚀 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 Console'a gidip weather-agent hizmetinizi tıklayın.

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

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

Ardından, yük testi yapmak için aşağıdaki komutu çalıştırın.

uv run locust -f load_test.py \
              -H {YOUR_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 sayısı, örnek başına 10 ile sınırlandırıldığından Cloud Run örneği, bu koşulu karşılamak için kapsayıcı sayısını otomatik olarak ayarlamaya çalışır.

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

Şimdi de aşağıdaki senaryoyu ele alalım. Temsilcinin istemini güncellemek istiyoruz. weather_agent/agent.py dosyasını açın 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 düzeltme dağıtmamız gerekiyor. Önceki aracı komut dosyasını kaydedin ve aşağıdaki komutu çalıştırın.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --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.

Ardından, Cloud Run ürün sayfasına gidip dağıtılan örneğinizi bulalım. Arama çubuğuna cloud run yazıp Cloud Run ürününü tıklayın.

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 dönebiliriz.

8. 🚀 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, Cloud Console arama çubuğuna gidip "trace explorer" yazın ve Trace Explorer ürününü seçin.

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

Kapsamlar 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.

9. 🎯 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.

10. 🧹 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.