الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.

handoffs أم sub-agents؟

البداية السريعة

أعطِ كل target name وdescription (الـ model يقرأ الـ description ليقرر متى يسلّم)، وبعدها مرّرها للـ triage agent في handoffs. بادئة vendor/ في الـ model تختار الـ provider. مع OpenRouter استخدم openrouter/<vendor>/<model> (مثال openrouter/openai/gpt-4o-mini):
كل target يُعرض على الـ model كـ tool واحدة اسمها transfer_to_<name> (transfer_to_billing وtransfer_to_tech-support). عندما يستدعيها الـ model، يكمل الـ run كـ target داخل استدعاء send() / stream() نفسه. وresult.agentName هو اسم الـ agent الذي أنتج الرد الأخير. يجب أن يأتي الـ target من createAgent() وأن يكون له name (فريد بين الـ handoffs) وdescription (أو description داخل handoff()). وإلا يرمي createAgent() الخطأ LOUSHO_CONFIG_INVALID. ولا يجوز أن يطابق اسم أداة الـ handoff اسم أي tool من tools الـ agent.

خيارات handoff()

غلّف الـ target بـ handoff() لتضبطه:

Input filters

يرى الـ target المحادثة كما يُرجعها inputFilter، تحت الـ system prompt الخاص به (system prompt الـ agent الذي سلّم يُستبدل، ولا يُحفظ أبدًا). الـ filter يستلم { messages, from, to, args }. وmessages هي السجل حتى تلك اللحظة بدون الـ system prompt، وتنتهي باستدعاء الـ handoff ونتيجته وrouting note: رسالة system يضيفها الـ run حتى يعرف الـ target مَن حُوِّل وأي args اجتازت الـ validation ([routing note - not from the user] handoff triage -> billing: reason="..."). الرسالة موسومة بـ metadata.handoff، فيستطيع الـ filter التعرف عليها. احذفها أو استبدلها وشكّل سياق الـ target بنفسك. الـ note تبقى في مكانها من السجل، لكن لا يوجد طلب model يحمل رسالة system بعد بداية المحادثة: كل طلب يضيف هذه الرسائل، بالترتيب، إلى الـ system prompt في أوله. فقوالب المحادثة (chat templates) في نماذج Qwen وLlama وMistral (LM Studio وllama.cpp وvLLM وOllama) وAPI الخاص بـ Anthropic ترفض رسالة system في وسط المحادثة. هناك فلتران جاهزان:
  • handoffFilters.removeToolCalls: يبقي نصوص المستخدم والـ assistant (والـ routing note)، ويحذف الـ tool calls ونتائجها.
  • handoffFilters.lastUserMessage: يبقي آخر رسالة من المستخدم فقط.
ما يُرجعه الـ filter يصبح سجل الـ run: result.messages وتاريخ الـ session يكملان منه. يجب أن يُبقي الـ filter رسالة واحدة على الأقل. الـ approvals (الموافقات) المتذكَّرة بـ once() في الجزء الأقدم من السجل تُسقط عند الـ handoff، فترجع tools الـ target تطلب الموافقة من جديد.

ماذا يتغيّر وماذا يبقى

الـ agent الذي بدأ به الـ run هو الـ lead. الـ target لا يحصل على tools الـ lead ولا sub-agents، لكنه يحتفظ بـ memory الخاصة بالـ lead: كتل <memory> المسترجَعة تُعاد إلى system prompt الـ target، وأدوات remember_<name> / recall_<name> تظل معروضة، مربوطة بمفاتيح النطاق نفسها (العميل أو المستخدم أو الـ session نفسه). وهذا ينطبق في run الـ handoff وفي كل دورة session لاحقة يشغّلها الـ target. خانات الـ memory الخاصة بالـ target نفسه لا تُستخدم؛ أعطِ الخانات للـ agent الذي تبدأ به الـ runs. وتعليمات output الخاصة بالـ lead تُضاف إلى system prompt كل target. ولأن الـ approvals والـ memory على مستوى الـ run، خيارات مثل approve وapprovalStore وpermissionMode وapprovalTtlMs وstore أو memory على الـ target لا تُقرأ أبدًا بعد الـ handoff. الـ agent يحذّر مرة واحدة (لكل target)، في أول run له يصل إلى مخطط الـ handoffs (وليس عند استدعاء createAgent())، إذا كان target يمكن الوصول إليه قد أُنشئ بها. اضبطها على الـ agent الذي تبدأ به الـ runs.

Sessions

في الـ session، الـ agent النشط هو آخر واحد استلم المحادثة (قيمة to في آخر علامة metadata.handoff). فالـ session.send() / session.stream() التالي يشغّل ذلك الـ agent:
agent.send() بدون session يبدأ دائمًا من الـ lead. الـ target يُعيد المحادثة عبر handoffs الخاصة به. ولأن الـ lead يُنشأ بعد الـ targets، أعطِ الـ target مصفوفة وأضف الـ lead إليها لاحقًا (المصفوفة تُقرأ في كل run):
الأسماء هي التي تعرّف الـ agents: كل agent يمكن الوصول إليه عبر handoffs يجب أن يكون له اسمه الخاص. إذا لم يعد الـ agent الذي يذكره السجل reachable، يعمل الـ lead.

Approvals والاستئناف بعد handoff

tool تابعة للـ target تحتاج approval توقف الـ run في الـ approval store الخاص بالـ lead، وagent.approvals.resolve() على الـ lead يكمله كـ target. الـ run الذي له checkpoint (send(message, { sessionId }) أو session لها store) إذا وقع بعد handoff يُستأنف كـ target بـ agent.resume(id) أو session.resume(). وفحص الـ drift عند الاستئناف (onAgentDrift، انظر Durable execution) يقارن مع بصمة الـ target المحفوظة. إذا كانت الخطوة فيها استدعاء handoff بجانب استدعاء يتوقف بانتظار approval، الـ handoff ينتظر: الـ run يتوقف بصفة الـ agent الذي سلّم، ويحدث الـ handoff بعد أن تُحسم الـ approval وتنفّذ بقية الاستدعاءات في الخطوة. استدعاء transfer_to_* نفسه يمر بالبوابة نفسها التي يمر بها أي tool call. قواعد permissions تنطبق عليه: deny تعطي الـ model خطأ tool من نوع kind: 'denied' ولا يحدث handoff، وask توقف الـ run لأجل approval وبعد حسمها الاستدعاء إما يسلّم أو يبلّغ الرفض. وpreToolCall hooks تستطيع رفضه أو إعادة كتابة وسائطه، والـ routing note والـ target يريان المدخل المعدّل. والقرار يُوثَّق في onPermissionDecision / permission.decision مثل أي tool call.

الأحداث

الـ run يبلّغ عن الـ handoff بين tool.start / tool.done الخاصين باستدعاء الـ handoff وأول step.start للـ target:
handoff يحمل from وto وtoolCallId. وللـ run حدث run.start واحد وrun.done واحد مهما كثرت الـ handoffs. انظر الـ event schema.

القيود

  • handoff واحد فقط في الدورة الواحدة للـ model: إذا استدعت الدورة عدة tools تسليم، يُنفَّذ الأول وتحصل البقية على خطأ tool.
  • maxHandoffs (خيار في createAgent()، الافتراضي 5) يحد عدد handoffs الـ run الواحد، لمنع الـ agents من تمرير المحادثة ذهابًا وإيابًا. أي استدعاء handoff يتجاوز الحد يحصل على خطأ tool ويجيب الـ agent بنفسه. الـ run الذي يُستأنف بعد approval أو بعد سقوط يعد من الصفر من جديد.
  • الـ remote agents (remoteAgent()) لا يمكن أن تكون targets للـ handoff؛ استخدمها كـ sub-agents.
  • الـ target لا يُعيد التسليم من تلقاء نفسه في نهاية دورته؛ أعطِه handoff إلى الـ lead (انظر Sessions).

executor API

AgentExecutor.execute() يستلم handoffs (ResolvedHandoff[]: name وtoolName وdescription وinput وspec(input) الذي يُرجع إعداد run الـ target وhandoffs الخاصة به، وinputFilter وonHandoff) وmaxHandoffs. createAgent() يبنيها. مرّرها بنفسك فقط عندما تشغّل الـ executor مباشرة.