Google ADK 2.6.3 ile Anahtarsız Workflow: Erişilebilirlik Triyajı Gerçek Testi

Kısa sonuç: Google Agent Development Kit (ADK) 2.6.3, yalnız “bir modele araç verip konuşmasını bekleyen” bir ajan kütüphanesi değil. Yeni Workflow motoruyla sıradan Python işlevlerini doğrulanan, izlenebilen ve gerektiğinde insan onayında durabilen bir akışa dönüştürüyor. Sürümü geçici Python 3.12 ortamında kurdum; model anahtarı ve bulut hesabı kullanmadan erişilebilirlik hata kaydını üç aşamada ayrıştıran gerçek bir akış çalıştırdım. ADK Web arayüzünü de yerelde açıp ekran akışını ve 320 piksel yeniden akışı kontrol ettim.

Google ADK 2 ne işe yarar?

ADK, ajanı oluşturan model, talimat ve araçlarla; ajanın nasıl yürütüleceğini belirleyen iş akışını birbirinden ayırır. Agent sınıfı bir dil modeliyle karar veren bileşeni tanımlar. Workflow ise işlevleri, ajanları ve alt akışları bir grafik üzerinde sıralar; paralel dallanma, birleştirme, yönlendirme, döngü, yeniden deneme, durum saklama ve insan girdisi gibi yürütme kurallarını yönetir.

Bu ayrım önemli: dosyayı doğrulama, tutarı sınama veya JSON şeması üretme gibi kesin adımların model tarafından “tahmin edilmesi” gerekmez. Bunlar normal Python işlevleri olabilir. Model yalnız belirsiz metni sınıflandırmak veya açıklama üretmek gibi uygun bir düğümde devreye girer. Böylece maliyet, hata alanı ve denetim yükü azalır.

ADK 2.0, 19 Mayıs 2026’da genel kullanıma açıldı. 1.x’e göre ajan API’si, olay modeli ve oturum şeması değişti. 2.0 oturumlarını 1.28 ve üzeri okuyabiliyor; daha eski 1.x sürümleriyle uyumluluk yok. Mevcut projesini yükselten ekip, yalnız paket sürümünü değiştirmek yerine oturum göçünü ve olay tüketen kodu test etmeli.

Kimler için?

Python bilen ürün, destek, veri ve kalite ekipleri için uygun. Özellikle aynı sürecin bir kısmı deterministik, bir kısmı model destekli ise güçlü. Örneğin erişilebilirlik bulgusunu ayrıştırma ve alanları doğrulama kodla; serbest metinden düzeltme önerisi üretme modelle yapılabilir.

Yalnız tek bir API çağrısı yapan küçük betik için çerçeve ağır kalabilir. Görsel sürükle-bırak arayanlar Dify, Flowise veya n8n’i daha hızlı öğrenebilir. Uzun süreli durum, çoklu ajan, değerlendirme ve izleme gerekmiyorsa sade bir Python işlev zinciri daha ucuz ve anlaşılırdır.

Depo, sürüm, lisans ve bakım kontrolü

İncelediğim kararlı etiket v2.6.3; 7 Ağustos 2026’da yayımlandı ve 0b55dcf sabit commit’ine karşılık geliyor. Sürüm notu, Cloud Run dağıtımındaki --sandbox-launcher seçeneğini uygun gcloud beta komutunun arkasına alan tek bir hata düzeltmesi içeriyor. Ana dalda 9 Ağustos’a kadar A2A kartı, özel planlayıcı, araç bağlamı ve kimlik bilgisi paylaşımıyla ilgili yeni düzeltmeler vardı. Bu hareketlilik bakımın sürdüğünü gösterir; tek başına kalite garantisi değildir.

Açık issue’larda OpenAPI hizmet hesabı kimlik doğrulaması, eski olayların göçü, statik talimat sırası ve oluşturulan proje dosyalarıyla ilgili sorunlar görülüyordu. Kapanan örnekler arasında Workflow ajanlarının Web UI değerlendirme kümesine eklenmesini bozan hata da var. Depo çok hızlı değiştiği için küçük sürümlerde bile regresyon testi gerekli.

Kod Apache 2.0 lisanslı. Lisans; kullanma, değiştirme ve dağıtmaya izin verir, bildirim ve lisans koşullarının korunmasını ister, patent hükmü içerir. Bağlanan Gemini, OpenAI, Anthropic veya başka model hizmetleri kendi koşullarına tabidir. GitHub’da yayımlanmış depo güvenlik duyurusu görünmüyordu ve kökte bir SECURITY.md bulamadım; bu, güvenlik açığı olmadığı anlamına gelmez. Temiz ortamda yaptığım pip-audit taraması bilinen açık bulmadı.

Kurulum ve başlangıç

ADK 2.6.3, Python 3.10 ve üzerini istiyor. Ana Python ortamını kirletmemek için ayrı bir sanal ortam kullanın:

mkdir adk-triyaj
cd adk-triyaj
uv venv --python 3.12
source .venv/bin/activate
uv pip install "google-adk==2.6.3"

Benim geçici ortamımda 56 paket kuruldu. Google, geçişli bağımlılıkları sınırlamak için Python sürümüne uygun resmî constraints dosyasını kullanmayı öneriyor. Üretimde etiketi sabitleyin, constraints dosyasını kaydedin ve yükseltmeyi CI üzerinde güvenlik taramasıyla sınayın.

Adım adım gerçek kullanım: erişilebilirlik bulgusu triyajı

Aşağıdaki akış, P1 | Form etiketi yok | /kayit biçimindeki girdiyi ayrıştırır, önceliği doğrular ve izleme sistemine gönderilebilecek JSON üretir. Model, API anahtarı, ağ isteği veya ücretli hizmet kullanmaz.

import asyncio
import json
from google.adk import Workflow
from google.adk.runners import InMemoryRunner
from google.adk.workflow import START
from google.genai import types

def ayristir(node_input: str) -> dict:
    p, sorun, sayfa = [
        x.strip() for x in node_input.split("|", 2)
    ]
    return {"oncelik": p, "sorun": sorun, "sayfa": sayfa}

def dogrula(node_input: dict) -> dict:
    if node_input["oncelik"] not in {"P1", "P2", "P3"}:
        raise ValueError("Öncelik P1, P2 veya P3 olmalı")
    return {**node_input, "durum": "incelenecek"}

def jsona_cevir(node_input: dict) -> str:
    return json.dumps(node_input, ensure_ascii=False)

akış = Workflow(
    name="erisilebilirlik_triage",
    edges=[(START, ayristir, dogrula, jsona_cevir)],
)

async def main():
    runner = InMemoryRunner(node=akış)
    await runner.session_service.create_session(
        app_name=runner.app_name,
        user_id="yerel-kullanici",
        session_id="yerel-oturum",
    )
    mesaj = types.Content(
        role="user",
        parts=[types.Part(
            text="P1 | Form etiketi yok | /kayit"
        )],
    )
    async for olay in runner.run_async(
        user_id="yerel-kullanici",
        session_id="yerel-oturum",
        new_message=mesaj,
    ):
        if olay.output is not None:
            print(olay.output)
    await runner.close()

asyncio.run(main())

Bu kodu triage.py olarak kaydedip uv run python triage.py komutuyla çalıştırın. Testte üç çıktı görüldü: ayrıştırılmış sözlük, durum: incelenecek eklenmiş doğrulanmış sözlük ve son JSON. İşlem çıkış kodu 0’dı. P4 girilirse akış kasıtlı olarak hata verir; sessizce yanlış öncelik üretmez.

Modeli nereye eklemeli?

Gerçek uçtan uca senaryoda doğrulamadan sonra bir Agent düğümü eklenebilir: ajan bulguyu WCAG başarı ölçütleriyle eşleştirir ve kısa düzeltme önerisi yazar. Ardından başka bir işlev, çıktının zorunlu alanlarını doğrular. Issue oluşturma veya e-posta gönderme son düğüm olmamalı; önce kullanıcı onayı isteyen bir kesinti eklenmeli. Modelin hata kaydını yeniden yazmasına izin verilebilir, öncelik ve hedef depo gibi yetki alanlarını değiştirmesine verilmemelidir.

ADK Web arayüzü ve erişilebilirlik

adk web uygulamalar komutu yerel geliştirme arayüzünü açar. Üst çubukta yan panel düğmesi, uygulama seçici, oturum seçici, tema ve kullanıcı menüsü bulunur. Testte triage_app seçiliydi. Orta alanda Info, State, Artifacts ve Evals sekmeleri; altında Events/Traces seçimi, Filter, yenileme ve seçenekler yer aldı. Alt bölümde “Type a message…” etiketli metin alanı, ekleme, çağrı ve gönderme denetimleri vardı.

Girdi gönderilince grafik START → ayristir → dogrula → jsona_cevir → END akışını gösterdi. Sohbet bölümünde kullanıcı girdisi, her işlevin yapılandırılmış çıktısı ve son JSON ayrı olaylar halinde sunuldu. Önceki/sonraki olay düğmeleriyle adımlar gezilebiliyor. Bu, hatanın hangi düğümde oluştuğunu bulmayı kolaylaştırıyor.

DOM incelemesinde sekmeler uygun tab rolleri taşıyordu; yan panel, kullanıcı menüsü ve olay gezinme düğümlerinin erişilebilir adları vardı. Bazı yalnız simgeli araç çubuğu düğmelerinde ise açık bir aria-label görünmedi; simge metnine güvenmek ekran okuyucuda belirsizlik yaratabilir. Klavye odağının görünürlüğü ve ok tuşlarıyla sekme davranışı ayrıca elle sınanmalı. Bu bir tam WCAG denetimi değildir.

320×800 piksel başlıksız Chrome testinde belge genişliği 320 pikselde kaldı ve yatay taşma oluşmadı. Dar görünümde çok panelli arayüzün hangi bölmeleri gizlediğini klavye ve ekran okuyucuyla ayrıca doğrulamak gerekir. ADK Web geliştirme aracıdır; son kullanıcı arayüzü olarak doğrudan yayımlamak yerine kendi erişilebilir ön yüzünüzü oluşturun.

Yerel sunucu günlüğünde ADK Web’in prism-dark.css dosyasını isterken 404 aldığı da görüldü. Açık tema ve Workflow çıktısı çalışmaya devam etti; yine de koyu tema kod renklendirmesi bu kurulumda eksik varlık riski taşıyor. Üretim benzeri bir arayüz incelemesinde tarayıcı ağ hatalarını ayrıca kontrol edin.

İzinler, gözlemlenebilirlik ve hata kurtarma

İzinleri düğüm bazında düşünün. Salt-okunur araçlarla başlayan akış, dosya yazma veya harici API çağrısı yapacaksa ayrı kimlik bilgisi kullanmalı. Araç girdileri Pydantic/JSON şemasıyla doğrulanmalı; ağ alan adları, dosya yolları ve azami tutarlar kod içinde sınırlandırılmalı. MCP veya üçüncü taraf eklentisi eklemek, o bileşenin lisansını ve izinlerini ayrıca incelemeyi gerektirir.

Runner olayları ve oturum durumu yerelde bellekte, SQLite’ta veya seçilen bulut hizmetinde tutulabilir. ADK OpenTelemetry ile iz sürmeyi destekler. Üretim kaydında düğüm adı, süre, hata türü, model ve token sayısı yararlıdır; tam istem, kişisel veri, erişim anahtarı ve araç çıktısı varsayılan olarak kaydedilmemelidir.

Yeniden deneme yalnız geçici ağ hatalarına uygulanmalı. Şema hatası aynı girdiyi üç kez modele göndermekle düzelmez. Workflow düğümlerine zaman aşımı ve sınırlı retry ekleyin; paralel dallarda max_concurrency ile maliyeti sınırlayın. İnsan onayından sonra devam eden akışlarda oturum geçmişinin kalıcılığını ve sürüm göçünü test edin.

Maliyet, gizlilik ve platform sınırları

ADK kütüphanesi ve yerel işlev akışımız ücretsizdi. Maliyet; bağlanan model, Vertex AI, veri tabanı, izleme, depolama ve ağ kullanımından gelir. Gemini Developer API’nin ücretsiz ve ücretli katmanları modele göre değişir; fiyatı Google’ın güncel sayfasından kontrol edin. OpenAI veya Anthropic gibi başka sağlayıcı kullanılırsa onların ücret ve veri koşulları geçerlidir.

Yerel çalıştırma verinin otomatik olarak cihazdan çıkmayacağı anlamına gelmez: bir LLM düğümü girdiyi sağlayıcıya gönderebilir, OpenTelemetry dış toplayıcıya aktarabilir, araçlar üçüncü taraf API çağırabilir. Veri konumu; ADK’dan çok seçilen model, oturum servisi ve dağıtım bölgesiyle belirlenir. Hassas içerikte veri akış şeması çıkarın ve her dış bağlantıyı belgeleyin.

Alternatiflerle karşılaştırma

LangGraph de grafik, durum ve insan onayı sunar; Python ekosisteminde olgun bir alternatiftir. CrewAI rol tabanlı ajan takımları ve hazır süreç anlatımında daha doğrudan olabilir. AutoGen çoklu ajan konuşmalarına odaklanır. n8n, Dify ve Flowise görsel kurulum isteyen ekipleri daha hızlı başlatır. ADK 2’nin öne çıkan yanı, model düğümleriyle sıradan Python işlevlerini aynı doğrulanan Workflow grafiğinde birleştirmesidir. Buna karşılık hızlı API değişimi ve Google belgelerinin Gemini/Cloud yönelimi ek bakım ister.

Sınırlamalar ve sorun giderme

• START içe aktarımı hata verirse 2.6.3’te google.adk.workflow yolunu kullanın; ana paket bunu doğrudan dışa aktarmıyor.
• SessionNotFoundError görülürse Runner’dan önce oturumu açıkça oluşturun.
• Web UI ajanı bulamazsa klasörde __init__.py ve agent.py bulunduğunu, kök nesnenin root_agent adını taşıdığını denetleyin.
• 1.x oturumlarını yükseltirken önce kopya veride göç testi yapın; eski istemciyle geri dönüş varsaymayın.
• Paralel dalların birden fazla terminal çıktısı varsa JoinNode ile tek sonuçta birleştirin.
• Arayüz yalnız geliştirme amaçlıdır; kimlik doğrulaması olmadan genel ağa açmayın.

Kaynaklar

• Google ADK Python deposu — README, kod, issue ve bakım durumu.
• ADK v2.6.3 sürüm notları — 7 Ağustos 2026.
• ADK 2.0 genel kullanım duyurusu — 19 Mayıs 2026.
• Apache 2.0 lisansı.
• Workflow mimarisi.
• Function Node kılavuzu.
• Resmî Python başlangıç kılavuzu.
• ADK gözlemlenebilirlik belgesi.
• Gemini Developer API fiyatları.

Test notu: Google ADK 2.6.3 kurulumu, anahtarsız Workflow çalıştırması, yerel ADK Web akışı ve 320 piksel taşma kontrolü 9 Ağustos 2026’da macOS üzerinde geçici dizinde yapıldı. Bir LLM sağlayıcısı, harici araç, bulut dağıtımı veya kalıcı üretim veritabanı çalıştırılmadı.