Cloud Run'da ADK aracısı oluşturma ve dağıtma

1. Giriş

Bu laboratuvarda, istemci aracısı hizmetinin uygulanması ve dağıtımı üzerinde durulmaktadır. Araçları kullanan bir yapay zeka aracısı oluşturmak için Agent Development Kit (ADK)'yı kullanacaksınız.

Bu laboratuvarda, hayvanlarla ilgili soruları yanıtlamak için Wikipedia'yı kullanan bir hayvanat bahçesi temsilcisi oluşturacağız.

Soldan sağa doğru bir aslan, iki penguen, safari şapkalı bir kişi, bir fil ve bir ayı, sırtları izleyiciye dönük şekilde duruyor. Bu hayvanlar ve kişi, beyaz bulutlarla dolu mavi gökyüzüne fırlatılan büyük bir kırmızı ve beyaz rokete bakıyor. Ayrıca, uzakta fırlatılan iki küçük roket de görülüyor. Sahne, ahşap çit ve kayalık uçurumların bulunduğu bir hayvanat bahçesi içinde yer alıyor.

Son olarak, tur rehberi aracısını yalnızca yerel olarak çalıştırmak yerine Google Cloud Run'a dağıtacağız.

Ön koşullar

  • Faturalandırmanın etkin olduğu bir Google Cloud projesi.

Neler öğreneceksiniz?

  • ADK dağıtımı için Python projesini yapılandırma
  • google-adk ile araç kullanan bir aracı nasıl uygulayabilirsiniz?
  • Python uygulamasını Cloud Run'a sunucusuz container olarak dağıtma
  • IAM rollerini kullanarak hizmetten hizmete güvenli kimlik doğrulama yapılandırma
  • Gelecekteki maliyetlerden kaçınmak için Cloud kaynaklarını silme

İhtiyacınız olanlar

  • Google Cloud hesabı ve Google Cloud projesi
  • Chrome gibi bir web tarayıcısı

2. Neden Cloud Run'a dağıtmalısınız?

Cloud Run, ADK aracılarını barındırmak için mükemmel bir seçimdir. Sunucusuz bir platform olduğu için altyapıyı yönetmek yerine kodunuza odaklanabilirsiniz. Operasyonel işleri sizin için biz hallederiz.

Bunu bir pop-up mağaza gibi düşünebilirsiniz: Yalnızca müşteriler (istekler) geldiğinde açılır ve kaynakları kullanır. Müşteri olmadığında tamamen kapanır ve boş bir mağaza için ödeme yapmazsınız.

Temel Özellikler

Her Yerde Kapsayıcı Çalıştırma:

  • Uygulamanızın bulunduğu bir container (Docker görüntüsü) getirirsiniz.
  • Cloud Run, bu işlemi Google'ın altyapısında gerçekleştirir.
  • İşletim sistemi yaması, sanal makine kurulumu veya ölçeklendirme ile ilgili sorunlar yok.

Otomatik Ölçeklendirme:

  • Uygulamanızı kullanan kişi sayısı 0 ise → 0 örnek çalıştırılır (maliyet açısından avantajlı olan sıfır örneğe kadar ölçeklendirilir).
  • 1.000 istek gelirse → gerektiği kadar kopya oluşturur.

Varsayılan olarak durum bilgisi yok:

  • Her istek farklı bir örneğe gidebilir.
  • Durumu depolamanız gerekiyorsa Cloud SQL, Firestore veya Memorystore gibi harici bir hizmet kullanın.

Herhangi bir dili veya çerçeveyi destekler:

  • Cloud Run, Linux kapsayıcısında çalıştığı sürece Python, Go, Node.js, Java veya .Net olup olmadığını önemsemez.

Kullandığınız Kadar Ödeyin:

3. Proje ayarlama

Google Hesabı

Kişisel Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir.

İş veya okul hesabı yerine kişisel hesap kullanın.

Google Cloud Console'da oturum açma

Kişisel bir Google Hesabı kullanarak Google Cloud Console'da oturum açın.

Faturalandırmayı Etkinleştir

Kişisel faturalandırma hesabı oluşturma

Faturalandırmayı Google Cloud kredilerini kullanarak ayarladıysanız bu adımı atlayabilirsiniz.

Kişisel faturalandırma hesabı oluşturmak için Cloud Console'da faturalandırmayı etkinleştirmek üzere buraya gidin.

Bazı notlar:

  • Bu laboratuvarı tamamlamak için 1 ABD dolarından daha az tutarda bulut kaynağı kullanmanız gerekir.
  • Daha fazla ödeme alınmaması için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
  • Yeni kullanıcılar 300 ABD doları değerindeki ücretsiz denemeden yararlanabilir.

Proje oluşturma (isteğe bağlı)

Bu laboratuvar için kullanmak istediğiniz mevcut bir projeniz yoksa buradan yeni bir proje oluşturun.

4. Cloud Shell Düzenleyici'yi açma

  1. Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
  2. Bugün herhangi bir noktada yetkilendirmeniz istenirse devam etmek için Yetkilendir'i tıklayın.Cloud Shell'e yetki vermek için tıklayın.
  3. Terminal ekranın alt kısmında görünmüyorsa açın:
    • Görünüm'ü tıklayın.
    • Terminal'i tıklayın.Cloud Shell Düzenleyici'de yeni terminal açma

5. API'leri etkinleştir

Cloud Run, Artifact Registry, Cloud Build, Vertex AI ve Compute Engine'i kullanmak için Google Cloud projenizde ilgili API'leri etkinleştirmeniz gerekir.

  • Terminalde API'leri etkinleştirin:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    Bu işlem tamamlandığında aşağıdaki gibi bir çıkış görürsünüz:
    Operation "operations/acat.p2-[GUID]" finished successfully.

API'lerle tanışın

  • Cloud Run Admin API (run.googleapis.com), ön uç ve arka uç hizmetlerini, toplu işleri veya web sitelerini tamamen yönetilen bir ortamda çalıştırmanıza olanak tanır. Container mimarisine alınmış uygulamalarınızı dağıtma ve ölçeklendirme altyapısını yönetir.
  • Artifact Registry API (artifactregistry.googleapis.com), kapsayıcı resimlerinizi depolamak için güvenli ve özel bir depo sağlar. Container Registry'nin gelişmiş sürümüdür ve Cloud Run ile Cloud Build'e sorunsuz bir şekilde entegre olur.
  • Cloud Build API (cloudbuild.googleapis.com), derlemelerinizi Google Cloud altyapısında yürüten sunucusuz bir CI/CD platformudur. Container görüntünüzü Dockerfile'ınızdan bulutta oluşturmak için kullanılır.
  • Vertex AI API (aiplatform.googleapis.com), dağıtılan uygulamanızın temel yapay zeka görevlerini gerçekleştirmek için Gemini modelleriyle iletişim kurmasını sağlar. Google Cloud'un tüm yapay zeka hizmetleri için birleşik API sağlar.
  • Compute Engine API (compute.googleapis.com), Google'ın altyapısında çalışan güvenli ve özelleştirilebilir sanal makineler sağlar. Cloud Run yönetilirken çeşitli ağ iletişimi ve bilgi işlem kaynakları için temel bağımlılık olarak genellikle Compute Engine API gerekir.

6. Geliştirme ortamınızı hazırlama

Dizini oluşturma

  1. Terminalde proje dizinini ve gerekli alt dizinleri oluşturun:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. Terminalde aşağıdaki komutu çalıştırarak Cloud Shell Düzenleyici Gezgin'de zoo_guide_agent dizinini açın:
    cloudshell open-workspace ~/zoo_guide_agent
  3. Soldaki Gezgin paneli yenilenir. Oluşturduğunuz dizini göreceksiniz.
    Gezgin yan panelindeki yeni dizinin ekran görüntüsü

Projenizi ayarlama

  1. Terminalde şu komutla projenizi ayarlayın:
    gcloud config set project [PROJECT_ID]
    Örnek: gcloud config set project lab-project-id-example Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  2. Şu mesajı görmeniz gerekir:
    Updated property [core/project].

Yükleme şartları

  1. requirements.txt dosyasını oluşturmak için terminalde aşağıdaki komutu çalıştırın.
    cloudshell edit requirements.txt
  2. Yeni oluşturulan requirements.txt dosyasına aşağıdakileri ekleyin.
    google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. Terminalde, uv'yi kullanarak sanal bir ortam oluşturun ve etkinleştirin. Bu şekilde, proje bağımlılıklarınızın sistem Python'uyla çakışmaması sağlanır.
    uv venv
source .venv/bin/activate
  4. Gerekli paketleri terminalde sanal ortamınıza yükleyin.
    uv pip install -r requirements.txt

Ortam değişkenlerini ayarlama

  • .env dosyasını oluşturmak için terminalde aşağıdaki komutu kullanın.
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-2.5-flash"
EOF

7. Aracı İş Akışı Oluşturma

__init__.py dosyası oluşturma

  1. Terminalde aşağıdaki komutu çalıştırarak init.py dosyasını oluşturun:
    cloudshell edit __init__.py
    Bu dosya, Python'a zoo_guide_agent dizininin bir paket olduğunu bildirir.
  2. Yeni __init__.py dosyasına aşağıdaki kodu ekleyin:
    from . import agent

agent.py dosyasını oluşturma

  1. Aşağıdaki komutu terminale yapıştırarak ana agent.py dosyasını oluşturun.
    cloudshell edit agent.py
  2. İçe Aktarma ve İlk Kurulum: Şu anda boş olan agent.py dosyanıza aşağıdaki kodu ekleyin:
    import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

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

load_dotenv()

model_name = os.getenv("MODEL")
    agent.py dosyasının bu ilk bloğu, ADK ve Google Cloud'dan gerekli tüm kitaplıkları getirir. Ayrıca, modelinize ve sunucu URL'nize erişmek için çok önemli olan .env dosyanızdaki ortam değişkenlerini yükler ve günlük kaydını ayarlar.
  3. Araçları tanımlayın: Bir aracı, yalnızca kullanabileceği araçlar kadar iyidir. Araçları tanımlamak için agent.py dosyasının en altına aşağıdaki kodu ekleyin:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    Araçlar Açıklanıyor
    • add_prompt_to_state 📝: Bu araç, hayvanat bahçesi ziyaretçisinin sorduklarını hatırlar. Bir ziyaretçi "Aslanlar nerede?" diye sorduğunda bu araç, söz konusu soruyu temsilcinin belleğine kaydeder. Böylece iş akışındaki diğer temsilciler neyi araştırmaları gerektiğini bilir.
      Nasıl: Ziyaretçinin istemini paylaşılan tool_context.state sözlüğüne yazan bir Python işlevidir. Bu araç bağlamı, aracının tek bir görüşmedeki kısa süreli belleğini temsil eder. Bir temsilci tarafından duruma kaydedilen veriler, iş akışındaki bir sonraki temsilci tarafından okunabilir.
    • LangchainTool 🌍: Bu, tur rehberi aracısına genel dünya bilgisi verir. Bir ziyaretçi, hayvanat bahçesinin veritabanında bulunmayan bir soru sorduğunda (ör. "Aslanlar vahşi doğada ne yer?") bu araç, temsilcinin Wikipedia'da yanıtı aramasına olanak tanır.
      Nasıl: Bir bağdaştırıcı görevi görerek aracımızın LangChain kitaplığındaki önceden oluşturulmuş WikipediaQueryRun aracını kullanmasına olanak tanır.
      Güleryüzlü robot, hayvan çizimlerinin olduğu bir not defteri ve aslan düşünce balonuyla bir adam ve sırt çantalı bir çocukla konuşuyor. Arka planda zürafalar ve diğer hayvanat bahçesi öğeleri, girişi çerçeveleyen palmiye ağaçları görülüyor.
  4. Uzman aracıları tanımlayın: comprehensive_researcher ve response_formatter aracılarını tanımlamak için agent.py dosyasının en altına aşağıdaki kodu ekleyin:
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • comprehensive_researcher temsilcisi, operasyonumuzun "beynidir". Paylaşılan State istemini alır, Wikipedia Aracı'nı inceler ve yanıtı bulmak için hangilerinin kullanılacağına karar verir.
    • response_formatter temsilcisinin rolü sunumdur. Araştırmacı aracısı tarafından toplanan ham verileri (State üzerinden iletilir) alır ve LLM'nin dil becerilerini kullanarak bunları samimi ve sohbet tarzında bir yanıta dönüştürür.
      Mavi gözleri parlayan robot, sol tarafta MCP ZOO SERVER, sağ tarafta ise ZOO Wikipedia sayfası gösteren büyük ve kavisli bir monitörün önünde oturuyor. Hayvan simgeleri, sunucu arayüzünde görünür. Masanın üzerinde birden fazla mavi ışıklı dokunmatik yüzey var. Arka planda büyük pencerelerden görünen bir şehir silüeti yer alıyor.
  5. İş akışı aracısını tanımlayın: Sıralı aracıyı tour_guide_workflow tanımlamak için bu kod bloğunu agent.py öğesinin en altına ekleyin:
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    İş akışı aracısı, hayvanat bahçesi turunun "arka ofis" yöneticisi olarak görev yapar. Araştırma isteğini alır ve yukarıda tanımladığımız iki aracının görevlerini doğru sırada (önce araştırma, sonra biçimlendirme) yapmasını sağlar. Bu sayede, ziyaretçilerin sorularını yanıtlama konusunda öngörülebilir ve güvenilir bir süreç oluşturulur.
    Nasıl: SequentialAgent, kendi başına düşünmeyen özel bir aracı türüdür. Tek görevi, sub_agents (araştırmacı ve biçimlendirici) listesini sabit bir sırayla çalıştırmak ve paylaşılan belleği otomatik olarak birinden diğerine aktarmaktır.
  6. Ana iş akışını oluşturun: agent.py bölümünün en altına aşağıdaki son kod bloğunu ekleyerek root_agent öğesini tanımlayın:
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
    ADK çerçevesi, tüm yeni görüşmeler için başlangıç noktası olarak root_agent simgesini kullanır. Birincil rolü, genel süreci yönetmektir. İlk kontrolör olarak hareket eder ve görüşmenin ilk dönüşünü yönetir.
    Üç robot gösteriliyor: Solda, aslan düşünce baloncuğuyla not defterine yazı yazan bir Karşılama Robotu, ortada, verilerin gösterildiği bir bilgisayarla masada oturan ve kendisine doğru yönlendirilmiş bir sorgu oku olan bir Araştırma Robotu, sağda ise &quot;Analiz Edilmiş Veriler&quot; etiketli bir grafik tutarak gülümseyen ve Araştırma Robotu&#39;nun kendisine doğru yönlendirdiği bir ok olan bir Sunum Robotu. Arka planda zürafalar ve filler görülüyor, sahneyi palmiye ağaçları çerçeveliyor.

Tam agent.py dosyası

agent.py dosyanız tamamlandı. Bu şekilde oluşturarak her bileşenin (araçlar, çalışan aracıları ve yönetici aracıları) nihai ve akıllı sistemi oluşturmada nasıl belirli bir role sahip olduğunu görebilirsiniz.

Dosyanın tamamı şu şekilde görünmelidir:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

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

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Sıradaki adım: Dağıtım

8. Uygulamayı dağıtıma hazırlama

Son yapıyı kontrol etme

Dağıtmadan önce proje dizininizin doğru dosyaları içerdiğini doğrulayın.

  • zoo_guide_agent klasörünüzün şu şekilde göründüğünden emin olun:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

IAM izinlerini ayarlama

Yerel kodunuz hazır olduğunda bir sonraki adım, aracınızın bulutta kullanacağı kimliği ayarlamaktır.

  1. Terminalde değişkenleri kabuk oturumunuza yükleyin.
    source .env
  2. Cloud Run hizmetiniz için özel bir hizmet hesabı oluşturarak hizmetin kendi iznine sahip olmasını sağlayın. Aşağıdakileri terminale yapıştırın:
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    Bu uygulama için özel bir kimlik oluşturarak, aracının aşırı geniş erişime sahip varsayılan bir hesap kullanmak yerine yalnızca ihtiyaç duyduğu izinlere sahip olmasını sağlarsınız.
  3. Hizmet hesabına, Google'ın modellerini çağırma izni veren Vertex AI Kullanıcısı rolünü atayın.
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

9. ADK CLI'yı kullanarak aracı dağıtma

Yerel kodunuz hazır ve Google Cloud projeniz hazırlanmış durumdayken aracı dağıtma zamanı gelmiştir. Tüm dağıtım iş akışını otomatikleştiren kullanışlı bir araç olan adk deploy cloud_run komutunu kullanacaksınız. Bu tek komut, kodunuzu paketler, bir container görüntüsü oluşturur, bu görüntüyü Artifact Registry'ye gönderir ve hizmeti Cloud Run'da başlatarak web'de erişilebilir hale getirir.

  1. Aracınızı dağıtmak için terminalde aşağıdaki komutu çalıştırın.
    # Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    uvx komutu, Python paketleri olarak yayınlanan komut satırı araçlarını bu araçların genel olarak yüklenmesini gerektirmeden çalıştırmanıza olanak tanır.
  2. Aşağıdaki istemi alırsanız:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    Bu durumda Y yazıp ENTER tuşuna basın.
  3. Aşağıdaki istemi alırsanız:
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    y yazıp ENTER tuşuna basın. Bu sayede, kolay test için bu laboratuvarda kimliği doğrulanmamış çağırmalara izin verilir. Başarılı bir şekilde yürütüldüğünde komut, dağıtılan Cloud Run hizmetinin URL'sini sağlar. (https://zoo-tour-guide-123456789.europe-west1.run.app gibi görünür.)
  4. Sonraki görev için dağıtılan Cloud Run hizmetinin URL'sini kopyalayın.

10. Dağıtılan temsilciyi test etme

Temsilciniz artık Cloud Run'da yayında olduğuna göre, dağıtımın başarılı olduğunu ve temsilcinin beklendiği gibi çalıştığını onaylamak için bir test yapacaksınız. ADK'nın web arayüzüne erişmek ve aracıyla etkileşim kurmak için herkese açık hizmet URL'sini (https://zoo-tour-guide-123456789.europe-west1.run.app/ gibi) kullanırsınız.

  1. Herkese açık Cloud Run hizmeti URL'sini web tarayıcınızda açın. --with_ui flag kullandığınız için ADK geliştirici kullanıcı arayüzünü görmeniz gerekir.
  2. Sağ üstteki Token Streaming simgesini açın.
    Artık hayvanat bahçesi temsilcisiyle etkileşimde bulunabilirsiniz.
  3. Yeni bir görüşme başlatmak için hello yazıp Enter tuşuna basın.
  4. Sonucu inceleyin. Aracı, aşağıdaki gibi bir selamlama mesajıyla hızlıca yanıt vermelidir:
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Temsilciye şu gibi sorular sorun:
    Where can I find the polar bears in the zoo and what is their diet?
    ADK aracısının bir dizi işlem yaptığına dair ekran görüntüsü: add_prompt_to_state, transfer_to_agent, wikipedia ve get_animals_by_species. İlk yanıtta, &quot;Bu hayvanat bahçesindeki kutup ayılarını nerede bulabileceğinizi söyleyemem ancak beslenme şekilleri hakkında bilgi verebilirim.&quot; ifadesi yer alıyor. İkinci yanıtta, &quot;Kutup ayıları, Kutup Yolu&#39;ndaki Kutup Sergisi&#39;nde yer alıyor. Mevcut araçlarla beslenme düzenleri hakkında bilgi alamıyorum.&quot; Üçüncü ve en kapsamlı yanıt ise &quot;Kutup ayılarımız hakkında bilgi vermekten memnuniyet duyarım. Kutup ayılarımızı Polar Yolu&#39;ndaki Kutup Sergisi&#39;nde bulabilirsiniz. Burada üç kutup ayısı var: 7 yaşındaki Snowflake, Blizzard, 5 yaşında. 9 yaşındaki Iceberg Beslenme şekillerine gelince, kutup ayıları çoğunlukla etoburdur. Özellikle halkalı foklar olmak üzere fokları avlama konusunda uzmanlaşmışlardır. Ayrıca mors, beyaz balina ve bazı kara hayvanlarını da yerler.

Temsilci Akışı Açıklaması

Sisteminiz akıllı bir çoklu aracı ekibi olarak çalışır. Süreç, kullanıcının sorusundan nihai ve ayrıntılı cevaba kadar sorunsuz ve verimli bir akış sağlamak için net bir sırayla yönetilir.

1. Hayvanat Bahçesi Karşılama Görevlisi (Karşılama Masası)

Tüm süreç, karşılama temsilcisiyle başlar.

  • Görevi: Sohbeti başlatmak. Talimatı, kullanıcıyı selamlamak ve hangi hayvan hakkında bilgi edinmek istediğini sormaktır.
  • Its Tool: Kullanıcı yanıtladığında Karşılayıcı, kullanıcının tam olarak ne söylediğini (ör. "Aslanlar hakkında bilgi ver") ve bunları sistemin belleğine kaydeder.
  • Devretme: Talimat kaydedildikten sonra kontrol hemen alt aracısı olan tour_guide_workflow'a geçer.

2. Kapsamlı Araştırmacı (Süper Araştırmacı)

Bu, ana iş akışındaki ilk adım ve operasyonun "beyni"dir. Artık büyük bir ekibiniz yerine, mevcut tüm bilgilere erişebilen tek bir yüksek vasıflı temsilciniz var.

  • Görevi: Kullanıcının sorusunu analiz edip akıllı bir plan oluşturmak. Aşağıdaki durumlarda dil modelinin araç kullanma özelliğinden yararlanır:
    • Web'den (Wikipedia API aracılığıyla) alınan genel bilgiler.
    • Karmaşık sorular için ise her ikisini de kullanabilirsiniz.

3. Yanıt Biçimlendirici (Sunucu)

Kapsamlı Araştırmacı tüm bilgileri topladıktan sonra çalıştırılacak son aracıdır.

  • Görevi: Hayvanat Bahçesi Tur Rehberi'nin samimi sesi olarak hareket etmek. Bu özellik, ham verileri (bir veya iki kaynaktan alınmış olabilir) alıp düzenler.
  • İşlevi: Tüm bilgileri tek, tutarlı ve ilgi çekici bir yanıtta birleştirir. Talimatlarına uyarak önce belirli hayvanat bahçesi bilgilerini sunuyor, ardından ilginç genel bilgileri ekliyor.
  • Nihai Sonuç: Bu aracı tarafından oluşturulan metin, kullanıcının sohbet penceresinde gördüğü eksiksiz ve ayrıntılı yanıttır.

Aracı oluşturma hakkında daha fazla bilgi edinmek isterseniz aşağıdaki kaynakları inceleyin:

  1. ADK belgeleri
  2. ADK Temsilcileri İçin Özel Araçlar Oluşturma

11. Ortamı temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek amacıyla kaynakları içeren projeyi silin veya projeyi koruyup tek tek kaynakları silin.

Cloud Run hizmetlerini ve görüntülerini silme

Google Cloud projesini korumak ancak bu laboratuvarda oluşturulan belirli kaynakları kaldırmak istiyorsanız hem çalışan hizmeti hem de kayıt defterinde depolanan kapsayıcı görüntüsünü silmeniz gerekir.

  • Terminalde aşağıdaki komutları çalıştırın:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

Projeyi silme (isteğe bağlı)

Bu laboratuvar için özel olarak yeni bir proje oluşturduysanız ve projeyi tekrar kullanmayı planlamıyorsanız temizlemenin en kolay yolu projenin tamamını silmektir. Bu işlem, hizmet hesabı ve gizli derleme yapıları da dahil olmak üzere tüm kaynakların tamamen kaldırılmasını sağlar.

  • Terminalde aşağıdaki komutu çalıştırın ([YOUR_PROJECT_ID] kısmını gerçek proje kimliğinizle değiştirin):
    gcloud projects delete $PROJECT_ID

12. Tebrikler

Google Cloud'da çok agent'lı bir yapay zeka uygulamasını başarıyla oluşturup dağıttınız.

Özet

Bu laboratuvarda, boş bir dizinden canlı ve herkese açık bir yapay zeka hizmetine geçtiniz. İşte oluşturduğunuz öğeler:

  • Uzman bir ekip oluşturdunuz: Genel bir yapay zeka yerine, olguları bulmak için "Araştırmacı" ve yanıtı düzenlemek için "Biçimlendirici"yi oluşturdunuz.
  • Onlara araçlar verdiniz: Wikipedia API'yi kullanarak temsilcilerinizi dış dünyaya bağladınız.
  • Başardınız: Yerel Python kodunuzu alıp Cloud Run'da sunucusuz bir kapsayıcı olarak dağıttınız ve özel bir hizmet hesabıyla güvenliğini sağladınız.

İşlediğimiz konular

  • ADK ile dağıtım için Python projesini yapılandırma
  • [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) kullanarak çoklu aracı iş akışı uygulama.
  • Wikipedia API gibi harici araçları entegre etme
  • adk deploy komutunu kullanarak Cloud Run'a nasıl aracı dağıtılacağı

13. Anket

Çıkış:

Bu eğitimi nasıl kullanacaksınız?

Sadece okuyun Okuyun ve alıştırmaları tamamlayın