استخدام Claude Tool Use في TypeScript: دليل تعليمي لـ Agentic Loop

[Alex]: أهلاً بكم من جديد في البودكاست الذكي من نيرد ليفل تك، حيث الشيء الوحيد اللي فيه "loops" أكتر من الكود بتاعنا هو كمية القهوة اللي بيشربها Jamie.

[Jamie]: يا عم، أنا شربت تلات كوبايات بس النهاردة. ده يعتبر يوم هادي جداً بالنسبة لخلايا مخي. [يضحك] على العموم، أنا Jamie.

[Alex]: وأنا Alex. النهاردة، هنتكلم عن حاجة متطورة جداً، وبصراحة ممتعة في التعامل معاها: استخدام الأدوات (tool use) في Claude Sonnet 4.6—تحديداً، إزاي تبني "agentic loop" حقيقي في TypeScript باستخدام Anthropic SDK.

[Jamie]: "Agentic loop"؟ ده اسم تحسه حاجة بتتحبس فيها وأنت بتخلص ورق في مصلحة حكومية.

[Alex]: [يضحك] مش بعيد أوي. تخيل ده: Claude، موديل الذكاء الاصطناعي، عاوز يجاوب على أسئلتك، بس ساعات بيحتاج ينادي أدوات خارجية—زي مثلاً، وظيفة بتعرف حالة الطقس أو ساعة—قبل ما يقدر يديك إجابة أكيدة. جزء الـ "loop" أو الحلقة هو إزاي الكود بتاعك بيخلي المحادثة مستمرة لحد ما Claude يكتفي.

[Jamie]: يعني كأن Claude بيقول، "استنى عليا، خليني أشوف الجو عامل إيه،" وبعدين يستنى السكريبت بتاعنا يشغل الأداة دي قبل ما يكمل؟

[Alex]: بالظبط! هي رقصة بين الطلب والاستجابة. والنهاردة، هنوريكم إزاي تبرمجوا الرقصة دي في TypeScript، بمساعدة بسيطة من Zod عشان التأكد من صحة البيانات (validation)، وAnthropic SDK عشان نكلم Claude.

[Jamie]: عظيم جداً. طيب، الناس محتاجة إيه عشان تتابع معانا؟

[Alex]: أول حاجة، Node.js 24 LTS—يعني أحدث نسخة مستقرة من Node، ولو إن Node 22 شغال برضه لو أنت دماغك ناشفة. هتحتاج مفتاح API من Anthropic، وبصراحة، محتاج ميزانية API بسيطة جداً. تشغيل الموضوع كله هيكلفك أقل من ربع دولار بأسعار Sonnet 4.6.

[Jamie]: أرخص من تالت كوباية قهوة شربتها. مش وحش. [توقف قصير] تمام، خلينا ندخل في التفاصيل. إزاي بنجهز الموضوع ده فعلياً؟

[Alex]: الخطوة الأولى: جهز هيكل المشروع. اعمل فولدر، وشغل `npm init` ، ونزل النسخ المحددة من anthropic-aisdk و zod. ثبت النسخ دي (Pin versions)—لأن الـ SDK بتاع Anthropic بيتحدث كتير، وأنت مش عاوز تغيير مفاجئ بكرة يبوظلك يومك.

[Jamie]: أنا اتعلمت الدرس ده بالطريقة الصعبة. مفيش أسوأ من تحديث SDK مفاجئ يبوظلك يوم الجمعة.

[Alex]: صح جداً. أول ما تجهز المكتبات اللي محتاجها، حط ملف `tsconfig.json` صارم. فيه حاجتين مهمين: `noUncheckedIndexedAccess` عشان يساعد TypeScript يكتشف الحقول الناقصة، و `verbatimModuleSyntax` عشان تخلي الـ imports بتاعتك نضيفة وشغالة تمام على Node 24.

[Jamie]: تمام، كده الأساس جاهز. إيه اللي بعده؟

[Alex]: دلوقتي بتعرف الأدوات بتاعتك. مثلاً، أداة للطقس. كل أداة ليها اسم، ووصف تفصيلي—بجد، Anthropic بتنصح بتلات أو أربع جمل لأي حاجة أعقد من "hello world"—وكمان JSON Schema للمدخلات.

[Jamie]: استنى، ليه الأوصاف الطويلة دي؟ هو Claude بيزهق مثلاً؟

[Alex]: [يضحك] مش بيزهق، بس تقدر تقول... بيتلخبط بسهولة. أوصاف الأدوات بتساعد Claude يقرر إمتى يستخدم أنهي أداة. اعتبرها زي ملف README للذكاء الاصطناعي بتاعك.

[Jamie]: التوثيق (Documentation) الكويس بينقذ الموقف—حتى بالنسبة للروبوتات.

[Alex]: مقدرش أقولها أحسن من كده. فبالنسبة لأداة الطقس، بنستخدم Zod عشان نتأكد من المدخلات—زي المدينة والوحدة. لو Claude حاول يبعت حاجة غريبة، Zod بيمسكها والكود بتاعك يقدر يرجع رسالة خطأ.

[Jamie]: يعني Zod زي "البودي جارد" على باب النادي، بيتأكد إن الناس الصح بس هي اللي بتدخل؟

[Alex]: بالظبط! ولو حد جه ببطاقة مزورة—مثلاً، Claude حاول يبعت "قوس قزح" كوحدة لقياس الحرارة—Zod موجود عشان يطرده بره فوراً. [توقف قصير]

[Jamie]: حلو أوي. تمام، كده عندنا أداة طقس. الـ "agentic loop" بقى بيشتغل إزاي فعلياً؟

[Alex]: هنا بقى المتعة بتبدأ. الحلقة الأساسية بتاعتك بتبعت رسالة لـ Claude—زي مثلاً، "الجو إيه في طوكيو؟" Claude يا إما يجاوب مباشرة أو، في الأغلب، هيرد بـ "tool_use" block بيقول فيه، "أنا عاوز أنادي get_weather بالمدخلات دي."

[Jamie]: يعني Claude أساساً بيدينا قائمة مهام (to-do list).

[Alex]: أيوة. السكريبت بتاعنا بيشغل الأداة، بياخد النتيجة، ويبعتها تاني في "tool_result" block. كرر العملية دي لحد ما الـ stop_reason بتاع Claude يبقى "end_turn"—وده معناه إنه خلص.

[Jamie]: طيب لو Claude عاوز يستخدم أكتر من أداة في نفس الوقت؟ زي مثلاً، "الجو إيه في باريس والساعة كام في طوكيو؟"

[Alex]: سؤال ممتاز! ده اسمه استخدام الأدوات المتوازي (parallel tool use)، وموديلات Claude 4 بتعمل ده تلقائياً. لو الإجابة محتاجة الأداتين، هيجيلك اتنين tool_use blocks في رد واحد. الكود بتاعك لازم يتعامل مع الاتنين، يشغل كل أداة، ويبعت نتايجهم—مع بعض، في مرة واحدة.

[Jamie]: استنى، مع بعض؟ هل فيه تريكة هنا؟

[Alex]: فيه فعلاً. الـ tool_result blocks لازم تيجي الأول في رسالة المستخدم، قبل أي نص. لو لغبطت ده—مثلاً حطيت نص قبل الـ tool_results—Claude هيديك 400 error وهتحس إن شكلك وحش.

[Jamie]: اسألني أنا... [يضحك] [توقف قصير] طيب، عشان نلخص: Claude بيطلب أدوات، إحنا بنشغلها، بنرجع النتائج، والـ loop بتفضل شغالة لحد ما Claude يكتفي؟

[Alex]: هو ده. وعشان تخلي التوازي ده واضح، ضيف أداة تانية—زي أداة "get_time" بترجع الوقت المحلي لمنطقة زمنية معينة. اسأل Claude، "الساعة كام في طوكيو والجو عامل إيه في باريس؟" وشوف الأداتين وهما بيشتغلوا مع بعض بالتوازي.

[Jamie]: هل ممكن يتحبس في حلقة مفرغة (endless loop)؟

[Alex]: نظرياً، أيوة. عشان كده بنحط حد أقصى للمحاولات (turn cap)—مثلاً 10 مرات—عشان لو Claude دخل في حالة فلسفية وفضل يطلب بيانات أكتر.

[Jamie]: "أنا محتاج أعرف نسبة الرطوبة في كل مدينة على كوكب الأرض!" [الاثنين يضحكان]

[Alex]: لو واجهت أسباب توقف غريبة زي "max_tokens" أو "pause_turn"، الـ loop بتاعتك تقدر تلقط الحاجات دي وتحاول تاني أو تنهي الموضوع بشكل شيك.

[Jamie]: تمام، آخر سؤال: إيه اللي يحصل لو Claude أدانا مدخلات غلط—زي مثلاً، "الجو إيه في أطلانتس؟"

[Alex]: Zod هيطلع error، والكود بتاعك هيعلم على الـ tool_result إنها error، وClaude هيقرر يعمل إيه—ممكن يطلب توضيح، أو ممكن يستسلم. الموضوع في الحقيقة منظم جداً.

[Jamie]: عظيم جداً. يعني كده عندك agent loop قوي، متقسم الأنواع (typed)، وبيدعم التوازي، وكل ده في حوالي 140 سطر TypeScript.

[Alex]: وبتحس إنك بتبني Jarvis الخاص بيك. بس مع أمان أكتر في أنواع البيانات (type safety).

[Jamie]: وانفجارات أقل.

[Alex]: ده بيعتمد على إزاي بتتعامل مع الأخطاء (error handling).

[Jamie]: [يضحك] تمام، كده خلصنا حلقة النهاردة من البودكاست الذكي من نيرد ليفل تك. لو جربتوا الموضوع ده، قولولنا إيه الأدوات الغريبة أو الرائعة اللي ربطتوها بـ Claude.

[Alex]: شكراً لمتابعتكم! متنسوش تشتركوا، وتسيبوا تقييم، وتخلوا الـ SDKs بتاعتكم دايماً محدثة. نشوفكم المرة الجاية! [موسيقى النهاية تتلاشى]