handoffs أم sub-agents؟
البداية السريعة
أعطِ كل targetname وdescription (الـ model يقرأ الـ description ليقرر
متى يسلّم)، وبعدها مرّرها للـ triage agent في handoffs. بادئة vendor/
في الـ model تختار الـ provider. مع OpenRouter استخدم
openrouter/<vendor>/<model> (مثال openrouter/openai/gpt-4o-mini):
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: يبقي آخر رسالة من المستخدم فقط.
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):
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 مباشرة.