ADK ile çoklu aracı sistemleri oluşturma

1. Giriş

Genel Bakış

Bu laboratuvarda, Google Agent Development Kit (Google ADK)'yi kullanarak karmaşık, çok ajanlı sistemleri nasıl düzenleyeceğinizi öğreneceksiniz. Basit aracı hiyerarşilerinden otomatikleştirilmiş, ortak çalışmaya dayalı iş akışları oluşturmaya geçeceksiniz.

Ne oluşturacaksınız?

İki farklı çoklu temsilci sistemi oluşturacaksınız:

  • Bir "beyin fırtınası" aracısı ile bir "gezilecek yer planlama" aracısı arasındaki görüşmeleri aktarmayı öğrenen basit bir seyahat planlama aracısı.
  • Tam bir film konusu oluşturmak için döngü içinde birlikte çalışan otomatik aracıların (ör. araştırmacı, senarist ve eleştirmen) "yazar odası"nı kullanan daha gelişmiş bir film önerisi oluşturucu.

Neler öğreneceksiniz?

  • Nasıl üst ve alt acente ilişkileri oluşturulur?
  • Bir araçtan oturuma state veri yazma
  • Anahtar şablonu (ör. {my_key?}) kullanarak state öğesinden nasıl okunur?
  • Adım adım iş akışları için SequentialAgent nasıl kullanılır?
  • Tekrarlı iyileştirme döngüleri oluşturmak için LoopAgent kullanma
  • Bağımsız görevleri eşzamanlı olarak çalıştırmak için ParallelAgent kullanma

Ö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 projesine erişim.
  • Yüklü CLI araçları: gcloud, uv.

2. Çoklu Ajan Sistemleri

Agent Development Kit (ADK), geliştiricilerin üretken modellerden daha güvenilir, gelişmiş ve çok adımlı davranışlar elde etmesini sağlar. ADK, tek bir karmaşık istem yerine, işi bölerek bir sorun üzerinde işbirliği yapan birden fazla basit ajan akışı oluşturmanıza olanak tanır.

Bu yaklaşımın, tek bir monolitik istem kullanmaya kıyasla çeşitli avantajları vardır:

  • Daha basit tasarım: Küçük ve özel aracıların akışını tasarlayıp düzenlemek, büyük ve karmaşık bir istem oluşturmaktan daha kolaydır.
  • Güvenilirlik: Uzmanlaşmış ajanlar, belirli görevlerinde büyük ve karmaşık bir ajandan daha güvenilirdir.
  • Bakım kolaylığı: Küçük ve özel bir temsilciyi, sistemin diğer kısımlarını bozmadan düzeltmek veya geliştirmek daha kolaydır.
  • Modülerlik: Bir iş akışı için oluşturulan aracılar, diğer iş akışlarında kolayca yeniden kullanılabilir.

Hiyerarşik Ajan Ağacı

Hiyerarşik aracıları gösteren ağaç yapısı

ADK'da aracıları ağaç yapısında düzenlersiniz. Bu hiyerarşi, hangi temsilcinin görüşmeyi hangi temsilciye "aktarabileceğini" sınırladığından görüşmenin akışını kontrol etmek için önemlidir. Bu, sistemin davranışını daha tahmin edilebilir ve hata ayıklamayı daha kolay hale getirir. Sunulan avantajlardan bazıları:

  • Sezgisel tasarım: Yapı, gerçek dünyadaki ekiplerden esinlenerek oluşturulduğu için hakkında akıl yürütmek daha kolaydır.
  • Kontrollü Akış: Hiyerarşi, görev devretme üzerinde hassas kontrol imkanı sunar. Bu da hata ayıklamaya yardımcı olur. Örneğin, ağaç yapısı, benzer açıklamalara sahip iki rapor yazma aracınız olsa bile doğru rapor yazma aracının çağrılmasını sağlar.

Yapının tamamı root_agent ile başlar. Bu aracı üst olarak kabul edebiliriz. Bir veya daha fazla alt aracı olabilir. Bu alt araçlar da kendi alt araçlarının üstü olabilir ve böylece ağaç yapısı oluşur.

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

Google Cloud kredilerini kullanma (isteğe bağlı)

Bu atölyeyi düzenlemek için biraz kredisi olan bir faturalandırma hesabına ihtiyacınız var. Başlamak için bu codelab'in üst kısmındaki banner'da yer alan kredileri kullanın. Zaten bir faturalandırma hesabına bağlıysanız bu adımı atlayabilirsiniz.

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. Cloud Shell'i yetkilendirmek 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
  4. 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
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  5. Şu mesajı görürsünüz:
    Updated property [core/project].

5. API'leri etkinleştir

Gemini Enterprise Agent Platform API'yi kullanmak ve Gemini modeliyle etkileşim kurmak için Google Cloud projenizde API'yi etkinleştirmeniz gerekir.

  1. Terminalde API'yi etkinleştirin:
    gcloud services enable aiplatform.googleapis.com

Python için Google GenAI SDK'ya Giriş

Python uygulamanızdan Gemini Enterprise Agent Platform'da barındırılan modellerle etkileşim kurmak için Python için Google GenAI SDK'yı kullanacaksınız. Bu SDK, temel API çağrılarının karmaşıklıklarını doğrudan ele almanıza gerek kalmadan istem gönderme, model parametrelerini belirtme ve yanıt alma sürecini basitleştirir.

Python için Google GenAI SDK'sına ilişkin kapsamlı dokümanları Google GenAI SDK Dokümanları sayfasında bulabilirsiniz.

6. Proje ortamını ayarlama

Depoyu klonlama

  1. Terminalde, başlangıç dosyalarını içeren depoyu klonlayın.
    git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git devrel-demos-multiagent-lab
    --depth 1 işareti yalnızca en yeni sürümü klonlar. Bu işlem daha hızlıdır.
  2. Terminalde laboratuvara özel klasörü ana dizininize taşıyın ve laboratuvarın beklenen yapısına uyacak şekilde yeniden adlandırın.
    mv devrel-demos-multiagent-lab/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems ~
  3. Terminalde bu laboratuvar için doğru çalışma dizinine (adk_multiagent_systems) gidin.
    cd ~/adk_multiagent_systems

Dosya yapınızı inceleme

Tüm dosyalarınız oluşturulduktan sonra, yapının tamamını görmek için Gezgin'de adk_multiagent_systems klasörünü açın.

  1. Cloud Shell Editor menüsünde File > Open Folder...'ı (Dosya > Klasörü Aç...) seçin.
    Klasörü Aç seçeneğinin belirlendiği Cloud Shell Düzenleyici Dosya menüsü
  2. Açılan kutuya, kullanıcı adınızdan sonra aşağıdaki klasör bilgilerini ekleyin: adk_multiagent_systems/. Tamam'ı tıklayın.
    Şuna benzer bir görünüm elde etmelisiniz:
    Proje yoluyla Klasörü Aç iletişim kutusunu açar.
  3. Soldaki Gezgin paneli yenilenir. Artık parent_and_subagents ve workflow_agents alt dizinleriyle birlikte projenizin yapısının tamamını görmelisiniz. Bir sonraki adımlara geçebilirsiniz.
    Açık olan adk_multiagent_systems klasörünü gösteren Gezgin paneli

Sanal ortamı etkinleştirme

  1. Terminalde, uv kullanarak sanal ortam oluşturun ve etkinleştirin. Bu sayede, proje bağımlılıklarınızın sistem Python'u veya diğer projelerle çakışmaması sağlanır.
    uv venv
source .venv/bin/activate
  2. Terminalde, google-adk ve requirements.txt dosyasındaki diğer bağımlılıkları yükleyin:
    uv pip install -r requirements.txt

Ortam değişkenlerini ayarlama

  1. Zaten adk_multiagent_systems dizinindesiniz. Terminalde, ortam değişkenlerinizi depolamak için bir .env dosyası oluşturun:
    cloudshell edit .env
  2. Aşağıdakileri düzenleyicide açılan .env dosyasına yapıştırın:
    GOOGLE_GENAI_USE_ENTERPRISE=true
GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
GOOGLE_CLOUD_LOCATION=global
MODEL="gemini-3.5-flash"
  3. [YOUR-PROJECT-ID] yerine gerçek Google Cloud proje kimliğinizi yazın. (ör. PROJECT_ID = "google-cloud-labs")
    Proje kimliğinizi hatırlamıyorsanız terminalinizde aşağıdaki komutu çalıştırın. Tüm projelerinizin ve kimliklerinin listesi gösterilir.
    gcloud projects list
  4. Terminalde, bu .env dosyasını alt aracı dizinlerine kopyalayın. Böylece alt aracılar da değişkenlere erişebilir:
    cp .env parent_and_subagents/.env
cp .env workflow_agents/.env
    Dosya yapısı artık şu şekilde görünmelidir:
    Açık olan adk_multiagent_systems klasörünü gösteren Gezgin paneli

7. Üst, alt ajan ve benzer düzeydeki ajanlar arasındaki transferleri keşfedin

Görüşme her zaman root_agent ile başlar. Varsayılan olarak, üst temsilci görüşmeyi ne zaman aktaracağına karar vermek için alt temsilcilerinin description değerini kullanır. Bu aktarımları, alt aracılarının name kullanarak ebeveynin instruction bölümünde de açıkça yönlendirebilirsiniz.

Bunu test edelim.

  1. Cloud Shell Düzenleyici'de adk_multiagent_systems/parent_and_subagents/agent.py dosyasını açın. agent.py dosyasındaki üç temsilciye dikkat edin:
    • root_agent (steering adlı): Kullanıcıya hangi alt ajana aktarılacağını belirlemek için bir soru sorar. Başlangıçta yalnızca alt aracıların description'ına dayanır.
    • travel_brainstormer: Kullanıcının gidilecek yerler hakkında beyin fırtınası yapmasına yardımcı olur.
    • attractions_planner: Kullanıcının belirli bir ülkede Aktivite Önerilerini listelemesine yardımcı olur.
  2. Aşağıdaki satırı root_agent oluşturma işlemine ekleyerek travel_brainstormer ve attractions_planner öğelerini root_agent öğesinin alt aracıları yapın:
        sub_agents=[travel_brainstormer, attractions_planner]
  3. Terminalde temsilcinizle sohbet edin:
    cd ~/adk_multiagent_systems
adk run parent_and_subagents
  4. Terminaldeki [user]: isteminde şunu yazın:
    hello
    Örnek çıkış (Sizinki biraz farklı olabilir):
    [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?
  5. Şimdi terminaldeki ajana şunu söyleyin:
    I could use some help deciding.
    Örnek çıkış (Sizinki biraz farklı olabilir):
    [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
...
    [travel_brainstormer] etiketine dikkat edin. root_agent, kontrolü yalnızca alt aracının description temelinde aktardı.
  6. Terminaldeki user: isteminde exit yazıp ENTER'a basarak görüşmeyi sonlandırın.
  7. Şimdi daha açık olalım. agent.py içinde, root_agent öğesinin instruction bölümüne aşağıdakileri ekleyin:
            If they need help deciding, send them to 'travel_brainstormer'.
        If they know what country they'd like to visit, send them to the 'attractions_planner'.
  8. Terminalde aracı tekrar çalıştırın:
    adk run parent_and_subagents
  9. Terminaldeki [user]: isteminde şunu yazın:
    hello
  10. Şöyle yanıt verin:
    I would like to go to Japan.
    Örnek çıkış (Sizinki biraz farklı olabilir):
    [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
...
    Yeni talimatlarınızda belirtildiği gibi attractions_planner'e transfer edildiğini fark edin.
  11. Şimdi şu yanıtı verin:
    Actually I don't know what country to visit.
    Örnek çıkış (Sizinki biraz farklı olabilir):
    [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
    attractions_planner'ın benzeri olan travel_brainstormer'a aktarıldığınızı bildiririz. Bu ayar varsayılan olarak etkindir.
  12. Kullanıcı isteminde oturumu sonlandırmak için exit yazın.

Özet

Bu bölümde, aracı hiyerarşisi ve görüşme akışıyla ilgili temel bilgileri öğrendiniz:

  • Görüşme her zaman root_agent ile başlar.
  • Bir üst aracı, description temelinde otomatik olarak bir alt aracıya aktarılabilir.
  • Bu akışı, üst kuruluşa instruction vererek alt ajana name ile aktarma izni vererek açıkça kontrol edebilirsiniz.
  • Ajanlar, varsayılan olarak peer ajanlarına (hiyerarşideki kardeşler) aktarım yapabilir.

8. Bilgileri depolamak ve almak için oturum durumunu kullanma

Her ADK görüşmesinde, oturum durumu sözlüğünü içeren bir Session bulunur. Bu duruma tüm temsilciler erişebilir. Bu nedenle, temsilciler arasında bilgi aktarmak veya görüşme boyunca verileri (ör. liste) korumak için idealdir.

Duruma ekleme ve durumdan okuma işlemlerini keşfetmek için:

  1. adk_multiagent_systems/parent_and_subagents/agent.py dosyasına dönün.
  2. Aşağıdaki işlev tanımını # Tools başlığının altına yapıştırın:
    def save_attractions_to_state(
tool_context: ToolContext,
attractions: List[str]
) -> dict[str, str]:
    """Saves the list of attractions to state["attractions"].

    Args:
        attractions [str]: a list of strings to add to the list of attractions

    Returns:
        None
    """
    # Load existing attractions from state. If none exist, start an empty list
    existing_attractions = tool_context.state.get("attractions", [])

    # Update the 'attractions' key with a combo of old and new lists.
    # When the tool is run, ADK will create an event and make
    # corresponding updates in the session's state.
    tool_context.state["attractions"] = existing_attractions + attractions

    # A best practice for tools is to return a status message in a return dict
    return {"status": "success"}
    Bu kodda şunlara dikkat edin:
    • İşlev tool_context: ToolContext değerini alır. Bu nesne, oturuma erişim noktanızdır.
    • tool_context.state["attractions"] = ... satırı, doğrudan oturumun durum sözlüğünden okur ve bu sözlüğe yazar. Geri kalan işlemler ADK tarafından yapılır.
  3. tools parametresini ekleyerek aracı attractions_planner temsilcisine ekleyin:
        tools=[save_attractions_to_state]
  4. Aşağıdaki madde işaretlerini attractions_planner aracısının mevcut instruction'ına ekleyin:
            - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
        - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
  5. Terminalde aşağıdaki komutu kullanarak Agent Development Kit web kullanıcı arayüzünü başlatın:
    adk web
    Çıkış
    INFO:     Started server process [2434]
INFO:     Waiting for application startup.
+-------------------------------------------------------+
| ADK Web Server started                                |
|                                                       |
| For local testing, access at http://localhost:8000.   |
+-------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  6. Cloud Shell terminalinde, web arayüzünü yeni bir sekmede görüntülemek için Web Önizlemesi düğmesini tıklayın ve Bağlantı Noktasını Değiştir'i seçin.
    Web önizlemesi menüsü
  7. Bağlantı noktası numarası olarak 8000'i girin ve Change and Preview'u (Değiştir ve Önizle) tıklayın. ADK Geliştirici kullanıcı arayüzünü içeren yeni bir tarayıcı sekmesi açılır.
    Metin kutusuna 8000 girilerek bağlantı noktası pop-up kutusunu değiştirme
  8. Soldaki Bir aracı seçin açılır listesinden parent_and_subagents simgesini seçin.
  9. Sohbeti başlatmak için: hello
  10. Temsilci sizi karşıladıktan sonra şu yanıtı verin:
    I'd like to go to Egypt.
    attractions_planner'a aktarılır ve gezilecek yerlerin listesi gösterilir.
  11. Bir cazibe merkezi seçin (örneğin):
    I'll go to the Sphinx
  12. Şuna benzer bir yanıt alırsınız: Tamam, Sfenks'i listenize kaydettim...
  13. Aracın yanıtından oluşturulan etkinliği görüntülemek için yanıt araç kutusunu (onay işaretiyle işaretlenmiş) tıklayın.
    Durumdaki değişiklikleri açıklayan stateDelta içeren bir işlemler alanı bulunduğunu unutmayın.
  14. Ajanın listesinden başka bir cazibe merkeziyle yanıt verin.
  15. Soldaki gezinme menüsünde, daha önce incelediğiniz etkinliğe odaklanma modundan çıkmak için "X"i tıklayın.
  16. Sol kenar çubuğunda Durum sekmesini tıklayın. Artık oturumun durumunda attractions dizisini görebilirsiniz. Bu dizi, seçtiğiniz her iki öğeyi de içermelidir.Web kullanıcı arayüzünde oturum durumu önizlemesi
  17. Bu mesajı temsilciye gönderin:
    What is on my list?
    Ajan artık durumdan okumalı ve listenizi döndürmelidir.
  18. Aracı denemeyi bitirdiğinizde web tarayıcısı sekmesini kapatın ve sunucuyu durdurmak için Cloud Shell Terminali'nde CTRL + C tuşlarına basın.

Bölüm Özeti

Bu bölümde, verileri paylaşmak için Session durumunu nasıl kullanacağınızı öğrendiniz:

  • Duruma yazmak için: tool_context.state nesnesini (ör. tool_context.state["my_list"] = [...]) kullanarak bir araç içinden durum sözlüğüne yazarsınız.
  • Durumu okumak için: Anahtar şablonu oluşturma (ör. Here is your list: {my_list?}) kullanarak durum verilerini doğrudan bir aracının instruction içine yerleştirirsiniz.
  • Durumu incelemek için: ADK Geliştirici Kullanıcı Arayüzü'ndeki Durum sekmesini kullanarak oturum durumunu canlı olarak izleyebilirsiniz.

9. İş akışı ajanları

Şimdiye kadar, üst aracının nasıl alt aracıya aktarım yaptığını ve ardından kullanıcıyı beklediğini gördünüz. İş akışı aracıları farklıdır: Kullanıcı girişini beklemeden, otomatik bir akışta alt aracılarını yürütürler.

Bu, "Planla ve Uygula" veya "Taslak Oluştur ve Revize Et" gibi otomatikleştirilmiş, çok adımlı görevler için idealdir. ADK, bunu yönetmek için üç yerleşik iş akışı aracısı sağlar:

  • SequentialAgent
  • LoopAgent
  • ParallelAgent

Bu laboratuvarın geri kalanında, bu üç iş akışı aracını kullanarak çok aracılı bir sistem oluşturmaya odaklanacağız.

Tarihi bir karakterle ilgili yeni bir film için tanıtım belgesi oluşturan bir ajan geliştireceksiniz. Ajanlarınız araştırma, yinelemeli yazma ve rapor oluşturma işlemlerini gerçekleştirir.

Sonuç olarak sisteminiz aşağıdaki gibi görünür:

film_concept_team çoklu ajan sisteminin diyagramı

Bu sistemi en basit iş akışıyla başlayarak adım adım oluşturacaksınız.

10. SequentialAgent ile çoklu temsilci sistemi oluşturma

SequentialAgent, alt aracılarını basit ve doğrusal bir sırada yürüten bir iş akışı aracısıdır. sub_agents listesindeki her aracı sırayla çalıştırır. Bu, görevlerin belirli bir sırayla yapılması gereken iş akışları için idealdir. Örneğin, şimdi oluşturacağınız film önerisi aracında bu özelliği kullanabilirsiniz.

Bu ilk sürüm şu şekilde yapılandırılacak:

Film_concept_team multi-agent system step 1

  • root_agent (greeter), kullanıcıyı karşılayıp film konusunu alacak.
  • Ardından, film_concept_team adlı SequentialAgent'a aktarılır. Bu:
    1. Wikipedia'dan bilgi almak için researcher aracını çalıştırın.
    2. Bu bilgileri kullanarak bir olay örgüsü yazmak için screenwriter ajanı çalıştırın.
    3. Son grafiği bir dosyaya kaydetmek için file_writer aracısını çalıştırın.

Uygulayalım.

  1. Cloud Shell Düzenleyici'de adk_multiagent_systems/workflow_agents/agent.py dosyasını açın.
    Bu aracı tanım dosyasını okuyun. Alt temsilciler, bir üst temsilciye atanmadan önce tanımlanmaları gerektiğinden dosyayı sohbet akışının sırasına göre okumak için temsilcileri dosyanın en altından en üstüne doğru okuyabilirsiniz.
  2. append_to_state aracına dikkat edin. Bu yardımcı işlev, temsilcilerin oturum durumundaki bir listeye veri eklemesine olanak tanır. researcher ve screenwriter, çalışmalarını bu şekilde aktarır.
  3. Ajanı deneyin. Terminalde, canlı yeniden yükleme etkin olarak web arayüzünü başlatın:
    cd ~/adk_multiagent_systems
adk web --reload_agents
  4. Cloud Shell terminalinde, web arayüzünü yeni bir sekmede görüntülemek için Web Önizlemesi düğmesini tıklayın ve Bağlantı Noktasını Değiştir'i seçin.
    Web önizlemesi menüsü
  5. Bağlantı noktası numarası olarak 8000'i girin ve Change and Preview'u (Değiştir ve Önizle) tıklayın. ADK Geliştirici kullanıcı arayüzünü içeren yeni bir tarayıcı sekmesi açılır.
    Metin kutusuna 8000 girilerek bağlantı noktası pop-up kutusunu değiştirme
  6. Bir temsilci seçin açılır listesinden workflow_agents simgesini seçin.
  7. Sohbeti başlatmak için: hello. greeter temsilcisi yanıt verecek.
  8. İstendiğinde tarihi bir şahsiyet girin. Bunlardan birini veya kendi yanıtınızı kullanabilirsiniz:
    • Zhang Zhongjing
    • Ada Ak
    • Marcus Aurelius
  9. SequentialAgent artık devralacak. Ara mesajlar gösterilmez. researcher, screenwriter ve file_writer birbiri ardına çalıştırılır. Ajan yalnızca dizinin tamamı bittiğinde yanıt verir.
    Başarısız olursa sağ üstteki + Yeni Oturum'u tıklayıp tekrar deneyebilirsiniz.
  10. Aracı, dosyanın yazıldığını onayladıktan sonra çıktıyı görmek için Cloud Shell Düzenleyicinizdeki movie_pitches dizininde yeni .txt dosyasını bulup açın.
  11. ADK Dev UI'de, olay görünümünü açmak için sohbet geçmişindeki son aracı simgesini tıklayın.
  12. Etkinlik görünümünde, aracı ağacının görsel grafiği gösterilir. greeter, film_concept_team'i aradı. ise sırayla alt aracılarını aradı.adk web graph
  13. Oturum durumu da dahil olmak üzere aktarılan verileri incelemek için grafikteki herhangi bir aracıda İstek ve Yanıt sekmelerini tıklayabilirsiniz.

Bölüm Özeti

Bu bölümde, iş akışı aracını nasıl kullanacağınızı öğrendiniz:

  • Bir SequentialAgent, alt aracılarını adım aralarında kullanıcı girişi beklemeden sırayla tek tek çalıştırır.
  • Bu bir "iş akışı"dır. Çünkü kullanıcı root_agent ile konuşur, ardından tamamlanması için işi SequentialAgent'ye devreder.
  • Sıradaki alt aracılar, önceki aracıların çalışmalarına erişmek için oturum durumunu (ör. { PLOT_OUTLINE? }) kullanır.
  • Tüm aracıdan aracıya iş akışını görselleştirmek ve hatalarını ayıklamak için geliştirici kullanıcı arayüzündeki etkinlik grafiğini kullanabilirsiniz.

11. İşleri tekrarlı olarak yapmak için LoopAgent ekleme

LoopAgent, alt temsilcilerini sırayla çalıştıran ve ardından baştan başlayarak tekrarlayan bir iş akışı temsilcisidir. Bu "döngü", bir koşul karşılanana kadar (ör. max_iterations sayısına ulaşma veya bir alt ajanın yerleşik exit_loop aracını çağırması) devam eder.

Yinelemeli iyileştirme gerektiren görevler için faydalıdır. Bu LoopAgent karakterini, film önerisi temsilciniz için bir "yazar odası" oluşturmak üzere ekleyeceksiniz. Bu sayede researcher, screenwriter ve yeni critic ajanı döngü içinde çalışarak critic hazır olduğuna karar verene kadar her geçişte kurguyu iyileştirir. Bu sayede, ajanın bir fikri araştırmasına ve iyileştirmesine olanak tanıyarak daha belirsiz kullanıcı girişlerini (ör. "eski bir doktor") işlemesine de yardımcı olur.

Film_concept_team çoklu ajan sistemi 2. adım

Bu değişiklikleri yapmak için:

  1. adk_multiagent_systems/workflow_agents/agent.py içinde, exit_loop için içe aktarma işlemini ekleyin (diğer google.adk içe aktarma işlemlerinin yakınına):
    from google.adk.tools import exit_loop
  2. Yeni critic temsilcisini ekleyin. Bu ajan, olay örgüsünü inceler. İyi bir tahminse exit_loop çağrısı yapılır. Aksi takdirde, bir sonraki döngü için duruma geri bildirim ekler.
    Aşağıdaki aracı tanımını # Agents bölümüne yapıştırın:
    critic = Agent(
    name="critic",
    model=model_name,
    description="Reviews the outline so that it can be improved.",
    instruction="""
    INSTRUCTIONS:
    Consider these questions about the PLOT_OUTLINE:
    - Does it meet a satisfying three-act cinematic structure?
    - Do the characters' struggles seem engaging?
    - Does it feel grounded in a real time period in history?
    - Does it sufficiently incorporate historical details from the RESEARCH?

    If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
    If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
    Explain your decision and briefly summarize the feedback you have provided.

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    RESEARCH:
    { research? }
    """,
    before_model_callback=log_query_to_model,
    after_model_callback=log_model_response,
    tools=[append_to_state, exit_loop]
)
  3. writers_room LoopAgent oluşturun. Bu, döngüde çalışacak üç aracıyı içerir.
    Aşağıdaki kodu film_concept_team aracı tanımının üzerine yapıştırın:
    writers_room = LoopAgent(
    name="writers_room",
    description="Iterates through research and writing to improve a movie plot outline.",
    sub_agents=[
        researcher,
        screenwriter,
        critic
    ],
    max_iterations=5,
)
  4. Yeni writers_room döngüsünü kullanmak için film_concept_team SequentialAgent öğesini güncelleyin. researcher ve screenwriter simgelerini tek bir writers_room aracısıyla değiştirin.Mevcut film_concept_team tanımınızı aşağıdakilerle değiştirin:
    film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        file_writer
    ],
)
  5. ADK Dev UI sekmesine dönün ve sağ üstteki + Yeni Oturum'u tıklayın.
  6. Şununla yeni bir görüşme başlatın: hello
  7. İstendiğinde, bu kez aracıya daha geniş bir konu verin. Bazı fikirler:
    • kitleler için ürünler tasarlayan bir endüstriyel tasarımcı
    • bir kartograf (harita yapımcısı)
    • ekinlerin daha fazla yiyecek üretmesini sağlayan adam
    Ajan artık döngü üzerinden çalışacak. ADK Geliştirici Kullanıcı Arayüzü'nde, günlükleri aracıların birden çok kez çalıştırılmasıyla birlikte görürsünüz (ör. "[araştırmacı]", "[senarist]", "[eleştirmen]", "[araştırmacı]", "[senarist]", "[eleştirmen]...").
  8. Döngü tamamlandığında aracı dosyayı yazar. Oluşturulan dosyayı adk_multiagent_systems/movie_pitches dizininde inceleyin.
  9. Döngü yapısını görmek için geliştirici kullanıcı arayüzündeki olay grafiğini inceleyin.

Bölüm Özeti

Bu bölümde, LoopAgent kullanarak şunları yapmayı öğrendiniz:

  • LoopAgent, alt ajan dizisini tekrarlayan bir iş akışı ajanıdır ve yinelemeli görevler için "iç döngü" oluşturur.
  • Döngü içindeki temsilciler, sonraki geçişlerde iş (ör. PLOT_OUTLINE) ve geri bildirim (ör. CRITICAL_FEEDBACK) iletmek için oturum durumunu kullanır.
  • Döngü, max_iterations sınırına ulaşıldığında veya exit_loop aracı çağrıldığında durdurulabilir.

12. "Fan out and gather" için ParallelAgent kullanma

ParallelAgent, tüm alt aracılarını aynı anda (eşzamanlı olarak) yürüten bir iş akışı aracısıdır. Bu, iki farklı araştırma işi yürütmek gibi bağımsız alt görevlere bölünebilen görevler için değerlidir.

Paralel olarak çalışan bir "ön üretim ekibi" oluşturmak için ParallelAgent kullanacaksınız. Bir temsilci gişe potansiyelini araştırırken başka bir temsilci aynı anda oyuncu seçimi fikirleri için beyin fırtınası yapıyor. Bu duruma genellikle "dağıt ve topla" modeli denir: ParallelAgent işi "dağıtır" ve daha sonraki bir aracı (file_writer) sonuçları "toplar".

Film_concept_team çoklu ajan sistemi 3. adım

Son ajan akışınız şu şekilde olacak:

  1. Sohbeti greeter (kök) başlatır.
  2. Bu işlem, film_concept_team (SequentialAgent) öğesine aktarılır ve şu işlemler gerçekleştirilir:
    • Karakterleri oluşturmak için writers_room (LoopAgent).
    • Gişe ve oyuncu kadrosu hakkında aynı anda araştırma yapmak için yeni preproduction_team (ParallelAgent) seçeneği.
    • Tüm sonuçları toplamak ve dosyayı kaydetmek için file_writer.

Bu değişiklikleri yapmak için:

  1. adk_multiagent_systems/workflow_agents/agent.py bölümünde, yeni ParallelAgent ve alt temsilcilerini # Agents başlığı altına yapıştırın.
    box_office_researcher = Agent(
    name="box_office_researcher",
    model=model_name,
    description="Considers the box office potential of this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
    """,
    output_key="box_office_report"
)

casting_agent = Agent(
    name="casting_agent",
    model=model_name,
    description="Generates casting ideas for this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Generate ideas for casting for the characters described in PLOT_OUTLINE
    by suggesting actors who have received positive feedback from critics and/or
    fans when they have played similar roles.
    """,
    output_key="casting_report"
)

preproduction_team = ParallelAgent(
    name="preproduction_team",
    sub_agents=[
        box_office_researcher,
        casting_agent
    ]
)
  2. film_concept_team SequentialAgent'ün sub_agents listesini yeni preproduction_team'ı (writers_room ile file_writer arasında) içerecek şekilde güncelleyin. Mevcut film_concept_team tanımınızı şu tanımla değiştirin:
    film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        preproduction_team,
        file_writer
    ],
)
  3. file_writer aracısının instruction özelliğini, eyaletteki yeni raporları "toplayıp" dosyaya ekleyecek şekilde güncelleyin.
    file_writer için instruction dizesini şununla değiştirin:
        instruction="""
    INSTRUCTIONS:
    - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
    If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
    - Use your 'write_file' tool to create a new txt file with the following arguments:
    - for a filename, use the movie title
    - Write to the 'movie_pitches' directory.
    - For the 'content' to write, include:
    - The PLOT_OUTLINE
    - The BOX_OFFICE_REPORT
    - The CASTING_REPORT

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    BOX_OFFICE_REPORT:
    { box_office_report? }

    CASTING_REPORT:
    { casting_report? }
    """,
  4. ADK Dev UI sekmesine dönün ve + New Session'ı (+ Yeni Oturum) tıklayın.
  5. Sohbeti başlatmak için hello girin.
  6. İstendiğinde yeni bir karakter fikri girin. Bazı fikirler:
    • wifi teknolojisini icat eden aktris
    • heyecan verici bir şef
    • Dünya fuarı sergilerindeki önemli oyuncular
  7. Aracı işini tamamladığında adk_multiagent_systems/movie_pitches dizinindeki son dosyayı inceleyin. Artık tek bir belgede olay örgüsü, gişe raporu ve oyuncu seçimi raporu yer almalıdır.

Bölüm Özeti

Bu bölümde, ParallelAgent kullanarak şunları yapmayı öğrendiniz:

  • Bir ParallelAgent "dağıtma" işlemi, tüm alt aracılarını sırayla değil aynı anda çalıştırır.
  • Bu, birbirine bağlı olmayan görevler (ör. iki farklı konuyu araştırma) için oldukça verimlidir.
  • Paralel temsilcilerin sonuçları daha sonraki bir temsilci tarafından "toplanır". Bu işlem, paralel aracıların çalışmalarını oturum durumuna (output_key kullanarak) kaydetmesi ve son bir aracının (ör. file_writer) bu anahtarları okumasıyla yapılır.

13. Özel iş akışı aracıları

SequentialAgent, LoopAgent ve ParallelAgent önceden tanımlanmış iş akışı ajanları ihtiyaçlarınızı karşılamadığında CustomAgent, yeni iş akışı mantığı uygulamanız için esneklik sağlar.

Akış denetimi, koşullu yürütme veya alt aracılar arasındaki durum yönetimi için kalıplar tanımlayabilirsiniz. Bu özellik; karmaşık iş akışları, durum bilgisi olan düzenlemeler veya özel iş mantığını çerçevelerin düzenleme katmanına entegre etmek için kullanışlıdır.

CustomAgent oluşturma işlemi bu laboratuvarın kapsamı dışındadır ancak ihtiyacınız olursa bu özelliğin varlığını bilmeniz iyi olur.

14. Tebrikler!

Google Agent Development Kit (ADK)'yi kullanarak gelişmiş bir çoklu temsilci sistemi oluşturdunuz. Basit bir üst-alt temsilci ilişkisinden, yaratıcı bir projeyi araştırabilen, yazabilen ve iyileştirebilen karmaşık, otomatik iş akışlarını yönetmeye geçtiniz.

Özet

Bu laboratuvarda şunları yaptınız:

  • Üst ve alt ajan ilişkileriyle hiyerarşik ağaçta düzenlenmiş ajanlar.
  • Hem otomatik olarak (description kullanılarak) hem de açıkça (instruction kullanılarak) kontrol edilen agent-to-agent transferleri.
  • tool_context.state sözlüğüne veri yazmak için bir araç kullanıldı.
  • Oturum durumundan okumak ve bir aracının istemine rehberlik etmek için anahtar şablonu (ör. { PLOT_OUTLINE? }) kullanıldı.
  • Basit ve adım adım iş akışı (araştırma -> yazma -> kaydetme) oluşturmak için SequentialAgent uygulandı.
  • Yinelemeli iyileştirme döngüsü oluşturmak için critic ajanı ve exit_loop aracıyla birlikte LoopAgent kullanıldı.
  • Bağımsız görevleri (ör. oyuncu seçimi ve gişe araştırması) aynı anda yürütmek için ParallelAgent kullanıldı.

Denemeye devam etme

Öğrendiklerinizi geliştirebileceğiniz birçok yol vardır. Aşağıdaki önerilerden yararlanabilirsiniz:

  • Daha fazla ajan ekleyin: preproduction_team ParallelAgent hesabınıza yeni bir ajan eklemeyi deneyin. Örneğin, PLOT_OUTLINE temelinde film için kısa açıklama yazan bir marketing_agent oluşturabilirsiniz.
  • Daha fazla araç ekleme: researcher temsilcinize daha fazla araç verin. Wikipedia'da bulunmayan bilgileri bulmak için Google Arama API'sini kullanan bir araç oluşturabilirsiniz.
  • Keşfet CustomAgent: Labs, standart şablonlara uymayan iş akışları için CustomAgent özelliğinden bahsetti. Örneğin, bir temsilciyi yalnızca oturum durumunda belirli bir anahtar varsa koşullu olarak çalıştıran bir temsilci oluşturmayı deneyin.