Sub-agent أم skill أم flow؟
بداية سريعة
أعطِ كل sub-agent حقلdescription (يقرؤه model الـlead لكي يختار)،
ثم مرّرها إلى الـlead تحت subagents:
AgentExecutor.execute() خيارات subagents وmaxSubagentDepth نفسها.
استخدمه عندما تحتاج إلى hooks أو tracing على run الـlead — إذ ترثها الـsub-agents
(راجع ما يرثه الـsub-agent). وتعمل الـapprovals (الموافقات)
من createAgent() أيضًا (راجع Approvals).
كيف يعمل
معsubagents، يحصل الـlead على:
- بلوك Available sub-agents في الـsystem prompt: سطر لكل
sub-agent (
- name: description)، وجملة تذكر أن الـsub-agent لا يرى إلا الـprompt الذي يستلمه. - tool واحدة فقط،
task، مدخلها{ agent: <one of the names>, prompt: string, description?: string, background?: boolean, taskId?: string, mode?: 'new' | 'resume' | 'fork' }(descriptionاسم مختصر اختياري من 3 إلى 5 كلمات يُستخدم في الـevents والـhooks؛ وtaskIdوmodeيكملان مهمة سابقة، راجع تكملة مهمة؛ وsubagentOptions: { continuation: false }يزيلهما). - ثلاث tools للمهام الخلفية:
agent_statusوagent_awaitوagent_cancel(راجع Sub-agents في الخلفية).
task، يعمل الـsub-agent المسمّى على prompt وحده.
نتيجة الـtool هي النص النهائي للـsub-agent، ومعها سطر footer صغير يمكن
للـlead الاستفادة منه:
maxSteps، أو توقف عند حد
budget، أو انقطع — يحصل الـlead على نتيجة خطأ (isError: true) تشرح السبب، مثل
Sub-agent 'researcher' used all 10 of its steps (maxSteps) without giving a final answer. والاسم المجهول لـagent يُرجع أيضًا نتيجة خطأ تعدّد
الأسماء الصحيحة. والجواب الذي ينقطع عند حد الـoutput tokens للـsub-agent
(finish reason 'length') يُرجَع رغم ذلك، ومعه سطر بعد الـfooter يذكر أنه
قد يكون ناقصًا. والـsub-agent الذي لديه output schema واستنفد خطواته يُجري
استدعاءً أخيرًا إجباريًا (Out of steps): عندما
يُرجع هذا الاستدعاء كائنًا صالحًا، تكون نتيجة task هي هذا الكائن (finish reason
'max-steps' في الـfooter، ومعه سطر يذكر أن الخطوات نفدت)، وليست خطأً.
يُضاف استهلاك الـsub-agent من الـtokens إلى result.usage الخاصة بالـlead،
وكذلك استهلاك الـremote sub-agent. أما result.toolErrors
الخاصة بالـlead نفسه فلا تعدّ إلا الـtool calls الخاصة به؛ وأما الاستدعاءات التي فشلت
داخل الـsub-agents التابعة له (وداخل الـsub-agents التابعة لها) فتُحتسب في
result.usage.delegated.toolErrors.
تُرمى أخطاء الإعداد ومعها طريقة الحل: sub-agent بدون description،
أو قيمة ليست agent من createAgent()، أو tool خاصة بك اسمها أصلًا
task (أو agent_status أو agent_await أو agent_cancel).
تكملة مهمة
يعمل كل استدعاءtask في محادثة فرعية لها taskId (task_1،
task_2، … في الـfooter). ويمكن للـlead الرجوع إليها:
يعرف الـmodel ذلك من وصف الـtool
task نفسه، لذا لا يحتاج سؤال المتابعة إلى
أي كود. لكن الـlead الذي يحتفظ بعمله عبر الدورات أو إعادات التشغيل يحتاج إلى
store وsession (جلسة):
- مع
createAgent({ store })(store.sessions) وrun للـlead لهsessionId(سواءsend(message, { sessionId })مع checkpoints أو دور في session)، تُحفظ كل مهمة فيstore.sessionsبعد انتهاء run المهمة، تحت مفتاح مُهشّم (hashed) من معرّف session الـlead ومنtaskId. وهي تبقى بعد انتهاء run الـlead: فالدورات اللاحقة في الـsession نفسها، والـlead المُستأنف بـagent.resume()أوapprovals.resolve()، والـprocess الجديدة على الـdurable store نفسه (مخزن يبقى بعد إعادة تشغيل الـprocess) — كلها تستطيع إكمالها. ولا يطابقtaskIdمن session لـlead آخر أبدًا. لا يحتوي الـsession store على list API، لذا لا تُسرد هذه المدخلات ولا تُحذف مع session الـlead؛ احذف بيانات الـstore للتخلص منها. ومعAgentExecutor.execute()عيّن الـstore باستخدامwithSubagentOptions(subagents, { sessions }). - في بقية الحالات (لا يوجد session store، أو run للـlead بدون
sessionId)، تبقى المهمة في الذاكرة لذلك الاستدعاء الواحد لـexecute()/send(): فالـrun الذي يتوقف بانتظار approval ثم يُستأنف يبدأ بدون أي مهمة. والـsub-agent الذي تستأنفه الـapproval نفسها يظل يرد على الـlead (كنتيجةtaskأوagent_await)، لكن لا يمكنك إكماله بـtaskIdبعد ذلك؛ استخدم session store لهذا الغرض.
stop أو length أو max-steps)،
لذا لا يمكنك إكمال المهمة التي فشلت أو أُلغيت. وتصل الأخطاء إلى الـlead كـ
tool errors منظمة: الـtaskId المجهول، أو التابع لـsession لـlead آخر، أو التابع
لـsub-agent آخر، يفشل بالخطأ LOUSHO_SUBAGENT_TASK_NOT_FOUND؛ والمهمة التي لا تزال
تعمل (مهمة background لم تنتهِ) تفشل بالخطأ LOUSHO_SUBAGENT_TASK_BUSY، الذي يطلب
من الـmodel أن يستدعي agent_await أو agent_cancel عليها أولًا. والخطأ الخاص
بـtaskId تابع لـsub-agent آخر يطلب من الـmodel حذف taskId لكي يبدأ مهمة
جديدة.
يمكن للـlead الذي لا يحتاج إلى متابعات أبدًا أن يزيل التكملة باستخدام
subagentOptions: { continuation: false }: عندها لا تحتوي الـtool task
على الوسيطين taskId وmode، ويبدأ كل استدعاء مهمة جديدة، ولا يذكر وصف الـtool
ولا بلوك الـprompt الـtaskIds. أحيانًا تمرّر الـmodels الأضعف للـlead
taskId خاصًا بـsub-agent إلى sub-agent آخر وتضيّع دورة على الخطأ؛ وهذا الخيار
يزيل هذا الاحتمال.
task عادي في كل ما عدا ذلك:
يمكنك تشغيلها في الخلفية (وتحتفظ بالـtaskId نفسه)، والـapproval داخلها توقف
الـlead وتستأنفه مثل أي approval لـsub-agent، ويُحتسب استهلاكها ضمن
usage وlimits الخاصة بالـlead. ويرى الـsub-agent كامل الـtranscript
من جديد مع كل resume، لذا تكلّف المهمة طويلة العمر tokens أكثر في كل مرة.
مهام بالتوازي
تعمل الـtool calls في دور model واحد معًا (راجعtoolConcurrency)،
لذا عندما يستدعي الـlead الأداة task أكثر من مرة في دور واحد، تعمل الـsub-agents
بالتوازي. تصل النتائج إلى transcript الـlead بالترتيب نفسه الذي
أجرى به الـmodel الاستدعاءات. ضع حدًا أقصى باستخدام toolConcurrency على الـlead
(1 يشغّلها واحدًا تلو الآخر).
Sub-agents في الخلفية
معbackground: true، تبدأ task الـsub-agent وتعود فورًا بـ
{ taskId, status: 'running', agent }، لذا يستطيع الـlead مواصلة عمله (أو بدء
مهام أخرى) أثناء عمله. بعد ذلك يستخدم الـlead:
يعمل في الوقت نفسه بحد أقصى
maxConcurrent sub-agent خلفي لكل run للـlead
(الافتراضي 3)؛ والاستدعاءات الزائدة بـbackground: true تحصل على
status: 'queued' وتبدأ عندما تتوفر أماكن. عيّنها باستخدام subagentOptions
في createAgent():
AgentExecutor.execute()، ألحِق الخيارات نفسها بقيمة subagents
باستخدام withSubagentOptions(subagents, options) الذي يُرجعها. وفي createAgent()
تتقدّم subagentOptions على الخيارات الملحقة بهذه الطريقة.
يمكن للـlead الذي لا يحتاج إلى مهام خلفية أبدًا أن يزيلها باستخدام
subagentOptions: { background: false }: عندها لا يحصل الـlead إلا على الـtool
task، بدون وسيط background الخاص بها، ولا يذكر بلوك الـprompt المهام
الخلفية. وهذا يوفّر الـschemas والنصوص الخاصة بالـtools الثلاث (بضع مئات من الـtokens) في كل
طلب للـlead.
يرث الـsub-agent الخلفي من run الـlead مثل المتزامن (hooks وtracing
وevent listeners وتجميع الاستهلاك)، ويُطبَّق maxSubagentDepth بالطريقة نفسها.
وإيقاف signal الـlead يلغي الـsub-agents الخلفية، سواء كانت queued أو
قيد التشغيل.
When the lead run ends
تتبع المهام الخلفية run واحدًا (استدعاء واحد لـexecute() / send() /
stream()). عندما ينتهي الـrun، أيًّا كانت طريقة انتهائه، تُلغى المهام التي لا
تزال queued أو قيد التشغيل افتراضيًا (تنقطع الـruns الخاصة بها). ومع
awaitBackgroundOnFinish: true ينتظر الـrun بدلًا من ذلك انتهاءها قبل أن
يكتمل (والـrun الخاص بـlead منقطع أو فاشل يلغيها أيضًا). في الحالتين لا يكتمل الـrun إلا
بعد أن تتوقف الـruns الخاصة بها، لذا لا يصل أي event لـsub-agent إلى مستمعي
الـrun بعد ذلك؛ ومع awaitBackgroundOnFinish تصل الـevents الخاصة بها قبل
run.done الخاص بالـlead.
تعدّد النتيجة كل مهمة خلفية في الـrun مع حالتها النهائية:
result.backgroundTasks القيمة { taskId, agent, status, elapsedMs, error?, approvalId?, toolName? } لكل مهمة (بشكل agent_status نفسه) وتغيب عندما
لا يبدأ الـrun أي مهمة خلفية. استخدم agent_await في الـlead (يطلب منه الـsystem
prompt ذلك) لكي تصل إجاباتها إلى المحادثة.
الـhook الخاص بالـexecutor الذي يقف وراء ذلك عام (public): يُستدعى ExecuteOptions.onRunEnd
مرة واحدة بالضبط لكل run، مع { result } (أيًّا كان finishReason)
أو { error }؛ ويُحسم الـrun بعد أن يعود. وتُسجَّل المهام الخلفية في
result قبل أن يراها onRunEnd الخاص بك.
القيود:
- run الـlead الذي يتوقف بانتظار approval (
finishReason: 'awaiting-approval') ينتهي هناك: تُلغى مهامه الخلفية التي لا تزال queued أو قيد التشغيل (أو يُنتظر انتهاؤها) مثل أي نهاية أخرى، ويبدأ الـrun المستأنف بدون أي مهمة. الـrun المستأنف run مستقل لا صلة له بمهام الـrun المتوقف (وقد يعمل حتى في process أخرى)، لذا لا يمكنه إبقاؤها حية عبر التوقف. - الـsub-agent الخلفي الذي يحتاج إلى approval يتوقف بـ
status: 'awaiting-approval'(معapprovalIdوtoolNameالخاصين بالـchild)؛ ولم يُنفَّذ استدعاؤه بعد. ولا يكمل إلا عندما ينتظره الـlead باستخدامagent_await(يخبر وصفاtaskوagent_statusالـmodel بذلك). عندها يتوقف الـlead على تلك الـapproval، مثل sub-agent متزامن: تحتوي نتيجة الـlead علىfinishReason: 'awaiting-approval'، وتسمّي الـapproval المعلقة استدعاء الـchild بـsubagentPath: ['<agent>']، وتُسرد فيagent.approvals.list(). ويُنفّذapprovals.resolve()(أوresume()بعد إعادة التشغيل، مع durable store) استدعاء الـchild أو يرفضه، ويتركه يكمل، ويحصل الـlead المكمّل على جواب الـchild كنتيجةagent_await(status: 'done'معresult، أو'failed'). يُضاف استهلاك الـchild إلى استهلاك الـlead، وتُحفظ محادثته تحتtaskIdمثل أي مهمة، لذا يستطيعtask({ taskId })إكمالها. - إذا توقف الـchild مرة أخرى، يتوقف الـlead مرة أخرى على الـapproval
التالية. وإذا كان استدعاء
agent_awaitواحد ينتظر عدة مهام كلها متوقفة، يتوقف الـlead عليها واحدة تلو الأخرى، ثم يُرجع ذلك الاستدعاء كل الإجابات دفعة واحدة. - المهمة التي لا تزال
awaiting-approvalعندما ينتهي الـlead دون أن ينتظرها تُسجَّل فيresult.backgroundTasksبالحالة نفسها ولا يمكنك استئنافها: فقد اختار الـmodel ألا ينتظرها.
Dynamic catalogs
بدلًا من record ثابت، مرّر catalog يحتوي علىlist() وresolve(name).
تُستدعى list() في بداية كل run يعرض الـtool task، لذا يمكن أن تتغير
المجموعة من run إلى آخر؛ وتُستدعى resolve() عندما يختار الـlead اسمًا (أرجع
undefined للاسم المجهول).
Remote sub-agents
يستخدمremoteAgent() agent نشرته أنت أصلًا (lousho build --target=node-server أو docker أو cloudflare-worker) كـsub-agent.
يوضع في subagents بجانب الـagents المحلية، ويفوّض إليه الـlead باستخدام الـtool
task نفسها، بما في ذلك background: true.
POST <url>/chat مع
{ sessionId, input }، وتُقرأ كـstream أحداث SSE، راجع
النشر)، وترسل prompt المهمة وتُرجع النص
النهائي للـagent البعيد (أو الكائن بصيغة JSON عندما يكون للـagent المنشور
output schema، راجع المخرجات المنظمة)، ويليه
footer يسمّي الـsession والـtaskId. واستدعاء task الذي يستأنف ذلك
الـtaskId يُرسَل إلى الـsession البعيدة نفسها، فيكمل الـagent البعيد بالـhistory
الخاص به (أبقِه في store على الطرف البعيد)؛ ولا يمكنك عمل
fork لمهمة بعيدة. لا يرى الـagent البعيد إلا ذلك الـprompt، ويعمل بالـmodel والـtools
والـlimits الخاصة به، لذا لا يصل إليه runtime الـlead (hooks وsandbox وapproval store).
وإشارة إيقاف run الـlead توقف الطلب. الخيارات: url وauth
وname وdescription وheaders وfetch (احقن fetch خاصة بك في
الاختبارات؛ فالـagent الذي يعمل في الـprocess نفسها خلف
createRouteHandler(agent, { basePath: '/' }).handler — الـFetch handler
المُصدَّر، راجع النشر — يعمل كـfake
deployment: fetch: (input, init) => handler(new Request(input, init))).
تصل حالات الفشل (تعذّر الوصول إلى الـagent، أو رد 401 أو أي رد آخر غير 2xx، أو stream
مشوَّه، أو run بعيد ينتهي بخطأ) إلى الـlead كـtool error منظم بالكود
LOUSHO_REMOTE_REQUEST_FAILED (وLOUSHO_REMOTE_UNAUTHORIZED لـ401)؛
ولا يكون الـtoken أبدًا جزءًا من خطأ أو event.
يُضاف استهلاك الـtokens للـrun البعيد، كما يُبلغ عنه الـagent البعيد في event
run.done الخاص به، إلى result.usage الخاصة بالـlead: إلى الإجماليات،
وإلى usage.delegated، وإلى byModel['remote:<name>'] (<name> هو المفتاح
في subagents). لا يرسل الطرف البعيد تفصيلًا لكل model، لذا يحمل ذلك الإدخال الواحد
إجمالياته وتقدير costUsd الخاص به؛ وعندما لا يرسل الطرف البعيد تكلفة،
تصبح costUsd الخاصة بالـlead هي undefined. يثق الـlead بهذه الأرقام: ولا
يستطيع التحقق منها. والنشر الأقدم من هذا التغيير لا يرسل usage، وعندها لا يُضاف
أي شيء. الـrun البعيد الذي يتوقف بانتظار approval يضيف ما استهلكه قبل التوقف، والتكملة لا تضيف
إلا ما استهلكته بعده. يصل الـusage عندما ينتهي الـrun البعيد، لذا لا تراه limits
الخاصة بالـlead إلا بعد أن يعود استدعاء task. والـRemoteSubagent
المكتوب يدويًا يحصل على الـusage لكل دور عبر خيار onUsage في run() الخاصة
به.
Remote approvals
إذا توقف الـrun البعيد بانتظار approval، يتوقف run الـlead عليها تمامًا مثل sub-agent محلي: تكونresult.finishReason هي 'awaiting-approval'،
وتحمل الـapproval المعلقة في agent.approvals.list() (وفي أزرار القنوات،
ومحادثة التطوير، وطلبات الصلاحية في ACP) اسم الـtool البعيدة ومدخلها،
مع subagentPath: ['researcher']. واستدعاء ask_question البعيد يصل
كسؤال (kind: 'question') تجيب عنه باستخدام agent.approvals.answer().
والبت فيها على الـlead (resolve أو streamResolve أو answer) يرسل
القرار إلى مسار الـapprovals لدى الـagent البعيد
(POST <url>/chat/<session>/approvals/<id>)، ويقرأ التكملة، ويصبح جوابها
النهائي نتيجة task؛ والتكملة التي تتوقف مرة أخرى توقف الـlead مرة أخرى.
taskId، واسم الـsub-agent، لذا تستطيع
process lead جديدة على الـstore نفسه البت فيها؛ ولا يُخزَّن الـbearer token
أبدًا (يُقرأ من خيارات remoteAgent() من جديد). والفشل أثناء
البت (رد 401، أو أي رد آخر غير 2xx مثل 404 من الطرف البعيد على approval لم تعد
معلقة، أو خطأ شبكة) هو الـtool error المنظم لذلك الاستدعاء task
بالأكواد المذكورة أعلاه، ويكمل run الـlead. ولا يظل يُفشل المهمة بالخطأ
LOUSHO_SESSION_AWAITING_APPROVAL إلا الـrun الذي لا يملك approval store
(AgentExecutor مجرد)، ويسمّي الخطأ الـsession البعيدة ومعرّف
الـapproval لكي تبت فيها على الـagent البعيد.
يغطي remoteAgent() الـagents المنشورة عبر HTTP. ونوع آخر من الـsub-agent
“البعيد” هو runner من frameworks أخرى للـagents يعمل داخل الـprocess —
ابنِ واحدًا على العقد نفسه باستخدام defineRemoteSubagent() (أدناه) أو استخدم
محوّل Pi الجاهز.
Pi coding-agent sub-agents (piAgent())
يشغّل piAgent() Pi coding agent
(@earendil-works/pi-coding-agent، peer dependency اختيارية — npm install @earendil-works/pi-coding-agent) داخل الـprocess كـsub-agent. لا يعمل إلا على
Node: إذ تعمل tools الخاصة بـPi (read وbash وedit وwrite و…)
على مجلد محلي.
task هو Pi session واحدة: يصبح sessionId الخاص بالمهمة
معرّف الـPi session، لذا فإن استئناف taskId — والاستئناف بعد توقف بانتظار approval،
حتى في process جديدة — يفتح ملف الـsession نفسه ويكمل الـprompt التالي
الـtranscript. لا يمكنك عمل fork لمهمة Pi (يفشل استدعاء task بخطأ
“cannot be copied” الخاص بالـsession البعيدة). الخيارات: cwd (مطلوب)،
model، modelRuntime، description (مطلوب)، name، permissions،
agentDir، sessionDir، tools (allowlist لـtools الخاصة بـPi)،
thinkingLevel.
تحكم قواعد permissions كل tool call لـPi (يُطلَق الـtool_call extension
event الخاص بـPi قبل أن تعمل الـtool): deny يرفض الاستدعاء،
وask يوقف run الـlead بانتظار approval تمامًا مثل الـremote sub-agent —
تكون result.finishReason هي 'awaiting-approval' وتحمل الـapproval المعلقة
اسم tool الـPi ووسائطها وsubagentPath. تخبر الموافقةُ Pi بأن
الاستدعاء معتمد وتسمح لذلك الاستدعاء بالذات (اسم الـtool نفسه + الوسائط
نفسها) بالعمل مرة واحدة (لا يملك Pi واجهة API لـ”تشغيل الاستدعاء المتوقف”، لذا يعيد الـmodel
إصداره وتسمح البوابة لذلك الاستدعاء الواحد)؛ ويرسل الرفض ملاحظة
القرار كدور مستخدم تالٍ ولا يعمل الاستدعاء المرفوض أبدًا. بدون approval
store يُرفض ask مباشرة. ويحتفظ run الـPi المتوقف بالـusage الخاص به عند
التوقف وتُبلغ تكملته عن الباقي، وفق حسابات remoteAgent() نفسها.
SubagentApprovalPause (المُصدَّرة حاليًا) هي ما يرميه adapter من هذا
النوع لكي يوقف الـlead؛ وتسجّل defineRemoteSubagent(impl) أي object يطابق
RemoteSubagent للاستخدام في subagents، لذا يوجّه استدعاء task إليه عبر
المسار البعيد.
Depth
يحددmaxSubagentDepth (الافتراضي 1) عمق تداخل الـsub-agents.
افتراضيًا، يستطيع الـlead استدعاء sub-agents لكنها لا تستطيع استدعاء
sub-agents خاصة بها: فالـrun الذي بلغ الحد لا تُعرض عليه الـtool task ببساطة،
حتى لو بُني مع subagents. وتسمح maxSubagentDepth: 2 لـsub-agents
الـlead بالتفويض مرة إضافية. تُطبَّق قيمة الـrun الأعلى على الشجرة كلها؛
ولا يكون لـmaxSubagentDepth الخاصة بـsub-agent معيّن أثر إلا عندما يعمل
كـagent في المستوى الأعلى.
What a sub-agent inherits
يحتفظ الـsub-agent بتعليماته، والـmodel/provider الخاص به، والـtools والـskills وmaxSteps الخاصة به، ويبقى سياقه معزولًا. ومن الـrun الذي استدعاه
يرث:
Hooks داخل sub-agents
راجع الـhooks لنقاط الربط والنتائج. تُطبَّق hooks الأب على الـsub-agents التابعة له افتراضيًا. ويُخبرctx.subagent
الـhook بأنه يعمل داخل أحدها — ويحتوي على name الـsub-agent، وdepth
عمقه (1 لـsub-agent تابع للـrun الأعلى)، وtoolCallId الخاص بالـlead
الذي بدأه، والـsub-agent المحيط في parent عند التداخل الأعمق. والـhook
الذي يجب ألا يرى إلا الـrun الأعلى يعود مبكرًا:
Events
يبثagent.stream() / AgentExecutor.stream() على الـlead الـrun الخاص بكل
sub-agent داخل الـstream نفسه — الخطوات، وdeltas النص، وevents الـtools،
والأخطاء — مع حقل subagent على كل event منها، لذا تستطيع واجهة المستخدم
أن تعرض نشاط الـsub-agent متداخلًا تحت استدعاء task الخاص بالـlead
(subagent.toolCallId). راجع Streaming: sub-agents.
يحصل الـlistener على الـlead (createAgent({ onEvent }) أو onAgentEvent) على
الـevents نفسها، بما فيها events الـsub-agents، لحظة وقوعها. راجع
الاستماع دون المرور على الأحداث.
Approvals inside a sub-agent
عندما يستدعي sub-agent أداة لهاneedsApproval، يتوقف الـrun كله:
يعود send() الخاص بالـlead بـfinishReason: 'awaiting-approval' ومعه
approvalId، ويحتفظ الـapproval store بسجل واحد فقط، استدعاؤه المعلق هو
استدعاء الـsub-agent (toolName، args) مع subagentPath يسمّي
الـsub-agents التي يعمل داخلها (مثل ['researcher']). وافق عليه أو ارفضه
باستخدام lead.approvals.resolve({ id, approved }) (فالـlead يعرف أصلًا
subagents الخاصة به؛ والـapproval store في الذاكرة هو الافتراضي، لذا لا
تحتاج إلى approvalStore):
task، ثم يكمل الـlead. إذا
احتاج الـsub-agent إلى approval أخرى، يتوقف الـrun مرة أخرى بـapprovalId
جديد. ويعمل ذلك على أي عمق.
خيار approve على الـlead يبت في استدعاءات الـsub-agents التابعة له
أيضًا.
الضمانات والحدود:
- لا يعمل أي استدعاء مرتين ولا يضيع أي استدعاء: تُخزَّن حالة الـsub-agent المتوقفة
داخل سجل الـapproval الخاص بالـlead (JSON عادي، لذا يعمل أي
ApprovalStore)، ويعمل الاستدعاء المعتمد مرة واحدة بالضبط، عند الاستئناف. - استدعاءات الـtools الأخرى في دور الـlead نفسه التي انتهت تحتفظ بنتائجها ولا تعمل من جديد.
- approval واحدة معلقة لكل run. إذا توقف sub-agentان في الدور نفسه،
يتوقف الـrun على الأول (بترتيب الاستدعاء)؛ ويُوقَف الثاني ويحصل الـlead على
نتيجة خطأ لذلك الاستدعاء
taskتذكر أن استدعاءه لم يُنفَّذ، لذا يستطيع طلبه من جديد بعد الـapproval. - تُطلَق hooks ما قبل الـtool وما بعدها الخاصة باستدعاء
taskمرة أخرى عند الاستئناف، مثل hooks أي tool معتمدة. - الـsub-agent الذي تغيّر تعريفه منذ التوقف (تعليمات أو model أو tools)
يعالجه
onAgentDriftالخاص بالـlead، كما يعالج الـlead نفسه:'error'يرفض الاستئناف ويترك الـapproval معلقة، و'warn'(الافتراضية) تحذّر وتُطلقagent.driftمع تعيينsubagent. والـsub-agent الذي لم تعد لديه tool الاستدعاء المعتمد يُرفض دائمًا بالخطأLOUSHO_RESUME_TOOL_MISSING. راجع الاستئناف بـagent متغير. - يستمر تراكم استهلاك الـtokens عبر التوقف: usage الـsub-agent قبل التوقف
موجود في النتيجة المتوقفة، وما يستهلكه بعد الاستئناف يُضاف إلى
result.usageالخاصة بالـlead المستأنف. - الـapproval الخاصة بـsub-agent خلفي توقف الـlead عندما ينتظره الـlead باستخدام
agent_await؛ راجع Sub-agents في الخلفية.
متقدم: executor API
معAgentExecutor.execute() بوصفه lead (راجع executor API)،
يحتاج الـrun إلى approvalStore؛ وبدونه يصبح استدعاء الـsub-agent نتيجة خطأ
ولا يُنفَّذ أي شيء. استأنف باستخدام resumeAfterApproval()، ومرّر خيار subagents نفسه
الذي استخدمه الـrun المتوقف: