الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
useLoushoAgent() يضع agent خلف واجهة محادثة. يشغّل turn، ويقرأ الـ typed event stream فور وصوله، ويحوّله إلى state جاهزة للـ render: رسائل بنصها وtool calls، وstatus لحقل كتابة الرسالة، والـ tool call المتوقف على approval إن وُجد. موجود على الـ subpath lousho/react. وreact (18 أو 19) peer dependency اختيارية: ثبّتها في التطبيق الذي يستخدم الـ hook.

المصادر

الـ argument الأول يحدد مكان تشغيل الـ agent. وضع داخل الـ process مخصص لكود React الذي يعمل في مكان يستطيع الـ agent أن يعمل فيه (Electron، React Native، الاختبارات). في المتصفح استخدم الـ remote mode: مكان مفاتيح API الخاصة بالـ models هو الخادم.

الـ state المُرجَعة

إلغاء تركيب المكوّن (unmount) يلغي الـ turn الجارية. أحداث run الخاص بـ sub-agent (التي تحمل subagent) لا تغيّر messages — باستثناء approval.requested من sub-agent، فهو يحدّث messages وpendingApproval وstatus (التوقف قرار المستخدم). إذا أردت عرض بقية أحداث الـ sub-agent فاقرأها من lastEvent.

Approvals

عندما يُستدعى tool عليه needsApproval، يتوقف الـ run بـ approval.requested. تصبح status هي 'awaiting-approval' ويمسك pendingApproval الـ call. بعد ذلك:
  • داخل الـ process، approve(note?) وreject(note?) يستدعيان agent.approvals.streamResolve({ id, approved, note }, { signal }) (انظر Approvals). أحداث الـ run المكمَّل تصل live، فيُلحق النص برسالة الـ assistant أولًا بأول وتعود status إلى 'idle'، أو 'awaiting-approval' إذا توقف الـ run مرة أخرى.
  • Remote، مرّر { approvalsUrl } كـ argument ثانٍ. يرسل الـ hook { "approved": true, "note": "..." } بـ POST إلى ${approvalsUrl}/${approvalId} ويعرض التكملة live من الـ SSE stream الذي يرد به الـ session API (أحداث أي turn محادثة نفسها؛ والتوقف الثاني يصل كـ approval.requested). والخادم الذي يرد بدلًا من ذلك بـ JSON من نوع ApprovalOutcome (مثل الذي أدناه) يظل يعمل.
  • Remote دون approvalsUrl، لا يفعل approve() وreject() شيئًا. اعرض pendingApproval واحسمه عبر الـ API الخاص بك، ثم أرسل الـ turn التالية بـ send().
إذا أنشأت الـ agent بـ askQuestion: true يستطيع أن يطرح سؤالًا على المستخدم (انظر سؤال المستخدم). يصل التوقف بالطريقة نفسها، مع pendingApproval.kind === 'question': اعرض pendingApproval.question.text والـ options الخاصة به، واستدعِ answer(text).

جهة السيرفر

نقطة نهاية Node للـ remote mode، مع route الموافقات (بادئة vendor/ في اسم الـ model هي التي تختار الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model>، مثل openrouter/openai/gpt-4o-mini):
بعد ذلك يستخدم الـ client useLoushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' }). لمحادثة multi-turn، احتفظ بـ agent.session({ id }) لكل محادثة على الخادم واستدعِ session.stream() بدلًا من agent.stream(). أعطِ الـ agent store (createAgent({ store: memoryStore() }) أو store من نوع durable) عندما تُفتح الـ sessions مع كل request: دون store، يحصل كل agent.session({ id }) على transcript جديد في الذاكرة، وتنسى الـ turn التالية الأولى (انظر اختيار الـ store).

داخل الـ process

الـ hook يستقبل الـ agent نفسه أيضًا. مثال على استدعائه من hook مخصّص:

بدون React

الـ hook مجرد wrapper رقيق. منطق الـ state هو reduceAgentEvents(state, event)، reducer نقي يعمل على AgentEvent وعلى بضعة actions محلية (ui.send، ui.decide، ui.resumed، ui.stopped، ui.reset، ui.error). وparseEventStream(response) يقرأ الأحداث من response الخاص بـ fetch. كلاهما مُصدَّر من الـ subpath نفسه، لاستخدامهما في binding مخصّص أو client دون React:
parseEventStream() يتخطى الأسطر الفارغة وتعليقات SSE وحقول event:/id: وأي سطر ليس حدثًا معروفًا، لذلك يقرأ صيغتَي التأطير الاثنتين. الخروج من حلقته يلغي الـ response body.

Todos

الـ agent الذي لديه todo tools يطلق حدث todo.updated مع كل todo_write. يخزن الـ hook أحدث قائمة في todos، وuseTodos(agent) يحوّلها إلى view فيه العدّادات والبند الجاري والتقدم. يستقبل ناتج الـ hook، فيغذي stream واحد المحادثة والخطة. تبقى القائمة عبر الـ turns ولا يمسحها شيء سوى hook جديد — ولا تُستعاد عندما تعيد الصفحة الاتصال بـ session موجودة.
current هو البند in_progress، وإن لم يوجد فهو أول بند pending، وundefined عندما لا يبقى شيء. progress هو completed / total (0 لقائمة فارغة). الـ view مُخزَّن memoized على agent.todos. وtodoView(todos) يحسب الـ view نفسه خارج React.