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 ajanı oluşturmak için Agent Development Kit'i (ADK) kullanacaksınız.

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

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, sunucusuz bir platform olduğu için ADK aracılarını barındırmak için mükemmel bir seçimdir. Bu sayede, altyapıyı yönetmek yerine kodunuza odaklanabilirsiniz. Operasyonel işleri sizin için biz hallederiz.

Bunu bir pop-up mağazaya benzetebiliriz: 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

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

• Uygulamanızı içeren bir container (Docker görüntüsü) getirirsiniz.
• Cloud Run, bu işlemi Google'ın altyapısında çalıştırır.
• İş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 ö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:

• İsteğe dayalı faturalandırma: İstek başına + işlem süresi (100 ms'ye kadar) faturalandırılır.
• Örnek tabanlı faturalandırma: Örnek kullanım süresinin tamamı için faturalandırılır (istek başına ücret alınmaz).

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.

İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.

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 ücret alınmaması için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
• Yeni kullanıcılar 300 ABD doları değerinde ücretsiz deneme sürümünden yararlanabilir.

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

Bu laboratuvarda 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.
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.

5. Projenizi ayarlama

1. Terminalde şu komutla projenizi ayarlayın:

   gcloud config set project [PROJECT_ID]
   

   Örnek: gcloud config set project lab-project-id-example

   Proje kimliğinizi hatırlamıyorsanız gcloud projects list komutuyla tüm proje kimliklerinizi listeleyebilirsiniz.

   
2. Şu mesajı görmeniz gerekir:

   Updated property [core/project].
   

   WARNING simgesini görüyorsanız ve Do you want to continue (Y/n)? soruluyorsa proje kimliğini yanlış girmiş olabilirsiniz. n tuşuna, Enter tuşuna basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.

6. 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ğıdakine benzer 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 işlem kaynakları için temel bağımlılık olarak genellikle Compute Engine API'si gerekir.

7. 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örürsünüz.
   
   

   Bunu yaptığınızda terminal kaybolursa üst menüde Görünüm'ü ve ardından Terminal'i tıklayarak terminali yeniden açabilirsiniz.

   CRITICAL: Yeni bir çalışma alanı açtığınızda Cloud Shell Düzenleyici sıfırlanır ve terminal oturumunuz yeniden başlatılır. Terminali yeniden açtığınızdan, doğru dizinde olduğunuzu doğruladığınızdan (gerekirse pwd ve cd ~/zoo_guide_agent komutlarını çalıştırın) ve gcloud projenizin hâlâ seçili olduğundan (gerekirse gcloud config set project [PROJECT_ID] komutunu çalıştırın) emin olmanız gerekir.~/zoo_guide_agent

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==2.4.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
   

   Not: Cloud Shell oturumunuz yenilenirse veya yeni bir terminal sekmesi açarsanız source .venv/bin/activate komutunu çalıştırarak sanal ortamı yeniden etkinleştirmeniz gerekebilir.

4. Gerekli paketleri terminalde sanal ortamınıza yükleyin.

   uv pip install -r requirements.txt
   

Hizmet hesabı oluşturma ve IAM izinlerini yapılandırma

Aracı oluşturmadan önce bir hizmet hesabı oluşturmanız ve gerekli izinleri yapılandırmanız gerekir. Bu sayede aracınız Vertex AI modellerini çağırabilir ve Cloud Build, uygulamanızı başarıyla dağıtabilir.

1. Terminalde, Cloud Run hizmetiniz için özel bir hizmet hesabı oluşturun:

   SA_NAME=lab-service-account
   PROJECT_ID=$(gcloud config get-value project)
   gcloud iam service-accounts create ${SA_NAME} \
       --display-name="Service Account for Zoo Agent"
   

2. Aracınızın Gemini'ı çağırabilmesi için hizmet hesabına Vertex AI Kullanıcısı rolünü verin:

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   

3. Cloud Build izinlerini yapılandırın. Modern Google Cloud projeleri varsayılan hizmet hesabı izinlerini kısıtladığından, varsayılan Compute Engine hizmet hesabına kapsayıcınızı oluşturup dağıtmak için gereken rolleri vermeniz gerekir. Terminalde şu komutları çalıştırın:

   PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   
   # Grant Artifact Registry Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/artifactregistry.writer"
   
   # Grant Storage Object Viewer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/storage.objectViewer"
   
   # Grant Logs Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/logging.logWriter"
   

Ortam değişkenlerini ayarlama

Şimdi, temsilci ve dağıtım komut dosyası tarafından kullanılan ortam değişkenlerini içeren bir .env dosyası oluşturacaksınız.

1. Önceki adımda değişkenleri terminal oturumunuzda tanımladığınız için .env dosyasını doğrudan oluşturabilirsiniz:

   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-3.5-flash"
   EOF
   

   .env dosyasını kontrol edin ve PROJECT_ID, PROJECT_NUMBER ve SERVICE_ACCOUNT değerlerinin atandığından emin olun. Proje ayrıntıları eksikse gcloud projects list komutunu çalıştırarak bu ayrıntıları bulun. gcloud iam service-accounts list komutunu çalıştırarak hizmet hesabının mevcut olduğunu doğrulayabilirsiniz.

8. 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
   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 ---
   
   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 ajanın performansı, kullanabileceği araçlarla sınırlıdır. 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
   api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
   api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
   wikipedia_tool = LangchainTool(
       tool=WikipediaQueryRun(api_wrapper=api_wrapper)
   )
   

   Araçlar Açıklanıyor
   • add_prompt_to_state 📝: Bu araç, hayvanat bahçesi ziyaretçilerinin 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 çalışır? 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 eyalete 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. (Wikipedia aracını yapılandırma ve çağırma hakkında daha fazla bilgiyi Wikipedia Aracını Kullanma kılavuzunda bulabilirsiniz.)
     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.
     
     
4. Uzman aracılarını tanımlayın: comprehensive_researcher ve response_formatter aracılarını tanımlamak için agent.py öğesinin 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 ajanı, 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 bu verileri samimi ve sohbet tarzında bir yanıta dönüştürür.
     
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'nın 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 dosyasının en altına aşağıdaki son kod bloğunu ekleyerek root_agent işlevini 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 kullanır. Birincil rolü, genel süreci yönetmektir. İlk kontrolcü olarak hareket eder ve görüşmenin ilk dönüşünü yönetir.
   

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

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
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 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

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

Son yapıyı kontrol edin

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
  

.gcloudignore dosyasını yapılandırma ve ortam değişkenlerini yükleme

1. Sanal ortamınızın (.venv/) ve diğer gereksiz dosyaların Google Cloud'a yüklenmesini önlemek için zoo_guide_agent dizininde bir .gcloudignore dosyası oluşturun:

   cloudshell edit .gcloudignore
   

2. .gcloudignore alanına aşağıdaki içeriği ekleyin:

   .gcloudignore
   .git
   .gitignore
   .venv/
   venv/
   __pycache__/
   .env
   

3. Ortam değişkenlerini terminal oturumunuza yükleyin:

   source .env
   

   Not: Cloud Shell oturumunuz yenilenirse veya yeni bir terminal sekmesi açarsanız dağıtımdan önce bu değişkenleri yeniden yüklemek için source .env komutunu tekrar çalıştırmanız gerekir.

10. ADK KSA'sını kullanarak aracı dağıtma

Yerel kodunuz hazır ve Google Cloud projeniz hazırlanmış durumdayken artık aracıyı dağıtma zamanı. Tüm dağıtım iş akışını otomatik hâle getiren 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==2.4.0 \
   adk deploy cloud_run \
     --project=$PROJECT_ID \
     --region=europe-west1 \
     --service_name=zoo-tour-guide \
     --with_ui \
     . \
     -- \
     --allow-unauthenticated \
     --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
     --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.

   Not: Aşağıdaki dağıtım komutunun çalışması birkaç dakika sürer.

2. Aşağıdaki mesajı görürseniz:

   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. Komut başarıyla yürütüldüğünde 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.

11. Dağıtılan ajanı 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 (ör. https://zoo-tour-guide-123456789.europe-west1.run.app/) 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örürsünüz.
2. Sağ üstteki Token Streaming simgesini açın.
   Artık Zoo temsilcisiyle etkileşimde bulunabilirsiniz.
3. Yeni bir görüşme başlatmak için hello yazıp Enter tuşuna basın.
4. Sonucu gözlemleyin. 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. Ajana şu gibi sorular sorun:

   Where can I find the polar bears in the zoo and what is their diet?
   

   

Agent Flow Açıklaması

Sisteminiz akıllı bir çoklu ajan 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. Kullanıcıyı karşılaması ve hangi hayvan hakkında bilgi edinmek istediğini sorması talimatı veriliyor.
• Its Tool: Kullanıcı yanıt verdiğinde Karşılayıcı, kullanıcının tam olarak ne söylediğini (ör. "bana aslanlardan bahset") yakalamak ve bunları sistemin belleğine kaydetmek için add_prompt_to_state aracını kullanır.
• Devretme: Talimat kaydedildikten sonra kontrol hemen alt aracısı olan tour_guide_workflow'a geçer.

2. Kapsamlı Araştırmacı (The Super-Researcher)

Bu, ana iş akışının ilk adımı ve operasyonun "beyni"dir. Artık büyük bir ekibiniz yerine, mevcut tüm bilgilere erişebilen tek bir uzman 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 Turu 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 hayvanat bahçesiyle ilgili bilgileri sunuyor, ardından genel olarak ilgi çekici bilgileri ekliyor.
• Sonuç: Bu ajan 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 kaynaklara göz atın:

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

12. 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, resimlerini ve kaynaklarını silme

Google Cloud projesini korumak ancak bu laboratuvarda oluşturulan belirli kaynakları kaldırmak istiyorsanız çalışan hizmeti, kapsayıcı resmi kayıt defterini, geçici kaynak depolama paketini ve hizmet hesabı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
  gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
  gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --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] yerine gerçek proje kimliğinizi girin):

  gcloud projects delete $PROJECT_ID
  

  Proje silme işlemi geri alınamaz. Devam etmeden önce lütfen bu projenin başka bir iş için kullanılmadığından emin olun.

13. Tebrikler

Google Cloud'da çoklu aracı içeren 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:

• Özel 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" oluşturursunuz.
• Onlara araçlar verdiniz: Ajanlarınızı Wikipedia API'yi kullanarak 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 projesi oluşturma
• [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) kullanarak çoklu ajan iş akışı uygulama
• Wikipedia API gibi harici araçları entegre etme
• adk deploy komutunu kullanarak Cloud Run'a nasıl aracı dağıtacağınız.

14. Anket

Çıkış:

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

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