المستوى: متوسط — هذا المقال يفترض إنك جربت Tool Use قبل كده، عارف ايه هي الـ system prompt، وقريت ولو سطرين Python. لو لسه ما اشتغلتش على tools خالص، ابدأ من توثيق Anthropic الأساسي قبل ما ترجع للمقال ده.

AI Agents في الإنتاج: ليه الوكلاء بيدخلوا في حلقات لا نهائية وازاي توقفهم

لو بنيت وكيل AI بيستدعي tools ومن غير سبب واضح بيفضل يعمل نفس الـ tool call 47 مرة لحد ما الـ context يفيض أو فاتورة Anthropic توصل 280 دولار في طلب واحد، انت مش لوحدك. تقرير Galileo State of AI Agents في 2025 لقي إن 73% من الوكلاء اللي بيوصلوا production بيفشلوا في أول 90 يوم لأسباب معمارية مش جودة النموذج. المقال ده هيوريك ازاي تبني loop آمن، وكام علامة إن وكيلك بدأ يدور حوالين نفسه، وامتى تستبدل الـ agent بـ pipeline تقليدي.

المشكلة باختصار

الـ AI Agent مش chatbot. هو نموذج بياخد قرار في كل دورة: "اعمل tool A؟ اعمل tool B؟ ولا ارد على المستخدم؟". القرار ده بيتكرر في حلقة لحد ما الوكيل يقرر يخلّص. لو القرار غلط في الـ loop، الوكيل ممكن يعمل نفس الخطوة 50 مرة بدون ما يلاحظ.

المشكلة دي مش نظرية. على مشروع دعم فني عربي عندنا 1,800 تذكرة شهرياً، أول agent بنيناه بـ Claude Sonnet 4.6 دخل في حلقة لمدة 38 دقيقة قبل ما يصل لـ max_tokens. التذكرة الواحدة كلّفت $4.20 بدل المتوقع $0.03. الـ pattern ده اتسمى "Reasoning Loop" في ورقة Galileo، وهو السبب رقم 1 لفشل الوكلاء في 2026.

مثال للمبتدئ: المهندس اللي بيصلّح سيارة

تخيّل مهندس صيانة جديد، واقف قدام سيارة معطّلة، ومعاه 5 أدوات: مفك، مفتاح إنجليزي، مالتي ميتر، كمبيوتر تشخيص، وكتاب التعليمات. خطواته الطبيعية كده:

1. يفكّر: "السيارة مش بتشغّل، يمكن البطارية".
2. يستخدم المالتي ميتر يقيس الجهد.
3. يلاحظ النتيجة: 12.4 فولت — البطارية سليمة.
4. يفكّر تاني: "ماشي، يمكن البنزين".
5. يفتح خزّان البنزين.

الـ AI Agent بيشتغل بنفس الطريقة بالظبط. بيفكّر، بيختار أداة، بياخد ملاحظة، يفكّر تاني. المشكلة اللي بتحصل: لو المالتي ميتر بيدّيله نفس القراءة الغلط مرة ورا مرة، المهندس المبتدئ ممكن يقعد ساعة يقيس البطارية بدل ما يقول "خلاص، البطارية مش هي المشكلة، خليني أجرّب حاجة تانية". الوكيل بيقع في نفس الفخ بالظبط. هو محتاج آلية تقوله "بطّل اللي بتعمله ده، جرّب حاجة جديدة".

الفرق بين مهندس متمرّس ومبتدئ مش في عدد الأدوات، الفرق في إنه بيعرف امتى يبطّل. الـ agent اللي بتبنيه لازم تديله نفس الذكاء ده — بشكل صريح في الكود، مش بالاعتماد على الـ LLM إنه "هيفهم لوحده".

تعريف علمي: ReAct Pattern

الـ pattern الأساسي لمعظم الوكلاء حالياً اسمه ReAct، اتنشر في ورقة Yao et al. 2022 من Princeton و Google Research. الفكرة بسيطة: في كل دورة، النموذج بيكتب 3 حاجات بالترتيب:

• Thought: سطر تفكير داخلي بيشرح ليه هياخد الخطوة دي.
• Action: اسم الـ tool + arguments.
• Observation: نتيجة الـ tool زي ما رجعت من النظام الخارجي.

الـ loop بيكمّل لحد ما النموذج يكتب "Final Answer" بدل Action جديدة. الـ implementation في Anthropic SDK 0.49+ بيخفي الـ Thought/Action/Observation في content blocks منفصلة (text + tool_use + tool_result)، لكن الـ structure نفسه.

الافتراض الصامت في ReAct: النموذج ذكي بما يكفي يلاحظ إن الـ Observation اللي بترجع مش بتقدّم في حل المشكلة. الواقع: مش دايماً، خصوصاً لو الـ tool بيرجّع نفس الـ payload بفروقات بسيطة، أو لو السؤال محتاج تفكير متعدّد المستويات.

الكود: agent بـ max_iterations و loop detection

ده كود تنفيذي شغّال على anthropic SDK 0.49 و Claude Sonnet 4.6. الفكرة بسيطة: نحدّ عدد الدورات بـ MAX_ITERATIONS، نعمل hash لكل tool call، ونوقف لو نفس الـ hash اتكرّر 3 مرات.

import hashlib
from anthropic import Anthropic

client = Anthropic()
MAX_ITERATIONS = 14
LOOP_THRESHOLD = 3

def call_signature(name, input_dict):
    raw = f"{name}::{sorted(input_dict.items())}"
    return hashlib.md5(raw.encode()).hexdigest()[:10]

def run_agent(user_message, tools, tool_executor):
    messages = [{"role": "user", "content": user_message}]
    call_counts = {}

    for iteration in range(MAX_ITERATIONS):
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )

        if response.stop_reason == "end_turn":
            return response.content[-1].text

        tool_blocks = [b for b in response.content if b.type == "tool_use"]
        if not tool_blocks:
            return "no_action_taken"

        messages.append({"role": "assistant", "content": response.content})
        tool_results = []

        for block in tool_blocks:
            sig = call_signature(block.name, block.input)
            call_counts[sig] = call_counts.get(sig, 0) + 1

            if call_counts[sig] >= LOOP_THRESHOLD:
                return f"loop_detected: {block.name} repeated {call_counts[sig]}x"

            result = tool_executor(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(result),
            })

        messages.append({"role": "user", "content": tool_results})

    return "max_iterations_exceeded"

الكود ده فيه 3 خطوط دفاع:

1. MAX_ITERATIONS = 14: حد أقصى مطلق. مفيش مهمة دعم فني محتاجة 50 خطوة.
2. call_signature: hash للـ tool name + arguments. لو نفس الاستدعاء بنفس المدخلات اتكرر، الـ hash بيكون نفسه.
3. LOOP_THRESHOLD = 3: لو نفس tool call اتكرر 3 مرات على نفس الـ arguments، احنا في حلقة. خروج فوري ورجوع للإنسان.

لاحظ إن الكود مش بيحاول يصلّح الـ loop، هو بيكسره. ده مقصود. محاولة إصلاح loop داخل الـ agent نفسه بتضاعف التكلفة في 90% من الحالات بدون ما تحل المشكلة الأصلية.

أرقام مقاسة على إنتاج فعلي

الأرقام دي من بيئة دعم فني عربي على 1,800 تذكرة شهرياً، خلال 30 يوم من تشغيل الـ agent. كل القياسات على Claude Sonnet 4.6 مع 8 tools (PostgreSQL query، Zendesk ticket fetch، knowledge base search، email send، order lookup، billing check، refund initiate، human handoff).

التحسّن في معدل النجاح من 71% لـ 82% مش بسبب إن الـ agent بقى أذكى — هو نفس Sonnet 4.6 بنفس الـ prompt. التحسّن جاي من إن الـ agent بقى يفشل بسرعة (fail fast) ويرجّع المهمة لإنسان بدل ما يفضل يدور في الحلقة لحد ما يضرب max_tokens ويرجّع response تالف. التذاكر الـ 18% الفاشلة بترجع للـ tier 2 خلال ثانيتين بدل دقيقة ونص.

4 trade-offs لازم تعرفها قبل ما تنشر الـ agent

كل قرار في تصميم الـ agent له ثمن. الأربع نقاط دي اللي بتفرق إنتاج ناجح من فاتورة كارثية.

1. MAX_ITERATIONS منخفض = أمان، عالي = قدرة

لو حطيت MAX_ITERATIONS = 5، هتمنع الـ loops تماماً، لكن هتقطع المهام المعقدة في النص. لو حطيتها 40، الـ agent هيخلّص أي مهمة، لكن لو حصل bug في tool هتدفع تمن 40 استدعاء API. التوصية بناءً على القياسات: ابدأ بـ 12-15 لمهام الدعم الفني، وارفعها لـ 25 بس لمهام البحث المركّب. لو شفت إن أقل من 5% من المهام بتاخد أكتر من 10 خطوات، نزّل الـ MAX_ITERATIONS لـ 12 وفّر 30% من الـ cost.

2. Loop detection بـ hash بيفشل في tools العشوائية

الكود اللي فوق بيفترض إن نفس المدخلات بترجّع نفس المخرجات. ده مش صحيح لو الـ tool فيه randomness (مثلاً search بـ pagination، أو خدمة طقس بترجّع قراءة جديدة كل ثانية، أو LLM-as-tool). في الحالات دي، احتاج تستخدم semantic deduplication بدل MD5 — مثلاً Embedding على الـ tool_result وقياس cosine similarity. لو الـ cosine بين آخر 3 نتائج أعلى من 0.92، انت في loop دلالي حتى لو الـ bytes مختلفة.

3. Agent بسعر Sonnet vs Pipeline بسعر Haiku

كل خطوة في الـ agent بتستهلك tokens، وكل خطوة بتعيد إرسال كل المحادثة + الـ tool_results السابقة. متوسط تذكرة بـ 5.7 خطوة على Sonnet 4.6 بيكلّف $0.038. لو الـ workflow بتاعك ثابت ومش محتاج تفكير شجري، استبدل الـ agent بـ pipeline ثابت يستدعي Haiku 4.5 في كل خطوة محدّدة — التكلفة بتنزل لـ $0.004 وP95 بينزل لـ 4 ثواني. الـ agent مش أفضل تلقائياً، هو أغلى وأبطأ، ومنطقي بس لما عندك تفرّع حقيقي في القرارات.

4. Streaming بيخفي الـ loops عن المستخدم

لو الـ frontend بيستخدم streaming، المستخدم بيشوف text بيتطبع وبيفتكر إن الـ agent شغّال. لكن لو الـ agent دخل في loop داخلي على الـ tools (مش على الـ text)، انت بتدفع tokens والمستخدم بينتظر بدون نتيجة. لازم تطلع warning في الـ UI لو iteration > MAX_ITERATIONS/2، أو حتى تقطع وترجّع رسالة "محتاج تدخّل بشري" بدل ما تخلّيه يكمّل لحد آخر iteration.

متى لا تستخدم AI Agent أصلاً

الـ agents بقت trend في 2026، وفي حالات كتير المهندسين بيستخدموها في مكان pipeline تقليدي كان هيكفي. الـ agent منطقي بس لو:

• المهمة محتاجة قرارات متعددة الفروع بتعتمد على نتائج tools. مثال: تشخيص خطأ في النظام بحسب logs متغيّرة.
• الـ workflow مش معروف مقدّماً. مثال: research deep في موضوع بيتفرّع حسب المصادر.
• المستخدم بيكتب طلب طبيعي مفتوح ومش form منظّم.

الـ agent مش منطقي لو:

• الـ workflow ثابت ومحدّد (مثال: استخراج بيانات من PDF بتنسيق ثابت). pipeline + Haiku أرخص 10x وأسرع 5x.
• محتاج determinism عالي. الـ agent بطبعه non-deterministic بسبب الـ temperature والـ tool ordering.
• المستخدم بيتحمّل تأخير أقل من 3 ثواني. متوسط agent step بياخد 1.5-3 ثواني × عدد الخطوات.

المصادر

• Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models", arXiv:2210.03629 (2022).
• Galileo, "State of AI Agents Report 2025" — 73% production failure rate في أول 90 يوم.
• Anthropic, "Tool use with Claude" documentation (2026).
• Digital Applied, "Agent Architecture Patterns: 2026 Taxonomy Guide".
• SitePoint, "Agentic Design Patterns: The 2026 Guide to Building Autonomous Systems".
• Redis, "AI Agent Architecture Patterns: Single & Multi-Agent Systems" (2026).

الخطوة التالية

افتح أحدث agent عندك في production. شغّل log query على الـ tool calls عبر آخر 100 محادثة، واعمل group by tool_name + arguments_hash. لو لقيت أي hash اتكرر أكتر من 3 مرات في نفس conversation، انت عندك loop bug خفي بيستنزف تكلفتك بدون ما تلاحظ. حط الـ MAX_ITERATIONS و call_signature من الكود اللي فوق، شغّله shadow mode على نفس الـ traffic لمدة 7 أيام، وقارن التكلفة. لو ما نزلتش 25% على الأقل، ابعتلي تفاصيل الـ tools وهنشوف فين الـ loop الحقيقي.