ADK: Temel Bilgilerden Çok Amaçlı Araçlara

1. Giriş

Bu codelab, temel bilgilerden başlayıp çok araçlı ajanların geliştirilmesine kadar ADK ile ajan oluşturma konusunda kapsamlı bir giriş sunar.

En basit haliyle yapay zeka temsilcisi, bir dizi görevi bağımsız olarak gerçekleştirerek bir amaca ulaşmak için "akıl yürütme motoru" olarak büyük dil modelini (LLM) kullanan bir yazılım sistemidir.

LLM, size tavsiye verebilen son derece yetenekli bir danışman gibidir. Yapay zeka aracısı ise bu tavsiyeleri uygulamak için araçları kullanabilen proaktif bir mühendistir.

LLM ve Temsilciler

Beyin (LLM): Akıl yürütme, planlama ve doğal dil anlama özellikleri sunar. Ne yapılması gerektiğine karar verir.

Eller (Araçlar): Bunlar, aracının gerçek dünyayla etkileşim kurmasına olanak tanıyan API'ler, SDK'lar ve özel işlevlerdir. Planı yürütür.

Agent Development Kit (ADK)

Agent Development Kit (ADK), yapay zeka aracı oluşturma, dağıtma ve düzenleme işlemlerini basitleştirmek için tasarlanmış özel bir çerçevedir. Bu kitaplık, statik bir büyük dil modelini kod yürütme, API çağırma ve çok adımlı iş akışlarını yönetme özelliklerine sahip dinamik bir aracıya dönüştürmek için gereken standartlaştırılmış yapı taşlarını sağlar.

Çok araçlı aracı, karmaşık sorunları çözmek için arama motoru, veritabanı ve hesap makinesi gibi farklı uzmanlaşmış işlevleri seçip sıralayabilen bir düzenleyicidir. Her adımda hangi aracın kullanılacağını akıllıca belirler ve nihai bir hedefe ulaşmak için bir işlemin çıktısını bir sonraki işlemin girişi olarak iletebilir.

Ne oluşturacaksınız?

Bu codelab'de, basit metin muhakemesinden çok araçlı bir güç merkezine geçiş yapan akıllı bir beslenme danışmanı olan "Sağlıklı İpuçları" adlı bir ajan oluşturacaksınız. Beslenme kavramlarını anlayan temel bir sohbet aracısı oluşturarak başlayacak, ardından bu aracı, malzeme resimlerini arşivlemek için bir Storage SDK aracı ve bu resimleri "okuyup" analiz etmek için bir Vision aracıyla kademeli olarak donatacaksınız. Bu laboratuvarın sonunda, yüklenen bir yemek etiketi fotoğrafını alabilen, kayıt tutmak için bir bulut paketinde saklayabilen ve her bir malzeme için anında "Sağlıklı İpuçları" sağlayabilen tam işlevsel bir düzenleyiciye sahip olacaksınız.

2. Ön koşullar

Faturalandırmanın etkin olduğu bir Google Cloud projesi
Web tarayıcısı

Projenizi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projenizde faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i etkinleştirme

Gerekli dillerin yüklü olduğu Google Cloud Console'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Cloud Console'da sağ üst köşedeki Cloud Shell'i etkinleştir'i tıklayın:

Cloud Shell'e bağlandıktan sonra kimliğinizin doğrulandığını ve projenin, proje kimliğinize ayarlandığını görürsünüz. Kimliğinizin doğrulandığını onaylamak için Cloud Shell'de şu komutu çalıştırın:

gcloud auth list

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

Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:

gcloud config set project <YOUR_PROJECT_ID>

gcloud komutları ve kullanımı için belgelere bakın.

Düzenleyiciyi Aç

Bu codelab'de yerleşik Cloud Düzenleyici'yi kullanacağız. Cloud Shell penceresinde, sağ üst köşedeki Düzenleyiciyi aç düğmesini tıklayın. Bu işlemle VSCode düzenleyicisi açılır.

3. ADK Kurulumu

Önceki bölümde etkinleştirdiğimiz Cloud Shell terminaline geçelim:

Sanal ortam oluşturma ve etkinleştirme (önerilir)

Cloud Shell Terminal'inizden bir sanal ortam oluşturun:

python -m venv .venv

Sanal ortamı etkinleştirin:

source .venv/bin/activate

ADK'yı yükleme

pip install google-adk

4. Google API Anahtarı

AI Studio'yu kullanarak Google API anahtarı oluşturma:

https://aistudio.google.com/ adresini ziyaret edin ve sol alttaki menüden Get API Key simgesini tıklayın.

API anahtarları penceresini görürsünüz. Bu pencerede API anahtarı oluştur'u tıklayın:

Yeni anahtar oluşturmayla ilgili bir pop-up gösterilir. Anahtara şu adı verin: healthy-hints-key

"İçe aktarılan bir proje seçin" açılır listesine gidin.

Import Project simgesini tıkladığınızda tüm Google Cloud projelerinizin listelendiği bir yan pencere açılır. Çalışmak istediğiniz projeyi seçin.

İçe aktar'ı tıklayın.

Açılır menü, yeni içe aktardığınız proje ile güncellenir. Açılır listeden projeyi seçin. Şimdi Anahtar Oluştur'u tıklayın. Oluşturulan API anahtarlarının listesini görürsünüz. Yeni oluşturduğunuz API anahtarının kopyalama simgesini tıklayın.

5. Örnek Temsilci

Cloud Shell Terminal'den, istediğiniz proje konumunda aracınız için bir kök dizin oluşturun:

adk create healthy_hints

Herhangi bir modeli seçebilirsiniz ancak bu codelab'de gemini-2.5-flash modelini kullanacağız.

Bu codelab'de Google AI'ı kullanacağız. Önceki adımda oluşturduğunuz API anahtarını yapıştırın.

Yeni oluşturduğumuz klasörü açalım. En soldaki menüde simgesini, ardından Dosya -> Klasörü Aç'ı tıklayın. Yeni oluşturulan klasörü healthy_hints seçin. Bu klasör genellikle /home/<username> klasöründe bulunur.
healthy_hints klasör yapısı genellikle şu şekilde görünür:

Google API anahtarınızın bulunduğu bir .env dosyası görürsünüz. Bu dosyayı herhangi bir ortam değişkenini ayarlamak için kullanabilirsiniz.
agent.py adlı başka bir dosya da oluşturulur. Bu dosya, ana aracı dosyamızdır. Bu bölümde örnek bir kök aracı oluşturulur. Bu dosyanın içeriğine yakından bakalım. Öncelikle ADK'dan llm_agent öğesini içe aktarıyoruz. Ardından, kök aracıyı oluşturmak için ADK DSL'yi kullanırız. Model adını Gemini-2.5-flash olarak belirtir, temsilciye ad verir ve güzel bir açıklama ekleriz. Buradaki en önemli şey talimattır. Temsilciye ne yapması gerektiğini doğal bir dilde burada söyleriz.
Bu örnek temsilci oldukça geneldir ve kullanıcının tüm sorularını yanıtlar.
Şimdi bu aracıyı yerel olarak çalıştıralım. Bu aracıyla etkileşim kurmanın iki yolu vardır : KSA ve Web.
CLI: Aşağıdaki komutu healthy_hints dizininin dışından çalıştırın.

adk run healthy_hints

Alternatif olarak, healthy_hints dizinindeyseniz aşağıdaki komutu çalıştırın:

adk run .

Aşağıdakine benzer bir çıkış görürsünüz:

"Merhaba" yazın veya sorunuzu sorun. Bu sorunun yanıtı kişiden kişiye değişebilir. Bu, üretken yapay zekanın doğasında vardır.

Web: healthy_hints öğesinin üst dizininden aşağıdaki komutu çalıştırın :

adk web

6. Çok Amaçlı Araç Aracısı

Araç, genellikle bir işlev veya API olan modüler bir kod parçasıdır. Temsilcinin, kendi içindeki bilgilerinin ötesinde dünyayla etkileşim kurmasına olanak tanır.

ADK'daki Araç Türleri

İşlev Araçları: Kendinizin yazdığı özel mantık. Örneğin, belirli veritabanınıza bağlanan bir işlev veya şirketinizin benzersiz biçimi için özel bir "Günlük Ayrıştırıcı".
Yerleşik Araçlar: Google veya ADK tarafından sağlanan kullanıma hazır özellikler (ör. Google Arama, Code Interpreter veya Google RAG Engine).
Agents-as-Tools: Gelişmiş "çok araçlı" veya "çok aracılı" sistemlerde, uzmanlaşmış bir aracı diğeri için araç olarak kullanılabilir. Örneğin, "Araştırma Yöneticisi Aracısı" tarafından kullanılan bir araç "Arama Aracısı" olabilir.

Bu codelab'de Function Tools'u ele alacağız. Şimdi de aracımızı geliştirip çok araçlı hale getirelim.

agent.py dosyasına yeni bir yöntem get_weather ekleyelim.

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

agent.py dosyasını değiştirelim ve aracının adını, açıklamasını ve talimatını değiştirelim:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Şu ana kadar yalnızca bir araç oluşturduk. Şimdi birden fazla araç oluşturalım:

get_current_time adlı başka bir yöntem oluşturalım :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Ayrıca, bu aracı da çağırmak için aracımızı değiştirelim:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Açıklamayı, talimatı ve araçları buna göre değiştirdik. Şimdi bu güncellenmiş aracı çalıştıralım. Bu kez temsilci, geçerli saat ve hava durumuyla ilgili bilgileri de yanıtına ekler.

7. SDK entegrasyonu

Birden fazla aracı nasıl kullanacağımızı öğrendiğimize göre Şimdi, gerçek hayattan birkaç örneği inceleyelim. Sağlıklı ipuçları veren bir temsilci oluşturalım. Buradaki amacımız, içeriğinde malzeme listesi bulunan tüm resimleri aracımıza yüklemek ve aracımızın, sağlıklı olup olmadığını belirterek her bir malzeme hakkında bize bilgi vermesini sağlamaktır.

Google Cloud Storage'a resmi yüklemek için önce bir paket oluşturalım. Yeni bir sekme açıp https://console.cloud.google.com/ adresine gidelim ve arama çubuğuna cloud storage yazalım. Şimdi Ürünler ve sayfalar bölümünde Cloud Storage'ı seçin:

Bu işlem sizi Google Cloud Storage'ın genel bakış sayfasına yönlendirir. Create bucket düğmesini tıklayın. Paket oluşturma sayfasında paketin adını girin. Ad herhangi bir şey olabilir ancak bu codelab'de healthy-hints-bucket-kolkata olarak ayarlayacağız . Diğer her şeyi olduğu gibi bırakıp Create düğmesini tıklayın.

requirements.txt adlı yeni bir dosya oluşturalım ve içine google-cloud-storage ekleyelim. Resmi Storage'a yüklemek için Python Storage SDK'yı kullanacağız.

Öncelikle bağımlılıkları yükleyelim:

pip install -r requirements.txt

Öncelikle Storage API'yi etkinleştirmeniz gerekebilir. Bu işlemi yapmak için terminalinizde aşağıdaki komutu çalıştırın:

gcloud services enable storage.googleapis.com

Şimdi de resmi yüklemek için yeni bir araç ekleyelim.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Şimdi temsilcimizi yeni aracı kullanacak şekilde güncelleyelim:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Artık resimdeki malzemeleri okuyacak başka bir araç ekliyoruz. requirements.txt konumuna google-cloud-vision ekleyelim ve yeni bağımlılığı yükleyelim.

pip install -r requirements.txt

Yine, önce Vision API'yi etkinleştirmeniz gerekebilir. Bu işlemi yapmak için terminalinizde aşağıdaki komutu çalıştırın:

gcloud services enable vision.googleapis.com

Şimdi yeni bir araç ekleyelim read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Şimdi de temsilcimizi bu aracı kullanacak şekilde güncelleyelim.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Sonuç

Healthy Hints codelab'ini tamamladığınız için tebrikler. Metin üreten modelden proaktif bir çoklu araç aracısına geçiş yaparak standart bir yapay zekayı başarıyla dönüştürdünüz. Vision API ve Cloud Storage SDK'yı entegre etmek için ADK'yı kullanarak aracınıza etiketleri okuyacak "gözler" ve bunları arşivleyecek "hafıza" vermiş olursunuz. Ajanın bir dosyayı ne zaman kaydedeceğine nasıl bağımsız olarak karar verdiğini ve gerçek hayata dair sağlık tavsiyeleri vermek için ham verileri nasıl yorumladığını gördünüz.

Bu ilkeler, bundan sonraki süreçte tüm otomatik sistemler için bir plan görevi görecek. İster bulut altyapısını yönetiyor ister kişisel asistanlar oluşturuyor olun, temel aynı kalır: Özel araçlar tanımlayın ve aracının mantığı düzenlemesine izin verin. Bir sonraki adım olarak, aracınızın etkisini artırmak için "Besin Veritabanı" veya "E-posta Aracı" gibi daha fazla araç eklemeyi deneyin.