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

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

• Python ve komut satırı arayüzleri hakkında bilgi sahibi olmanız gerekir.
• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• Yüklü KSA araçları: gcloud, gsutil, uv.

Neler öğreneceksiniz?

• ADK dağıtımı için Python projesi nasıl yapılandırılır?
• Google-adk ile araç kullanan bir aracı nasıl uygulayabilirim?
• 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 maliyetleri önlemek için Cloud kaynaklarını nasıl sileceğinizi öğrenin.

İhtiyacınız olanlar

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

2. Neden Cloud Run'a dağıtım yapmalısınız?

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

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

• Uygulamanızın bulunduğu bir container (Docker görüntüsü) getirirsiniz.
• Cloud Run, bu kapsayıcıyı Google'ın altyapısında çalıştırır.
• İşletim sistemi yaması, VM 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şturulur.

Varsayılan olarak durum bilgisi yok:

• Her istek farklı bir örneğe gidebilir.
• Durumu saklamanı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 olmamasıyla ilgilenmez.

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: Tam örnek ömrü 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 tüm proje kimliklerinizi şu komutla listeleyebilirsiniz: gcloud projects list

   
2. Şu mesajı görürsünüz:

   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 basın, 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, Gemini Enterprise Agent Platform 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'lerin tanıtımı

• Cloud Run Admin API (run.googleapis.com), tamamen yönetilen bir ortamda ön uç ve arka uç hizmetleri, toplu işler veya web siteleri ç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ü olan Artifact Registry, Cloud Run ve Cloud Build ile 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. Dockerfile'ınızdan bulutta kapsayıcı görüntünüzü oluşturmak için kullanılır.
• Gemini Enterprise Agent Platform 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 Compute Engine API, çeşitli ağ ve bilgi işlem kaynakları için temel bağımlılık olarak sıklıkla gereklidir.

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 ~/zoo_guide_agent (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.

Yükleme koşulları

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 sayede, 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 Gemini Enterprise Agent Platform 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. Ajanınızın Gemini'ı çağırabilmesi için hizmet hesabına Gemini Enterprise Agent Platform User 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ı bulabilirsiniz. gcloud iam service-accounts list komutunu çalıştırarak hizmet hesabının mevcut olduğunu doğrulayabilirsiniz.

8. Ajan iş 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ın Açıklaması
   • 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 aracının belleğine kaydeder. Böylece iş akışındaki diğer aracılar 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ı, ajanın tek bir görüşmedeki kısa süreli belleğini temsil eder. Bir aracı tarafından duruma kaydedilen veriler, iş akışındaki bir sonraki aracı 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ını sağlar. (Wikipedia Aracı'nı Kullanma rehberinden Wikipedia aracını yapılandırma ve çağırma hakkında daha fazla bilgi edinebilirsiniz.)
     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 ajanları tanımlayın: agent.py dosyasının en altına aşağıdaki kodu ekleyerek comprehensive_researcher ve response_formatter ajanlarını tanımlayın:

   # 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 adlı temsilcinin rolü sunumdur. Araştırmacı ajanın topladığı ham verileri (State aracılığıyla 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 dosyası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 işlev görür. Araştırma isteğini alır ve yukarıda tanımladığımız iki aracının görevlerini doğru sırayla (ö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 ajan 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: root_agent işlevini tanımlamak için bu son kod bloğunu agent.py dosyasının en altına ekleyin:

   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 denetleyici olarak görev yapar 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 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
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 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
  

.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 CLI'yı kullanarak aracı dağıtma

Yerel kodunuz hazır ve Google Cloud projeniz hazırlanmış durumdayken artık 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 kapsayıcı 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_ENTERPRISE=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üyorsanı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. Başarıyla 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.

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ğ üstte Token Streaming simgesini açın.
   Artık Zoo temsilcisiyle etkileşimde bulunabilirsiniz.
3. Yeni bir sohbet 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. Ajan'a şu gibi sorular sorun:

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

   

Ajan Akışı 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.
• Kullandığı Araç: Kullanıcı yanıt verdiğinde Karşılayıcı, kullanıcının tam olarak ne söylediğini (ör. "Aslanlar hakkında bilgi ver") 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ı (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 uzman temsilciniz var.

• Görevi: Kullanıcının sorusunu analiz edip akıllı bir plan oluşturmak. Şunlara ihtiyaç duyup duymadığına karar vermek için dil modelinin araç kullanma özelliğini kullanı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 bir tutarlı ve ilgi çekici yanıtta birleştirir. Talimatlarına uyarak önce belirli hayvanat bahçesi bilgilerini sunar, ardından ilginç genel bilgileri ekler.
• 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 kaynakları inceleyin:

1. ADK dokümanları
2. ADK ajanları için özel araçlar oluşturma

12. Ortamı temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızdan ücret alınmaması amacıyla kaynakları içeren projeyi silin veya projeyi koruyup tek tek kaynakları silin.

Cloud Run hizmetlerini, görüntülerini ve kaynaklarını silin.

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] kısmını gerçek proje kimliğinizle değiştirin):

  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 ajanlı bir yapay zeka uygulamasını başarıyla oluşturup dağıttınız.

Özet

Bu laboratuvarda, boş bir dizinden herkese açık ve canlı bir yapay zeka hizmetine geçiş yaptınız. Oluşturduğunuz içeriklere göz atın:

• Özel bir ekip oluşturdunuz: Genel bir yapay zeka yerine, olguları bulmak için bir "Araştırmacı", yanıtı düzenlemek için bir "Biçimlendirici" oluşturdunuz.
• Onlara araçlar verdiniz: Wikipedia API'sini kullanarak temsilcilerinizi dış dünyaya bağladınız.
• Uygulamanızı yayınladı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ğıtılacağı

14. Anket

Çıkış:

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

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