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 güvenli bir şekilde nasıl 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 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ı etkili bir şekilde nasıl 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. Başlamadan önce

Cloud Console'da Etkin Projeyi Seçme

Bu codelab'de, faturalandırmanın etkin olduğu bir Google Cloud projenizin olduğu varsayılmaktadır. Henüz kullanmıyorsanız başlamak için aşağıdaki talimatları uygulayabilirsiniz.

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın bir projede etkin olup olmadığını kontrol etmeyi öğrenin.

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. Öncelikle Cloud Console'un üst bölümündeki arama çubuğuna gidin ve "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 sürümünü seçin.

Ardından, postgres kullanıcısı için örnek adını ve varsayılan şifreyi buradan ayarlayın. Bunu istediğiniz kimlik bilgileriyle ayarlayabilirsiniz. Ancak bu eğitimde hem örnek adı hem de şifre için "adk-deployment"ı kullanacağız.

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.

Cloud Shell Terminal'de Cloud projesi oluşturma

Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:

gcloud auth list

gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.

gcloud config list project

Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:

gcloud config set project <YOUR_PROJECT_ID>

Alternatif olarak, PROJECT_ID kimliğini konsolda da görebilirsiniz.

Bu seçeneği tıkladığınızda sağ tarafta tüm projenizi ve proje kimliğini görürsünüz.

Aşağıda gösterilen komutu kullanarak gerekli API'leri etkinleştirin. Bu işlem birkaç dakika sürebilir. Lütfen bekleyin.

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.

Gcloud komutuna alternatif olarak, her ürünü arayarak veya bu bağlantıyı kullanarak konsolu kullanabilirsiniz.

Herhangi bir API atlanırsa uygulama sırasında istediğiniz zaman etkinleştirebilirsiniz.

gcloud komutları ve kullanımı için belgelere bakın.

Cloud Shell Düzenleyici'ye gidin 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.

Düzenleyiciyi aç düğmesini tıklayın. Bu işlemle Cloud Shell Düzenleyici açılır. Kodumuzu buraya yazabiliriz.
Cloud Shell düzenleyicisinin sol alt köşesinde (durum çubuğu) Cloud Code projesinin ayarlandığından emin olun. Bu proje, aşağıdaki resimde vurgulandığı gibi faturalandırmanın etkinleştirildiği etkin Google Cloud projesi olarak ayarlanmalıdır. İstenirse Yetkilendir'i seçin. Önceki komutu zaten uyguladıysanız düğme, oturum açma düğmesi yerine doğrudan etkinleştirilmiş projenize de yönlendirebilir.

Ardından, bu codelab için şablon çalışma dizinini GitHub'dan klonlayalım ve aşağıdaki komutu çalıştıralım. Ç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, 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üzenleyiciniz artık aşağıdaki gibi görünmelidir.

Ardından, Python ortamı kurulumumuzu yapılandırabiliriz.

Ortam Kurulumu

Python sanal ortamını hazırlama

Bir sonraki adım, geliştirme ortamını hazırlamaktır. Mevcut etkin terminal çalışma dizininiz, deploy_and_manage_adk çalışma dizininin içinde 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.

Terminali henüz açmadıysanız Terminal -> Yeni Terminal'i tıklayarak açın veya Ctrl + Üst Karakter + C tuşlarını kullanın. Bu tuşlar, tarayıcının alt kısmında bir terminal penceresi açar.

uv'yı indirin ve aşağıdaki komutla Python 3.12'yi yükleyin.

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

Şimdi uv kullanarak sanal ortamı başlatalım. Bu komutu çalıştırın.

uv sync --frozen

Bu işlem, .venv dizinini oluşturur ve bağımlılıkları yükler. pyproject.toml dosyasına hızlıca göz atarak, bağımlılıklar hakkında aşağıdaki gibi bilgiler edinebilirsiniz.

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

Sanal ortamı test etmek için main.py adlı yeni bir dosya oluşturun ve aşağıdaki kodu kopyalayın.

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

if __name__ == "__main__":
   main()

Ardından aşağıdaki komutu çalıştırın.

uv run main.py

Aşağıdaki gibi bir çıkış alırsınız.

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

Bu, Python projesinin düzgün şekilde ayarlandığını gösterir.

Yapılandırma dosyalarını ayarlama

Şimdi bu proje için yapılandırma dosyaları oluşturmamız gerekiyor.

.env.example dosyasını .env olarak yeniden adlandırın. Bu durumda, aşağıdaki değer gösterilir. GOOGLE_CLOUD_PROJECT değerini proje kimliğinizle güncelleyin.

# 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

Bu codelab'de GOOGLE_CLOUD_LOCATION ve GOOGLE_GENAI_USE_VERTEXAI. için önceden yapılandırılmış değerleri kullanacağız. Şimdilik SESSION_SERVICE_URI 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 Aracısı'nı 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 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 deneme
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

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

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.

Aşağıdaki web sayfasında, sol üstteki açılır düğmeden ( bizim durumumuzda weather_agent olmalıdır) kullanılabilir aracıları seçip bot ile etkileşim kurabilirsiniz. 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 bu öğeyle 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. Arka uç sunucu komut dosyası

Aracıyı hizmet olarak erişilebilir hale getirmek için FastAPI uygulamasına sarmalayacağız. Burada, üretim amaçlı olarak Oturum, Bellek veya Yapı hizmeti 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
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)

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 bulut izlemeyi etkinleştirin.

5. 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 bu yöntemin güvenli olmadığı için en iyi uygulama olmadığını unutmayın.

Bu codelab'de, aracımızı Cloud Run'a dağıtmak için Dockerfile'ı kullanacağız. Aşağıda, kullanılacak Dockerfile 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"]

Bu noktada, uygulamalarımızı Cloud Run'a dağıtmak için gereken tüm dosyalara sahibiz. Şimdi dağıtalım. Cloud Shell Terminali'ne gidin ve mevcut projenin etkin projeniz olarak yapılandırıldığından emin olun. Aksi takdirde, proje kimliğini ayarlamak için gcloud configure komutunu kullanmanız gerekir:

gcloud config set project [PROJECT_ID]

Ardından, Cloud Run'a dağıtmak için aşağıdaki komutu çalıştırın.

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

{YOUR_DB_CONNECTION_NAME} değerini almak için Cloud SQL'e tekrar gidip oluşturduğunuz örneği tıklayabilirsiniz. Örnek sayfasında "Bu örneğe bağlanın" bölümüne gidin ve {YOUR_DB_CONNECTION_NAME} değerinin yerine geçecek bağlantı adını kopyalayabilirsiniz. Örneğin, aşağıdaki resme bakın.

Docker deposu için bir Artifact Registry oluşturmayı onaylamanız istenirse Y yanıtını verin. Bunun bir demo uygulaması olması nedeniyle burada kimliği doğrulanmamış erişime izin verildiğini unutmayın. Kurumsal ve üretim uygulamalarınız için uygun kimlik doğrulama yöntemini kullanmanız önerilir.

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

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

Uygulamanızı gizli pencereden veya mobil cihazınızdan kullanmaya devam edebilirsiniz. Bu özellik şu anda kullanılabilir.

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. 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 \
                  --concurrency 10

Ardından 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 üst sınırını örnek başına 10 ile sınırladığımız için Cloud Run örneği, bu koşulu karşılamak üzere kapsayıcı sayısını otomatik olarak ayarlamaya çalışır.

7. Yeni düzeltmeleri aşamalı olarak yayınlama

Şimdi de aşağıdaki senaryoyu ele alalım. Temsilcinin istemini aşağıdaki gibi güncellemek istiyoruz :

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

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 {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. Sunulan trafik %0 olarak gösterilir.

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 Tracing

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

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)

...

Burada izleyiciyi ve dışa aktarıcıyı başlatıyoruz. Dışa aktarıcının ayrıntıları tracing.py adresinden incelenebilir . Cloud Trace'e aktarılabilecek izleme verileriyle ilgili bir sınır olduğundan burada özel bir dışa aktarıcı oluşturuyoruz. Bu izleme özelliği için https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html adresindeki bir uygulamayı kullanıyoruz.

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

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.