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

Gemini 3.8 Flash, 2 Eylül 2026'da piyasaya sürüldü ve Google bunu “araçları iteratif olarak çağırmak” için geliştirdi: zor bir görevde tek seferde her şeyi tahmin etmek yerine bir çağrı yapar, sonucu kontrol eder ve başka bir çağrı yapar. Bu, aracılar için iyi bir haber ve araç döngüsü 3.7 Flash için ayarlanmış herkes için yeni bir baş ağrısı. İki API detayı her şeyden daha önemlidir. Her işlev sonucu hem call_id hem de name içermeli ve generateContent yerine Interactions API artık döngüyü çalıştırmanın birincil yoludur.

Bu kılavuz, Interactions API'sindeki tam iki turlu akışı anlatır, muhtemelen hala kullandığınız eski generateContent yapısını gösterir, yeni modelin araçlar üzerinde neden daha fazla dönüş ve jeton harcadığını açıklar ve her gün çalıştırabileceğiniz bir test kurulumuyla sona erer: aracın arka ucunu taklit edin, her iki dönüşü birbirine bağlayın ve call_id gidiş-dönüşlerinin doğru çalıştığını doğrulayın. Önce modelin genel görünümüne ihtiyacınız varsa, Gemini 3.8 Flash nedir ile başlayın. Aşağıdaki alan adları Google'ın işlev çağırma belgelerinden alınmıştır.

Buradaki her istek, JSON içeren düz HTTP olduğundan, uygulama koduna geçmeden önce Apidog'da oluşturup hata ayıklayabilirsiniz.

Bir Bakışta Gemini 3.8 Flash'ta İşlev Çağırma

Öğe	Gemini 3.8 Flash
Model Kimliği	`gemini-3.8-flash` (kararlı, önizleme eki yok)
Birincil API	Interactions API (`POST /v1beta/interactions`); `generateContent` eskidir ancak tam olarak desteklenmektedir
Araç bildirimi	`tools: [{"type": "function", "name", "description", "parameters"}]`
Modelin çağrısı	`id`, `name`, `arguments` ile `function_call` adımı
Yanıtınız	`call_id` + `name` (her ikisi de gerekli) artı `previous_interaction_id` ile `function_result`
Düşünme	`thinking_level` `low` / `medium` (varsayılan) / `high`; `minimal` bir doğrulama hatası döndürür
Araç kullanım puanı	Tau3-Banking %45, 3.7 Flash'a göre +12 puan (Artificial Analysis, bağımsız)
Jeton maliyeti	AA indeksinde görev başına ~48k çıkış jetonu, 3.7 Flash'a göre %30 daha fazla
Fiyat	31 Aralık 2026'ya kadar 1 milyon başına 0,75 dolar giriş / 3,75 dolar çıkış; düşünme çıkış olarak faturalandırılır

Adım 1: Aracı bildirin

Interactions API'sinde bir araç düz bir nesnedir: function tipi, bir name, modelin ne zaman çağıracağına karar vermek için okuduğu bir description ve parameters altında bir JSON Şeması. Açıklamayı belirli tutun. “Bir siparişin mevcut gönderim durumunu kimliğine göre arayın” doğru zamanda çağrılır; “sipariş yardımcısı” rastgele çağrılır.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $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"]
      }
    }]
  }'

Bu istekteki iki seçim kasıtlıdır. thinking_level low çünkü tek bir arama varsayılan medium'a ihtiyaç duymaz; düşünme seviyeleri kılavuzu ne zaman yükseltileceğini kapsar. Ve temperature yok. Google'ın Gemini 3 rehberliği, varsayılan 1.0'da bırakılmasını önerir, çünkü düşürmek döngüye neden olabilir ki bu, bir araç döngüsünün içinde isteyeceğiniz son şeydir.

Adım 2: `function_call` adımını okuyun

Interactions API tek bir mesajla yanıt vermez. Etkileşimin kendi id'sini ve bir dizi yürütme adımını döndürür: model düşünceleri, araç çağrıları ve modelin bir cevabı olduğunda nihayet bir model_output adımı. Model aracınıza ihtiyaç duyduğuna karar verdiğinde, liste bir model_output yerine bir function_call adımı içerir:

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

Üç alan ve hepsine ihtiyacınız var. id, call_id olarak geri gönderdiğiniz tanıtıcıdır. name, hangi işlevi çalıştıracağınızı söyler ve o da geri yankılanmalıdır. arguments zaten ayrıştırılmış JSON'dır, bu yüzden herhangi bir şeyi yürütmeden önce kendi kurallarınıza göre doğrulayın; model bildirdiğiniz şekli doldurur, ancak sipariş kimliklerinizin beş karakter uzunluğunda olduğunu bilmez.

Yanıtın başındaki etkileşim id'sini aynı anda saklayın. Bir sonraki turda previous_interaction_id olur.

Adım 3: Sonucu `call_id` ve `name` ile döndürün

İşlevinizi çalıştırın, ardından input'u function_result olan ikinci bir istek gönderin. Gemini 3.8 Flash'ta hem call_id hem de name gereklidir. Herhangi birini atarsanız çağrı başarısız olur, bu da ekiplerin eski modeller için yazılmış döngüleri taşırken karşılaştığı en yaygın hatadır.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -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 bir içerik parçaları listesidir ve metin kısmı JSON'ınızı bir dize olarak taşır. previous_interaction_id önceki tura işaret ettiği için, sunucu zaten orijinal istemi, araç bildirimini ve modelin muhakemesini tutar; bunların hiçbirini yeniden göndermezsiniz. Yanıt başka bir adım listesidir. Eğer model_output ile bitiyorsa, işiniz bitti demektir ve SDK metni interaction.output_text olarak sunar. Eğer başka bir function_call içeriyorsa, adım 2'ye geri dönün. Bu döngü tüm kalıptır.

Python'da akış, aynı JSON alanlarını anahtar kelime argümanları olarak kullanarak client.interactions.create(model="gemini-3.8-flash", input=..., ...) şeklindedir, ardından previous_interaction_id ve function_result listesi input olarak ikinci bir create çağrısı yapılır. Eğer uç nokta sizin için yeniyse, Gemini 3.8 Flash API nasıl kullanılır kılavuzu anahtarları, akışı ve jeton kullanımını okumayı kapsar.

Eski generateContent Eşdeğeri

Mevcut Gemini kodlarının çoğu hala models/gemini-3.8-flash:generateContent çağırıyor ve Google bunun hiçbir sonlandırma tarihi olmadan “tam olarak desteklenmeye devam ettiğini” belirtiyor. Kelime dağarcığı farklı; kural aynı. Araçlar functionDeclarations altında bildirilir, model bir functionCall parçasıyla yanıt verir ve siz bir functionResponse parçasıyla cevap verirsiniz. Eski yapıda modelin functionCall parçası bir id taşır ve functionResponse parçanız, name ve response'un yanı sıra kendi id alanında aynı değeri yankılamalıdır. Bu, Interactions API'sindeki call_id ile farklı bir alan adı altında aynı sözleşmedir ve Google'ın Gemini 3 rehberliği, hem kimliğin hem de adın gerekli olduğunu açıkça belirtir.

İki pratik fark. Birincisi, generateContent durumsuzdur, bu yüzden konuşmayı kendiniz yürütürsünüz: modelin functionCall parçası ve döndürdüğü tüm düşünce imzaları dahil olmak üzere tam contents geçmişi her dönüşte geri gider. İkincisi, düşünme `generation_config.thinking_level` yerine `generationConfig.thinkingConfig.thinkingLevel` altında yapılandırılır:

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

Düşünme jetonları yanıtta usageMetadata.thoughtsTokenCount olarak görünür ve çıkış olarak faturalandırılır. Yeni bir proje için iki API arasında seçim yapıyorsanız, Interactions'ı seçin: sunucu tarafı durumu, yeniden gönderilen bir geçmişin bir imza veya bir call_id eksik olduğu hata sınıfını ortadan kaldırır.

3.8 Flash Neden Araçları İteratif Olarak Çağırır ve Döngüyü Nasıl Sınırlarsınız?

Google'ın lansman yazısı modelin “daha çok çalıştığını” belirtiyor: karmaşık görevlerde “ekstra muhakeme adımları yürütür ve araçları iteratif olarak çağırır”, “daha küçük muhakeme adımları atar” ve yol boyunca çalışmasını doğrular. Google ayrıca “tasarım gereği, daha uzun süren ve karmaşık görevlerde daha fazla jeton kullanabileceğini” belirtiyor. Artificial Analysis etkisi ölçtü: kendi indekslerinde görev başına yaklaşık 48 bin çıkış jetonu, 3.7 Flash'a göre %30 daha fazla ve aynı jeton fiyatlarıyla görev başına high seviyesinde 0,58 dolar maliyet, 3.7 Flash için 0,40 dolar. Medium 0,41 dolar ve low 0,24 dolar olarak geldi.

Bir araç döngüsü için bu, görev başına daha fazla function_call adımı anlamına gelir. Artı yönü gerçek: AA'nın araç kullanım değerlendirmesi olan Tau3-Banking, 12 puan artarak %45'e yükseldi. Dezavantajı ise, tavanı olmayan bir döngünün artık Ağustos ayına göre daha uzun sürmesidir. Dört kontrol, uygulanma sırasına göre:

Araç takımınızdaki maksimum dönüş sayısı. Görev başına function_call adımlarını sayın ve seçtiğiniz bir limitte durun; aramalar için 6 ila 10 makul bir başlangıç aralığıdır, ajanssal kodlama için daha yüksek. Limit aşıldığında, araçsız son bir dönüş gönderin veya kullanıcıya bir hata döndürün. Model kendini sınırlamaz.
Rota başına thinking_level. Aramalar ve tek adımlı araçlar için low, çok adımlı çalışmalar için medium (varsayılan), yalnızca ekstra doğrulamanın karşılığını verdiği durumlarda high. minimal göndermeyin; 3.8 Flash bir doğrulama hatası döndürür.
Her iki tarafta zaman aşımları. Gemini çağrısında istek başına zaman aşımı ve döngüde görev başına gerçek zaman saati. AA'nın yüksek muhakemeli çalıştırmaları görev başına ortalama 2,5 dakika, düşük seviyede 0,8 dakika sürdü.
Idempotent araçlar. İteratif bir model yeniden dener. get_order_status'ı iki kez çağrılmaya güvenli hale getirin ve yan etkileri olan her şeyin (geri ödemeler, gönderimler) bir onay adımı gerektirmesini sağlayın.

Bütçeniz ekstra dönüşleri karşılayamıyorsa, 3.7'den 3.8 Flash'a geçiş kılavuzu, tamamen desteklenmeye devam eden 3.7 Flash'ı bir yapılandırma bayrağının arkasında tutmayı kapsar.

Düşünce İmzaları, Paralel Çağrılar ve Yapılandırılmış Çıkışlar

Düşünce imzaları. Gemini 3 modelleri muhakemelerine imzalar ekler. Varsayılan depolanmış Interactions akışı ile previous_interaction_id bunları sizin için halleder. Durumsuz bir kurulum için store: false ayarlarsanız veya generateContent kullanırsanız, düşünce bloklarını ve imzaları her parça tipinde tam olarak alındığı gibi geri göndermeniz gerekir. Kesmeyin, yeniden sıralamayın veya yeniden serileştirmeyin; bir imza opaktır ve herhangi bir düzenleme onu geçersiz kılar. Google'ın Interactions API belgeleri depolanmış ve durumsuz takaslarını kapsar.

Paralel çağrılar. Yanıt bir listedir, bu yüzden model aynı anda birkaç bağımsız arama istediğinde birden fazla function_call adımı içerebilir. Google'ın işlev çağırma belgeleri, Gemini 3 modellerinin her çağrıda benzersiz bir kimlik döndürdüğünü, böylece sonuçların herhangi bir sırada geri gelebileceğini doğrular. Bunu, aynı input dizisinde çağrı başına bir function_result döndürerek yapın, her biri kendi call_id'sine göre eşleştirilir. Yalnızca name ile eşleştirme yeterli değildir; aynı işlev için iki çağrıya iki farklı call_id değeri gerekir.

Yapılandırılmış çıkışlar. 3.8 Flash, aynı model üzerinde yapılandırılmış çıkışları ve işlev çağırmayı destekler. Temiz desen, döngü için araçlar ve son yanıt için bir JSON şemasıdır, böylece döngüyü kapatan model_output metin yerine makine tarafından okunabilir olur. Google'ın işlev çağırma ve yapılandırılmış çıkış sayfaları yapılandırmayı belgeler. Sahte bir araç bildirerek ve arguments'larını okuyarak taklit etmeyin; bu, modelin çağıracak hiçbir şeyi olmadığına karar verdiği anda bozulur.

Yukarıdakilerin hepsi, modelin sisteminize bildirilmiş işlevler aracılığıyla ulaştığını varsayar. Google ayrıca 3.8 Flash için Bilgisayar kullanımı (Önizleme) listeler; yapılandırılmış bir API'nin bir aracıyı ekran sürmekten daha iyi olduğu durumlarda, bilgisayar kullanımı ve yapılandırılmış API'ler karşılaştırmasına bakın.

Apidog'da Araç Döngüsünü Test Etme

Bir araç döngüsünün bozulabileceği üç yer vardır: bildirim, kimlik gidiş-dönüşü ve nihai cevap. Gerçek arka ucunuza dokunmadan Apidog'da her üçünü de kapsayabilirsiniz.

1. Aracın arka ucunu taklit edin. GET /orders/{order_id}'i bir uç nokta olarak tanımlayın ve sahte sunucusunu açın. Sabit bir yanıt gövdesi verin: {"status": "in_transit", "eta": "2026-09-05"}, böylece her çalıştırma aynı girişi alır ve modelin nihai yanıtındaki herhangi bir değişiklik modelin işi olur, veritabanınızın değil. Araç takımınız test ortamında sahte URL'ye, üretimde ise gerçek hizmete işaret eder.

2. Bir test senaryosunda her iki dönüşü birbirine bağlayın. GEMINI_API_KEY'i bir ortam değişkeni olarak saklayın ve x-goog-api-key başlığında {{GEMINI_API_KEY}} olarak referans verin. Ardından üç adımlı bir senaryo oluşturun:

Adım A: `/v1beta/interactions` adresine istem ve `get_order_status` bildirimiyle POST isteği gönderin. Etkileşim `id`'sini ve `function_call` adımının `id`'sini, `name`'ini ve `arguments.order_id`'sini değişkenlere çıkarın.
Adım B: `{{order_id}}` ile sahte uç noktaya GET isteği gönderin. Bu sizin “işlevi çalıştır” adımınızdır.
Adım C: `call_id`'si `{{call_id}}` olarak, `name`'i `{{tool_name}}` olarak, `previous_interaction_id`'si `{{interaction_id}}` olarak ayarlanmış ve Adım B'nin gövdesi metin kısmı olarak `function_result`'ı POST edin.

3. Önemli olanı doğrulayın.

Adım A 200 döndürür ve `type`'ı `function_call` olan ve `name`'i `get_order_status`'a eşit olan bir adım içerir.
Çıkarılan `arguments.order_id`, `A1029`'a eşittir, bu da modelin istemi ayrıştırdığını ve şemaya uyduğunu kanıtlar.
Adım C 200 döndürür ve `type`'ı `model_output` olan ve ikinci bir `function_call` içermeyen bir adımla biter, bu da gönderdiğiniz `call_id` ve `name`'in kabul edildiğini ve döngünün tek bir turda kapandığını kanıtlar.
Nihai metin `in_transit` içerir, bu da modelin kendi tahminini değil, araç sonucunu kullandığını kanıtlar.
Aynı senaryoyu `generateContent`'e karşı çalıştırırsanız, `thinking_level` başına `usageMetadata.thoughtsTokenCount` üzerinde bir tavan ekleyin. Bu, “daha çok çalışma” maliyetinin faturanıza ulaşmadan önce yakalanmasını sağlar.

Senaryoyu her gün çalışacak şekilde planlayın. Model davranışı sessiz güncellemelerle değişir ve geçen hafta tek turda kapanan bir döngü iki tura ihtiyaç duymaya başlayabilir. Yapay zeka ajanı API test kılavuzu çok adımlı doğrulama hakkında daha derinlemesine bilgi verir ve bir kuruş harcamadan önce ücretsiz katmana karşı senaryoyu oluşturmak için Apidog'u indirebilirsiniz.

Sıkça Sorulan Sorular

Gemini 3.8 Flash'ta `call_id` gerekli mi? Evet. Interactions API'sinde her function_result'ın call_id ve name'e ihtiyacı vardır; generateContent'te her functionResponse'ın çağrının id'sine ve name'ine ihtiyacı vardır. Sadece adı gönderen eski kod, Gemini 3 modellerinde başarısız olur.

Araç döngüm 3.8 Flash'ta neden 3.7'ye göre daha fazla tur çalışıyor? Tasarım gereği. Google, modelin “araçları iteratif olarak çağırdığını” ve “daha uzun süren ve karmaşık görevlerde daha fazla jeton kullanabileceğini” belirtiyor. Araç takımınızdaki dönüşleri sınırlayın ve thinking_level'i düşürün; düşünme seviyeleri kılavuzu, seviye başına ölçülen maliyeti içerir.

İşlev çağırmak için hala `generateContent` kullanabilir miyim? Evet. Google bunu eski olarak adlandırsa da, hiçbir sonlandırma tarihi olmadan “tamamen desteklenmeye devam ettiğini” belirtiyor. Geçmişi kendiniz taşırsınız, düşünce imzaları dahil, ve çağrı kimliği (bu API'de id olarak yazılır) artı name hala geçerlidir.

`thinking_level` “minimal” araçlarla çalışır mı? Hayır. 3.8 Flash'ta bir doğrulama hatası döndürür. low kullanın.

Araç ağırlıklı bir görevin maliyeti ne kadar? Jeton başına fiyatlandırma, 31 Aralık 2026'ya kadar 1 milyon jeton başına 0,75 dolar giriş ve 3,75 dolar çıkıştır, düşünme çıkış olarak faturalandırılır. Artificial Analysis, kendi indekslerinde görev başına high seviyesinde 0,58 dolar, medium seviyesinde 0,41 dolar ve low seviyesinde 0,24 dolar ölçtü. Görevleriniz farklılık gösterecektir, bu yüzden jeton sayımlarını doğrulayın ve ölçüm yapın.

Döngüyü Bir Tavan ile Gönderin

Aracı bildirin, function_call adımını okuyun ve previous_interaction_id altında hem call_id hem de name ile function_result döndürün. Tüm sözleşme budur. Gemini 3.8 Flash ile değişen şey, modelin döngüye girme isteğidir, bu yüzden araç takımının üretime geçmeden önce bir dönüş sınırı, rota başına bir thinking_level ve bir zaman aşımı ihtiyacı vardır. Arka ucu taklit edin, iki dönüşü zincirleyin, kimlik gidiş-dönüşlerini doğrulayın ve çalıştırmayı planlayın. Google'ın Gemini 3.8 Flash'taki Yenilikler sayfası geçiş notlarını içerir; temel kılavuz model hakkındaki her şeyi içerir.