Ajan ve MCP rehberleri · 2026-05-26

Gemini Interactions API nedir? generateContent'ten agent state'e geçiş

Gemini Interactions API ile generateContent farkını, previous_interaction_id, store, background, webhook_config, steps ve LLM gateway mimarisindeki karar noktalarını öğrenin.

Gemini Interactions API akışında generateContent, previous_interaction_id, background job, webhook, steps ve LLMTR gateway ölçüm katmanını gösteren diyagram.

Gemini Interactions API neyi değiştirir?

Gemini Interactions API, tek seferlik prompt-yanıt mantığından daha stateful bir etkileşim modeline geçişi temsil eder. Uygulama yalnızca modele metin göndermek yerine, etkileşimin adımlarını, önceki interaction kimliğini ve uzun sürebilecek görevlerin durumunu da yönetir.

Bu yüzey, her iş için zorunlu değildir. Kısa sınıflandırma, özetleme veya basit chat akışı için mevcut chat/completions veya generateContent benzeri çağrılar daha sade kalabilir. Interactions API ise çok adımlı agent, tool kullanımı ve background yürütme ihtiyacı doğduğunda anlam kazanır.

generateContent ile temel fark

generateContent tarzı çağrıda bağlamın önemli kısmı client tarafında taşınır: konuşma geçmişi, tool çıktıları ve retry davranışı uygulama kodunda toparlanır. Interactions API tarafında ise `previous_interaction_id` ile önceki etkileşime bağlanmak, `steps` üzerinden ara çıktıları okumak ve `store` davranışını bilinçli seçmek gerekir.

Bu ayrım mimari bir karardır. Stateless çağrı daha şeffaf ve taşınabilirdir; stateful interaction ise uzun görevlerde daha az orchestration kodu ve daha iyi ara adım gözlemi sağlayabilir.

  • `previous_interaction_id`: takip çağrısının hangi interaction üzerinden süreceğini belirtir.
  • `store`: etkileşim state'inin provider tarafında tutulup tutulmayacağını etkiler.
  • `steps`: model çıktısı, function call veya action gerektiren ara durumları ayrıştırır.
  • `usage`: text, thought ve tool kullanım tokenlarını ayrı izlemeyi gerektirir.

Background job ve webhook kararı

Agent ve araştırma görevleri bazen standart HTTP isteği süresini aşar. Interactions API'de `background` ve `webhook_config` gibi alanlar, istemcinin beklemeden işi başlatması ve sonuç hazır olduğunda bildirim alması için tasarlanır.

Üretim sisteminde bu, yeni bir durum makinesi anlamına gelir. Kullanıcıya bekleyen görev gösterimi, duplicate webhook koruması, idempotency, timeout politikası ve kısmi hata mesajları planlanmalıdır.

  • Uzun süren görevlerde kullanıcıya pending/running/completed/failed durumu gösterin.
  • Webhook event'lerini imza doğrulama, idempotency ve retry toleransıyla işleyin.
  • Background görev sonucunu doğru kullanıcı hesabı ve erişim sınırıyla eşleştirin.

Managed Agents ile karıştırılmaması gereken sınır

Managed Agents, Interactions API üzerinde çalışan bir runtime ve orchestration katmanı olarak düşünülmelidir. Model katalogunda görünen Gemini modeli, fiyat ve yetenek bilgisini anlatır; managed agent ise bu modeli araç, sandbox, dosya state'i ve takip çağrılarıyla çalıştıran daha geniş bir yürütme yüzeyidir.

Bu yüzden maliyet hesabı yalnızca input ve output tokenlarından oluşmayabilir. Thought token, tool use token, tekrar deneme, background çalışma ve agent ortamının sınırları ayrıca izlenmelidir.

LLMTR açısından üretim mimarisi

LLMTR gibi çoklu sağlayıcı gateway katmanında Interactions API doğrudan birebir proxy kararı değildir. Önce hangi işlerin OpenAI uyumlu chat yüzeyinde kalacağı, hangi işlerin provider-native agent API'sine gideceği ve kullanıcıya hangi capability bilgisinin gösterileceği ayrılmalıdır.

Doğru sınır, API key, harcama limiti, kullanım ölçümü ve güvenli hata formatıyla birlikte çizilir. Provider key'leri frontend'e taşınmamalı ve her agent runtime için açık maliyet/metrik politikası olmalıdır.

Gemini Interactions API kullanım kararını verme

Bir Gemini entegrasyonunda stateless model çağrısı, stateful interaction ve managed agent seçeneklerini üretim gereksinimine göre ayırın.

  1. Görevin state ihtiyacını belirleyin. Tek yanıtla bitecek sınıflandırma ve özetleme işlerini, takip çağrısı veya dosya state'i gerektiren agent görevlerinden ayırın.
  2. Interaction alanlarını seçin. `previous_interaction_id`, `store`, `background`, `webhook_config` ve `steps` alanlarını yalnızca görev gerçekten gerektiriyorsa tasarıma alın.
  3. Gateway ölçümünü bağlayın. Token, thought token, tool kullanımı, retry ve latency metriklerini kullanıcı akışı ve API key sınırlarıyla birlikte kaydedin.
  4. Güvenlik sınırlarını kapatın. Provider key'i server-side tutun, prompt veri politikasını netleştirin ve webhook işleme katmanını idempotent yapın.

Sık sorulan sorular

Gemini Interactions API chat completions yerine mi geçer?

Hayır. Kısa ve stateless işler için chat/completions veya generateContent tarzı çağrılar daha sade olabilir. Interactions API, state, background görev, tool kullanımı veya managed agent ihtiyacı olduğunda değerlendirilmelidir.

previous_interaction_id kullanmak prompt saklamak anlamına gelir mi?

Provider tarafındaki state davranışı `store` ve ilgili API politikalarıyla birlikte değerlendirilmelidir. LLMTR tarafındaki veri politikası model ve yasal metinlerde kontrol edilmelidir.

Background agent görevlerinde maliyet nasıl izlenmeli?

İlk istek, takip çağrıları, tool kullanımı, thought tokenları, retry ve webhook sonucu aynı kullanıcı akışıyla ilişkilendirilmelidir. Yalnızca son yanıt tokenına bakmak gerçek maliyeti eksik gösterir.

İlgili yazılar