Function calling

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

299 araç tanımlamayın

Büyük sağlayıcıların hepsinde araç listesi uzadıkça performans düşer: şemalar daha sohbet başlamadan bağlam penceresini doldurur ve birkaç aracın açıklaması birbirine benzediğinde doğru aracı seçme isabeti azalır. Çoğu aynı dört alanı alan 299 endpoint'le, modelin seçim yapmasını zorlaştırmak için her mesajda binlerce token harcamış olursunuz.

Bir, en fazla 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ı modelin kendisinin yapmamasını söyler; bu da göründüğünden daha önemlidir. Nakshatra sorulan bir model, gezegen konumlarının efemeris gerektirdiğini kimse söylemezse eğitim verisinden makul görünen 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;
}

Kendi kodunuza uyarlarken korumanız gereken üç şey var. Anahtar sunucu tarafında okunur: tarayıcı kodundaki bir anahtar, artık başkasının harcadığı bir anahtardır. 402 yeniden denenmez: bakiyenin boş olduğu anlamına gelir, bekleyip yeniden deneyen bir döngü yalnızca zaman harcar ve hiçbir şeyi düzeltmez. Hata mesajı olduğu gibi aktarılır: API hangi alanın yanlış olduğunu söyler ve bu bilgiyi alan model bir sonraki adımda kendi isteğini düzeltir.

Modelin keşif yapması 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 de arama aracı verin. Arama kredi harcamaz; 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 ya da daha kapsamlı /llms-full.txt dosyasına yönlendirin; ikisi de tam olarak bu iş için var. Framework'ünüz araçları bir şemadan üretiyorsa bir OpenAPI 3.1 tanımı da mevcut.

Önceden önlem almaya değer dört hata

Her hesaplama için ayrı çağrı. Çoğu endpoint 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 sizin sunucunuzda çalışmalıdır. Modelin anahtarı görmesine hiç gerek yoktur; görebildiği her tasarım, anahtarın sızması için tek bir prompt injection'a bakar.
Uydurma alan adları. Modeller date ya da lat diye tahmin eder. Gerçek alanlar date_time, latitude, longitude ve timezone_as_float alanlarıdır. Modelin bunları bir 400 hatasıyla keşfetmesini beklemeyin, 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, tek kredi. Yanıt X-Credits-Charged ve X-Credits-Remaining başlıklarını taşır; kendi arayüzünüzde anlık maliyeti göstermenin en ucuz yolu budur.