Gemini Decisions API ile Yapay Zeka Ajanı Görevleri Nasıl Yönlendirilir?

Özet

Yapay zekâ ajan görevlerini Gemini Decisions API ile yönlendirmek için görevin başlığını ve açıklamasını üç soruyla birlikte gemini-decision-1 modeline gönderin: Görevi hangi Ajanın devralacağını belirleyen bir choice, zorluğunu ölçen bir score ve önce bir insanın karar vermesi gerekip gerekmediğini denetleyen bir noul. Güven skoru belirlediğiniz eşiği aştığında atamayı otomatik yapın. Geriye kalan her şeyi bir insanın incelemesine bırakın.

Giriş

Birden fazla kodlama ajanı çalıştıran her ekip eninde sonunda aynı angaryayla karşılaşır: Birinin gelen her yeni görevi okuyup kimin devralacağına karar vermesi gerekir. Backend Ajanı mı yoksa frontend Ajanı mı? Ekonomik model mi yoksa güçlü olan mı? Başlamaya hazır mı, yoksa hâlâ alınması gereken bir karar mı var?

Google, 11 Kasım 2026'da tam da bu angarya için özel olarak geliştirilmiş bir araç yayımladı. Gemini Decisions API, metin üretmek yerine kapalı uçlu soruları kalibre edilmiş olasılıklarla yanıtlıyor. Google bu aracı Gemini Notebook içinde her sorguyu doğru model katmanına ve düşünme (thinking) düzeyine yönlendirmek için kullanıyor ve bunun günlük sorgulardaki gecikmeyi %40'a varan oranda azalttığını belirtiyor.

Bu yazıda bir ajan panosu için aynı yönlendiriciyi kuruyoruz: görev başına tek bir çağrı, üç soru, tek bir eşik değeri ve yönlendiricinin emin olamadığı durumlarda görevi sorunsuzca bir insana devretme mantığı. Üzerinde denemeler yapabileceğiniz bir pano arıyorsanız Sharkly platformuna ücretsiz başlayabilirsiniz. Yönlendirme politikasının kendisi (hangi görevlerin güçlü modeli hak ettiği) için öncelikle ajan görevlerini zorluğa göre yönlendirme yazısını okuyun. Bu yazı ise doğrudan bu politikayı uygulayan çağrıyı konu alıyor.

Gemini Decisions API ne işe yarar?

Gemini Decisions API, ortak bir girdiye dayalı olarak tiplendirilmiş soruları değerlendiren ve her biri için bir olasılık ile güven skoru döndüren bir uç noktadır (endpoint). Hiçbir metin üretmez; dolayısıyla çıktı belirteçleri (output tokens) her zaman sıfırdır. Kodunuz, herhangi bir ayrıştırma (parsing) adımına ihtiyaç duymadan doğrudan bu sayılara göre dallanır.

Yönlendirme için üç soru tipi kullanılır:

Tek bir istek, aynı girdiye yönelik 1.000 adede kadar soru içerebilir. Decisions API belgelerine göre sorular tek bir ileri geçişte (forward pass) çalışır ve birbirini göremez; bu nedenle yeni bir soru eklemek diğer yanıtları değiştirmez. Google, uçtan uca gecikme süresinin 150 ila 250 ms arasında olduğunu ve 1'den 100 soruya kadar neredeyse hiç değişmediğini belirtiyor.

Kodlama ajanlarının üzerindeki karar modelleri ve Jev hakkındaki yazımızı okuduysanız bu yapı size tanıdık gelecektir. Buradaki fark pratiktir: Google tarafından barındırılan bir model, açıkça tanımlanmış üç soru ve bir panoya yapılan bağlantı.

Yönlendirme çağrısı: Görev başına üç soru

İşte yönlendirici. Çalışması için google-genai 3.2 veya daha yeni bir sürüm ile Google AI Studio üzerinden alınmış bir GEMINI_API_KEY gerekir.

import json
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

AGENTS = {
    "backend": "Server code, APIs, database migrations, and backend tests.",
    "frontend": "UI components, styling, client state, and frontend tests.",
    "docs": "README files, docs pages, and changelogs. No code changes.",
    "other": "Work that fits none of the options above.",
}

DIFFICULTY = [
    "Trivial: one file, obvious change, no design decision.",
    "Routine: a few files, follows a pattern already in the repo.",
    "Involved: several modules or a new pattern, needs new tests.",
    "Hard: cross-cutting, touches auth or data migrations, or the spec is thin.",
]

def ask(task):
    state = json.dumps({
        "title": task["title"],
        "description": task["description"][:8000],
    })
    result = client.decisions.create(
        model="gemini-decision-1",
        input=state,
        questions={
            "agent": {
                "type": "choice",
                "instructions": "Which agent should take the task in `title` and `description`?",
                "criteria": AGENTS,
            },
            "difficulty": {
                "type": "score",
                "instructions": "How hard is this task for a coding agent working alone?",
                "criteria": DIFFICULTY,
            },
            "needs_human": {
                "type": "noul",
                "instructions": "Does a person need to make a decision before any agent starts?",
                "criteria": {
                    "true_description": "The spec is ambiguous, contradicts itself, or asks for a product, security, or pricing call.",
                    "false_description": "The spec is clear enough to implement as written.",
                },
            },
        },
    )
    return result.answers

Bu koddaki dört ayrıntı doğrudan resmi belgelerden alınmıştır ve kolayca gözden kaçabilir.

Model anahtarlarınızı asla görmez. Yalnızca instructions ve criteria alanlarını okur; bu yüzden sorunun tamamını instructions kısmına yazın ve her seçeneği ayrıntılı biçimde açıklayın.

Seçenek anahtarları alfabetik olarak sıralanır. API, puanlamadan önce seçim anahtarlarını UTF-8 bayt sırasına göre dizer. Kapsayıcı seçeneğin, gerçek seçeneklerin önüne geçecek olan none_of_the_above yerine other olarak adlandırılmasının nedeni budur.

Puan seviyeleri doğrusal olmalıdır. Dönen score değeri, seviye dizinlerinin olasılık ağırlıklı ortalamasıdır (buradaki örnekte 0 ila 3). Birbirine komşu seviyelerin net biçimde ayrışmasını sağlayın.

Yalnızca soruların ihtiyaç duyduğu bilgileri gönderin. Belgelerde konuyla ilgisi olmayan içeriğin doğruluğu düşürdüğü belirtiliyor. Görev başlığı ve açıklaması genellikle tüm yorum geçmişini göndermekten çok daha iyi sonuç verir.

Güven eşiğini kendi görevlerinize göre belirleyin

Yanıt değeri ne yapmanız gerektiğini söyler. Güven (confidence) ise bunu danışmadan yapıp yapamayacağınızı belirtir. Bir choice yanıtında güven skoru, en yüksek olasılığa sahip seçeneğin olasılığına eşittir. Bir noul için ise max(noul, 1 - noul) formülüyle hesaplanır.

İşte karar katmanı:

AUTO = 0.75      # assign without a person above this
HARD = 2.4       # difficulty score that earns the strong-model Agent

def decide(a):
    if a["needs_human"].noul >= 0.5:
        return ("human", "needs a decision first")
    if a["agent"].choice == "other" or a["agent"].confidence < AUTO:
        return ("human", f"router unsure ({a['agent'].confidence:.2f})")
    tier = "strong" if a["difficulty"].score >= HARD else "default"
    return (f"{a['agent'].choice}-{tier}", "auto")

0,75 değerini körü körüne kopyalamayın. Google, eşik değerlerinin kendi trafiğinizden etiketlenmiş örneklerle belirlenmesini öneriyor. Son tamamlanan 50 ila 100 görevi çekin, her birini hangi Ajanın tamamladığını not edin ve bunları ask() fonksiyonundan geçirin. Otomatik yönlendirilen görevlerin ekibinizin yaptığı tercihlerle eşleştiği en düşük eşik değerini seçin. Hatalı bir otomatik yönlendirmenin bedeli başarısız bir çalıştırma ve yeniden atamadır; gereksiz yere bir insana bekletmenin bedeli ise birkaç dakikadır. Yuvarlak bir sayıya takılmak yerine bu iki maliyeti birbiriyle tartın.

İki kritik tuzak var: Birincisi, noul olasılığı asla 0,99'un üzerine çıkmaz; bu nedenle > 0.99 gibi bir denetim hiçbir zaman tetiklenmez. İkincisi, 1,5 değerindeki bir score, "1. ve 2. seviyeler arasında eşit kalındığı" veya "dört seviyenin tümü konusunda kararsız olunduğu" anlamına gelebilir. Durumun kritik olduğu anlarda probabilities değerini de mutlaka kontrol edin.

Yönlendiriciyi bir Sharkly panosuna bağlama

Yönlendirici yalın Python kodundan oluştuğu için her yerde çalışabilir. Bir Sharkly panosunda en temiz tetikleyici, bir görevin üzerinde çalışılmaya hazır hale geldiği andır.

1. Her kulvar ve katman için bir Ajan oluşturun. Örneğin backend-default, backend-strong, frontend-default. Sharkly Agents belgelerine göre her Ajan varsayılan olarak kendi Runtime modelini izler; Model satırı ise o Runtime kataloğundan başka bir model seçmenize olanak tanır. Zorluğun bir model seçimine dönüştüğü yer tam olarak burasıdır.

2. Kararı sharkly CLI ile uygulayın.

import subprocess

def apply(task_id, target, reason, a):
    note = (f"Router: agent={a['agent'].choice} ({a['agent'].confidence:.2f}), "
            f"difficulty={a['difficulty'].score:.1f}, "
            f"needs_human={a['needs_human'].noul:.2f}")
    if target == "human":
        subprocess.run(["sharkly", "task", "comment", task_id,
                        "--body", f"{note}. Held for a person: {reason}."], check=True)
        return
    subprocess.run(["sharkly", "task", "edit", task_id,
                    "--delegate-agent", target], check=True)
    subprocess.run(["sharkly", "task", "comment", task_id, "--body", note], check=True)

Görev hazır durumundayken bir Ajan atamak, o ajanın çalışmasını başlatır. Olasılıkları bir yorum olarak kaydetmek göründüğünden çok daha önemlidir: Bir ay sonra yönlendiriciyi denetleyebilmenizin yolu budur.

3. Durum değişikliğinde tetikleyin. Bir Sharkly Automation (Otomasyonu); talimatları, atanan Ajanı ve tetikleyicileri barındırır. Küçük bir Yönlendirici Ajanına "seni tetikleyen görev üzerinde route.py dosyasını çalıştır" talimatını verin, ardından ekibinizin "hazır" için kullandığı duruma yönelik bir görev durumu tetikleyicisi ekleyin. Görev durumu tetikleyicisiyle başlatılan çalıştırmalar o göreve geri bağlanır; böylece yönlendirme kaydı doğrudan işin kendisinde saklanır. CLI üzerinden:

sharkly automation trigger create <automation-id> --kind task_event --to-status "Ready"

Bir yönlendirme çağrısının maliyeti nedir?

Google'ın duyuru yazısına göre Gemini Decision 1, 1 milyon girdi belirteci (input token) başına 0,10 dolar ücretlendirilirken çıktı belirteçleri için 0 dolar alıyor. Kaç soru sorarsanız sorun, ortak girdi istek başına yalnızca bir kez faturalandırılır.

Yönlendirici, tek bir görevde tek bir ajanın çalışmasından bile daha ucuza mal olur. Google ayrıca prototipleme için AI Studio'da ücretsiz bir katman da sunuyor.

Güvenmeden önce bilmeniz gereken kısıtlamalar

API, Gemini Developer API üzerinde v1beta olarak sunuluyor; Google Cloud'daki Gemini desteği ise "yakında" olarak listelenmiş durumda. Belgelerde bağlam önbelleğe alma (context caching), Batch API veya Flex ve Priority çıkarımının (inference) desteklenmediği belirtiliyor; bu nedenle tekrarlanan girdiler her seferinde eksiksiz olarak hesaba katılır. Katmanlara göre hız limitleri (rate limits) Google'ın hız sınırları sayfasında yer alıyor; her görevi tek bir anahtar üzerinden yönlendirmeden önce kendi limitlerinizi kontrol edin.

Görev açıklamalarını güvenilmeyen girdi olarak değerlendirin. Belgeler, kullanıcı tarafından sağlanan metinlerin kendi sınıflandırmasını manipüle etmeye çalışabileceği konusunda uyarıyor. Ekibiniz dışından herhangi biri görev oluşturabiliyorsa yönlendirici ne derse desin kimlik doğrulama (auth), ödemeler veya canlı ortam (production) verilerine dokunan her şeyi insan onayında tutun.

Google'ın kıyaslama (benchmark) iddiaları (ürün ailesindeki en düşük kalibrasyon hatası, Interactions API üzerinden Gemini 3.5 Flash-Lite modeline kıyasla neredeyse 5 kat daha ucuz olması) Google'ın kendi verileridir. Asıl önemli olan kıstas, kendi etiketlediğiniz görevlerdir.

Yönlendirme çağrısının yanlış araç olduğu durumlar

Görevler bir insanın inceleyebileceğinden daha hızlı geldiğinde ve seçenekler sabit olduğunda Decisions çağrısı kullanın: belirli bir Ajan kümesi, belirli katmanlar, evet/hayır kararı gibi. Zaten bir etiketle karar verilebiliyorsa basit bir kural kullanın. docs etiketi taşıyan her görev dokümantasyon Ajanına gidiyorsa, bir if koşulu hem daha ucuzdur hem de asla yanılmaz.

Yönlendiricinin kararını uzun uzadıya açıklamasına, teknik şartnameyi yeniden yazmasına veya görevi alt görevlere bölmesine ihtiyaç duyuyorsanız üretken (generative) bir model kullanın. Decisions API metin değil, sayılar döndürür. İşi birden çok rol arasında paylaştırmak için liderin hedefi parçalara ayırdığı bir Ekip (Crew) daha uygundur; ayrıntılar için ajan Ekipleri (Crews) için model yönlendirme yazısına bakın.

Sonuç

Yönlendirme, kapalı küme (closed-set) bir karardır ve Gemini Decisions API kapalı küme kararlar için inşa edilmiştir: tek bir çağrı, tiplendirilmiş yanıtlar, eşik uygulayabileceğiniz bir güven skoru ve sentin kesirleriyle ölçülen bir maliyet. Geriye kalan iş ise size ait: net seçenek açıklamaları yazmak, eşik değerini kendi tamamlanmış görevleriniz üzerinde kalibre etmek ve düşük güvene sahip durumları bir insana iletmek.

Tek bir kulvarla başlayın. Yeni backend görevlerini bir hafta boyunca yönlendirin, yönlendiricinin seçimlerini ekibinizin yapacağı tercihlerle karşılaştırın ve ardından kapsamı genişletin. Yönlendiriciyi Ajanların, Otomasyonların ve insan incelemesinin tek bir yerde toplandığı gerçek bir pano üzerinde çalıştırmak için Sharkly ile kullanmaya başlayın.

Sıkça Sorulan Sorular (SSS)

Gemini Decisions API nedir?

11 Kasım 2026'da kullanıma sunulan ve metin, görsel, ses, video veya PDF'ler hakkındaki evet/hayır, çoktan seçmeli (choice) ve puanlama (score) sorularını yanıtlayan bir Gemini API uç noktasıdır. gemini-decision-1 modelini kullanarak metin üretmek yerine kalibre edilmiş olasılıklar ve güven skorları döndürür.

Gemini Decision 1'in maliyeti nedir?

Google, 1 milyon girdi belirteci başına 0,10 dolar ve çıktı belirteçleri için 0 dolar listeliyor; ortak girdi istek başına bir kez faturalandırılıyor. Prototipleme için Google AI Studio'da ücretsiz bir katman mevcuttur.

Bir istekte kaç soru sorulabilir?

Girdi ve tüm sorular genelinde 262.144 belirteçlik bağlam penceresiyle sınırlı olmak üzere 1 ila 1.000 soru sorulabilir. Seçim (choice) soruları 2 ila 255 seçenek alabilir.

Yönlendirme için hangi güven eşiğini kullanmalıyım?

Herkes için geçerli tek bir sayı yoktur. Google, eşik değerlerinin kendi trafiğinizdeki etiketlenmiş örneklerden yola çıkılarak belirlenmesini önerir. Tamamlanmış 50 ila 100 görevi yeniden test edin ve otomatik seçimlerin ekibinizin tercihleriyle örtüştüğü eşiği belirleyin.

Decisions API bir ajanın hangi modeli kullanacağını seçebilir mi?

Dolaylı yoldan evet. Zorluk derecesi için bir score sorusu sorun, ardından yüksek puanları daha güçlü bir modelle yapılandırılmış bir Ajana eşleyin. Sharkly'de her Ajan, kendi Runtime kataloğundaki bir modele ayarlanabilir.

Gemini Decisions API, Vertex AI üzerinde mevcut mu?

Henüz değil. Google'ın duyuru yazısında Google Cloud'daki Gemini desteğinin yakında geleceği belirtiliyor. Günümüzde Gemini Developer API üzerinde v1beta olarak çalışmaktadır.