Gemini 3.8 Flash ile Fonksiyon Çağırma: call_id, Yinelemeli Araç Döngüleri ve Nasıl Test Edilir

Gemini 3.8 Flash'ta İşlev Çağırma: Interactions API ve Araç Döngüleri

Gemini 3.8 Flash, 2 Eylül 2026'da piyasaya sürüldü. Google modeli, zor görevlerde tek seferde her şeyi tahmin etmek yerine araçları iteratif olarak çağıracak, sonuçları kontrol edecek ve gerektiğinde yeni çağrılar yapacak şekilde geliştirdi. Bu, aracılar için iyi haber; Gemini 3.7 Flash için yazılmış araç döngülerini taşıyan ekipler içinse yeni bir baş ağrısı demek. En önemli iki API detayı şunlar: Her işlev sonucu hem call_id hem de name içermeli ve generateContent yerine Interactions API, döngüyü çalıştırmanın birincil yolu olarak kullanılmalı.

Apidog'u bugün deneyin

Bu kılavuzda Interactions API ile iki turlu tam akışı, eski generateContent eşdeğerini, Gemini 3.8 Flash'ın neden daha fazla araç çağrısı ve jeton kullandığını ve her gün çalıştırabileceğiniz bir test düzenini ele alacağız. Modelin genel görünümüne ihtiyacınız varsa Gemini 3.8 Flash nedir? ile başlayabilirsiniz. Alan adları Google'ın işlev çağırma belgelerinden alınmıştır.

Buradaki tüm istekler, JSON içeren düz HTTP istekleridir. Bu nedenle uygulama koduna geçmeden önce akışı Apidog içinde oluşturup hata ayıklayabilirsiniz.

Gemini 3.8 Flash'ta işlev çağırma: hızlı bakış

Öğe	Değer
Model kimliği	gemini-3.8-flash
Birincil API	Interactions API (POST /v1beta/interactions)
Eski API	generateContent; sonlandırma tarihi olmadan desteklenmeye devam ediyor
Araç bildirimi	tools: [{"type": "function", "name", "description", "parameters"}]
Model çağrısı	id, name, arguments alanlarına sahip function_call adımı
Yanıtınız	call_id + name ve previous_interaction_id ile function_result
Düşünme seviyeleri	low, medium (varsayılan), high
Araç kullanım puanı	Tau3-Banking: %45; Gemini 3.7 Flash'a göre +12 puan
Jeton kullanımı	Artificial Analysis indeksinde görev başına yaklaşık 48 bin çıkış jetonu; %30 daha fazla
Fiyat	31 Aralık 2026'ya kadar 1 milyon jeton başına 0,75 dolar giriş / 3,75 dolar çıkış

1. Aracı bildirin

Interactions API'de bir araç; function tipi, araç adı, açıklama ve parameters altında bir JSON Şeması içeren düz bir nesnedir.

Açıklamayı mümkün olduğunca spesifik yazın:

• İyi: “Bir siparişin mevcut gönderim durumunu kimliğine göre arayın.”
• Zayıf: “Sipariş yardımcısı.”

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL]GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

Burada iki seçim bilinçlidir:

• Tek adımlı bir arama için thinking_level: "low" yeterlidir. Ne zaman yükseltme yapacağınızı düşünme seviyeleri kılavuzundan öğrenebilirsiniz.
• temperature belirtilmemiştir. Google'ın Gemini 3 rehberliği, varsayılan 1.0 değerinin korunmasını önerir; daha düşük değerler araç döngülerinde sorun çıkarabilir.

2. function_call adımını okuyun

Interactions API tek bir mesaj yerine etkileşimin id değerini ve yürütme adımlarını döndürür. Bu adımlar düşünme bloklarını, araç çağrılarını ve son yanıtı içerebilir.

Model bir araca ihtiyaç duyduğunda yanıt, model_output yerine function_call adımı içerir:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {
    "order_id": "A1029"
  }
}

Üç alanın tamamı önemlidir:

• id: Sonraki turda call_id olarak geri gönderilir.
• name: Çalıştırılacak işlevi belirtir ve yanıtta tekrar gönderilmelidir.
• arguments: Ayrıştırılmış JSON'dır. Aracı çalıştırmadan önce kendi doğrulamanızı yapın; model, örneğin sipariş kimliklerinizin beş karakter olması gerektiğini bilemez.

Yanıtın başındaki etkileşim id değerini de saklayın. Bir sonraki istekte bu değer previous_interaction_id olur.

3. Sonucu call_id ve name ile döndürün

İşlevi çalıştırdıktan sonra function_result içeren ikinci bir istek gönderin. Gemini 3.8 Flash'ta hem call_id hem de name zorunludur.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [
        {
          "type": "text",
          "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"
        }
      ]
    }]
  }'

result, içerik parçalarından oluşan bir listedir. Buradaki metin bölümü JSON sonucunu dize olarak taşır.

previous_interaction_id önceki tura işaret ettiği için sunucu; ilk istemi, araç bildirimini ve modelin muhakemesini zaten bilir. Bunları yeniden göndermeniz gerekmez.

İkinci yanıtı da adım listesi olarak ele alın:

• Liste model_output ile bitiyorsa işlem tamamlanmıştır.
• interaction.output_text üzerinden nihai metni alabilirsiniz.
• Yeni bir function_call varsa aynı döngüye geri dönün.

Python SDK'de aynı akış şu şekildedir:

client.interactions.create(
    model="gemini-3.8-flash",
    input=...,
    tools=...
)

Ardından previous_interaction_id ve function_result listesini input olarak kullanan ikinci bir create çağrısı yapılır. Uç noktanın kurulumu, API anahtarı ve jeton kullanımı için Gemini 3.8 Flash API nasıl kullanılır? kılavuzuna bakabilirsiniz.

Eski generateContent eşdeğeri

Mevcut Gemini uygulamalarının çoğu hâlâ models/gemini-3.8-flash:generateContent çağırıyor. Google bu API'yi eski olarak tanımlasa da herhangi bir sonlandırma tarihi olmadan tam olarak desteklemeye devam ediyor.

Kavramlar farklı adlandırılsa da sözleşme aynıdır:

• Araçlar functionDeclarations altında bildirilir.
• Model functionCall parçasıyla yanıt verir.
• Uygulama functionResponse parçasıyla karşılık verir.
• Çağrının id değeri ve name değeri yanıtta geri gönderilir.

İki pratik fark vardır:

1. generateContent durumsuzdur. Modelin functionCall parçası ve tüm düşünce imzaları dahil olmak üzere tam contents geçmişini her turda kendiniz göndermelisiniz.
2. Düşünme yapılandırması şu alandadır:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "low"
    }
  }
}

Düşünme jetonları usageMetadata.thoughtsTokenCount alanında görünür ve çıkış olarak faturalandırılır.

Yeni bir proje başlatıyorsanız Interactions API'yi tercih edin. Sunucu tarafı durum yönetimi, eksik imza veya call_id içeren geçmişi yeniden gönderme hatalarını azaltır.

3.8 Flash neden daha fazla araç çağrısı yapıyor?

Google'ın lansman yazısına göre model:

• Ek muhakeme adımları yürütür.
• Araçları iteratif olarak çağırır.
• Daha küçük muhakeme adımları atar.
• Süreç boyunca çalışmasını doğrular.

Google ayrıca karmaşık ve uzun görevlerde modelin tasarım gereği daha fazla jeton kullanabileceğini belirtiyor. Artificial Analysis ölçümlerine göre:

• Görev başına yaklaşık 48 bin çıkış jetonu kullanılıyor.
• Gemini 3.7 Flash'a göre %30 daha fazla jeton harcanıyor.
• High seviyesinde görev başına maliyet yaklaşık 0,58 dolar.
• Medium seviyesinde yaklaşık 0,41 dolar.
• Low seviyesinde yaklaşık 0,24 dolar.

Aynı ölçümlerde Tau3-Banking araç kullanımı puanı %45'e çıkmış; bu, 3.7 Flash'a göre 12 puanlık artış demek.

Daha iyi araç kullanımı karşılığında daha uzun süren döngüler alırsınız. Üretimde şu dört sınırı uygulayın:

1. Maksimum dönüş sayısı: Görev başına function_call adımlarını sayın. Basit aramalar için 6–10 dönüş iyi bir başlangıçtır; ajansal kodlama için daha yüksek bir sınır gerekebilir. Limit aşılırsa araçsız son bir dönüş yapın veya hata döndürün.
2. Rota başına thinking_level: Tek adımlı işlemlerde low, çok adımlı görevlerde medium, yalnızca ek doğrulama değerliyse high kullanın. minimal göndermeyin; 3.8 Flash doğrulama hatası döndürür.
3. Zaman aşımı: Hem Gemini isteğine hem de tüm araç döngüsüne zaman aşımı koyun. Artificial Analysis, high seviyesinde ortalama 2,5 dakika, low seviyesinde 0,8 dakika bildirmiştir.
4. İdempotent araçlar: Model aynı aracı yeniden çağırabilir. get_order_status gibi okumalar güvenle tekrarlanabilmeli; geri ödeme ve gönderim gibi yan etkili işlemler onay adımı gerektirmelidir.

Ekstra dönüşlerin maliyeti bütçenizi aşıyorsa 3.7'den 3.8 Flash'a geçiş kılavuzunu inceleyin ve 3.7 Flash'ı bir yapılandırma bayrağının arkasında tutun.

Düşünce imzaları, paralel çağrılar ve yapılandırılmış çıkışlar

Düşünce imzaları

Gemini 3 modelleri muhakeme bloklarına imza ekler.

Depolanan Interactions akışında previous_interaction_id bu süreci sizin için yönetir. store: false kullanıyor veya generateContent çağırıyorsanız düşünce bloklarını ve imzaları her parça türünde alındığı gibi geri göndermelisiniz.

İmzaları:

• Kesip kısaltmayın.
• Yeniden sıralamayın.
• Yeniden serileştirmeyin.
• İçeriğini değiştirmeyin.

Bir imza opaktır; herhangi bir düzenleme onu geçersiz kılabilir. Ayrıntılar için Interactions API belgelerine bakın.

Paralel çağrılar

Yanıt bir liste olduğu için model aynı anda birden fazla bağımsız arama isteyebilir. Gemini 3 modelleri her çağrı için benzersiz kimlik döndürür.

Aynı input dizisinde çağrı başına bir function_result gönderin ve her sonucu kendi call_id değeriyle eşleştirin. Yalnızca name alanına göre eşleştirme yapmayın; aynı işlev için iki farklı çağrının iki farklı call_id değeri olabilir.

Yapılandırılmış çıkışlar

Gemini 3.8 Flash, işlev çağırmayı ve yapılandırılmış çıkışları aynı modelde destekler. Kullanışlı desen şudur:

• Döngü sırasında araçları kullanın.
• Son model_output için bir JSON Şeması tanımlayın.
• Döngüyü makine tarafından okunabilir bir sonuçla kapatın.

Yapılandırma ayrıntıları için Google'ın işlev çağırma ve yapılandırılmış çıkış belgelerine bakın.

Sahte bir araç bildirip arguments alanını kendiniz okumaya çalışmayın. Model çağıracak bir araç olmadığına karar verdiği anda bu yaklaşım bozulur.

Bu yaklaşım, modelin sisteminize bildirilmiş işlevler üzerinden eriştiğini varsayar. Google, Gemini 3.8 Flash için Bilgisayar kullanımı'nı (Önizleme) de listeliyor. Yapılandırılmış bir API'nin ekran sürmeye göre ne zaman daha iyi olduğunu görmek için bilgisayar kullanımı ve yapılandırılmış API'ler karşılaştırmasına bakabilirsiniz.

Apidog'da araç döngüsünü test etme

Bir araç döngüsü genellikle üç noktada bozulur:

1. Araç bildirimi
2. Kimliklerin gidiş-dönüşü
3. Nihai yanıt

Gerçek arka ucunuza dokunmadan üçünü de Apidog'da test edebilirsiniz.

1. Araç arka ucunu taklit edin

GET /orders/{order_id} uç noktasını tanımlayın ve mock sunucuyu açın. Sabit bir yanıt gövdesi kullanın:

{
  "status": "in_transit",
  "eta": "2026-09-05"
}

Böylece her çalıştırmada aynı araç sonucu üretilir ve modelin nihai yanıtındaki değişikliklerin veritabanından değil modelden kaynaklandığını anlayabilirsiniz.

Test ortamında araç takımınız mock URL'ye, üretimde gerçek hizmete yönlendirilebilir.

2. İki dönüşü zincirleyin

GEMINI_API_KEY değerini bir ortam değişkeninde saklayın ve x-goog-api-key başlığında {{GEMINI_API_KEY}} olarak kullanın.

Üç adımlı bir senaryo oluşturun:

• Adım A: /v1beta/interactions adresine, istem ve get_order_status bildirimiyle POST gönderin. Yanıttan etkileşim id değerini, ayrıca function_call adımının id, name ve arguments.order_id alanlarını çıkarın.
• Adım B: {{order_id}} kullanarak mock uç noktasına GET gönderin. Bu adım işlev yürütmesini temsil eder.
• Adım C: function_result içeren ikinci POST isteğini gönderin:
  • call_id: {{call_id}}
  • name: {{tool_name}}
  • previous_interaction_id: {{interaction_id}}
  • result: Adım B'nin gövdesini metin parçası olarak taşıyan liste

3. Beklentileri doğrulayın

• Adım A 200 döndürmeli ve type: "function_call" olan bir adım içermelidir.
• Bu adımın name değeri get_order_status olmalıdır.
• arguments.order_id, A1029 değerine eşit olmalıdır.
• Adım C 200 döndürmeli ve type: "model_output" ile bitmelidir.
• Adım C'nin yanıtında yeni bir function_call bulunmamalıdır.
• Nihai metin in_transit içermelidir. Bu, modelin araç sonucunu kullandığını gösterir.
• Aynı senaryoyu generateContent ile çalıştırıyorsanız usageMetadata.thoughtsTokenCount için thinking_level bazında bir üst sınır belirleyin.

Senaryoyu her gün çalışacak şekilde planlayın. Model davranışı sessiz güncellemelerle değişebilir; geçen hafta tek turda tamamlanan bir döngü bu hafta iki tura ihtiyaç duyabilir.

Çok adımlı doğrulama için Yapay zeka ajanı API test kılavuzuna bakabilir, senaryoyu ücretsiz katmanda oluşturmak için Apidog'u indirebilirsiniz.

Sıkça sorulan sorular

Gemini 3.8 Flash'ta call_id gerekli mi?

Evet. Interactions API'de her function_result hem call_id hem de name içermelidir. generateContent tarafında da functionResponse, çağrının id ve name değerlerini taşımalıdır. Yalnızca adı gönderen eski kod Gemini 3 modellerinde başarısız olur.

Araç döngüm neden 3.7'ye göre daha fazla tur çalışıyor?

Bu davranış tasarıma dahildir. Google, 3.8 Flash'ın araçları iteratif olarak çağırdığını ve karmaşık görevlerde daha fazla jeton kullanabileceğini belirtiyor. Dönüş sayısını sınırlayın ve uygun thinking_level değerini seçin.

İşlev çağırmak için hâlâ generateContent kullanabilir miyim?

Evet. API eski olarak tanımlansa da herhangi bir sonlandırma tarihi olmadan tam olarak desteklenmektedir. Konuşma geçmişini, düşünce imzalarını ve bu API'deki id + name sözleşmesini kendiniz yönetmelisiniz.

thinking_level: "minimal" araçlarla çalışır mı?

Hayır. Gemini 3.8 Flash doğrulama hatası döndürür. low kullanın.

Araç ağırlıklı bir görev ne kadar tutar?

31 Aralık 2026'ya kadar fiyatlandırma 1 milyon jeton başına 0,75 dolar giriş ve 3,75 dolar çıkıştır. Düşünme jetonları çıkış olarak faturalandırılır.

Artificial Analysis indeksinde ölçülen yaklaşık görev maliyetleri:

• High: 0,58 dolar
• Medium: 0,41 dolar
• Low: 0,24 dolar

Gerçek maliyet görevlerinize göre değişir. Jeton kullanımını ölçerek doğrulayın.

Döngüyü bir tavanla üretime gönderin

Sözleşme basit:

1. Aracı bildirin.
2. function_call adımını okuyun.
3. previous_interaction_id altında call_id ve name içeren function_result gönderin.
4. Yeni bir çağrı gelirse döngüyü sürdürün.

Gemini 3.8 Flash'ta değişen şey modelin daha uzun döngülere girme eğilimidir. Bu nedenle üretime geçmeden önce araç takımınıza maksimum dönüş sayısı, rota başına thinking_level, zaman aşımı ve idempotency kuralları ekleyin.

Arka ucu mock'layın, iki dönüşü zincirleyin, kimlik gidiş-dönüşlerini doğrulayın ve testi planlayın. Geçiş notları için Gemini 3.8 Flash'taki Yenilikler sayfasına bakabilirsiniz.

Referanslar

• Gemini 3.8 Flash nedir?
• Google işlev çağırma belgeleri
• Apidog
• Gemini 3.8 Flash düşünme seviyeleri
• Gemini 3.8 Flash API nasıl kullanılır?
• Gemini 3.8 Flash lansman yazısı
• Artificial Analysis
• 3.7'den 3.8 Flash'a geçiş kılavuzu
• Interactions API belgeleri
• Gemini generateContent işlev çağırma belgeleri
• Bilgisayar kullanımı ve yapılandırılmış API'ler
• Yapay zeka ajanı API test kılavuzu
• Apidog'u indirin
• Gemini 3.8 Flash'taki Yenilikler