DEV Community

Cover image for OpenAI Fonksiyon Çağırma Nasıl Kullanılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

OpenAI Fonksiyon Çağırma Nasıl Kullanılır

Bu kılavuzda OpenAI işlev/araç çağırmayı uçtan uca uygulayacaksınız: aracı tanımlayacak, modele gönderecek, modelin döndürdüğü araç çağrısını ayrıştıracak, kendi fonksiyonunuzu çalıştıracak ve sonucu modele geri vereceksiniz. Son bölümde katı mod, paralel çağrılar ve üretime çıkmadan önce Apidog ile argüman doğrulama ve API taklidi akışını kuracaksınız. Referans için OpenAI’ın işlev çağırma dokümantasyonunu açık tutabilir, daha üst seviye bir mimari bakış için OpenAI Agents SDK ile aracı oluşturma yazısına göz atabilirsiniz.

Apidog'u bugün deneyin

Başlamadan önce

İşlev çağırma, modelin uygulamanızdaki kodla veya harici sistemlerle güvenli şekilde etkileşime geçmesini sağlar.

Önemli nokta şudur:

  • Model fonksiyonu çalıştırmaz.
  • Model hangi fonksiyonun çağrılması gerektiğine karar verir.
  • Model fonksiyon adı ve JSON argümanlarını döndürür.
  • Fonksiyonu sizin uygulama kodunuz çalıştırır.
  • Sonucu tekrar modele gönderirsiniz.

Örneğin kullanıcı şunu yazabilir:

Paris'teki hava durumu nasıl?
Enter fullscreen mode Exit fullscreen mode

Model bunu serbest metin olarak yorumlamak yerine şu yapıda bir çağrıya çevirebilir:

get_weather({ location: "Paris, France" })
Enter fullscreen mode Exit fullscreen mode

Devam etmek için ihtiyacınız olanlar:

  • OpenAI API anahtarı
  • Modelin çağırmasını istediğiniz bir uygulama fonksiyonu
  • Fonksiyon argümanlarını tanımlayan JSON Schema
  • İsteğe bağlı olarak API sözleşmesini test etmek için Apidog

Bu özellik hem eski Chat Completions API hem de daha yeni Responses API ile kullanılabilir. Mantık aynıdır, ancak istek/yanıt şekilleri biraz farklıdır.

Adım 1: Aracınızı tanımlayın

Bir araç, modele sunduğunuz fonksiyon tanımıdır. Temel olarak şunları içerir:

  • name: Fonksiyon adı
  • description: Modelin bu fonksiyonu ne zaman kullanacağını açıklayan talimat
  • parameters: Fonksiyonun beklediği argümanları tanımlayan JSON Schema

Açıklamayı kısa bir etiket gibi değil, model için davranış talimatı gibi yazın.

Chat Completions formatı 

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Responses API formatı

Responses API’de aynı bilgiler daha düz bir yapıyla verilir. name, description, parameters ve strict alanları doğrudan araç nesnesinin üst seviyesinde yer alır.

Örneğin:

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country, e.g. Bogotá, Colombia"
      }
    },
    "required": ["location"],
    "additionalProperties": false
  },
  "strict": true
}
Enter fullscreen mode Exit fullscreen mode

Eğer temel servisiniz için zaten bir OpenAPI spesifikasyonunuz varsa, parametre tanımları büyük ölçüde bu şemaya karşılık gelir. Bu yaklaşımı test tarafında da kullanmak için OpenAPI spesifikasyonlarından test koleksiyonları oluşturma rehberine bakabilirsiniz.

Adım 2: İlk isteği gönderin

Aracı, kullanıcının mesajıyla birlikte modele gönderin.

Chat Completions için örnek istek:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Paris right now?"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string"
              }
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Bu istekte:

  • messages: Kullanıcı girdisini taşır.
  • tools: Modele sunulan fonksiyonları listeler.
  • Model uygun görürse düz metin yerine araç çağrısı döndürür.

Adım 3: Modelin döndürdüğü araç çağrısını okuyun

Model bir fonksiyonu çağırmak istediğinde, yanıt içinde araç çağrısı döner.

Chat Completions yanıtı

Chat Completions’ta araç çağrıları tool_calls dizisinde yer alır:

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}
Enter fullscreen mode Exit fullscreen mode

Burada dikkat edilmesi gereken alanlar:

  • id: Bu çağrının kimliği
  • function.name: Çağrılacak fonksiyon
  • function.arguments: JSON kodlu argüman dizesi

Responses API yanıtı

Responses API’de çağrı output dizisi içinde daha düz bir yapıyla gelir:

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}
Enter fullscreen mode Exit fullscreen mode

Burada da önemli alanlar:

  • call_id: Çağrı kimliği
  • name: Fonksiyon adı
  • arguments: JSON kodlu argüman dizesi

arguments alanı nesne değil, string olarak gelir. Bu nedenle uygulama kodunuzda ayrıştırmanız gerekir.

Örnek JavaScript ayrıştırma:

const toolCall = response.choices[0].message.tool_calls[0];

const functionName = toolCall.function.name;
const args = JSON.parse(toolCall.function.arguments);

console.log(functionName); // get_weather
console.log(args.location); // Paris, France
Enter fullscreen mode Exit fullscreen mode

Adım 4: Kendi fonksiyonunuzu çalıştırın

Model yalnızca neyin çağrılacağını söyler. Asıl yürütme sizin kodunuzdadır.

Basit bir örnek:

async function getWeather({ location }) {
  // Gerçek uygulamada burada hava durumu sağlayıcınızı çağırırsınız.
  return {
    location,
    temperature: 21,
    unit: "celsius",
    condition: "cloudy"
  };
}
Enter fullscreen mode Exit fullscreen mode

Araç çağrısını aldıktan sonra fonksiyonu çalıştırabilirsiniz:

const args = JSON.parse(toolCall.function.arguments);

let result;

if (toolCall.function.name === "get_weather") {
  result = await getWeather(args);
}
Enter fullscreen mode Exit fullscreen mode

Bu aşamada mutlaka şunları yapın:

  • JSON.parse hatalarını yakalayın.
  • Argümanları şemanıza göre doğrulayın.
  • Beklenmeyen fonksiyon adlarını reddedin.
  • Harici API hatalarını yönetin.

Adım 5: Sonucu modele geri gönderin

Fonksiyon sonucunu aldıktan sonra, modelin nihai kullanıcı yanıtını oluşturabilmesi için sonucu tekrar modele göndermeniz gerekir.

Chat Completions mantığı

Chat Completions’ta fonksiyon sonucunu tool rolüyle gönderirsiniz. Bu mesaj, önceki çağrının tool_call_id değerine bağlanır.

Örnek yapı:

{
  "role": "tool",
  "tool_call_id": "call_12345xyz",
  "content": "{\"location\":\"Paris, France\",\"temperature\":21,\"unit\":\"celsius\",\"condition\":\"cloudy\"}"
}
Enter fullscreen mode Exit fullscreen mode

Akış şu şekildedir:

  1. Kullanıcı mesaj gönderir.
  2. Model araç çağrısı döndürür.
  3. Uygulama fonksiyonu çalıştırır.
  4. Uygulama sonucu tool mesajı olarak modele döndürür.
  5. Model kullanıcıya nihai cevabı üretir.

Responses API mantığı

Responses API’de fonksiyon sonucu function_call_output olarak gönderilir ve call_id ile eşleştirilir:

{
  "type": "function_call_output",
  "call_id": "call_12345xyz",
  "output": "{\"location\":\"Paris, France\",\"temperature\":21,\"unit\":\"celsius\",\"condition\":\"cloudy\"}"
}
Enter fullscreen mode Exit fullscreen mode

Her iki API’de de temel döngü aynıdır:

Model çağrı ister → Kodunuz çalıştırır → Sonuç modele döner → Model yanıt üretir
Enter fullscreen mode Exit fullscreen mode

Adım 6: Paralel çağrıları ve katı modu ayarlayın

Temel akış çalıştıktan sonra iki ayarı yapılandırın:

  • parallel_tool_calls
  • strict
Ayar Ne Kontrol Eder Varsayılan Ne Zaman Değiştirilir
parallel_tool_calls Tek bir dönüşte birden fazla araç çağrısı gelip gelemeyeceği true Çağrılar birbirine bağlıysa veya sırayla çalışması gerekiyorsa false yapın
strict Argümanların JSON Schema ile eşleşmeye zorlanıp zorlanmadığı Ayarlanmadıkça en iyi çaba Argümanları doğrudan ayrıştırıp çalıştıracağınız durumlarda açın
tool_choice Modelin araç çağırıp çağıramayacağını veya hangi aracı çağıracağını auto Çağrıyı zorlamak için required, kapatmak için none, belirli aracı seçmek için araç adı kullanın

Paralel araç çağrıları

Varsayılan olarak model aynı turda birden fazla araç çağrısı döndürebilir.

Örneğin kullanıcı şunu sorarsa:

Paris, Berlin ve Roma'daki hava durumu nasıl?
Enter fullscreen mode Exit fullscreen mode

Model üç ayrı get_weather çağrısı döndürebilir. Bunları eş zamanlı çalıştırabilirsiniz.

Eğer çağrıların sırayla çalışması gerekiyorsa:

{
  "parallel_tool_calls": false
}
Enter fullscreen mode Exit fullscreen mode

Katı mod

Katı mod için fonksiyon tanımında strict: true kullanın.

Katı modda modelin döndürdüğü argümanların JSON Schema ile eşleşmesi beklenir. OpenAI bunu etkinleştirmeyi önerir.

Ancak katı modun önemli kuralları vardır:

  • Her nesnede additionalProperties: false bulunmalıdır.
  • properties içindeki her alan required içinde yer almalıdır.
  • İsteğe bağlı alanlar için alanı required listesinden çıkarmak yerine null tipine izin verilir.

Örneğin unit alanını opsiyonel yapmak istiyorsanız:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string"
    },
    "unit": {
      "type": ["string", "null"],
      "enum": ["celsius", "fahrenheit", null]
    }
  },
  "required": ["location", "unit"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

Bu durumda model şu iki değerden birini geçebilir:

{
  "location": "Paris, France",
  "unit": "celsius"
}
Enter fullscreen mode Exit fullscreen mode

veya:

{
  "location": "Paris, France",
  "unit": null
}
Enter fullscreen mode Exit fullscreen mode

Böylece ayrıştırma kodunuz her zaman aynı anahtarları bekler.

Katı mod yapısal güvenilirliği artırır, ancak iş mantığını garanti etmez. Örneğin location alanı şemaya göre geçerli bir string olabilir, ancak servisinizin desteklemediği bir şehir içerebilir. Bu nedenle ayrıca doğrulama ve test yapmanız gerekir.

Apidog’da nasıl test edilir

Modelden gelen araç çağrısını canlı fonksiyona bağlamadan önce iki şeyi doğrulamanız gerekir:

  1. Modelin ürettiği argümanlar beklenen şemaya uyuyor mu?
  2. Fonksiyonunuzun çağıracağı alt sistem API’si beklediğiniz gibi davranıyor mu?

Apidog bu iki sözleşme noktasını test etmenize yardımcı olur.

Apidog uygulama fonksiyonunuzu çalıştırmaz. Bunun yerine:

  • Modelden gelen argüman yapısını doğrulamanıza yardımcı olur.
  • Fonksiyonunuzun bağlı olduğu API’yi taklit etmenizi sağlar.
  • Gerçek API’ye istek atmadan hata ve başarı senaryolarını test etmenize izin verir.

1. Araç argümanlarını doğrulayın

Modelden gelen arguments dizesini alın:

"{\"location\":\"Paris, France\",\"unit\":\"celsius\"}"
Enter fullscreen mode Exit fullscreen mode

Bunu JSON’a çevirin:

{
  "location": "Paris, France",
  "unit": "celsius"
}
Enter fullscreen mode Exit fullscreen mode

Ardından Apidog’da bu yapıyı istek gövdesi gibi doğrulayabilirsiniz.

Kontrol edilecek örnekler:

  • location var mı?
  • location string mi?
  • unit yalnızca celsius, fahrenheit veya null mı?
  • Gerekli alanların tamamı mevcut mu?
  • Beklenmeyen ek alan var mı?

Belirli alanları çekmek için JSONPath ifadeleri kullanabilirsiniz.

Daha güçlü doğrulama için OpenAI’a verdiğiniz şemayı yansıtan JSON Schema doğrulaması kurabilirsiniz.

Böylece aynı sözleşme iki yerde uygulanır:

  • Model tarafında araç parametresi olarak
  • Test tarafında doğrulama şeması olarak

2. Alt sistem API’sini taklit edin

get_weather fonksiyonunuz muhtemelen gerçek bir hava durumu sağlayıcısını çağırır.

Geliştirme sırasında bu API:

  • Ücretli olabilir
  • Rate limit uygulayabilir
  • Henüz hazır olmayabilir
  • Hata senaryolarını kolay üretmeyebilir

Bu durumda Apidog’da bir sahte API oluşturabilirsiniz.

Örnek mock yanıt:

{
  "location": "Paris, France",
  "temperature": 21,
  "unit": "celsius",
  "condition": "cloudy"
}
Enter fullscreen mode Exit fullscreen mode

Ardından uygulama fonksiyonunuzu gerçek sağlayıcı yerine bu mock endpoint’e yönlendirin.

Test etmeniz gereken senaryolar:

  • Başarılı hava durumu yanıtı
  • Geçersiz şehir
  • Zaman aşımı
  • 429 Too Many Requests
  • 500 Internal Server Error
  • Eksik veya beklenmeyen alanlar

Bu sayede gerçek API kotası harcamadan tüm araç çağırma yolunu test edebilirsiniz.

Özet akış:

OpenAI araç çağrısı üretir
→ arguments alanını yakalarsınız
→ Apidog ile şemaya göre doğrularsınız
→ Fonksiyonunuzu Apidog mock API’ye yönlendirirsiniz
→ Başarı ve hata senaryolarını test edersiniz
→ Üretime daha güvenli çıkarsınız
Enter fullscreen mode Exit fullscreen mode

Sıkça sorulan sorular

İşlev çağırma hem Chat Completions hem de Responses API’de çalışır mı?

Evet. Her iki uç nokta da işlev çağırmayı destekler.

Temel fark yanıt ve araç tanımı şeklidir:

  • Chat Completions, fonksiyon tanımını function anahtarı altında taşır ve tool_calls döndürür.
  • Responses API, daha düz bir araç tanımı kullanır ve output içinde function_call öğeleri döndürür.

Model neden argümanları nesne yerine string olarak döndürüyor?

arguments alanı JSON kodlu metindir. Bu nedenle kullanmadan önce uygulama kodunuzda ayrıştırmanız gerekir.

Örnek:

const args = JSON.parse(toolCall.function.arguments);
Enter fullscreen mode Exit fullscreen mode

Ayrıştırdıktan sonra da doğrulama yapmalısınız. Bu argümanları JSON Schema doğrulamasından geçirmek, hatalı biçimlendirilmiş yükleri fonksiyonunuza ulaşmadan yakalamanıza yardımcı olur.

Katı mod fonksiyonun başarılı çalışacağını garanti eder mi?

Hayır.

Katı mod yalnızca argümanların JSON Schema ile eşleşmesini sağlar. Şunları garanti etmez:

  • Konum gerçekten destekleniyor mu?
  • Harici API çalışıyor mu?
  • İş mantığı başarılı olacak mı?
  • API rate limit’e takılacak mı?

Bu kontroller hâlâ uygulama kodunuzda ve test sürecinizde yapılmalıdır.

Apidog gerçek fonksiyonumu çalıştırabilir mi?

Hayır. Apidog uygulama içindeki fonksiyonunuzu çalıştırmaz.

Apidog’un rolü şudur:

  • Modelin ürettiği argümanları doğrulamak
  • Fonksiyonunuzun bağlı olduğu API’yi mocklamak
  • API sözleşmesini ve hata senaryolarını test etmek

Fonksiyon yürütme yine sizin uygulamanızda kalır.

Sonuç

OpenAI işlev çağırma akışı şu döngüden oluşur:

Aracı tanımla
→ Modele gönder
→ tool_calls veya function_call çıktısını oku
→ arguments değerini ayrıştır
→ Kendi fonksiyonunu çalıştır
→ Sonucu modele geri gönder
→ Nihai yanıtı üret
Enter fullscreen mode Exit fullscreen mode

Üretime yaklaşırken:

  • strict: true kullanın.
  • additionalProperties: false ekleyin.
  • Argümanları JSON Schema ile doğrulayın.
  • Paralel çağrıların uygulamanıza uygun olup olmadığını belirleyin.
  • Harici API’leri mocklayarak başarı ve hata senaryolarını test edin.

Test tarafını denemek için araç çağırma argümanlarını şemanıza göre doğrulayabilir ve fonksiyonlarınızın bağlı olduğu API’leri tek yerden taklit etmek için Apidog’u indirebilirsiniz.

Top comments (0)