DEV Community

Cover image for Google ADK (Ajan Geliştirme Kiti) Nedir? Pratik Kılavuz
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Google ADK (Ajan Geliştirme Kiti) Nedir? Pratik Kılavuz

Google ADK, yapay zeka ajanlarını oluşturmak, değerlendirmek ve dağıtmak için açık kaynaklı bir çerçevedir. Agentspace gibi Google ürünlerindeki gerçek ajanlara güç verir. Daha önce OpenAI Agents SDK gibi ajan yığınlarını incelediyseniz, ADK benzer problemi Gemini ve Vertex AI ekosistemine yakın kalarak çözer. Bu rehberde ADK’nın temel parçalarını, basit bir ajanı nasıl yapılandıracağınızı ve Apidog ile ajanınızın çağırdığı API’leri nasıl test edebileceğinizi göreceksiniz.

Apidog'u bugün deneyin

Google ADK Nedir?

ADK, Agent Development Kit’in kısaltmasıdır. Google, ADK’yı Nisan 2025’te Google Cloud Next’te tanıttı. Amaç, ajan yaşam döngüsünü tek bir çatı altında toplamaktır:

  1. Ajanı tanımlamak
  2. Araçları bağlamak
  3. Birden fazla ajanı orkestre etmek
  4. Davranışı değerlendirmek
  5. Üretime dağıtmak

ADK ilk olarak Python ile başladı. Google daha sonra Java’yı ekledi; Go ve TypeScript desteği de bunu takip etti. Çerçeve, Google’ın Agentspace ve Müşteri Etkileşim Paketi’ndeki ajanlar için dahili olarak kullandığı altyapıya dayanır. Bu yüzden yalnızca demo amaçlı bir SDK değil, üretim iş yükleri için tasarlanmış bir ajan geliştirme katmanıdır.

ADK modelden bağımsızdır, ancak Google ekosistemi için optimize edilmiştir. Gemini ve Vertex AI Model Garden ile doğal çalışır. LiteLLM entegrasyonu sayesinde Anthropic, Meta, Mistral ve diğer sağlayıcılara da yönlendirme yapabilirsiniz. Böylece Gemini entegrasyonundan yararlanırken tek bir modele kilitlenmezsiniz.

ADK, Gemini ve Vertex AI Ekosisteminde Nerede Yer Alır?

ADK’yı anlamak için üç katmanı ayırın:

  • Model: Gemini veya Vertex AI Model Garden / LiteLLM üzerinden kullanılan başka bir model muhakeme yapar.
  • Çerçeve: ADK, ajanları tanımladığınız, araçları bağladığınız ve çoklu ajan akışlarını organize ettiğiniz kod katmanıdır.
  • Çalışma zamanı: Vertex AI Agent Engine, ajanınızı üretimde çalıştırmak için yönetilen ve ölçeklenebilir bir ortam sağlar. Alternatif olarak Cloud Run veya herhangi bir konteyner çalışma zamanına dağıtabilirsiniz.

Pratikte akış şöyledir:

  1. ADK ile ajan kodunu yazarsınız.
  2. Ajan, Gemini veya seçtiğiniz başka bir modeli kullanır.
  3. Araç fonksiyonları üzerinden API’lere, veritabanlarına veya servislerinize erişir.
  4. Geliştirme sırasında adk run veya adk web ile test edersiniz.
  5. Üretimde Vertex AI Agent Engine, Cloud Run veya başka bir konteyner ortamına dağıtırsınız.

Temel Kavramlar

ADK ile çalışırken en sık kullanacağınız parçalar şunlardır:

  • Ajanlar
  • Araçlar
  • Çoklu ajan yapıları
  • Runner
  • Değerlendirme ve dağıtım

Ajanlar

ADK’daki temel birim, LLM destekli ajandır. Python’da google.adk.agents içinden içe aktarılır. Sınıf adı LlmAgent’tır; Agent ise bunun için kullanılan pratik takma addır.

Bir ajana genellikle şunları verirsiniz:

  • name: Ajanın adı
  • model: Kullanılacak model
  • instruction: Davranışı belirleyen sistem talimatı
  • tools: Ajanın çağırabileceği fonksiyonlar

Örnek:

from google.adk.agents import Agent

def get_exchange_rate(base: str, target: str) -> dict:
    """İki para birimi arasındaki güncel dönüşüm oranını döndürür."""
    # Gerçek FX API'nizi burada çağırın
    return {
        "base": base,
        "target": target,
        "rate": 1.08
    }

currency_agent = Agent(
    name="currency_exchange_agent",
    model="gemini-2.0-flash",
    instruction=(
        "Kullanıcıların döviz kurları arasında dönüşüm yapmasına yardımcı ol. "
        "Yalnızca araçtan gelen verilere dayan ve emin olmadığın durumda bunu belirt."
    ),
    tools=[get_exchange_rate],
)
Enter fullscreen mode Exit fullscreen mode

Bu örnekte ajan doğrudan döviz kuru üretmez. Bunun yerine get_exchange_rate aracını çağırır ve sonucu kullanıcıya açıklar.

Uygulamada araç fonksiyonunu gerçek API’ye bağlayabilirsiniz:

import requests

def get_exchange_rate(base: str, target: str) -> dict:
    """İki para birimi arasındaki güncel dönüşüm oranını gerçek FX API'sinden alır."""
    response = requests.get(
        "https://example.com/rates",
        params={"base": base, "target": target},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()
Enter fullscreen mode Exit fullscreen mode

Burada önemli nokta: Ajanın güvenilirliği, aracın döndürdüğü JSON sözleşmesine bağlıdır. Bu yüzden API yanıtlarını ayrıca test etmeniz gerekir.

Araçlar

Araçlar, ajanın metin üretmenin ötesinde işlem yapmasını sağlar. ADK’da basit bir Python fonksiyonu araç olabilir.

Model şu bilgilerden yararlanır:

  • Fonksiyon adı
  • Parametre adları
  • Tip ipuçları
  • Docstring
  • Dönüş formatı

Bu yüzden araç fonksiyonlarını belirsiz yazmayın.

Kötü örnek:

def search(q):
    """Search."""
    ...
Enter fullscreen mode Exit fullscreen mode

Daha iyi örnek:

def search_flights(origin: str, destination: str, date: str) -> dict:
    """Belirtilen kalkış, varış ve tarih için uygun uçuş seçeneklerini döndürür."""
    ...
Enter fullscreen mode Exit fullscreen mode

ADK ayrıca google_search ve kod yürütme gibi yerleşik araçlarla gelir. Harici araç sunucularını bağlamak için Model Bağlam Protokolü (MCP) desteği vardır. LangChain veya LlamaIndex gibi üçüncü taraf kütüphaneleri sarabilir ya da başka bir ajanı araç olarak kullanabilirsiniz.

Çoğu gerçek ajan, araçlar üzerinden REST API’leri çağırır. Bu noktada test, mock ve sözleşme doğrulama kritik hale gelir.

Çoklu Ajan Sistemleri

Tek bir ajan basit işler için yeterlidir. Ancak ADK, uzmanlaşmış ajanları bir araya getirmek için tasarlanmıştır.

Tipik yapı:

  1. Bir koordinatör ajan kullanıcı isteğini alır.
  2. İşi alt ajanlara böler.
  3. Alt ajanlar kendi araçlarını çağırır.
  4. Koordinatör sonuçları birleştirir.

ADK, deterministik akışlar için iş akışı ajanları sağlar:

  • SequentialAgent: Alt ajanları sırayla çalıştırır.
  • ParallelAgent: Alt ajanları paralel çalıştırır.
  • LoopAgent: Bir koşul sağlanana kadar tekrarlar.

Bu yapıları LLM tabanlı yönlendirme ile birleştirerek araştırma, planlama, destek veya veri toplama ajanları oluşturabilirsiniz.

Çalıştırıcılar: Runner

Üretim kodunda ajanı doğrudan çağırmak yerine Runner kullanırsınız. Runner, ADK’nın yürütme motorudur.

Runner şunları yönetir:

  • Oturum
  • Olay akışı
  • Durum güncellemeleri
  • Model çağrıları
  • Araç çağrıları
  • Alt ajan geçişleri

Geliştirme sırasında iki komut özellikle kullanışlıdır:

adk run
Enter fullscreen mode Exit fullscreen mode

Bu komut interaktif terminal oturumu başlatır.

adk web
Enter fullscreen mode Exit fullscreen mode

Bu komut yerel bir tarayıcı arayüzü açar. Ajanla sohbet edebilir, adımları inceleyebilir ve hangi aracın ne zaman çağrıldığını görebilirsiniz.

Değerlendirme ve Dağıtım

Ajan davranışını yalnızca manuel test ederek doğrulamak yeterli değildir. İstem, model, araç veya API yanıtı değiştiğinde ajan farklı davranabilir.

ADK, ajanı beklenen yörüngelere ve yanıtlara göre değerlendirmek için araçlar içerir. Bu yaklaşım özellikle şu durumlarda faydalıdır:

  • Model değiştirirken
  • Prompt güncellerken
  • Yeni araç eklerken
  • Çoklu ajan yönlendirmesini değiştirirken
  • Üretime çıkmadan önce regresyon kontrolü yaparken

Dağıtım tarafında iki ana yol vardır:

  • Yönetilen yol: Vertex AI Agent Engine kullanmak.
  • Taşınabilir yol: Ajanı konteyner haline getirip Cloud Run veya başka bir konteyner platformuna dağıtmak.

Uygulama Örneği: Basit Çoklu Ajan Yapısı

Aşağıdaki örnekte bir seyahat planlama ajanı, uçuş ve otel araması için iki alt ajana yetki verir.

from google.adk.agents import Agent

def search_flights(origin: str, destination: str, date: str) -> dict:
    """Belirtilen rota ve tarih için uçuş seçeneklerini döndürür."""
    # Uçuş API'nizi burada çağırın
    return {
        "origin": origin,
        "destination": destination,
        "date": date,
        "flights": []
    }

def search_hotels(destination: str, check_in: str, check_out: str) -> dict:
    """Belirtilen şehir ve tarihler için otel seçeneklerini döndürür."""
    # Otel API'nizi burada çağırın
    return {
        "destination": destination,
        "check_in": check_in,
        "check_out": check_out,
        "hotels": []
    }

flights = Agent(
    name="flight_agent",
    model="gemini-2.0-flash",
    instruction="Kullanıcının rotası ve tarihleri için uçuş seçeneklerini bul.",
    tools=[search_flights],
)

hotels = Agent(
    name="hotel_agent",
    model="gemini-2.0-flash",
    instruction="Hedefe yakın otel seçeneklerini bul.",
    tools=[search_hotels],
)

trip_planner = Agent(
    name="trip_planner",
    model="gemini-2.0-flash",
    instruction=(
        "Bir gezi planı oluştur. "
        "Uçuş aramaları için flight_agent'a, otel aramaları için hotel_agent'a devret. "
        "Sonuçları kullanıcı için kısa ve uygulanabilir şekilde özetle."
    ),
    sub_agents=[flights, hotels],
)
Enter fullscreen mode Exit fullscreen mode

Bu yapıda:

  • trip_planner koordinatördür.
  • flight_agent yalnızca uçuş aramasıyla ilgilenir.
  • hotel_agent yalnızca otel aramasıyla ilgilenir.
  • Her alt ajan kendi API aracını çağırır.

Geliştirme sırasında bu ajanı adk web ile çalıştırıp şu soruları test edebilirsiniz:

  • Koordinatör doğru alt ajana yönlendiriyor mu?
  • Araç doğru parametrelerle çağrılıyor mu?
  • API yanıtı eksik olduğunda ajan nasıl davranıyor?
  • Hata durumlarında kullanıcıya açık yanıt dönüyor mu?

ADK ve OpenAI Agents SDK Karşılaştırması

ADK ve OpenAI Agents SDK, kod öncelikli ajan çerçeveleridir. İkisi de araç çağrıları, ajanlar arası geçişler ve izleme gibi temel ihtiyaçları karşılar. Temel fark, hangi ekosisteme daha yakın olduklarıdır.

Google ADK OpenAI Agents SDK
Varsayılan model Gemini (Vertex AI) OpenAI modelleri
Diğer modeller Vertex AI Model Garden, LiteLLM LiteLLM ve diğerleri
Diller Python, Java, Go, TypeScript Python, JavaScript/TypeScript
Çoklu ajan Alt ajanlar artı Sıralı, Paralel, Döngü iş akışı ajanları Araç olarak ajanlar ve devirler
Yönetilen çalışma zamanı Vertex AI Agent Engine Kendi getirmeniz gerekir
Araç protokolü MCP, yerleşik araçlar, fonksiyon araçları MCP, fonksiyon araçları

Google Cloud üzerinde çalışıyorsanız ADK + Vertex AI doğal bir seçimdir. OpenAI öncelikli bir yığın kullanıyorsanız OpenAI Agents SDK daha doğrudan bir yol sunar. Her iki taraf da MCP’yi desteklediği için araç sunucularını paylaşmak mümkündür.

ADK Ne Zaman Kullanılır?

ADK’yı şu durumlarda tercih edin:

  • Google Cloud üzerinde geliştirme yapıyorsanız.
  • Gemini ve Vertex AI Agent Engine ile yönetilen bir çalışma zamanı istiyorsanız.
  • Birden fazla uzman ajana ihtiyacınız varsa.
  • Sıralı, paralel veya döngüsel ajan akışlarını açıkça kontrol etmek istiyorsanız.
  • Değerlendirme mekanizmasının çerçevenin parçası olmasını istiyorsanız.
  • Model değiştirme ihtimaliniz varsa ve LiteLLM / Vertex AI Model Garden üzerinden esneklik istiyorsanız.

ADK’yı şu durumlarda kullanmayabilirsiniz:

  • Tek bir prompt ve bir veya iki fonksiyon çağrısı yeterliyse.
  • Başka bir model ekosistemine sıkı şekilde bağlıysanız.
  • Çoklu ajan orkestrasyonu gerekmiyorsa.
  • Ek çerçeve yapısı, projeniz için gereksiz karmaşıklık oluşturuyorsa.

Kural basit: İş akışınız büyüdükçe ADK değer kazanır. İş çok küçükse, daha basit bir fonksiyon çağrısı mimarisi yeterli olabilir.

Apidog Nereye Uyar: Ajanınızın Çağırdığı API’leri Test Etme ve Taklit Etme

ADK ajanınızı düzenler. Ancak ajanınızın bağlı olduğu harici API’leri test etmez. Bu boşluğu erken kapatmak önemlidir.

Gerçek bir ajandaki araçlar genellikle şunları çağırır:

  • LLM uç noktaları
  • Ödeme API’leri
  • Dahili mikro servisler
  • Üçüncü taraf veri kaynakları
  • Arama servisleri
  • CRM veya ERP sistemleri

Bu servislerden biri beklenmeyen formatta yanıt döndürürse, ajan hatalı veri üzerinden muhakeme yapar. Hata bazen API’de, bazen araç fonksiyonunda, bazen de prompt davranışında gibi görünebilir. Bu yüzden API sözleşmesini ajandan ayrı test etmek gerekir.

Apidog burada devreye girer. Açık olmak gerekirse: Apidog bir ajan çerçevesi değildir ve ADK’nın yerini almaz. Apidog, ajan araçlarınızın çağırdığı API katmanını test etmek, taklit etmek ve doğrulamak için kullanılır.

ADK geliştirme sırasında Apidog’u şu şekilde kullanabilirsiniz:

1. Araçlarınızın çağırdığı uç noktaları mock edin

Ajanınız canlı servislere bağlanmadan önce REST uç noktalarını taklit edebilirsiniz.

Örneğin search_flights fonksiyonunuzun beklediği yanıt şu olabilir:

{
  "flights": [
    {
      "airline": "Example Air",
      "price": 320,
      "departure": "2026-07-10T09:30:00Z",
      "arrival": "2026-07-10T12:15:00Z"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Apidog’da bu yanıtı mock olarak tanımlayıp ajanı canlı API’ye bağlanmadan test edebilirsiniz. Böylece:

  • Token veya API kotası harcamazsınız.
  • Rate limit’e takılmazsınız.
  • Hata senaryolarını kontrollü üretirsiniz.
  • Ajanın beklenmeyen yanıtlarla nasıl davrandığını test edersiniz.

Daha fazla bilgi için taklit API rehberine bakabilirsiniz.

2. Araç yanıt şeklini doğrulayın

Ajanınız belirli alanların var olduğunu varsayabilir. Örneğin:

result = search_flights("IST", "BER", "2026-07-10")
first_price = result["flights"][0]["price"]
Enter fullscreen mode Exit fullscreen mode

Eğer API artık price yerine amount döndürürse ajanınız bozulur veya yanlış yanıt üretir.

Apidog’daki API iddiaları ile şu kontrolleri yapabilirsiniz:

  • Yanıt HTTP 200 mü?
  • flights alanı var mı?
  • price sayısal mı?
  • Tarihler beklenen formatta mı?
  • Hata yanıtları tutarlı mı?

Bu kontrolleri ajanın loglarında hata aramak yerine API testlerinde yakalarsınız.

3. Ortam bazlı anahtarları yönetin

Geliştirme, hazırlık ve üretim ortamlarında farklı anahtarlar kullanırsınız. Apidog ortamlarıyla bu değerleri ayrı tutabilirsiniz.

Örnek ortam değişkenleri:

BASE_URL=https://api-dev.example.com
API_KEY=dev-key
Enter fullscreen mode Exit fullscreen mode

Hazırlık ortamında:

BASE_URL=https://api-staging.example.com
API_KEY=staging-key
Enter fullscreen mode Exit fullscreen mode

Aynı araç fonksiyonu, farklı ortam değerleriyle test edilebilir. Böylece ajan kodunu değiştirmeden farklı aşamalarda doğrulama yapabilirsiniz.

Ajanlara özel daha derin bir örnek için yapay zeka ajanının araç çağrılarını üretime geçmeden önce nasıl test edeceğinize bakabilirsiniz. Ayrıca Apidog’u indirebilir ve birkaç dakika içinde tek bir uç noktayı mock edebilirsiniz.

Sıkça Sorulan Sorular

Google ADK ücretsiz ve açık kaynak mı?

Evet. ADK, GitHub’daki Apache lisanslı bir depoda açık kaynaklıdır ve yerel olarak ücretsiz çalıştırılabilir. Ancak çağırdığınız modeller ve Vertex AI Agent Engine gibi yönetilen çalışma zamanları için ödeme yaparsınız. Çerçevenin kendisi ücretsizdir.

ADK yalnızca Gemini ile mi çalışır?

Hayır. ADK, Gemini ve Vertex AI için optimize edilmiştir; ancak modelden bağımsızdır. Vertex AI Model Garden ve LiteLLM aracılığıyla Anthropic, Meta, Mistral ve diğer sağlayıcıları kullanabilirsiniz. Gemini varsayılan ve doğal seçenektir, zorunluluk değildir.

ADK hangi dilleri destekler?

Python ilk desteklenen dildir ve en eksiksiz seçenek olmaya devam eder. Google daha sonra Java’yı ekledi; Go ve TypeScript desteği de bunu takip etti. En geniş özellik kapsamını istiyorsanız Python en güvenli tercihtir.

ADK ajanımın bağımlı olduğu API’leri nasıl test ederim?

API’leri ajandan ayrı test edin. LLM veya araç uç noktalarını mock edin, ajanı canlı çağrılar yapmadan çalıştırın ve her yanıtın beklenen sözleşmeyle eşleştiğini doğrulayın. Apidog bu iki ihtiyacı da kapsar. ChatGPT API’sini nasıl test edeceğinize dair rehber, araçlarınızın çağırabileceği bir LLM uç noktası için aynı deseni gösterir.

Özet

Google ADK, Gemini ve Vertex AI’ye yakın duran ama diğer modellere de açık kalan üretim odaklı bir ajan geliştirme çerçevesidir. Başlamak için tek bir ajan ve birkaç araç tanımlayın. Davranışı görmek için adk web kullanın. Akış büyüdükçe alt ajanlara, iş akışı ajanlarına ve yönetilen dağıtıma geçin.

Ajanınız harici API’lere bağımlı hale geldikçe bu API’leri ayrı bir sözleşme olarak ele alın. Mock edin, doğrulayın ve ortamlar arasında tutarlı test edin. Bu katman, Apidog’un çözdüğü problemdir ve kararsız ajan davranışlarının büyük kısmı burada başlar.

Top comments (0)