الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـsub-agent (وكيل فرعي) هو agent مستقل — له تعليمات وmodel وtools وskills خاصة به — يسلّمه الـlead (الوكيل الرئيسي) مهمة مكتفية بذاتها. يبدأ بسياق نظيف: لا يرى إلا الـprompt الذي تعطيه إياه، ولا يرى محادثة الـlead أبدًا. يعمل بالخطوات التي يحتاجها، ثم يعود جوابه النهائي إلى الـlead كنتيجة tool واحدة.

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 على:
  1. بلوك Available sub-agents في الـsystem prompt: سطر لكل sub-agent (- name: description)، وجملة تذكر أن الـsub-agent لا يرى إلا الـprompt الذي يستلمه.
  2. 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 } يزيلهما).
  3. ثلاث tools للمهام الخلفية: agent_status وagent_await وagent_cancel (راجع Sub-agents في الخلفية).
عندما يستدعي الـlead الأداة task، يعمل الـsub-agent المسمّى على prompt وحده. نتيجة الـtool هي النص النهائي للـsub-agent، ومعها سطر footer صغير يمكن للـlead الاستفادة منه:
إذا لم ينتهِ الـsub-agent — رمى خطأً، أو استهلك كل 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 آخر وتضيّع دورة على الخطأ؛ وهذا الخيار يزيل هذا الاحتمال.
المهمة المستأنفة أو المتفرّعة (forked) هي استدعاء 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.
تفتح كل مهمة session جديدة على الـagent البعيد (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 مرة أخرى.
لا يحتفظ الـsnapshot الخاص بالـapproval لدى الـlead إلا بمعرّف الـsession البعيدة، ومعرّف الـapproval البعيدة، والـ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):
يشغّل الاستئناف استدعاء الـsub-agent المعلق (أو يرفضه)، ويتركه ينتهي، ويُرجع جوابه النهائي إلى الـlead كنتيجة 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 المتوقف: