Google ADK (Agent Development Kit) 1.12.0 Mimarisi: Deklaratif YAML Ajan Tanımlama, Bigtable Toolset ve Vertex AI Agent Engine Dağıtımı

Kod-Öncelikli Çatıdan Hibrit Orkestrasyona: Google ADK 1.12.0 Neden Önemli?

Google tarafından çoklu yapay zeka ajanlarını (Multi-Agent Systems) geliştirmek, değerlendirmek ve bulut-yerel ortamlarda çalıştırmak üzere açık kaynaklı olarak sunulan Agent Development Kit (ADK), GitHub üzerinde yayınlanan 1.12.0 sürümüyle önemli bir mimari eşiği geride bıraktı. İlk sürümlerinden itibaren kod-öncelikli (code-first) tasarım felsefesini benimseyen ADK, 1.12.0 güncellemesiyle birlikte yapılandırma-öncelikli (config-first / declarative YAML) ajan tanımlama modelini birinci sınıf vatandaş olarak çekirdeğine dahil etti.

Kurumsal yapay zeka mühendisliğinde ajan sayısı ve hiyerarşi derinliği arttıkça; model parametrelerinin, sistem yönergelerinin (instructions), alt ajan (sub-agent) yönlendirmelerinin ve araç (tool) bağlantılarının yalnızca uygulama kodu içinde tutulması dağıtım süreçlerinde darboğaz yaratır. ADK 1.12.0, bu problemi dört ana eksende çözen kapsamlı bir mühendislik paketi sunar:

1. Deklaratif YAML Ajan Tanımlama (Agent Config): LlmAgent, SequentialAgent, ParallelAgent ve LoopAgent bileşenlerinin Pydantic şema doğrulamalı (AgentConfig.json) YAML dosyalarıyla inşa edilmesi ve doğrudan Vertex AI Agent Engine üzerine dağıtılması.
2. Birinci Parti Google Cloud Bigtable Araç Seti (BigtableToolset): Petabayt ölçekli NoSQL tablolarında şema keşfi, küme denetimi ve SQL sorgulama yeteneklerinin ajanlara yerleşik olarak açılması.
3. Çoklu API İsim Uzayı İzolasyonu (tool_name_prefix): Otomatik üretilen GoogleApiToolset ve Cloud Spanner araçlarında fonksiyon adı çakışmalarını önleyen önek mimarisi ve OAuth kapsam iyileştirmeleri.
4. Sunucusuz Dağıtım ve Çalışma Zamanı Optimizasyonları: adk deploy cloud_run için build_image otomasyonu, State.setdefault() durum yönetimi, paralel araç çağrılarında invocation_id bütünlüğü ve kod yürütücülerde (Code Executors) tembel yükleme (lazy loading).

1. Deklaratif YAML Ajan Mimarisi: Agent Config ve AgentConfig.json Şeması

ADK 1.12.0 sürümünün en dikkat çekici yeniliği, ajanların Python kodunun yanı sıra tamamen YAML yapılandırma dosyalarıyla yazılabilmesidir. Sürümle birlikte eklenen yaml_utils.py (1fd58cb) ve Pydantic Field açıklamalarıyla zenginleştirilmiş AgentConfig.json şeması (5b999ed), VS Code veya JetBrains IDE'lerinde YAML yazarken gerçek zamanlı alan doğrulaması, tip kontrolü ve dokümantasyon ipuçları sağlar.

YAML tabanlı ajan örneklerinde standart isimlendirme kuralı olarak _config soneki (43f302c) benimsenmiştir. Çoklu ajan kurulumunu (1328e6e) gösteren tipik bir root_agent.yaml mimarisi aşağıdaki gibi kurgulanır:

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
name: telemetry_orchestrator_config
model: gemini-2.5-flash
description: Dağıtık altyapı metriklerini ve Bigtable telemetri tablolarını analiz eden kök orkestratör ajan.
instruction: |
  Gelen altyapı anomalisi taleplerini analiz et.
  Veritabanı şema ve zaman serisi sorguları için alt ajanları ve Bigtable araçlarını deterministik sırayla çalıştır.
sub_agents:
  - config_path: ./sub_agents/bigtable_inspector_agent.yaml
  - config_path: ./sub_agents/remediation_planner_agent.yaml
tools:
  - name: google_search
  - name: custom_tools.alert_dispatcher

Programatik Yükleme ve Doğrudan Agent Engine Dağıtımı

YAML ile tanımlanan bir ajan, çalışma zamanında config_agent_utils.from_config() yardımcısıyla Python nesnesine dönüştürülebildiği gibi, b3b7003 commit'i ile gelen CLI desteği sayesinde tek satır Python sarmalayıcı kodu yazmaya gerek kalmadan doğrudan Vertex AI Agent Engine ortamına dağıtılabilir:

from google.adk.agents import config_agent_utils

# YAML yapılandırma dosyasından tip güvenli LlmAgent / SequentialAgent inşası
root_agent = config_agent_utils.from_config("telemetry_agent/root_agent.yaml")

Ayrıca 8a9a271 yamasıyla SequentialAgent.config_type tip bildirimleri düzeltilerek ardışık iş akışı ajanlarının YAML şema ayrıştırıcısıyla tam uyumlu çalışması güvence altına alınmıştır.

2. Veri Katmanı Entegrasyonu: Yerleşik BigtableToolset ve İsim Uzayı İzolasyonu

Kurumsal ajanların yalnızca metin üretmekle kalmayıp yüksek hacimli operasyonel veritabanlarını gerçek zamanlı sorgulayabilmesi kritik bir gereksinimdir. ADK 1.12.0, Google Cloud'un düşük gecikmeli geniş sütunlu (wide-column) NoSQL veritabanı için birinci parti BigtableToolset bileşenini (deneysel özellik olarak) kullanıma sunar.

BigtableToolset İçerisinde Sunulan Yerleşik Fonksiyonlar

google.adk.tools.bigtable modülü altında gelen araç seti, ajanın proje içindeki Bigtable topolojisini otonom olarak keşfetmesini ve SQL sorguları yürütmesini sağlayan 7 temel aracı barındırır:

• Örnek ve Küme Keşfi: list_instances, get_instance_info, list_clusters, get_cluster_info
• Tablo ve Şema Denetimi: list_tables, get_table_info (sütun aileleri ve üst veri analizi)
• Veri Sorgulama: execute_sql (Bigtable tablosu üzerinde parametreli GoogleSQL sorguları çalıştırma)

import os
from google.adk.agents import Agent
from google.adk.tools.bigtable import BigtableToolset
from google.adk.tools.bigtable.settings import BigtableToolSettings

# Deneysel özellik uyarılarını üretim loglarında susturma (v1.12.0 - 4afc9b2)
os.environ["ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS"] = "true"

bigtable_tools = BigtableToolset(
    settings=BigtableToolSettings()
)

telemetry_agent = Agent(
    model="gemini-2.5-flash",
    name="bigtable_telemetry_analyst",
    instruction=(
        "Google Cloud Bigtable örneklerindeki zaman serisi tablolarını incele, "
        "şema yapısını doğrula ve execute_sql aracıyla anomali pencerelerini raporla."
    ),
    tools=[bigtable_tools],
)

Çoklu Araç Ortamlarında İsim Uzayı Çakışmalarının Önlenmesi (tool_name_prefix)

Bir ajan aynı anda hem Google Calendar, hem Google Drive hem de birden fazla Cloud Spanner veya REST API kaynağına bağlandığında, otomatik üretilen get, list, update veya execute_sql gibi fonksiyon isimleri LLM'in araç çağırma (function calling) şemasında birbiriyle çakışır. ADK 1.12.0 bu mimari sorunu iki kritik adımla çözer:

1. Otomatik Üretilen GoogleApiToolset İçin Özel Önek (a2832d5): Google API keşif belgelerinden (Discovery Docs) otomatik üretilen araç setlerine tool_name_prefix parametresi eklenerek her API'nin kendi isim uzayında (calendar_events_list, drive_files_list vb.) izole edilmesi sağlanır.
2. Cloud Spanner Önek ve OAuth Yetki Yaması (a27927d & b66054d): Spanner araçlarına standart önek eklenerek Bigtable gibi diğer veritabanı araçlarıyla aynı ajan içinde çakışmadan kullanılması sağlanmış; ayrıca Spanner yönetici kapsamı (spanner.admin) varsayılan OAuth kapsamlarına dahil edilmiştir.

3. Sunucusuz Dağıtım Otomasyonu ve Çalışma Zamanı Optimizasyonları

ADK 1.12.0, ajanların yerel geliştirme ortamından (adk web) üretim ortamına geçiş sürecini hızlandıran altyapı iyileştirmeleri içerir:

Cloud Run build_image Seçeneği ve A2A (Agent2Agent) İyileştirmeleri

• adk deploy cloud_run İmaj İnşası (c843503): CLI üzerinden Google Cloud Run'a yapılan dağıtımlarda konteyner imajının inşasını doğrudan tetikleyen build_image seçeneği eklendi.
• Agent2Agent (A2A) Ajan Kartı Yolu Düzeltmesi (fa64545 & a117cf0): Farklı ajanların birbirlerinin yeteneklerini keşfetmek için kullandığı .well-known/agent.json (Agent Card) adresleme yolu A2A referans uygulamalarında standartlaştırıldı.

Tembel Yüklemeli Kod Yürütücüler (Lazy Loading) ve Oturum Durumu (State)

• VertexAiCodeExecutor ve ContainerCodeExecutor Lazy Loading (018db79): Önceki sürümlerde kod yürütme modüllerinin paket içe aktarma (import) aşamasında ağır Docker SDK veya Vertex AI bağımlılıklarını belleğe yüklemesi başlangıç gecikmesine yol açıyordu. 1.12.0 ile bu yürütücüler yalnızca ajan gerçekten kod çalıştırma yeteneğine ihtiyaç duyduğunda tembel olarak yüklenir.
• State.setdefault() Desteği (77ed1f5): Çok adımlı ajan hafızasını temsil eden ADK State nesnesine Python sözlüklerinden alışılan .setdefault(key, default) metodu eklenerek geri çağırma (callback) ve araç fonksiyonlarında durum ilklendirme kodu sadeleştirildi:

from google.adk.agents.callback_context import CallbackContext

def before_agent_execution(callback_context: CallbackContext) -> None:
    # Oturum durumunda anahtar yoksa atomik olarak varsayılan değeri atar
    retry_budget = callback_context.state.setdefault("max_sql_retries", 3)
    audit_trail = callback_context.state.setdefault("executed_queries", [])

• Paralel Fonksiyon Yanıtlarında invocation_id Bütünlüğü (279e4fe): Bir LLM tek adımda birden fazla paralel araç çağrısı yaptığında, dönen yanıt olayları (function response events) birleştirilirken artık temel olayın invocation_id değeri korunur. Bu sayede telemetri ve izleme (tracing) sistemlerinde paralel çağrıların hangi ana akıl yürütme (reasoning) adımına ait olduğu kesintisiz takip edilir.
• Eksik candidates_token_count Koruması (22f34e9): Bazı akışlı (streaming) veya üçüncü parti model yanıtlarında isteğe bağlı (Optional) olan candidates_token_count alanı dönmediğinde yaşanan çalışma zamanı çökmesi giderildi.

4. Google ADK 1.12.0 Mimari Yenilikler ve Bileşen Matrisi

Aşağıdaki tablo, ADK 1.12.0 sürümüyle gelen teknik bileşenleri, ilgili commit referanslarını ve kurumsal ajan mimarilerindeki karşılıklarını özetlemektedir:

5. Mimari Değerlendirme

Google ADK 1.12.0, yapay zeka ajanlarının geliştirilmesinde "deklaratif orkestrasyon, imperatif araçlar" paradigmasını olgunlaştıran stratejik bir sürümdür. Ajan topolojisinin, model seçiminin ve sistem yönergelerinin tip güvenli YAML dosyalarına (AgentConfig.json) taşınması; platform ekiplerinin ajan yapılandırmalarını GitOps süreçleriyle yönetmesine olanak tanırken, Python geliştiricilerinin BigtableToolset, Spanner ve özel MCP araçlarıyla derin entegrasyonlar kurmasını kolaylaştırmaktadır.