Tool Calling — amaliy qo'llanma

Kirish

Nazariyada tool calling sodda: model JSON’da tool nomi va argumentlarni chiqaradi, siz funksiyani chaqirasiz. Amaliyotda uchta muammo takrorlanadi: noto‘g‘ri argument, timeout va parallel chaqiruvni jamlash. Bu dars shu uch joyni kod bilan yopadi.

1. JSON schema va validatsiya

Model erkin matn emas, sxema bo‘yicha JSON chiqarishi kerak. Tool ta’rifida parameters — JSON Schema: type: object, properties va required majburiy, enum tanlovni cheklaydi. Masalan, city — type: string, required, units — enum: ["celsius", "fahrenheit"].

Ishlab chiqarishda zod yoki ajv bilan validatsiya qiling. zod sxemasini yasang, safeParse bilan tekshiring. Validatsiya o‘tmasa tool’ni chaqirmang — "args.city is required" kabi aniq xatoni modelga qaytaring. Bu keyingi urinishni to‘g‘rilaydi.

2. Parallel tool calling

Foydalanuvchi “Toshkent va Samarqand ob-havosini solishtir” desa, model ikkita get_weather chaqiruvini bir javobda chiqaradi. Ularni ketma-ket emas, parallel ishga tushirish kerak — aks holda kechikish ikki baravar ortadi. Har bir chaqiruvga tool_call_id biriktiriladi, natijalarni esa xuddi shu id bilan modelga qaytarasiz.

const calls = response.choices[0].message.tool_calls;
const toolMap = { get_weather, search_docs };

// parallel — har bir tool_call alohida bajariladi
const settled = await Promise.all(calls.map(async (c) => {
  const fn = toolMap[c.function.name];
  const args = JSON.parse(c.function.arguments);
  const data = await fn(args);
  return { tool_call_id: c.id, role: "tool", content: JSON.stringify(data) };
}));
const final = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [...messages, response.choices[0].message, ...settled]
});
return final.choices[0].message.content;

Promise.all ikkita tarmoq so‘rovini bir vaqtda yuboradi, settled natijalarni id bo‘yicha jamlaydi. Tool’lar bog‘liq bo‘lmasa parallel tezroq, bog‘liq bo‘lsa ketma-ket chaqiring.

3. Xatoliklar va retry

Har qanday tashqi chaqiruv xato berishi mumkin. Xatoni turi bo‘yicha ajratib, shunga yarasha harakat qiling.

Qayta urinishni faqat vaqtinchalik xatolarda (timeout, 5xx) ishlating. 4xx va sxema xatolarida retry muammoni takrorlaydi.

async function withRetry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.status >= 400 && e.status < 500) throw e;
      if (i === retries - 1) throw e;
      await new Promise(r => setTimeout(r, 2 ** i * 400));
    }
  }
}

4. Xavfsizlik

Tool — bu kodni ishga tushirish huquqi. Uchta himoyani majburiy qiling.

Ruxsatlar eng kam prinsip bo‘yicha: o‘qish tool’i yozolmaydi. Idempotency — tool_call_id dan idempotency-key yasang. Rate limit uchun p-limit bilan chegaralang. Loglarda argument va natijani saqlang, maxfiy kalitni yozmang.

Xulosa

Amaliy tool calling — bu uch odat: sxemani qattiq yozish va validatsiya qilish, parallel chaqiruvlarni Promise.all bilan jamlash va xatoni turi bo‘yicha to‘g‘ri qayta ishlash. Xavfsizlikni boshidan o‘rnatsangiz, keyingi tool’larni qo‘shish osonlashadi.