ADK ile prototiplerden temsilcilere

ADK ile prototiplerden temsilcilere

Bu codelab hakkında

subjectSon güncelleme Haz 12, 2025
account_circleYazan: Author: Abirami Sukumaran

1. Genel Bakış

Yapay zeka ile geliştirme bugün nerede başlıyor? Çoğumuz için bu süreç genellikle basit bir soruyla başlar: "Model, üzerinde düşündüğüm bu sorunu çözmeye gerçekten yardımcı olabilir mi?". İşte tam da bu noktada Google AI Studio devreye girer. Herhangi bir şeyin hızlıca prototipini oluşturabileceğiniz bir yerdir. Mutfağımı yeniden tasarlamak istiyorum ve Gemini'nin bu konuda yardımcı olabileceğini düşünüyorum. Ancak ben bir mühendisim, genel müteahhit değilim. Ne isteyeceğimden bile emin değilim. Düzenlemeler, armatürler vb. gibi dikkate alınması gereken çok fazla şey var. Bu yüzden konuyu parçalara ayıralım ve Gemini'nin bizim için çok ayrıntılı bir istem oluşturmasını, ardından tam bir yenileme planı oluşturmasını ve yenilemeyi görselleştirmesini sağlayalım. Ama bekleyin. İşletmeleri ölçeklendirme konusunda nasıl yardımcı olabilirim? AGENTS yazın.

Temsilci, sahip olduğu araçları ve bağlamı kullanarak hedefe dayalı bir işlem gerçekleştirmek için bir yapay zeka modeliyle konuşan ve gerçeğe dayalı otonom karar verme yeteneğine sahip otonom bir programdır.

Temsilci Geliştirme Kiti (ADK)

Agent Development Kit (ADK), yapay zeka aracılarını geliştirmek ve dağıtmak için esnek ve modüler bir çerçevedir. ADK, birden fazla farklı aracı örneğini bir Çoklu Aracı Sistemi'nde (MAS) birleştirerek karmaşık uygulamalar oluşturmayı destekler.

ADK'de çok aracılı sistem, genellikle hiyerarşi oluşturan farklı aracıların daha büyük bir hedefe ulaşmak için birlikte çalıştığı veya koordine ettiği bir uygulamadır. Uygulamanızı bu şekilde yapılandırmak, gelişmiş modülerlik, uzmanlaşma, yeniden kullanılabilirlik, sürdürülebilirlik ve özel iş akışı aracılarını kullanarak yapılandırılmış kontrol akışları tanımlama gibi önemli avantajlar sunar.

Ne oluşturacaksınız?

Prototip istemimizden temsilci oluşturmaya geçmeye hazır mısınız? Mutfak yenileme projesi için teklif belgesi oluşturmanıza yardımcı olacak bir temsilci oluşturacağız. Bu laboratuvarda şunları yapacaksınız:

  1. ADK ile yenileme teklifi belgesi oluşturmak için basit bir temsilci oluşturma
  2. Oluşturulan yenileme teklifi belgesini bir Cloud Storage paketinde depolama
  3. Aracısı Cloud Shell'de ve aracı web çıkışında test etme

Şartlar

  • Chrome veya Firefox gibi bir tarayıcı
  • Faturalandırma özelliği etkinleştirilmiş bir Google Cloud projesi.

2. Başlamadan önce

Proje oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin .
  3. Ayrıca, bu makaleyi okuyor ve Google Cloud'a başlamanıza ve ADK'yı kullanmanıza yardımcı olacak krediler almak istiyorsanız bu bağlantıyı kullanarak kredileri kullanabilirsiniz.
  4. Kullanmak için buradaki talimatları uygulayabilirsiniz. Bu bağlantının yalnızca 15 Temmuz 2025'e kadar geçerli olduğunu lütfen unutmayın.
  5. Bu bağlantıyı tıklayarak Cloud Shell'i etkinleştirin. Cloud Shell'den ilgili düğmeyi tıklayarak Cloud Shell Terminal (bulut komutlarını çalıştırmak için) ve Düzenleyici (proje oluşturmak için) arasında geçiş yapabilirsiniz.
  6. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
  1. Projeniz ayarlanmadıysa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
  1. Python 3.9 veya sonraki bir sürümün yüklü olduğundan emin olun.

Diğer gcloud komutları ve kullanımları için belgelere bakın.

3. Prototip

Google AI Studio'ya gidin. İsteminize yazmaya başlayın. İstemim şu şekilde:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

En iyi yanıtı almak için sağ taraftaki parametreleri ayarlayın ve yapılandırın.

Gemini, bu basit açıklamaya dayanarak yenileme çalışmama başlamam için inanılmaz ayrıntılı bir istem oluşturdu. Aslında, AI Studio'dan ve modellerimizden daha da iyi yanıtlar almak için Gemini'yi kullanıyoruz. Ayrıca, kullanım alanınıza bağlı olarak kullanılacak farklı modeller de seçebilirsiniz.

Gemini 2.5 Pro'yu seçtik. Bu bir Düşünme modelidir. Yani uzun analizler ve ayrıntılı dokümanlar için daha da fazla çıkış jetonu (bu durumda 65 bin jetona kadar) alırız. Gemini düşünme kutusu, doğal akıl yürütme özelliklerine sahip ve uzun bağlam isteklerini alabilen Gemini 2.5 Pro'yu etkinleştirdiğinizde gösterilir.

Yanıtın snippet'ini aşağıda görebilirsiniz:

a80d4bad4b3864f7.png

AI Studio, verilerimi analiz ederek dolaplar, tezgahlar, tezgah arkası, zemin, lavabo, uyum, renk paleti ve malzeme seçimi gibi tüm bu öğeleri oluşturdu. Gemini, kaynakları bile belirtir.

Şimdi farklı bir istemle fikrin hayata geçirilmesini görmeyi deneyin.

  1. Bu istemi kopyalayıp istem düzenleyiciye yapıştırın:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Mevcut mutfağınızın resmini ekleyin (veya örnek mutfak resmimi kullanabilirsiniz).
  2. Görsel oluşturma özelliğine erişebilmek için modeli "Gemini 2.0 Flash Önizleme Resim Oluşturma" olarak değiştirin.

Aşağıdaki çıkışı aldım:

b5b1e83fcada28f5.png

İşte Gemini'nin gücü!

Videoları anlama, yerel resim oluşturma ve gerçek bilgileri Google Arama ile temellendirme gibi özellikler yalnızca Gemini ile geliştirilebilir.

AI Studio'dan bu prototipi alıp API anahtarını alabilir ve Vertex AI ADK'nın gücünü kullanarak tam bir aracı uygulamaya ölçeklendirebilirsiniz.

4. ADK kurulumu

Şimdi "Başlamadan önce" bölümünde etkinleştirdiğimiz Cloud Shell Terminal'e geçelim:

  1. Sanal Ortam Oluşturma ve Etkinleştirme (Önerilir)

Cloud Shell Terminal'inizden sanal ortam oluşturun:

python -m venv .venv

Sanal ortamı etkinleştirin:

source .venv/bin/activate
  1. ADK'yı yükleme
pip install google-adk

5. Proje Yapısı

  1. Cloud Shell Terminal'de, istediğiniz proje konumunda aracı uygulamalarınız için bir kök dizin oluşturun:
mkdir agentic-apps
  1. Ana dizinde, mevcut projemize özel bir klasör oluşturun:
mkdir renovation-agent
  1. Cloud Shell düzenleyicisine gidin ve aşağıdaki dosyaları (başlangıçta boş) oluşturarak aşağıdaki proje yapısını oluşturun:
renovation-agent/
        __init__
.py
        agent
.py
        requirements
.txt
       
.env

6. Kaynak Kod

  1. "init.py" dosyasına gidin ve aşağıdaki içerikle güncelleyin:
from . import agent
  1. agent.py dosyasına gidin ve dosyayı aşağıdaki yoldaki içerikle güncelleyin:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py

agent.py dosyasında gerekli bağımlılıkları içe aktarır, yapılandırma parametrelerini .env dosyasından alır ve bir teklif belgesi oluşturup Cloud Storage paketinde depolayan root_agent'ı tanımlarız. Cloud Storage adımını gerçekleştirmek için store_pdf adlı bir araç kullanırız.

  1. Cloud Storage paketinizin bulunduğundan emin olun

Bu, temsilcinin oluşturduğu teklif belgesini depolamak içindir. Vertex AI ile oluşturduğumuz aracı sistem bu veritabanına erişebilmesi için veritabanını oluşturun ve erişim hazırlayın. Bunu şu şekilde yapabilirsiniz:

https://cloud.google.com/storage/docs/creating-buckets#console

Paketinizi "next-demo-store" olarak adlandırın. Başka bir ad kullanırsanız .env dosyasında (ENV Değişkenleri Kurulumu adımında) STORAGE_BUCKET değerini güncellemeyi unutmayın.

  1. Pakete erişimi ayarlamak için Cloud Storage Console'a ve Storage paketinize gidin (bizim durumumuzda paket adı "next-demo-storage"dır: https://console.cloud.google.com/storage/browser/next-demo-storage).

İzinler -> Ana Hesapları Görüntüle -> Erişim İzni Ver'e gidin. Yetkililer olarak "allUsers", Rol olarak da "Storage Object User"ı seçin.

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. Bağımlılıklar listesi oluşturma

Tüm bağımlılıkları requirements.txt dosyasında listeleyin. Bu dosyayı repo'dan kopyalayabilirsiniz.

Tek aracılı sistem kaynak kodu açıklaması

agent.py dosyası, Temsilci Geliştirme Kiti'ni (ADK) kullanarak mutfak yenileme çok temsilcili sistemimizin yapısını ve davranışını tanımlar. Temel bileşenleri inceleyelim:

Temsilci Tanımı

Kök aracı (Orchestrator): proposal_agent

root_agent, bu tek aracılı sistemin orkestratörüdür. İlk yenileme isteğini alır ve isteğin ihtiyaçlarına göre hangi araçların çağrılacağını belirler.

Ardından root_agent, araçlardan gelen yanıtları toplar ve kullanıcıya kapsamlı bir yanıt vermek için bunları birleştirir. Bu durumda yalnızca bir aracımız var: "store_pdf".

7. Veri Akışları ve Temel Kavramlar

Kullanıcı, ADK arayüzü (terminal veya web kullanıcı arayüzü) üzerinden bir istek başlatır.

  1. İstek, root_agent tarafından alınır.
  2. root_agent, isteği analiz eder ve gerektiğinde araca yönlendirir.
  3. "store_pdf" aracı, yenilenen metin içeriğini bir PDF dosyasına yazıp Google Cloud Storage'a yüklemek için tasarlanmıştır.
  4. Ardından, root_agent'a yanıt döndürülür.
  5. root_agent, yanıtları birleştirir ve kullanıcıya nihai bir çıkış sağlar.

LLM'ler (Büyük Dil Modelleri)

Temsilciler, metin oluşturmak, soruları yanıtlamak ve akıl yürütme görevlerini gerçekleştirmek için büyük ölçüde LLM'lerden yararlanır. LLM'ler, temsilcilerin kullanıcı isteklerini anlama ve yanıtlama becerilerinin arkasındaki"beyin"dir. Bu uygulamada Gemini 2.5'i kullanıyoruz.

Google Cloud Storage

Oluşturulan yenileme teklifi dokümanlarını depolamak için kullanılır. Bir paket oluşturmanız ve temsilcilerin bu pakete erişmesi için gerekli izinleri vermeniz gerekir.

Cloud Run (İsteğe bağlı)

OrderingAgent, AlloyDB ile arayüz oluşturmak için bir Cloud Run işlevi kullanır. Cloud Run, HTTP isteklerine yanıt olarak kod yürütmek için sunucusuz bir ortam sağlar.

AlloyDB

OrderingAgent kullanıyorsanız sipariş bilgilerini depolamak için bir AlloyDB veritabanı oluşturmanız gerekir.

.env dosyası

.env dosyası, API anahtarları, veritabanı kimlik bilgileri ve paket adları gibi hassas bilgileri depolar. Bu dosyayı güvenli bir şekilde saklamak ve deponuza eklememek çok önemlidir. Ayrıca, temsilciler ve Google Cloud projeniz için yapılandırma ayarlarını depolar. root_agent veya destekleyici işlevler genellikle bu dosyadan değer okur. Gerekli tüm değişkenlerin .env dosyasında doğru şekilde ayarlandığından emin olun. Cloud Storage paket adı da buna dahildir.

8. Model Kurulumu

Temsilcinizi kullanıcı isteklerini anlama ve yanıt oluşturma özelliği, büyük dil modeli (LLM) tarafından desteklenir. Temsilcinizi bu harici LLM hizmetine güvenli çağrılar yapması gerekir. Bu işlem için kimlik doğrulama kimlik bilgileri gerekir. Geçerli kimlik doğrulaması olmadan LLM hizmeti aracının isteklerini reddeder ve aracı çalışamaz.

  1. Google AI Studio'dan API anahtarı alın.
  2. .env dosyasını ayarladığınız sonraki adımda <<your API KEY>> değerini gerçek API KEY değerinizle değiştirin.

9. ENV Değişkenleri Kurulumu

  1. Bu repo'daki şablon .env dosyasında parametre değerlerini ayarlayın. Benim durumumda .env dosyası şu değişkenleri içeriyor:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Yer tutucuları kendi değerlerinizle değiştirin.

10. Temsilcinizi çalıştırma

  1. Terminali kullanarak temsilci projenizin üst dizinine gidin:
cd agentic-apps/renovation-agent
  1. Tüm bağımlılıkları yükleme
pip install -r requirements.txt
  1. Aracıyı çalıştırmak için Cloud Shell terminalinizde aşağıdaki komutu çalıştırabilirsiniz:
adk run .
  1. ADK tarafından sağlanan bir web kullanıcı arayüzünde çalıştırmak için aşağıdakileri çalıştırabilirsiniz:
adk web
  1. Şu istemleri kullanarak test yapın:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Sonuç

adk run komutu için Sonuç şu şekildedir"

ae50e6f6b2bab0a0.png

38a2c34667a8fd05.png

...

a8a39e8323d3ceb9.png

Yenileme Teklifi belgesinin Cloud Storage paketinde oluşturulup oluşturulmadığını doğrulayabilirsiniz.

12. Temizleme

Bu yayında kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
  2. Proje listesinde, silmek istediğiniz projeyi seçin ve ardından Sil'i tıklayın.
  3. İletişim kutusuna proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

13. Tebrikler

Tebrikler! ADK'yı kullanarak çok görevli uygulamanızı başarıyla oluşturdunuz ve uygulamanızla etkileşime geçtiniz. Çok temsilcili sistem, teklif oluşturma, izin kontrolü ve sipariş durumu takibi gibi görevleri otomatikleştirerek mutfak yenileme sürecini kolaylaştırmak için tasarlanmıştır. Her aracının belirli bir rolü vardır ve root_agent, kapsamlı bir çözüm sunmak için etkinliklerini koordine eder. Sistem, işlevlerini yerine getirmek için LLM'lerden, Google Cloud hizmetlerinden ve harici API'lerden yararlanır. Ürün dokümanlarının bağlantısı burada verilmiştir.