Function calling

Bir LLM'e 299 endpoint'i 299 ayrı araç olarak vermek akla ilk gelen yöntemdir ve yanlıştır. Burada işe yarayan yapıyı ve tasarlarken önlem almaya değer dört hatayı anlatıyoruz.

299 araç tanımlamayın

Araç listesi uzadıkça her büyük sağlayıcıda kalite düşer. Şemalar, sohbet başlamadan bağlam penceresini doldurur; birkaç aracın açıklaması örtüşmeye başladığında da doğru aracı seçme isabeti azalır. Çoğu aynı dört alanı alan 299 endpoint ile, modelin seçim yapmasını kötüleştirmek için her turda binlerce token harcamış olursunuz.

Bir ya da iki araç tanımlayın. Model, yüzlerce şema arasından seçim yapmak yerine yolu bir argüman olarak belirler.

Tek araçlı yapı

araç tanımı

{
  "name": "occult_api",
  "description":
    "Vedic astrology calculations from the Occult API. Call this for anything involving a birth chart, panchanga, dasha, muhurta, matching or numerology. Do not compute astrology yourself - planetary positions require an ephemeris and cannot be derived from a date.",
  "input_schema": {
    "type": "object",
    "properties": {
      "route": {
        "type": "string",
        "description": "Endpoint path, e.g. /api/astro/panchanga/. Use the catalogue at https://occultapi.com/llms.txt to choose one."
      },
      "body": {
        "type": "object",
        "description": "Request body. Always include date_time (ISO 8601 with offset), latitude, longitude, timezone_as_float. Batch calculations with a keys array where the endpoint supports it."
      }
    },
    "required": ["route", "body"]
  }
}

Açıklama iki iş görür. Araca ne zaman başvurulacağını söyler ve hesabı kendisinin yapmaması gerektiğini belirtir. İkincisi göründüğünden daha önemlidir: bir nakshatra sorulan model, gezegen konumlarının efemeris gerektirdiğini söyleyen bir şey yoksa eğitim verisinden akla yatkın bir nakshatra uydurmaktan çekinmez.

İşleyici

node

async function occultApi({ route, body }) {
  const response = await fetch(`${process.env.OCCULT_API_BASE}${route}`, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.OCCULT_API_KEY,   // server-side only
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const payload = await response.json();

  // 402 means out of credits. It is NOT transient - retrying spends nothing
  // and fixes nothing, so surface it rather than backing off.
  if (response.status === 402) {
    return { error: "insufficient_credits", retryable: false };
  }

  // The envelope is the same on every endpoint: branch on is_error, and hand
  // the model the message rather than a stack trace it cannot act on.
  if (payload.is_error) {
    return { error: payload.message, retryable: false };
  }

  return payload.data;
}

Kendinize uyarlarken korumaya değer üç nokta var. Anahtar sunucu tarafında okunur: tarayıcı kodundaki bir anahtarı artık başkası harcıyor demektir. 402 yeniden denenmez: bakiye boş demektir, bekleyip yeniden deneyen bir döngü yalnızca zaman kaybettirir ve hiçbir şeyi düzeltmez. Hata mesajı olduğu gibi iletilir: API hangi alanın hatalı olduğunu söyler ve bu bilgiyi alan model bir sonraki turda kendi isteğini düzeltir.

Modelin keşfetmesi gerektiğinde iki araçlı yapı

Kullanıcılarınız açık uçlu sorular soruyorsa model hangi yola ihtiyaç duyduğunu bilemez. Ona bir arama aracı da verin. Arama kredi harcamaz; yani keşif ücretsizdir, yalnızca yanıt ücretlendirilir.

araç tanımları

[
  {
    "name": "occult_search",
    "description": "Find the right Occult API endpoint by name or by what it calculates, e.g. 'manglik' or 'sunrise'. Returns routes and their request fields. Costs nothing.",
    "input_schema": {
      "type": "object",
      "properties": { "query": { "type": "string" } },
      "required": ["query"]
    }
  },
  {
    "name": "occult_call",
    "description": "Call an Occult API endpoint found with occult_search. One credit per successful call (the PDF reports and chat cost 25); failures are free.",
    "input_schema": {
      "type": "object",
      "properties": {
        "route": { "type": "string" },
        "body": { "type": "object" }
      },
      "required": ["route", "body"]
    }
  }
]

occult_search aracını /llms.txt dosyasına ya da daha kapsamlı /llms-full.txt dosyasına yönlendirin; ikisi de tam bu iş için var. Çatınız araçları bir tanımdan üretiyorsa bir OpenAPI 3.1 tanımı da mevcut.

Tasarlarken önlem almaya değer dört hata

Her hesaplama için ayrı çağrı. Endpoint'lerin çoğu bir keys dizisi alır ve tek istekte, tek krediye birden fazla şey hesaplar. Kendi hâline bırakılan bir model dört kez çağırır ve dört kredi harcar. Bunu araç açıklamasında belirtin.
402'yi yeniden denemek. Bu bir ağ sorunu değil, bakiye sorunudur. İşleyicide yeniden denenemez olarak işaretleyin, çünkü model yalnızca durum koduna bakarak farkı anlayamaz.
Anahtarın istemciye ulaşması. Araçlar sunucunuzda çalışmalıdır. Modelin anahtarı görmesine hiç gerek yoktur; görebildiği her tasarım, anahtarın sızmasına tek bir prompt injection uzaklıktadır.
Uydurulmuş alan adları. Modeller date ya da lat diye tahmin eder. Gerçek alanlar date_time, latitude, longitude ve timezone_as_float. Modelin bunları bir 400 hatasıyla keşfetmesini beklemek yerine açıklamaya yazın.

Gerçek bir çağrı nasıl görünür

curl

curl -X POST https://api.occultapi.com/api/astro/panchanga/ \
  -H 'X-API-Key: yt_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_time": "2026-09-17T06:00:00+05:30",
    "latitude": 26.9124,
    "longitude": 75.7873,
    "timezone_as_float": 5.5,
    "keys": ["tithi", "nakshatra_segments", "yogam", "karana"]
  }'

Dört hesaplama, bir kredi. Yanıt X-Credits-Charged ve X-Credits-Remaining başlıklarını taşır; kendi arayüzünüzde güncel maliyeti göstermenin en ucuz yolu budur.