وجد وكيل البحث حساب العميل، وأكد الخطة، وسحب آخر أربع فواتير. ثم سلمه إلى وكيل الفوترة بملخص من سطر واحد: "العميل يريد استردادًا". يبدأ وكيل الفوترة، الذي لا يعرف الآن شيئًا عن الحساب أو الخطة أو الفواتير، بطلب معرف الحساب.
كل حقيقة جمعها الوكيل الأول تم التخلص منها عند نقطة الانتقال. هذه هي مشكلة التسليم، وتكلفك مرتين: مرة في استدعاءات API المكررة، ومرة في الأخطاء التي تنشأ عندما يعمل الوكيل الثاني بمعلومات أقل من الأول.
يغطي هذا الدليل ما يجب أن يصمد عند التسليم، والطرق الثلاث التي تمرر بها الفرق الحالة ومتى يعمل كل منها، ولماذا تفقد الملخصات أكثر مما يتوقعه الناس، وكيفية اختبار أن التسليم حمل ما ادعاه. منشورنا حول لماذا تتعطل الوكلاء في الإنتاج يعامل الحالة المفقودة كوضع فشل أساسي؛ هذه هي النسخة متعددة الوكلاء منه.
يظهر Apidog لأن الحل الأرخص عادةً هو التوقف عن تمرير البيانات تمامًا وتمرير المعرفات بدلاً من ذلك، وهذا لا ينجح إلا إذا كان بإمكان كل وكيل جلب نفس السجل بنفس الطريقة.
ما الذي يحتاج فعلاً إلى تجاوز الحد
ليس كل شيء. التسليم الذي ينسخ المحادثة بأكملها معطّل تمامًا مثل الذي لا ينسخ شيئًا، ولكن في الاتجاه الآخر: يرث الوكيل الثاني نافذة سياق كاملة ويجب عليه معرفة الأجزاء المهمة.
تستحق أربع فئات الفصل.
المعرفات. معرفات الحساب، معرفات الطلب، معرفات الوظيفة، أرقام التذاكر. هذه صغيرة ومستقرة وتسمح للوكيل المستلم بجلب أي شيء يحتاجه. إنها أثمن شيء يمكن تمريره وأكثرها شيوعًا في التخلي عنها.
القرارات المتخذة بالفعل. "العميل مؤهل لاسترداد المبلغ بموجب السياسة 3." يجب على الوكيل المستلم ألا يعيد النظر في هذا. إذا فعل ذلك، سيكون لديك وكيلان يختلفان داخل مهمة واحدة.
القيود. حدود الميزانية، الموافقات الممنوحة، الإجراءات المتخذة بالفعل. فقدان هذا هو كيف تنتهي مهمة بالتحصيل مرتين أو طلب نفس الموافقة مرة ثانية. إنه يقترن مباشرة بمنشورنا حول التكرارية لوكلاء الذكاء الاصطناعي.
الأسئلة المفتوحة. ما لم يستطع الوكيل الأول حله. تمرير هذا يوقف صراحة الوكيل الثاني عن الافتراض بصمت.
ما الذي لا يحتاج إلى العبور: استجابات API الأولية، سجل الاستدلال، وأي شيء يمكن للوكيل المستلم جلبه بنفسه في استدعاء واحد.
ثلاث طرق لتمرير الحالة
تمرير المحادثة بأكملها. بسيط، ويعمل لوكيلين في مهمة قصيرة واحدة. يفشل بمجرد أن يكون السجل طويلاً، لأن الوكيل المستلم يقضي معظم ميزانيته في قراءة التاريخ وتكون الحقائق ذات الصلة مدفونة في المنتصف. يشرح منشورنا حول إبقاء استجابات الأدوات خارج نافذة السياق لماذا هذا المنتصف هو بالضبط المكان الذي تفقد فيه النماذج الأشياء.
تمرير ملخص. يكتب الوكيل الأول رسالة تسليم؛ يبدأ الوكيل الثاني منها. هذا هو الافتراضي في معظم الأطر وهو يفقد المعلومات بطريقة محددة: تلخص النماذج باتجاه السرد وبعيدًا عن المعرفات. اطلب ملخصًا وستحصل على "العميل مشترك منذ عامين ومحبط" بدلاً من "الحساب 8812، خطة احترافية، أربع فواتير، تم اعتماد استرداد للفاتورة inv_44."
تمرير كائن تسليم منظم. يملأ الوكيل الأول مخططًا. يقرأ الوكيل الثاني الحقول، وليس النثر. يتطلب هذا المزيد من العمل للإعداد وهو الذي يصمد.
{
"task_id": "task_2026_08_26_0031",
"from_agent": "research",
"to_agent": "billing",
"entities": {
"customer_id": "cus_8812",
"invoice_ids": ["inv_41", "inv_42", "inv_43", "inv_44"],
"subscription_id": "sub_119"
},
"decisions": [
{ "decision": "refund_eligible", "value": true, "basis": "policy 3.2, charged twice in one cycle" }
],
"constraints": {
"max_refund_cents": 4900,
"human_approval_granted": false,
"actions_taken": ["read_invoices"]
},
"open_questions": ["Customer has not confirmed which invoice to refund"],
"summary": "Customer cus_8812 was double-charged in August. Refund of one invoice is approved under policy 3.2, up to 4900 cents. Awaiting the customer's choice of invoice."
}
لا يزال النثر يظهر، في حقل summary، لأنه يحمل تفاصيل دقيقة لا يمتلكها المخطط. إنه يجلس بجانب الحقول المنظمة بدلاً من استبدالها، وهذا هو الهدف الأساسي.
تحقق من صحة الكائن قبل تشغيل التسليم. إذا كان customer_id مفقودًا، افشل بصوت عالٍ عند الحد بدلاً من السماح للوكيل الثاني باكتشاف ذلك بعد ثلاث مكالمات.
تمرير المراجع، لا الحمولات
أقوى نسخة من التسليم لا تمرر أي بيانات تقريبًا. إنها تمرر المعرفات، ويجلب الوكيل المستلم ما يحتاجه.
يعمل هذا لثلاثة أسباب. تبقى الحالة حديثة، فإذا تغير شيء بين الوكيلين، يرى الثاني القيمة الحالية بدلاً من نسخة قديمة. يبقى التسليم صغيرًا، بضع مئات من البايتات بدلاً من عشرات الآلاف من الرموز. ويتحسن مسار التدقيق، لأن كل قراءة تظهر كاستدعاء API بدلاً من نص منسوخ بين المطالبات.
يتطلب هذا شيئًا واحدًا: أن يتمكن كل وكيل من الوصول إلى نفس واجهة برمجة التطبيقات بنفس الصلاحيات. وهذا ليس مجانيًا. يحتاج كل وكيل إلى بيانات اعتماده الخاصة والمحددة لنطاق عمله، وهذا هو الحجة في منشورنا حول مفاتيح API بأقل امتياز لوكلاء الذكاء الاصطناعي. لا يمكن لوكيل الفوترة الذي يحمل رمز بحث للقراءة فقط إصدار استرداد، ووكيل البحث الذي يحمل رمز الفوترة هو مشكلة تتعلق بنطاق الضرر.
حيثما يكون الجلب المكثف مكلفًا أو بطيئًا، قم بتخزين السجل مؤقتًا في المنسق الخاص بك ومرر مرجعًا إلى إدخال ذاكرة التخزين المؤقت. لا يزال الوكيل المستلم يطلب البيانات صراحةً، لذا يبقى النمط كما هو، لكن القراءة الثانية تكون رخيصة.
أين تتعطل عمليات التسليم فعليًا
تغطي أربعة أنواع من الفشل معظم الحوادث.
المعرف المفقود. يقول الملخص "العميل" ولا يعطي معرفًا أبدًا، لذا يبحث الوكيل الثاني بالاسم، يجد تطابقين، ويختار الخطأ. امنع ذلك عن طريق التحقق من وجود معرفات الكيانات المطلوبة قبل السماح بإجراء التسليم.
الإجراء المكرر. أرسل الوكيل الأول البريد الإلكتروني بالفعل. لا يسجل التسليم ذلك. يرسله الوكيل الثاني مرة أخرى. سجل actions_taken في كائن التسليم وتحقق منه قبل أي كتابة، مدعومًا بمفاتيح التكرارية التي تجعل التكرار غير ضار.
الموافقة المفقودة. وافق شخص على استرداد بينما كان الوكيل الأول يعمل. الوكيل الثاني، غير مدرك لذلك، يطلب الموافقة مرة أخرى. يقرأ المستخدمون المطالبة الثانية كنظام لا يستمع. حمل الموافقات كقيود صريحة، وعاملها على أنها مخصصة للمهمة بدلاً من الوكيل.
الاختراع الواثق. يحتاج الوكيل المستلم إلى قيمة لم يحملها التسليم، وبدلاً من السؤال، يخترع قيمة تتناسب مع السرد. هذا هو أخطر فشل لأنه يبدو وكأنه مهمة مكتملة. الدفاع هو حقل open_questions بالإضافة إلى قاعدة صارمة في مطالبة الوكيل المستلم: إذا كان معرف مطلوب غائبًا، توقف واسأل.
تجعل الحلقات كل هذه الأربعة أسوأ. عندما يسلم الوكيل أ إلى ب ويسلم ب مرة أخرى إلى أ، تتحلل الحالة في كل تمريرة، تمامًا مثل نسخة ضوئية من نسخة ضوئية. حدد عدد القفزات واحمل كائن المهمة الأصلي عبر كل منها بدلاً من إعادة بنائه عند كل حد.
اختبار الحد، وليس الوكلاء فقط
عمليات التسليم هي نقاط تكامل، لذا اختبرها كنقاط تكامل.
تأكد من كائن التسليم. قم بتشغيل الوكيل الأول مقابل سيناريو ثابت وتحقق من الكائن الذي ينتجه: المعرفات المطلوبة موجودة، القرارات مسجلة، الإجراءات مدرجة. هذا تأكيد حتمي على حمولة منظمة على الرغم من أن الوكيل الذي أنتجها ليس حتميًا، وهذا ما يجعله اختبارًا قابلاً للاستخدام. النهج العام موجود في دليلنا حول اختبار وكلاء الذكاء الاصطناعي غير الحتميين.
اختبر المستلم بشكل منفصل. قم بتغذية وكيل الفوترة بكائن تسليم يدوي الصنع وتحقق مما يفعله. ثم قم بتغذيته بكائن معطّل عمدًا، مع إزالة معرف العميل، وتأكد من أنه يسأل بدلاً من التخمين. هذا الاختبار الثاني هو الذي يكشف عن الاختراع.
قم بتشغيل كليهما مقابل نماذج وهمية. اختبار التسليم الذي يصدر استردادات حقيقية هو اختبار ستجريه مرة واحدة. وجه كلا الوكيلين إلى نقاط نهاية وهمية بحيث يمكن تشغيل المجموعة في كل تغيير، باتباع منشورنا حول تشغيل الوكلاء مقابل نماذج وهمية بدلاً من الإنتاج. في Apidog، تأتي النماذج الوهمية من نفس تعريف API الذي يستدعيه كلا الوكيلين، لذا لا يبتعد الاثنان أبدًا.
سجل كل تسليم. سجل الكائن الكامل عند كل حد بمعرف المهمة. عندما تسوء عملية تشغيل متعددة الوكلاء، يخبرك سجل التسليم أي وكيل كان لديه المعلومات وأي واحد فقدها، وهو عادة ما يكون التحقيق بأكمله. يغطي منشورنا حول تتبع استدعاءات أداة الوكيل ما ينتمي أيضًا إلى هذا السجل.
ما تقدمه الأطر
تشحن معظم أطر التنسيق أداة تسليم بدائية، ومن المفيد معرفة ما ينقله كل منها فعليًا عبر الحدود قبل الاعتماد عليه.
توثيق OpenAI Agents SDK handoff يصمم التسليم كأداة يمكن للوكيل استدعاؤها، مما يعني أن النموذج يقرر متى يتم نقل التحكم. هذا مريح، ويضع القرار في الجزء الأقل حتمية من نظامك، لذا قم بإقرانه بالتحقق عند الخروج.
إرشادات LangGraph للوكلاء المتعددين تتخذ نهجًا معاكسًا: الحالة هي كائن رسم بياني صريح يقرأه كل عقدة ويكتبه. هذا يتطابق بشكل وثيق مع التسليم المنظم الموضح أعلاه، والعمل الرئيسي المتبقي لك هو تحديد الحقول المطلوبة.
كتابة Anthropic حول بناء نظام بحث متعدد الوكلاء تستحق القراءة للتفاصيل التشغيلية، لا سيما حول مقدار التعليمات التي يحتاجها الوكيل الفرعي قبل أن يتمكن من العمل بشكل مفيد بمفرده.
الخيط المشترك: كل إطار عمل سينقل شيئًا ما. لا يقرر أي منهم لك الحقائق الأساسية. هذه القائمة هي لك لتكتبها، وهي الشيء الذي يستحق المراجعة عندما تسوء عملية التشغيل.
احتفظ بكائن المهمة خارج المحادثة
يمنع تغيير هيكلي واحد عائلة كاملة من الأخطاء. قم بتخزين حالة المهمة في مكان دائم، مفهرسة بمعرف المهمة، واجعل كل وكيل يقرأها ويكتبها بدلاً من تمريرها عبر الرسائل.
المحادثة ليست حاوية جيدة للحالة. يتم ضغطها واختصارها وإعادة كتابتها بواسطة التلخيص، ولا تعرف أي من هذه العمليات الحقول التي لا يمكنك تحمل فقدانها. لا يواجه الصف في قاعدة البيانات هذه المشكلة.
النمط صغير. في بداية كل دور، يقوم الوكيل بتحميل كائن المهمة. عندما يتخذ إجراءً، يضيف إلى actions_taken ويحفظ. عند التسليم، يمرر معرف المهمة، ويقوم الوكيل المستلم بتحميل نفس الكائن. لا شيء مهم ينتقل في المطالبة، لذلك لا يمكن تلخيص أي شيء مهم.
هذا يمنحك أيضًا نقطة استئناف. إذا توقفت عملية تشغيل في الخطوة الرابعة، لا يزال كائن المهمة يحتوي على كل ما أنشأته الخطوات الثلاث الأولى، وتبدأ المحاولة من هناك بدلاً من لا شيء.
حيث يمكن للمنصة الاحتفاظ بالحالة
إذا كانت وكلاءك تعمل كوقت تشغيل CLI على أجهزة المطورين، فإن كائن المهمة الدائم الموضح أعلاه هو شيء تقوم ببنائه. بعض منصات إدارة عمل الوكيل تقوم بالفعل بنمذجة ذلك، ومن الجدير معرفة كيف يبدو ذلك قبل أن تكتب نسختك الخاصة.
Sharkly هو نظام لإدارة العمل للأشخاص والوكلاء مبني حول هذه الوحدة بالضبط. تحمل المهمة الهدف، والحالة، والشخص المسؤول، والوكيل أو الطاقم المعين لتنفيذها، والتعليقات، وحالة تنفيذ الوكيل والنتيجة. يقرن الطاقم وكيلًا قائدًا بوكلاء وأشخاص آخرين، لذا فإن المهمة التي تحتاج إلى عدة متخصصين يتم تعيينها لمجموعة قابلة لإعادة الاستخدام بدلاً من تمريرها يدويًا عبر المطالبات. نظرًا لأن الحالة تعيش على المهمة بدلاً من المحادثة، فإن التسليم بين وكيلين لا يعتمد على أحدهما في التلخيص الجيد.
تظل أوقات التشغيل هي نفسها التي تستخدمها بالفعل. يقوم Claude Code، Codex، والبقية بتنفيذ العمل على جهاز كمبيوتر تقوم بتسجيله؛ توفر المنصة سجل المهمة، والتعيين، وحلقة المراجعة حولهم. إذا كنت تبني نمط المهمة الدائمة بنفسك، فإن وثائق Sharkly هي مرجع مفيد للحقول التي يتبين أنها مهمة.
قائمة مراجعة لعمليات التسليم
- يوجد مخطط محدد للتسليم، ويتم التحقق منه عند الحد.
- معرفات الكيان هي حقول مطلوبة، وليست اختيارية.
- القرارات تحمل أساسها، حتى لا يعيد المستلم عملية الاستدلال.
- الإجراءات المتخذة بالفعل مسجلة ويتم التحقق منها قبل أي كتابة.
- الموافقات والميزانيات تنتقل مع المهمة، وليس مع الوكيل.
- الأسئلة المفتوحة صريحة، والمستلم يسأل بدلاً من الافتراض.
- يتم تمرير البيانات عن طريق المرجع حيث يكون الاسترجاع رخيصًا.
- عدد القفزات محدد، وكائن المهمة الأصلي يبقى بعد كل قفزة.
- يتم تسجيل كل تسليم بمعرف المهمة.
- تُجرى اختبارات الحدود في CI مقابل النماذج الوهمية، بما في ذلك التسليم غير المكتمل عمدًا.
معظم حالات فشل الوكلاء المتعددين ليست فشلًا في الاستدلال. إنها حقيقة كانت موجودة في وكيل واحد ولم تكن في التالي. صمم الحد كواجهة، بمخطط واختبارات، وسيتوقف الوكيل الثاني عن طرح أسئلة أجاب عليها الأول بالفعل. قم بتنزيل Apidog للاحتفاظ بالنماذج الوهمية واختبارات الحدود بجانب API الذي يعتمد عليه كلا الوكيلين.
الأسئلة المتكررة
هل التسليم المنظم يستحق العناء لوكيلين؟ بالنسبة لوكيلين في مهمة قصيرة، تمرير المحادثة عادة ما يكون جيدًا. يكسب الكائن المنظم قيمته عند وجود ثلاثة وكلاء أو أكثر، أو في المهام الطويلة، أو في أي مكان يعبر فيه التسليم عملية أو حد تشغيل.
هل يجب أن يكتب النموذج كائن التسليم أم يجب أن ينشئه الكود؟ الكود حيثما أمكن. يجب أن تملأ المعرفات، والإجراءات المتخذة، والموافقات بواسطة منسقك مما حدث بالفعل، وليس من ذاكرة النموذج. دع النموذج يكتب فقط summary والأسئلة المفتوحة.
كيف أوقف اضمحلال السياق في حلقة؟ احمل كائن مهمة واحدًا عبر عملية التشغيل بأكملها وقم بتحديثه، بدلاً من إعادة إنشائه عند كل حد. ثم حدد عدد القفزات. إذا كانت المهمة تحتاج إلى أكثر من عدد قليل، فمن المحتمل أن يكون التفكيك خاطئًا.
ماذا عن الأطر التي تحتوي على دعم مدمج للتسليم؟ استخدمها، وتحقق مما تنقله فعليًا. يمرر الكثير منها سجل الرسائل ولا شيء آخر، مما يعني أن المعرفات لا تبقى إلا إذا ظهرت بالصدفة في النص. أضف حمولة منظمة جنبًا إلى جنب مع ما يحمله الإطار.
هل يحتاج الوكلاء الفرعيون إلى بيانات اعتماد API منفصلة؟ نعم، محددة لما يفعله كل منهم. مشاركة مفتاح قوي واحد عبر الوكلاء يزيل قدرتك على الحد من الضرر ومعرفة أي وكيل أجرى مكالمة. يغطي منشورنا حول مفاتيح API بأقل امتياز لوكلاء الذكاء الاصطناعي الإعداد.
كم يجب أن يحتوي حقل الملخص؟ بضع جمل، تغطي النية والدقة التي لا يمكن أن تحتويها الحقول المنظمة. إذا بدأ في إدراج المعرفات والمبالغ، فإن هذه تنتمي إلى الحقول المنظمة حيث يمكن التحقق منها.