استدعاء الأدوات في Claude API لا يعني أن النموذج يشغل كل دالة داخل تطبيقك تلقائيًا. في الأدوات التي ينفذها تطبيقك، يطلب النموذج عملية منظمة ثم ينفذ التطبيق الوظيفة ويعيد نتيجتها قبل استمرار الإجابة. هذا دليل للتحضير لعام 2027 وفق الوثائق المتاحة في 27 أكتوبر 2026، وليس وعدًا بثبات الواجهة أو أسعارها مستقبلًا.
من التعريف إلى طلب التنفيذ
تصف الأداة باسمها ووظيفتها ومخطط input_schema للمدخلات. وعندما يختارها النموذج، تتضمن الاستجابة كتلة tool_use باسم الأداة و input ومعرف id خاص بذلك الاستدعاء، ويكون stop_reason هو tool_use في المسار المعتاد لأدوات التطبيق.
اقرأ جميع كتل المحتوى، فقد تحتوي الاستجابة نصًا واستدعاءً أو أكثر. لا تفترض أن أول كتلة هي طلب الأداة، ولا تستخدم الاسم وحده لربط النتيجة إذا استدعيت الأداة نفسها أكثر من مرة.
إعادة النتيجة بترتيب صحيح
بعد التنفيذ، أعد كتلة tool_result داخل رسالة بدور user، واجعل tool_use_id يطابق id الذي جاء في طلب الأداة. احتفظ برسالة assistant الأصلية وكتلها في سجل المحادثة، ثم أضف رسالة النتائج بعدها مباشرة دون إدخال رسالة أخرى بينهما.
تأتي كتل tool_result أولًا داخل مصفوفة محتوى رسالة النتائج، ويأتي أي نص إضافي بعدها في حالة الأدوات التي ينفذها التطبيق وحدها. وضع النص قبل النتائج أو فقد معرف مطابق قد يؤدي إلى رفض الطلب، لا إلى إجابة ناقصة فقط.
الخطأ ليس نتيجة ناجحة
عندما تفشل الوظيفة، يمكن إرجاع is_error بقيمة true مع وصف محدد للمشكلة داخل النتيجة. أخبر النموذج بما حدث فعلًا بدل اختلاق قيمة افتراضية تبدو كاستجابة صحيحة. وراجع تعريف الأداة ووصفها عند تكرار طلب مدخلات ناقصة أو غير مناسبة.
وبعد إرسال النتائج، افحص stop_reason مجدّدًا: قد يطلب النموذج أدوات أخرى. أما max_tokens أو refusal أوغيرهما فلا يعامل تلقائيًا كإجابة نهائية مكتملة لمجرد أنه ليس tool_use.
الأدوات التي يديرها الخادم
تختلف أدوات البحث أو التنفيذ التي يديرها الخادم عن دوال التطبيق؛ لا تصنع لها tool_result يدويًا كأنك نفذتها. وقد يتوقف مسارها مع pause_turn، وعندئذ يستكمل بإعادة المحادثة بما فيها الاستجابة المتوقفة وفق نمط الاستمرار.
وإذا جمعت الاستجابة طلب أداة من تطبيقك مع server_tool_use لم يصل ناتجه بعد، أعد رسالة تحتوي نتائج أدوات التطبيق فقط مع الإبقاء على تعريفات الأدوات نفسها، دون نص إضافي ينهي المسار مبكرًا.
حدود الثقة
قد تتضمن نتائج صفحات الويب أو الملفات تعليمات مزروعة. تعامل معها كمحتوى خارجي غير موثوق واحتفظ بها داخل tool_result بدل نقلها إلى تعليمات النظام. ونجاح تنسيق الاستدعاء لا يغني عن التحقق من المدخلات وصلاحيات العملية قبل تنفيذ تغيير ذي أثر.
