إنتقل إلى المحتوى الرئيسي

استخدام الأدوات / استدعاء الدوال

متوسط

يتيح استخدام الأدوات لـ Claude استدعاء دوال تُعرّفها أنت — بحث، أو آلة حاسبة، أو قاعدة بياناتك، أو أي واجهة برمجية — واستخدام النتائج. إنه أساس كل وكيل.

What you'll learn
  • كيف تعمل الحلقة الوكيلة المكوّنة من أربع خطوات، من تعريفات الأدوات إلى الإجابة النهائية
  • كيف تعرّف أداة في Python باسم ووصف ومدخل بصيغة JSON-Schema
  • لماذا تعمل أوصاف الأدوات كمطالبات تشكّل متى وكيف يستدعيها Claude
  • كيف تتحقق من المدخلات، وتعيد الأخطاء كنتائج، وتستخدم الأدوات من جهة الخادم بأمان

الحلقة​

استخدام الأدوات محادثة، وليس استدعاءً واحدًا. أنت تُسلّم Claude قائمة من الأدوات؛ يختار Claude واحدة ويتوقّف؛ تشغّلها أنت وتُبلّغ بالنتيجة؛ يدمج Claude النتيجة في إجابته — مكرّرًا ذلك حسب الحاجة.

Guided walkthrough1 of 4
  1. تُضمّن قائمة من تعريفات الأدوات — لكل منها اسم ووصف ومدخل بصيغة JSON-Schema.

تعريف أداة (Python)​

تعريف الأداة هو مجرد اسم، ووصف بلغة بسيطة، ومدخل بصيغة JSON-Schema. مرّره في tools، ثم تحقّق من stop_reason لتعرف متى يريد Claude أن يتصرف.

أداة get_weather + الاستدعاء الأول

tools = [{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
  },
}]

msg = client.messages.create(
  model="claude-sonnet-5", max_tokens=1024,
  tools=tools,
  messages=[{"role": "user", "content": "What's the weather in Rome?"}],
)
# If msg.stop_reason == "tool_use": run the tool, then send a tool_result back.

نصائح​

الخيارات الصغيرة في كيفية تعريفك للأدوات والتعامل معها تُحدث فرقًا كبيرًا في الموثوقية.

  • الأوصاف مطالبات. وصف description واضح للأداة وتوثيق المعاملات يحسّنان كثيرًا متى وكيف يستدعيها Claude.
  • تحقّق من المدخلات التي تتلقّاها قبل التنفيذ — لا تثق بها بشكل أعمى أبدًا.
  • أعِد الأخطاء كنتائج. إذا أخفقت أداة، أرسل tool_result يصف الخطأ كي يتمكّن Claude من التعافي.
  • أدوات من جهة الخادم. تقدّم Anthropic أيضًا أدوات مدمجة (مثل البحث على الويب، وتنفيذ الشيفرة، واستخدام الحاسوب) — راجع الوثائق للاطّلاع على القائمة الحالية.

:::warning الأدوات = إجراءات = مخاطر أي أداة تتّخذ إجراءات حقيقية ترث نموذجًا أمنيًا. طبّق أقل صلاحية ممكنة وأبقِ إنسانًا ضمن الحلقة للاستدعاءات الخطرة — راجع تأمين الوكلاء والأدوات. :::

مفردات استخدام الأدوات
اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.
1 / 4

اختبر نفسك

0/3
  1. بعد أن يعيد Claude كتلة tool_use، من الذي يشغّل الأداة؟
  2. أداة عرّفتها تخفق أثناء التشغيل. ما الإجراء المُوصى به؟
  3. لماذا يهم وصف الأداة الواضح إلى هذا الحد؟
Key takeaways
  • استخدام الأدوات حلقة: أرسل تعريفات الأدوات، يعيد Claude كتلة tool_use ويتوقّف، أنت تنفّذ وتعيد tool_result، يتابع Claude حتى يجيب.
  • تعريف الأداة هو اسم ووصف ومدخل بصيغة JSON-Schema — مرّره في tools وتحقّق من stop_reason == tool_use.
  • الأوصاف مطالبات؛ تحقّق من المدخلات قبل التنفيذ؛ أعِد حالات الإخفاق كأخطاء tool_result كي يتمكّن Claude من التعافي.
  • تقدّم Anthropic أيضًا أدوات من جهة الخادم، وأي أداة تتّخذ إجراءات حقيقية تحتاج إلى أقل صلاحية ممكنة إضافةً إلى إنسان ضمن الحلقة.

التالي​