استخدام أدوات Claude: كيف أمنح وكلاء الذكاء الاصطناعي قدرات حقيقية

جدول المحتويات

محدَّث يوليو 2026.

ملخص: يتيح استخدام أدوات Claude لوكيلك اتخاذ إجراءات فعلية وليس مجرد توليد النص. تُعرِّف الأدوات كمخططات JSON، ويقرر Claude متى يستدعيها، وينفِّذ كودك الإجراء الحقيقي. الحلقة ثلاث خطوات: إرسال رسالة ← استقبال كتلة tool_use ← تنفيذ وإعادة النتيجة. طبَّقت هذا النمط في أكثر من 15 وكيلاً إنتاجياً على Cloudflare Workers. نقطة الفشل لا تكمن تقريباً في الذكاء الاصطناعي، بل في النتائج الغامضة التي تعود من الأدوات.

[منظور المشغِّل] أُشغِّل أكثر من 30 وكيل ذكاء اصطناعي في بيئة الإنتاج، موزَّعين بين علامة تجارية للاستشارات ومنشأة Pickleland للبيكلبول في بفلوغرفيل، تكساس. يستخدم ما يقارب النصف منها استخدام الأدوات — ميزة واجهة برمجة تطبيقات Claude التي تتيح للنموذج استدعاء الدوال التي يُعرِّفها كودك. إليك النمط الذي توصَّلت إليه بعد النشر والتكرار في الإنتاج.

لماذا يُغيِّر استخدام الأدوات قدرات الوكيل

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

استخدام الأدوات هو الطريقة التي تمنح بها Claude هذا الوصول. تُعرِّف مجموعة من الأدوات كمخططات JSON. يقرأ Claude المخططات، ويقرر أي أداة يستدعي وبأي وسائط، ويُعيد كتلة محتوى tool_use منظَّمة. ينفِّذ كودك الدالة الفعلية. يحصل Claude على النتيجة ويقرر ما يفعله بعد ذلك — بما في ذلك استدعاء أداة أخرى أو توليد استجابة نصية نهائية.

المفتاح: يقرر Claude متى وما إذا كان سيستدعي أداة. أنت تُعرِّف القدرات. يستنتج النموذج متى يستخدمها.

كيف يعمل تدفق واجهة برمجة التطبيقات

حلقة استخدام الأدوات لها ثلاث خطوات. ستُشغِّل هذه الحلقة مرة واحدة أو أكثر حسب عدد استدعاءات الأدوات التي يُجريها النموذج.

الخطوة 1: أرسل رسالتك مع تعريف الأدوات

const response = await anthropic.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 1024,
  tools: [
    {
      name: "check_court_availability",
      description:
        "Check if a court is available at a given date, time, and duration",
      input_schema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            description: "Date in YYYY-MM-DD format",
          },
          time: {
            type: "string",
            description: "Start time in HH:MM format (24h)",
          },
          duration_minutes: {
            type: "number",
            description: "Duration of the booking in minutes",
          },
        },
        required: ["date", "time", "duration_minutes"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Is a court available tomorrow at 2pm for 90 minutes?",
    },
  ],
});

الخطوة 2: تحقق مما إذا كان Claude يريد استدعاء أداة

if (response.stop_reason === "tool_use") {
  const toolUseBlock = response.content.find(
    (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
  );

  if (!toolUseBlock) throw new Error("Expected tool_use block");

  // Run your actual function
  const toolResult = await checkCourtAvailability(
    toolUseBlock.input as CourtAvailabilityInput
  );

  // Step 3: Return the result to Claude
  const finalResponse = await anthropic.messages.create({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 1024,
    tools: [
      /* same tools as before */
    ],
    messages: [
      {
        role: "user",
        content: "Is a court available tomorrow at 2pm for 90 minutes?",
      },
      { role: "assistant", content: response.content },
      {
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolUseBlock.id,
            content: JSON.stringify(toolResult),
          },
        ],
      },
    ],
  });

  // finalResponse.content now has the text answer
}

هذا هو النمط بالكامل. ثلاث تفاعلات مع واجهة برمجة التطبيقات لكل استدعاء أداة: تعريف الأدوات ← استقبال كتلة tool_use ← إعادة النتيجة.

مثال حقيقي: مدقق توافر Pickleland

Pickleland منشأة للبيكلبول. نتلقى استفسارات الحجز عبر Facebook Messenger والتعليقات وروبوت المحادثة. السؤال دائماً تقريباً تنويع على “هل أنتم مفتوحون السبت الساعة 3 مساءً؟” أو “هل يمكنني حجز ملعب لمجموعتي المكوَّنة من 8 أشخاص؟”

يستخدم وكيل مدقق التوافر أداة الاستخدام للاستعلام عن نظام الحجز الحقيقي في الوقت الفعلي بدلاً من إعطاء إجابة جاهزة.

إليك الوكيل الكامل — مبسَّط لكن دقيق للإنتاج:

// workers/availability-checker.ts
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const AVAILABILITY_TOOLS: Anthropic.Tool[] = [
  {
    name: "check_availability",
    description:
      "Check court availability for a date, time, and group size. Returns available courts and their prices.",
    input_schema: {
      type: "object",
      properties: {
        date: { type: "string", description: "YYYY-MM-DD" },
        start_time: { type: "string", description: "HH:MM (24h)" },
        duration_minutes: { type: "number" },
        players: { type: "number", description: "Number of players" },
      },
      required: ["date", "start_time", "duration_minutes"],
    },
  },
  {
    name: "get_pricing",
    description:
      "Get current pricing for court rentals and open play sessions",
    input_schema: {
      type: "object",
      properties: {
        session_type: {
          type: "string",
          enum: ["court_rental", "open_play", "clinics"],
        },
      },
      required: ["session_type"],
    },
  },
];

export async function handleInquiry(
  userMessage: string,
  env: Env
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  // Agentic loop — keep going until stop_reason is "end_turn"
  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-haiku-4-5-20251001",
      max_tokens: 512,
      system:
        "You are the booking assistant for Pickleland, a pickleball facility in Pflugerville, TX. " +
        "Use the tools to look up real availability and pricing. Never make up availability or prices. " +
        "If the customer wants to book, direct them to pickleland.com/book.",
      tools: AVAILABILITY_TOOLS,
      messages,
    });

    // Push the assistant's response into message history
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find(
        (b): b is Anthropic.TextBlock => b.type === "text"
      );
      return (
        textBlock?.text ??
        "I wasn't able to answer that — please call us directly."
      );
    }

    if (response.stop_reason === "tool_use") {
      // Process ALL tool calls in this response (Claude can request multiple at once)
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type !== "tool_use") continue;

        let result: unknown;

        switch (block.name) {
          case "check_availability":
            result = await checkAvailability(
              block.input as AvailabilityInput,
              env
            );
            break;
          case "get_pricing":
            result = await getPricing(block.input as PricingInput, env);
            break;
          default:
            result = { error: `Unknown tool: ${block.name}` };
        }

        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result),
        });
      }

      // Return all tool results in a single user message
      messages.push({ role: "user", content: toolResults });
    }
  }
}

نقطتان تستحقان الإشارة هنا.

الحلقة الوكيلية. أستمر حتى stop_reason === "end_turn". قد يستدعي Claude أداة check_availability، ثم يقرر أنه يحتاج أيضاً إلى الأسعار، فيستدعي get_pricing، ثم يولِّد الإجابة النهائية — هذه ثلاث استدعاءات لواجهة برمجة التطبيقات لرسالة مستخدم واحدة. تتعامل الحلقة مع هذا دون أي منطق خاص.

استدعاءات أدوات متعددة في الدور الواحد. يمكن لـ Claude إعادة كتل tool_use متعددة في استجابة واحدة. أعالجها جميعاً وأُعيد جميع النتائج في رسالة user واحدة. إذا عالجتها واحدة تلو الأخرى وأعدتها بشكل فردي، فستُعطِّل تدفق المحادثة وتُهدر الرموز.

مثال حقيقي: وكيل بحث العملاء المحتملين

تستخدم علامتي التجارية الاستشارية وكيل بحث يُثري العملاء المحتملين الواردين قبل التحدث معهم. عندما يملأ شخص ما نموذج الاتصال، يبحث الوكيل عن شركته ويستخرج ما أحتاج معرفته قبل المكالمة.

تشمل تعريفات الأدوات لهذا الوكيل أداة كتابة — وهنا يصبح النمط مثيراً للاهتمام:

const RESEARCH_TOOLS: Anthropic.Tool[] = [
  {
    name: "search_company",
    description: "Search for information about a company",
    input_schema: {
      type: "object",
      properties: {
        company_name: { type: "string" },
        website: { type: "string", description: "Company website if known" },
      },
      required: ["company_name"],
    },
  },
  {
    name: "save_research",
    description:
      "Save the completed research summary to Airtable. Call this when all research is complete.",
    input_schema: {
      type: "object",
      properties: {
        company_summary: { type: "string" },
        estimated_size: {
          type: "string",
          enum: ["1-10", "11-50", "51-200", "200+"],
        },
        likely_use_case: { type: "string" },
        priority: { type: "string", enum: ["high", "medium", "low"] },
        notes: { type: "string" },
      },
      required: [
        "company_summary",
        "estimated_size",
        "likely_use_case",
        "priority",
      ],
    },
  },
];

save_research هي ما أسمِّيه أداة الكتابة — غرضها ليس جلب المعلومات، بل تثبيت مخرجات Claude في قاعدة البيانات بشكل منظَّم. أستخدم هذا النمط بدلاً من محاولة تحليل JSON من استجابة نصية. يعرف Claude متى اكتمل البحث فيستدعي save_research بحقول مكتوبة بشكل صحيح. لا أكتب محلِّلاً قط.

هذا هو التطبيق الأنظف لاستخدام الأدوات: عرِّف أداة “الإجراء النهائي” بالمخطط الدقيق الذي تريده، وسيُقدِّم Claude مخرجات منظَّمة عبر استدعاء الأداة. لا تحليل للنص، ولا تعابير نمطية، ولا تحقق JSONSchema من المخرجات النصية الحرة.

أداة واحدة مقابل أدوات متعددة

الغريزة عند البدء باستخدام الأدوات هي بناء أداة ضخمة واحدة تفعل كل شيء. قاوم هذا. الأدوات الصغيرة المركَّزة أفضل لثلاثة أسباب:

1. يستنتج Claude أفضل بشأن الأدوات الصغيرة. أداة باسم get_court_status تُعيد التوافر أسهل على النموذج معالجتها من أداة manage_facility تأخذ معامل mode وتتفرع داخلياً.

2. الأدوات الصغيرة أسهل في الاختبار. كل أداة هي دالة TypeScript يمكنك اختبارها وحدةً باستقلالية عن النموذج اللغوي الكبير. يجب عليك ذلك — أخطاء الأدوات يصعب تصحيحها داخل محادثة نشطة.

3. يمكن لـ Claude توازي الأدوات الصغيرة. إذا كانت أداتان لا تعتمدان على بعضهما، يجوز لـ Claude استدعاؤهما في نفس الاستجابة وتعالجهما بالتوازي. يعمل هذا فقط إذا كانت الأدوات مستقلة حقاً.

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

قاعدتي العملية: ابدأ بأداة واحدة لكل قدرة مستقلة. ادمج الأدوات فقط عندما ترى Claude يستدعيها معاً في كل طلب.

تداعيات التكلفة

يضيف استخدام الأدوات رموزاً. يدخل كل تعريف أداة في سياق موجِّه النظام. تستهلك كل كتلة tool_use وtool_result رموزاً في تاريخ المحادثة. لحلقة وكيلية متعددة الأدوار، يتراكم هذا بسرعة.

بالنسبة لمدقق توافر Pickleland، تُنفِّذ المحادثة النموذجية 3-4 استدعاءات لواجهة برمجة التطبيقات إجمالاً (الرسالة الأولية + 1-2 استدعاء أداة + الإجابة النهائية)، كل منها يعالج 600-900 رمز. بأسعار Haiku، يبلغ تكلفة أقل من 0.001 دولار لكل استفسار. كما أوضحت في منشور حساب تكلفة وكلاء الذكاء الاصطناعي، يتعامل Haiku مع مهام استدعاء الأدوات المحددة بشكل موثوق وأرخص بـ 10 مرات من Sonnet لنفس حجم الرموز.

يعمل وكيل بحث العملاء المحتملين على Sonnet لأن قرارات الحكم — ترتيب أولويات العميل المحتمل، وتقدير الملاءمة — تتطلب قدرة استنتاج أعلى مما يُقدِّمه Haiku بشكل موثوق على المدخلات المفتوحة. يعمل الحساب رغم ذلك لأنه يعمل بشكل غير متكرر (بضع مرات في الأسبوع، لا الآلاف يومياً). يتبع اختيار النموذج تعقيد المهمة، لا التفضيل الشخصي.

نقطة الفشل التي لا يتحدث عنها أحد

نقطة الفشل الأكثر شيوعاً التي أراها في استخدام الأدوات الإنتاجي ليست Claude يستدعي الأداة الخاطئة. إنها الأداة التي تُعيد شيئاً لا يستطيع Claude الاستنتاج بشأنه بوضوح.

إذا أعادت أداتك كائن قاعدة بيانات خاماً بـ 40 حقلاً، يرتبك Claude في تحديد الحقول المهمة. إذا رمت أداتك استثناءً (يظهر كعطل في Worker لا كنتيجة أداة)، تنكسر الحلقة بصمت. إذا أعادت أداتك null بمعنى “لا نتائج”، لا يعرف Claude إذا كان يجب إعادة المحاولة أو الاستسلام.

ثلاث قواعد لنتائج الأدوات:

أعِد نتائج موجزة وصريحة. { available: true, courts: ["Court 3", "Court 5"], price_per_hour: 20 } — لا صف قاعدة البيانات الكامل.

التقط الأخطاء داخل دالة الأداة وأعدها كنتائج منظَّمة. { error: "booking system timeout", retry: true } — لا استثناء مُرمى يُعطِّل Worker.

اجعل “لا نتائج” صريحاً. { available: false, next_available: "2026-07-23T14:00:00Z" } — لا null ولا مصفوفة فارغة بدون سياق.

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

خلاصة المشغِّل

استخدام الأدوات هو الميزة التي تحوِّل Claude من مولِّد نصوص إلى مشغِّل. عرِّف أدوات مركَّزة بمخططات إدخال واضحة. عالج جميع كتل tool_use في استجابة واحدة للنموذج. شغِّل الحلقة الوكيلية حتى stop_reason === "end_turn". أعِد نتائج نظيفة وموجزة من دوال أداواتك — لا كائنات بيانات خام، ولا استثناءات مُرماة، ولا قيم null غامضة.

يتولى النموذج الاستنتاج. يتولى كودك الإجراءات الحقيقية. احتفظ بهذين الدورين منفصلَين بوضوح يظل الهيكل قابلاً للصيانة حتى مع إضافة الأدوات.

إذا كنت تبني أول وكيل باستخدام الأدوات، ابدأ بنمط مدقق التوافر أعلاه — أداة واحدة، غرض واحد، حلقة وكيلية واحدة. انشر ذلك. ثم أضف الأداة الثانية.

ذات صلة: حزمة الوكلاء التي أستخدمها لتشغيل 30+ وكيلاً إنتاجياً · Haiku مقابل Sonnet: حساب التكلفة لمهام الوكلاء · وكلاء الأحداث المُشغَّلة مقابل المجدوَلة: أي نمط لأي عمل

هل تبني وكيلاً باستخدام الأدوات وتواجه عقبات؟ تواصل معي — أصمِّم وأبني هياكل وكلاء الإنتاج لفرق المشغِّلين.

الأسئلة الشائعة

هل يعمل استخدام أدوات Claude مع جميع النماذج؟

نعم — يُدعَم استخدام الأدوات على جميع نماذج Claude الحالية. يتعامل Claude Haiku بموثوقية مع الأدوات المحددة جيداً ذات المخططات الواضحة، وهو الخيار الأرخص لأنواع المهام ذات الحجم الكبير. يتعامل Sonnet بشكل أفضل مع قرارات استدعاء الأدوات الأكثر غموضاً أو انفتاحاً. ابدأ بـ Haiku؛ انتقل للأعلى إذا كانت جودة المخرجات غير كافية.

ما الفرق بين استخدام أدوات Claude واستدعاء الدوال في OpenAI؟

متطابقان من الناحية الميكانيكية. ابتكر OpenAI مصطلح “function calling”؛ يسمِّيه Anthropic “tool use”. في كلتا الحالتين: تُعرِّف مخططات JSON، يُعيد النموذج استدعاءات منظَّمة، وينفِّذ كودك الدالة. تتباين صيغة واجهة برمجة التطبيقات لكن المفهوم واحد.

هل يمكن لـ Claude استدعاء أدوات متعددة في استجابة واحدة؟

نعم. يمكن لـ Claude إعادة كتل tool_use متعددة في استجابة assistant واحدة. عالجها جميعاً وأعِد جميع النتائج في رسالة user واحدة. راجع نمط الحلقة الوكيلية في مثال Pickleland أعلاه — يتعامل حلقة for على response.content مع هذا بشكل صحيح.

كم عدد الأدوات التي يجب أن أعرِّفها لكل وكيل؟

أبقي على أقل من 8-10 أدوات لكل وكيل. وراء ذلك، رأيت Claude أحياناً يختار الأداة الخاطئة في المحاولة الأولى، مما يُهدر الرموز في حلقة تصحيح. إذا كنت تحتاج إلى أكثر من 10 قدرات، قسِّم الوكيل إلى وكلاء متعددة بمجموعات أدوات متخصصة بدلاً من بناء وكيل يعرف كل شيء.

هل يجب أن أستخدم استخدام الأدوات للحصول على مخرجات منظَّمة؟

نعم — نمط أداة الكتابة save_research أنظف من طلب Claude إعادة JSON في كتلة نصية ثم تحليله. عرِّف أداة “الإجراء النهائي” بالمخطط الدقيق الذي تريده. سيستدعيها Claude بحقول مكتوبة بشكل صحيح عند الانتهاء. لا حاجة لمحلِّل.