الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـ hook هو object بالشكل { name, preToolCall?, postToolCall?, preGenerate?, postGenerate? } يعمل داخل الـ agent loop، حول كل tool call وكل model call. استخدمه لكتابة audit log، أو لرفض tool، أو لحجب نتيجة أو قصّها، أو لحقن context قبل الـ model call، أو لتغيير الـ request الذي سيُرسَل (header أو temperature). الـ hooks كود تكتبه أنت، وليست policy ولا قرارًا بشريًا: للقواعد التي تسمح أو ترفض أو تسأل على مستوى كل tool، ولموافقة شخص على call معيّن، استخدم permissions وneedsApproval (الموافقات). الـ listeners مثل onEvent تراقب الـ run فقط ولا تستطيع تغييره (Streaming)؛ أما الـ hook فيستطيع.

أول hook لك

مرّر الـ hooks إلى createAgent({ hooks }). هذا الـ hook يسجّل كل tool call والنتيجة التي أعادها:
كل method اختيارية: نفّذ النقاط التي تحتاجها فقط. الـ hook الذي لا يعيد شيئًا يراقب فقط؛ وتعديل ctx.args أو ctx.messages أو ctx.request في مكانه يغيّر الـ run أيضًا.

نقاط الـ hook الأربع

الحقول المشتركة في كل context هي agentId وagentName وsessionId وmessages (سجل المحادثة الـ live) وmetadata (مساحة حرة تضع فيها ما تريد) وsubagent (تُملأ داخل sub-agent). سياقات الـ tool call تحمل أيضًا resumedAfterApproval: تكون true فقط عندما يعمل الـ hook على call يُعاد تشغيله بعد أن وافق شخص على إيقافه، لكي يستطيع hook لديه state (مثل loop guard أو عدّاد audit) تخطي إعادة التشغيل بـ if (ctx.resumedAfterApproval) return;. ويوجد ctx.emit عندما يكون للـ run listeners (createAgent({ onEvent }) أو onAgentEvent) أو عندما يكون هناك streaming، ويضيف حدثَي compaction.start وcompaction.done إلى أحداث الـ run. وداخل run الـ executor، يحصل preGenerate أيضًا على ctx.generate(provider, request, purpose): model call جانبي (يستخدمه الـ summarizer الخاص بالـ compaction) له chat span خاص به موسوم بـ lousho.call.purpose، ويُحسب ضمن usage الخاص بالـ run وضمن الـ budgets.

Hook outcomes

الـ tool-call hook يستطيع أن يغيّر ما يحدث، لا أن يراقبه فقط. الـ preToolCall hook يستطيع أن يعيد:
  • لا شيء: يستمر الـ call دون تغيير (وتعديل ctx.args في مكانه يعمل أيضًا).
  • { deny: reason }: لا يعمل الـ call. يصل إلى الـ model خطأ الـ tool نفسه kind: 'denied' الذي ينتج عن رفض needsApproval (انظر الموافقات)، وترى الـ streams tool.error، وonPermissionDecision يسجّل decision: 'deny' مع hook وreason.
  • { result: value }: لا يعمل الـ call وتصبح value نتيجته. حدث tool.done ورسالة tool في الـ transcript (metadata) يحملان replacedByHook: '<hook name>'.
  • { input: args }: يعمل الـ call بـ args. يُجرى عليها validation مرة أخرى مقابل الـ input schema الخاصة بالـ tool؛ وإذا لم تطابقها تصبح خطأ tool من النوع kind: 'validation' تذكر رسالته اسم الـ hook، ولا يعمل الـ tool.
الـ postToolCall hook يستطيع أن يعيد { result: value } لاستبدال النتيجة التي يراها الـ model (يحجبها أو يقصّها)؛ وإعادة لا شيء تُبقي النتيجة الأصلية. الـ hooks تعمل بترتيب تسجيلها: أول deny أو result من pre-hook يتخطى الـ pre-hooks التي تليه، وقيم input تتسلسل (كل hook يرى قيمة الذي قبله في ctx.args)، وكل post-hook يرى النتيجة التي استبدلها hook قبله. والـ hook الذي يرمي error يُفشل الـ run كما كان من قبل. والـ sub-agents ترث hooks الـ agent الرئيسي ونتائجها.

أمثلة

كل مثال برنامج كامل. جميعها تعمل على mockModel، فلا يحتاج أيٌّ منها إلى API key ولا إلى model call حقيقي؛ والنمط نفسه يختبر الـ hooks التي كتبتها offline (Testing). كل مثال يجهّز turn للـ model فيه tool call، تليه إجابة نهائية.

أوقف run لا يتقدّم

createProgressGuard() يوقف run ينفق الـ budget الخاص به على calls لا تؤدي إلى شيء. وهو معطّل ما لم تُضِفه:
  • ابتداءً من الفشل الثاني لـ tool بالخطأ نفسه، يضيف hint إلى النتيجة، فيه نصيحة بحسب نوع الفشل (classifyToolFailure(): input خاطئ، أو timeout، أو قدرة ناقصة، أو صلاحية، أو غير معروف).
  • بعد maxFailures من حالات الفشل بالخطأ نفسه (الافتراضي 3)، يرفض هذا الـ tool لبقية الـ run. الأرقام في الرسالة لا تجعل الخطأ مختلفًا.
  • بعد maxRepeats من الـ calls المتطابقة التي تعيد النتيجة نفسها (الافتراضي 3)، يرفض هذا الـ call. الـ call الذي تتغيّر نتيجته ليس تكرارًا.
  • بعد أن تعيد maxSameResults من الـ calls لـ tool النتيجة نفسها (الافتراضي 5)، يرفض هذا الـ tool، حتى لو اختلفت الـ arguments في كل call. هذا يكشف الـ model عندما يعيد صياغة بحث يظل يجد الشيء نفسه.
  • بعد maxDenials من حالات الرفض (الافتراضي 3)، يوقف الرفض التالي الـ run بـ LOUSHO_RUN_NO_PROGRESS، ولا يعيد agent.recover() محاولته.
كل action يُبث كحدث heal.action. النتيجة التي استبدلها تُعلَّم على الـ span الخاص بالـ tool بـ lousho.tool.replaced_by_hook، ويُسجَّل الرفض كخطأ في الـ span. الـ guard يعدّ من سجل محادثة الـ run، فيحتفظ الـ run المستأنَف بتاريخه. الـ calls الموجودة في batch واحدة لا تُعدّ إلا بعد أن تنتهي الـ batch، وقد يُزيل ضغط السياق (compaction) calls قديمة من العدّ.

افحص ما أخرجته الـ tool

الكتابة الناجحة لا تثبت أن الـ output صالح للاستخدام. createOutputCheck() يشغّل الفحص الخاص بك بعد أن تنجح الـ tool. إذا أعاد مشكلة، أو رمى خطأً، يراها الـ model كـ outputCheckFailed على النتيجة ويستطيع إصلاح الـ output. الفحص هو كودك، فاجعله مستقلًا عما كتبه الـ model.

امنع tool بالاسم

أضف argument افتراضي

أعِد { input } لكي تشغّل الـ tool بـ arguments مختلفة. يُجرى عليها validation مرة أخرى مقابل الـ schema الخاصة بالـ tool.

قصّ النتيجة أو احجبها

الـ postToolCall يستلم النتيجة المستقرة، ويستطيع أن يعيد { result } لكي يستبدل ما يراه الـ model. الـ tool نفسه عمل دون تغيير.

احقن context قبل الـ model call

الـ preGenerate يرى ctx.messages وctx.request الـ live. نفّذ push لرسالة لكي تضيف context، أو غيّر حقلًا في الـ request.

الترتيب والتفاعل

للـ tool call الواحد، الترتيب هو: validation على الـ arguments، ثم preToolCall hooks، ثم قواعد الـ permissions (permissions)، ثم الـ tool guardrails، ثم needsApproval الخاص بالـ tool، ثم إيقاف الموافقة، ثم التنفيذ، ثم postToolCall hooks. الـ hooks تعمل قبل كل قرار موافقة، فالقواعد وneedsApproval والشخص جميعهم يرون الـ input الذي أنتجه الـ hook ويوافقون عليه؛ وargs في الموافقة المعلّقة تُظهره. وعندما يُستأنف call موافَق عليه، تعمل الـ pre-hooks مرة أخرى: تظل قادرة على رفضه أو تقديم نتيجته، لكن { input } المختلف عن الـ input الموافَق عليه يُرفض بخطأ tool بدلًا من أن يعمل. انظر الموافقات للإيقاف والاستئناف.
  • أكثر من hook تعمل بترتيب مصفوفة hooks، واحدًا تلو الآخر: يُنتظر كل واحد بـ await قبل الذي يليه، فيرى الـ hook اللاحق ما غيّره السابق.
  • hook يرمي error يُفشل الـ run. الـ hooks كود موثوق: لا يتحوّل الـ error إلى tool result يراه الـ model.
  • Compaction. createAgent({ hooks }) يشغّل الـ hooks التي كتبتها أولًا، ثم الـ compaction hook، فيرى الـ compaction ما أضافته (Context compaction).
  • Sub-agents ترث hooks الـ agent الرئيسي. ctx.subagent تُملأ عندما يعمل الـ hook داخل أحدها، فيستطيع الـ hook أن يعود مبكرًا لكي يرى الـ run الأعلى فقط (الـ hooks داخل الـ sub-agents).

HookRegistry

createAgent({ hooks }) يقبل array عاديًا. الكود الذي يستخدم الـ executor API (executor API) يمرّر HookRegistry: مجموعة مرتّبة فيها register وregisterMany وget وhas وlist وunregister وclear وsize() — انتبه، size هي method (hooks.size())، وليست property بنمط Map. تسجيل hook ثانٍ بالـ name نفسه يستبدل الأول ويطبع warning.
HookRegistry وAgentHook وأنواع الـ context موجودة في جذر الـ package وفي الـ subpath lousho/hooks. الـ hooks التي تُكتب في محرر الـ canvas الخاص بـ Agent Forge تُترجَم إلى HookRegistry وتعمل داخل sandbox بدلًا من الـ host process: انظر Agent Forge.