استدعاء الأدوات والدوال عبر API في كل صيغة

يتيح استدعاء الأدوات للنموذج أن يطلب من برنامجك تشغيل دالة، مثل جلب حالة الطقس أو البحث في قاعدة بياناتك، ثم يجيب بالنتيجة. النموذج لا يشغّل شيئًا بنفسه: يعيد اسم الدالة ووسائطها، فيشغّلها برنامجك، ثم ترسل النتيجة في الطلب التالي.

الدورة#

1. 1

   صِف أدواتك#

   أرسل قائمة أدوات في الطلب، لكل أداة اسم ووصف ومخطط JSON Schema لوسائطها. الوصف الواضح هو ما يجعل النموذج يختار الأداة الصحيحة.

2. 2

   اقرأ الاستدعاء#

   حين يحتاج النموذج أداة يحمل الرد استدعاءً فيه اسم الأداة ووسائطها بدلًا من إجابة نهائية، ويدل سبب التوقف على ذلك.

3. 3

   شغّلها وأرسل النتيجة#

   شغّل الدالة في برنامجك، ثم أرسل طلبًا جديدًا بالمحادثة كاملة: استدعاء النموذج، ثم نتيجتك مربوطة بمعرّف الاستدعاء. بعدها يجيب النموذج، أو يستدعي أداة أخرى.

الأداة نفسها في كل صيغة#

• Chat Completions: الأدوات في tools مع type: "function" وfunction.parameters. يصل الاستدعاء في message.tool_calls مع finish_reason: "tool_calls". أرسل النتيجة رسالةً بالدور role: "tool" ومعها tool_call_id.
• Responses: الأدوات في tools مع type: "function" وparameters. الاستدعاء عنصر في output من نوع function_call ومعه call_id. أرسل النتيجة عنصرًا في input من نوع function_call_output بالقيمة نفسها لـ call_id.
• Messages: الأدوات في tools مع input_schema. الاستدعاء كتلة tool_use مع stop_reason: "tool_use". أرسل النتيجة كتلة tool_result في رسالة user ومعها tool_use_id.
• Gemini: الأدوات في tools مع functionDeclarations. الاستدعاء جزء functionCall. أرسل النتيجة جزء functionResponse في دور user.

طلبات كاملة مع ردودها المسجّلة: Chat Completions وResponses وMessages وGemini.

إرسال النتيجة#

في Chat Completions يكرر الطلب الثاني المحادثة، ويضيف استدعاء النموذج كما وصل، ثم نتيجتك:

[
  { "role": "user", "content": "What is the weather in Cairo?" },
  { "role": "assistant", "content": null, "tool_calls": [
    { "id": "call_1", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Cairo\"}" } }
  ] },
  { "role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 31, \"sky\": \"clear\"}" }
]

وفي Messages يكون الاستدعاء والنتيجة كتلًا:

[
  { "role": "user", "content": "What is the weather in Cairo?" },
  { "role": "assistant", "content": [
    { "type": "tool_use", "id": "toolu_1", "name": "get_weather", "input": { "city": "Cairo" } }
  ] },
  { "role": "user", "content": [
    { "type": "tool_result", "tool_use_id": "toolu_1", "content": "{\"temp_c\": 31, \"sky\": \"clear\"}" }
  ] }
]

ما تدعمه كل عائلة#

• كل العائلات تقبل tools في Chat Completions وMessages، ونماذج Claude وGPT تقبلها في Responses.
• فرض أداة بعينها عبر tool_choice يعمل مع Claude وGPT. أما نماذج Gemini فتختار بنفسها في Chat Completions وMessages، ومع generateContent استخدم toolConfig.
• للحقل parallel_tool_calls أثر مع نماذج GPT فقط. قد تستدعي نماذج Claude عدة أدوات في رد واحد، فعالج كل الاستدعاءات قبل أن تجيب.
• للحصول على إجابة JSON من Claude عرّف أداة واحدة مخططها هو الشكل الذي تريده، وافرضها عبر tool_choice، فتكون الوسائط هي بيانات JSON التي تريدها.

نصائح#

• تحقق من الوسائط قبل أن تشغّل أي شيء، فقد يرسل النموذج قيمة غير صحيحة.
• اجعل نتائج الأدوات قصيرة ومحددة، فالنتائج الطويلة تكلّف توكنات إدخال في كل طلب لاحق.
• أعد الأخطاء نتائجَ، مثل {"error": "city not found"}، ليتمكن النموذج من التصرف.