توقف عن توجيه وكيل البرمجة يدويًا. ابنِ حلقة توجهه آليًا

لم يعد عليك توجيه وكلاء البرمجة (coding agents). يجب عليك تصميم حلقات (loops) توجه وكلاءك. قد يبدو هذا كلامًا عابرًا، لكنه يشير إلى أكبر تحول في كيفية عمل المهندسين الجيدين مع الذكاء الاصطناعي في الوقت الحالي. الأشخاص الذين يحققون أقصى استفادة من وكلاء البرمجة بالذكاء الاصطناعي توقفوا عن التعامل مع الوكيل كشريك في الدردشة. بل يتعاملون معه كعامل داخل حلقة قاموا ببنائها.

باختصار

حلقة وكيل البرمجة هي بنية تحكم تشغل الوكيل بشكل متكرر: قم بإنشاء تغيير، قم بتشغيله، تحقق من النتيجة مقابل إشارة صارمة، أعد إرسال الفشل، كرر حتى ينجح التحقق أو يتم الوصول إلى حد معين. الوكيل ليس الجزء الصعب. بوابة التحقق هي الصعبة. الحلقة ذات البوابة الغامضة ("تبدو جيدة، جرب مرة أخرى") تنحرف وتتوهّم "الانتهاء". الحلقة ذات البوابة المحددة (اختبار فاشل، عدم تطابق مخطط، عقد مكسور) تتقارب. بالنسبة لعمل واجهة برمجة التطبيقات (API) والواجهة الخلفية، فإن مجموعة اختباراتك الآلية وفحوصات العقود هي تلك البوابة، وهذا هو السبب في أن اختبار واجهة برمجة التطبيقات ينتمي إلى مركز سير عمل وكيل، وليس يتم تركيبه في النهاية.

من التوجيه إلى تصميم الحلقات

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

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

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

تحول النموذج الذهني صغير ولكنه شامل. توقف عن السؤال "ماذا يجب أن أقول للوكيل؟" ابدأ بالسؤال "ما هي الحلقة التي ستجعل الوكيل يخبر نفسه؟"

ما هي حلقة وكيل البرمجة بالفعل

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

1. مواصفات مهمة. وصف واضح ومكتوب لما يبدو عليه الإنجاز. ليس "اجعلها تعمل"، بل "نقطة النهاية POST /orders تعيد 201 مع الطلب الذي تم إنشاؤه، تتحقق من الجسم مقابل المخطط، وترفض الحقول المفقودة بـ 422."
2. الوكيل. النموذج بالإضافة إلى أدواته: قراءة الملفات، كتابة الملفات، تشغيل أوامر Shell. هذا هو الجزء الذي يركز عليه الجميع وهو الجزء الذي تتحكم فيه بأقل قدر.
3. خطوة إجراء. يقوم الوكيل بإجراء تغيير، ثم يقوم شيء ما بتشغيله بالفعل. الاختبارات، بناء، فحص نوع، طلب مقابل نقطة نهاية حية.
4. بوابة تحقق. تحقق حتمي يعيد "نجاح" أو "فشل" مع سبب ملموس. هذا هو عجلة القيادة. سنقضي معظم هذا المنشور هنا.
5. شرط إنهاء. متى تتوقف الحلقة؟ تمر البوابة، أو تصل إلى أقصى عدد من التكرارات، أو تتجاوز ميزانية التكلفة. الحلقة التي لا تحتوي على مخرج هي حلقة جامحة، وليست سير عمل.

في الكود الزائف (pseudocode) يتناسب النمط بأكمله في بضعة أسطر:

task = load_spec("orders-endpoint.md")
for attempt in range(MAX_ITERATIONS):
    agent.run(task, feedback=last_result)   # generate
    result = run_verification()             # run + check the gate
    if result.passed:
        break                               # terminate: success
    last_result = result.failures           # feed failure back
else:
    escalate_to_human(last_result)          # terminate: gave up

هذه الحلقة هي الفكرة بأكملها. الوكيل يُولِّد، والبوابة تُقيِّم، والفشل يصبح الموجه التالي، وكل ذلك يستمر حتى ينجح أو تنفد المحاولات. المتغير الذي يشاركه الناس عبر الإنترنت بتقنية "رالف" هو هذا مع تعيين `MAX_ITERATIONS` على قيمة عالية وتحديد المواصفات بدقة. إذا قرأت تحليلنا لـ بنية تسخير الوكيل، فهذا هو التسخير في أبسط صورة صادقة له.

لماذا يصل التوجيه لمرة واحدة إلى طريق مسدود

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

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

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

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

الجزء الذي يقلل الجميع من بنائه: بوابة التحقق

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

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

البوابات المحددة تتقارب. البوابات الغامضة تنجرف. هذه هي اللعبة بأكملها.

ما الذي يجعل البوابة جيدة؟

• إنها ثنائية وقابلة للتكرار. نفس الإدخال، نفس الحكم، في كل مرة. لا يوجد "يعتمد على شعور النموذج اليوم."
• تفشل بصوت عالٍ مع ذكر السبب. اسم اختبار، اختلاف متوقع مقابل فعلي، رقم سطر، رمز خطأ. السبب هو التوجيه التالي، لذا يجب أن يكون محددًا.
• لا يمكن للوكيل تعديلها بهدوء. إذا كان الوكيل يستطيع تغيير الاختبار لجعله ينجح، فالبوابة هي مجرد مسرحية. احمِ البوابة. تعامل معها على أنها المواصفات، وليست كودًا يملكه الوكيل.
• تعمل بسرعة كافية للتكرار. بوابة تستغرق 20 دقيقة تحد من سرعة التكرار. تتطلب الحلقات الضيقة فحوصات سريعة.

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

لعمل واجهة برمجة التطبيقات (API) والواجهة الخلفية، مجموعة الاختبارات الخاصة بك هي الحلقة

هنا تصبح الفكرة المجردة ملموسة لأي شخص يقوم ببناء الخدمات. عندما يقوم وكيل بكتابة نقطة نهاية API، ما هي الحقيقة الأساسية التي تقول إنها تعمل؟ ليست ملخص النموذج. بل السلوك الفعلي لنقطة النهاية قيد الاختبار: رموز الحالة الصحيحة، مطابقة جسم الاستجابة للمخطط، فرض المصادقة، رفض الإدخال السيئ، احترام العقد.

كل واحد من هذه الأمور يمكن التحقق منه تلقائيًا، بنتيجة حتمية. مما يعني أن مجموعة اختبارات API الخاصة بك مصممة بالفعل تمامًا مثل بوابة التحقق التي تحتاجها حلقة الوكيل. لقد كنت تبني البوابة طوال الوقت؛ لقد سميتها فقط اختبارًا.

حلقة ملموسة لعمل نقطة النهاية تبدو كالتالي:

1. يقرأ الوكيل مواصفات المهمة وتعريف OpenAPI، ثم يكتب أو يعدل نقطة النهاية.
2. يقوم النظام بتشغيل مجموعة اختبارات API مقابل الخدمة قيد التشغيل: تأكيدات الحالة، التحقق من صحة مخطط JSON على كل استجابة، فحوصات العقود مقابل المواصفات.
3. تأتي الأخطاء منظمة. "كان من المتوقع 422 عند نقص `customer_id`، ولكن تم الحصول على 500." "حقل الاستجابة `total` هو سلسلة نصية، والمخطط يقول رقمًا." "نقطة النهاية `/orders/{id}` في المواصفات لا تحتوي على تطبيق."
4. يصبح هذا الفشل المنظم هو التوجيه التالي للوكيل. يقوم بتصحيح الثغرة المحددة.
5. كرر حتى تصبح المجموعة خضراء، ثم سلمها لإنسان للمراجعة.

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

هذا هو الدور الذي يلعبه Apidog في سير العمل الوكالي. إنه منصة API متكاملة حيث يعيش التصميم، والمخطط، والخادم الوهمي، والاختبارات الآلية في مكان واحد، مما يعني أن البوابة والمواصفات تظلان متزامنتين افتراضيًا. توجه الحلقة إلى سيناريو اختبار Apidog، ويحصل الوكيل على نجاح/فشل تم التحقق منه بالمخطط في كل تكرار، ويحل الخادم الوهمي محل التبعيات التي لم يتم بناؤها بعد حتى يتمكن الوكيل من العمل مقابل هدف مستقر. تقوم الفرق التي تشغل هذا النمط بالفعل بتوصيل وصول أدوات الوكيل من خلال شيء مثل مصدر أخطاء وكيل Apidog AI حتى يتمكن الوكيل من الوصول إلى نقاط النهاية وفحصها بنفس الطريقة التي يقوم بها المختبر البشري. قم بتنزيل Apidog إذا كنت ترغب في بناء البوابة بصريًا بدلاً من بناء مشغل اختبار يدويًا.

قم ببناء حلقة API تصحيح ذاتي صغيرة اليوم

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

الخطوة 1: اكتب المواصفات كهدف للبوابة. ضع العقد في ملف OpenAPI والسلوك في حالات الاختبار. يقرأ الوكيل كلاهما. هذا يعمل أيضًا كتوثيق، لذا فهو ليس عملًا لا طائل منه.

الخطوة 2: اختر أمر اختبار يخرج برمز غير صفري عند الفشل. أي شيء يعمل طالما أن رمز الخروج صادق. مجموعة pytest، تشغيل Newman، سيناريو اختبار Apidog CLI. لا تهتم الحلقة إلا بالنجاح/الفشل بالإضافة إلى المخرجات الملتقطة.

# the gate, as one command
apidog run ./tests/orders-suite --reporter json > result.json

الخطوة 3: قم بربط الحلقة. قم بتشغيل الوكيل، قم بتشغيل البوابة، وقم بالتشعب بناءً على النتيجة.

MAX_ITERATIONS = 8
feedback = None
for attempt in range(MAX_ITERATIONS):
    run_agent(task="implement orders API per spec", feedback=feedback)
    gate = subprocess.run(["apidog", "run", "./tests/orders-suite",
                           "--reporter", "json"], capture_output=True)
    if gate.returncode == 0:
        print(f"green on attempt {attempt + 1}")
        break
    feedback = parse_failures(gate.stdout)   # the next prompt writes itself
else:
    print("8 attempts, still red; escalating to a human")

الخطوة 4: حماية البوابة. احتفظ بملفات الاختبار والمواصفات خارج مجموعة الملفات التي يُسمح للوكيل بتعديلها. إذا كان بإمكانه إعادة كتابة الاختبار ليمرر، فقد بنيت آلة لتزييف التقدم.

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

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

تصميم الحلقات الجيدة: الأخطاء التي تسبب المشاكل

تفصل بعض الأنماط الحلقات التي تعمل عن الحلقات التي تهدر المال بصمت.

• السماح للوكيل بتقييم واجبه المنزلي. إذا كان التحقق الوحيد هو "وكيل، هل انتهيت؟" فليس لديك حلقة، بل لديك روبوت محادثة بخطوات إضافية. يجب أن تكون البوابة خارجية للوكيل.
• بوابة غامضة جدًا. "الاختبارات تمر" مع ثلاثة اختبارات سطحية تعني أن الوكيل يرضي ثلاثة اختبارات ويشحن أخطاء في كل ما لم يتم تغطيته. جودة الحلقة محددة بتغطية البوابة. اختبارات ضعيفة، نتائج ضعيفة.
• لا يوجد حارس إنهاء. الحلقات التي لا تحتوي على حد أقصى للتكرار وسقف للتكلفة يمكن أن تستمر إلى الأبد في مهمة لا يمكن للنموذج حلها. دائمًا ما تحدد مخرجًا، ودائمًا ما تصعد الأمر إلى إنسان عند حدوث مشكلة.
• بوابات بطيئة. مجموعة تكامل تستغرق 15 دقيقة هي فحص ليلي جيد وحلقة داخلية مروعة. حافظ على بوابة سريعة للحلقة وبوابة شاملة للدمج. قم بتصغير الاعتمادات الخارجية حتى لا تنتظر الحلقة على طرف ثالث غير مستقر.
• مواصفات قابلة للتغيير. إذا قام الوكيل بتعديل ملف OpenAPI لمطابقة الكود المعيب، فإن اختبار العقد يصبح أخضر لسبب خاطئ. المواصفات هي الدستور. يعمل الوكيل بموجبها، وليس عليها.
• مهمة واحدة عملاقة. حلقة تعمل على "بناء الخدمة بأكملها" نادرًا ما تتقارب. قم بتقسيمها إلى مهام بحجم نقطة نهاية، كل منها ببوابتها الخاصة. الحلقات الصغيرة تكتمل؛ الحلقات الكبيرة تتعثر.

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

إلى أين يتجه هذا

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

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

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

الخلاصة

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

ابدأ صغيرًا. اكتب مواصفات دقيقة واحدة، وجه حلقة إلى مجموعة اختبار API سريعة واحدة، احمِ البوابة، حدد التكرارات، وشاهد وكيلًا يحول نقطة نهاية حمراء إلى خضراء بدون تدخل منك في الحلقة الداخلية. ثم ابنِ الحلقة التالية. إذا كنت تريد أن تكون البوابة مرئية، ومدركة للمخطط، وقابلة للمشاركة عبر فريقك، يوفر لك Apidog التصميم والمحاكاة والاختبار الآلي في مساحة عمل واحدة؛ قم بتنزيله واجعل اختباراتك هي ما يدفع وكلاءك.