apps/agent-forge، واسمه الآخر الـ Studio) هو الـ dashboard
المرافق لهذه الـ SDK: تطبيق واحد فيه navigation على اليسار تبني منه الـ
agents وتشغّلها، وتجرّب الـ prompts، وتقرأ ما فعلته الـ agents الخاصة بك من
الـ observe daemon. تبني فيه graph الـ agent على canvas (لوحة الرسم)،
وتشغّله، وتحاوره، وتكتب pre/post hooks تعمل داخل sandbox (بيئة معزولة)
(وكل هذا يقرأ ويكتب ملف AgentSpec YAML نفسه الذي يستخدمه lousho dev
وlousho build)، وتجرّب الـ prompts في playground، وتقرأ من
الـ observe daemon الـ traces والـ
threads ومراقبة الـ fleet ودرجات الـ evals والـ datasets وطوابير التعليق
(annotation queues) وسجل الـ prompts والـ context hub. تشغّله بأمر واحد:
lousho studio، ويأتي ضمن حزمة npm للـ SDK نفسها.
تغطي هذه الصفحة: التثبيت، والـ quickstart مع lousho studio،
والـ navigation والشاشات، وجولة أول agent، وكتابة hooks، والـ
time travel (إعادة run من خطوة سابقة)، والـ endpoint الخاص بالـ playground،
وكيف تعمل إعدادات الـ secrets والـ deploy.

التثبيت
يأتي Agent Forge داخلlousho نفسه — لا توجد حزمة منفصلة
تثبّتها:
lousho studio (أدناه) نسخة جاهزة من التطبيق، فلا تحتاج إلى
كود apps/agent-forge المصدري ولا إلى الـ devDependencies الخاصة به (Vite،
وtsx، وغيرها) لكي تستخدمه.
إذا كنت تعمل داخل الـ monorepo الخاص بالـ SDK نفسها (تساهم في Agent Forge
ذاته)، فانظر وضع التطوير أدناه.
البدء السريع
http://127.0.0.1:4750/?token=<random>). افتح هذا الرابط بالضبط في المتصفح.
يفتح على شاشة Agents (#/agents): الـ navigation على اليسار، وشريط
أدوات البناء (اسم الـ agent وحالة الـ run، وشارة الـ model، ثم Debug
وStop وRun وImport وExport وSave)، وشريط الـ agents (الـ agents
المحفوظة + لوحة nodes وhooks)، والـ canvas، والـ Inspector على اليمين،
وdrawer سفلي فيه tabs Chat وLogs وTrace وOutput وHistory وSettings. يُفتح الـ
agent دون تحديد أي شيء والـ graph معروض كاملًا في الشاشة؛ ويبقى الـ
Inspector مطويًا حتى تحدد node، أو تضغط زر Inspector في الزاوية
العلوية اليمنى للـ canvas (اسمه للـ accessibility هو “Show inspector”)،
ويُحفظ هذا الاختيار. بقية الشاشات على بعد ضغطة في الـ navigation؛ انظر
Navigation.
عندما يكون العرض أقل من 860px، يصبح الـ navigation drawer تفتحه من زر
Navigation (القائمة) في الأعلى؛ ويغلقه اختيار شاشة أو الضغط على الخلفية المعتمة
أو Esc. في شاشة Agents، يصبح شريط الـ agents والـ Inspector
لوحات منزلقة تفتحها من الشريط العلوي؛ ويبقى Run (أو Stop) وSave في
الشريط، وتنتقل Debug وImport وExport وشارة الـ model إلى قائمة More
actions (⋯) فيه.
flags مفيدة:
رمز الوصول
يستطيع الـ studio تخزين مفاتيح الـ providers، وبدء runs، وتنفيذ كود الـ hooks، لذا فإن الـ API الخاص به مقفل على tab المتصفح الذي فتحته من الرابط المطبوع:- يولّد كل تشغيل token عشوائيًا ويطبعه في الرابط (
?token=...). تحتفظ الصفحة به لهذا الـ tab (يبقى بعد الـ reload) وترسله مع كل استدعاء API (headerx-lousho-studio-token) ومع الـ WebSocket (query?token=). وأي طلب بدونه يُرجع401. إذا فتحتhttp://127.0.0.1:4750بدون token في tab جديد، تُفتح الصفحة لكن استدعاءات الـ API فيها تفشل حتى تستخدم الرابط المطبوع. - لا يرسل السيرفر أي CORS headers، ويرفض (
403) أي طلب لا يكونOriginالخاص به هو origin الـ studio نفسه، أو لا يكونHostالخاص به اسم loopback (localhost،127.0.0.1،[::1]) ولا الـ--hostالذي ربطت عليه. ومع--host 0.0.0.0يُقبل أيHost، ويصبح الـ token الحماية الوحيدة. - لا يحتاج
GET /healthوالـ client الـ static إلى token.
curl، مرّر الـ token: curl -H "x-lousho-studio-token: $TOKEN" localhost:4750/agents.
يمرّر lousho studio هذه القيم إلى العمليات التي يشغّلها عبر متغيرات بيئة؛
ولا تحتاج إلى ضبطها بنفسك إلا عندما تشغّل سيرفر الـ studio بدون الـ CLI:
أين تعيش الـ agents
يحفظlousho studio ملفات specs الـ agents وحالة الـ runs تحت .lousho/
في المجلد الذي شغّلته منه: ملفات YAML للـ agents تحت .lousho/agents/،
وبجانبها الـ checkpoints (نقاط الحفظ) والـ approvals. وهو ترتيب .lousho/ نفسه
الذي يستخدمه lousho dev وlousho build. وملفات الـ YAML هذه مستندات
Agent spec v2، وتلك الصفحة تشرحها حقلًا حقلًا.
يعرض شريط الـ agents في شاشة Agents بالضبط الـ agents الموجودة في .lousho/agents/ هذا:
أي ملف YAML تضيفه هناك يظهر، وأي agent تنشئه في الـ studio يُكتب هناك
فورًا (الـ autosave وSave كلاهما يكتبان الملف)، فتستطيع محاورته
مباشرة. والمشروع الآخر، المفتوح في lousho studio خاص به، لا يعرض إلا الـ agents الخاصة به.
ولا يحتفظ المتصفح بشيء سوى مسودة لتعديل لم يستطع الوصول إلى السيرفر (تُرسل
في التحميل التالي)، محفوظة لكل مجلد workspace على حدة. وأي ملف في
.lousho/agents/ لم تعد قراءته ممكنة بشكل صحيح يُتخطّى مع تحذير في سجل السيرفر.
وضع production ووضع dev
لدىlousho studio وضعان ويختار المناسب منهما تلقائيًا:
- Production (الافتراضي بعد بناء Agent Forge): سيرفر Express واحد
يقدّم الـ REST/WebSocket API و الـ client الجاهز (تطبيق React) كملفات
static على port واحد. هذا ما يعمل عندما تثبّت الحزمة المنشورة بـ
npm install— لا يوجد Vite dev server منفصل ولا TypeScript loader. - Dev (يعود إليه إذا لم يحدث البناء بعد، أي داخل نسخة source من هذا الـ
monorepo): يعمل الـ API server مباشرة من كود TypeScript عن طريق
tsx، ومعه Vite dev server حقيقي (مع hot-module reload) يمرّر إليه طلبات الـ API. عمليتان، وportان داخليًا، وأمر واحد.
--prod و--dev أحد الوضعين. شغّل بدون أي منهما
وسيكتشف lousho studio الوضع بنفسه حسب وجود
apps/agent-forge/dist-server.
الـ Navigation
يعرض الـ navigation على اليسار كل الشاشات، مقسّمة إلى مجموعات:
خارج شاشة Agents، يوجد header للصفحة يسمّي الشاشة ويضع pill حالة الـ run
الحي في آخر سطر العنوان، بعد أي chips تضيفها الشاشة (مثل labels الـ
prompt). وتحت Settings، توجد بطاقة صغيرة تعرض حالة الـ collector (انظر
الـ collector). والزر الذي بجانب اسم
Agent Forge أعلى الـ nav (Collapse navigation) يصغّره إلى شريط
أيقونات؛ مرّر الماوس على أيقونة لكي ترى اسمها. ويُحفظ الاختيار بعد الـ
reload. وعندما يكون العرض أقل من 860px، يكون الـ nav دائمًا الـ drawer
الكامل.
الـ Routes والروابط المباشرة
لكل شاشة hash route، وتعيش فلاتر الشاشة في الـ query string الخاص بالـ URL، فيفتح الـ reload أو الـ bookmark أو الرابط الذي تلصقه الشاشة نفسها بالفلاتر نفسها. ولا تُكتب القيم الافتراضية أبدًا (#/traces وحده هو القائمة
الافتراضية لآخر 24 ساعة). وتستبدل تعديلات الفلتر والترتيب والصفحة الإدخال
الحالي في الـ history، ويضيف فتح صف إدخالًا جديدًا، فيعيدك زر Back في المتصفح
من trace إلى القائمة بدلًا من المرور على تعديلات الفلاتر واحدًا تلو الآخر. والـ hash
الفارغ أو غير المعروف يذهب إلى #/agents (ويبقى ?token=).
تُكتب الفترة الزمنية التي تختارها من preset غير الافتراضي كحدود
from/to
مطلقة، فيعرض الـ reload الصفوف نفسها بالضبط. والقائمة الكاملة للـ routes في
apps/agent-forge/src/screens/routeTable.ts.
لوحة المفاتيح
يعرض الـ command palette Go to لكل شاشة في الـ nav، وOpen agent
لكل agent محفوظ، وToggle theme (فاتح/داكن، ويُحفظ في المتصفح)؛ اكتب
لكي تفلتر. الصق trace id (8 أو أكثر من أرقام hex وشرطات) فيصبح أول عنصر
Open trace له. تتنقل الأسهم، وينفّذ Enter.

S العنصر (انظر
Annotation queues).
كلمات الحالة
كل حالة في الـ Studio هي الـ pill نفسه:- الـ Runs:
ok،error،running،interrupted(توقفت عملية الـ agent في منتصف الـ run؛ انظر الـ observe daemon). - الـ Agents:
healthy،stale(فاتته heartbeats)،down،stopped. - الـ Threads:
active،ended(خامل، انظر الـ sessions الخاملة)،interrupted. - الـ Scores:
pass،fail. - runs الـ builder:
idle،running،done،stopped،error،awaiting approval.
الـ collector (الـ observe daemon)
كل شيء تحت Observe وEvaluate وAssets يقرأ من الـ observe daemon (lousho observe start) عبر الـ proxy /observe في سيرفر الـ Studio. ولا يقرأ الـ
proxy إلا LOUSHO_OBSERVE_URL (الافتراضي http://127.0.0.1:7777)؛
ولا يغيّر LOUSHO_OBSERVE المكان الذي تقرأ منه الشاشات (فهو يحدد فقط إلى أين
تبلّغ runs الـ builder، انظر الجولة). وعندما يكون
LOUSHO_OBSERVE_TOKEN مضبوطًا، يرسله الـ proxy إلى الـ daemon كـ bearer token
مع كل قراءة وكتابة (كما يفعل تبليغ الـ runs والـ judge evaluators)،
فتعمل الشاشات أيضًا مع daemon مشغّل بـ --require-token. وبدونه، يرد هذا
الـ daemon بـ 401 على كل قراءة /api/ وتعرض الشاشات هذا الخطأ بدلًا من
البيانات (يبقى /health يرد، فتُظهر بطاقة الـ collector أنه يعمل). أما
credentials المتصفح نفسه (token الـ Studio، والـ cookies،
وAuthorization) فلا تُمرَّر أبدًا. يمرّر الـ proxy القراءات فقط مع
الكتابات التي تجريها الشاشات (درجات الـ feedback، وإصدارات prompts جديدة
من الـ Playground، ونقل labels الـ prompts، وتعديلات عناصر الـ hub، وكتابات
الـ datasets والأمثلة، وكتابات الـ annotation queues، وكتابات rules الـ
evaluators)؛ وأي كتابة أخرى، وأولها الـ ingest، تُرفض بـ 405. ويستدعي
الـ daemon دائمًا على LOUSHO_OBSERVE_URL، مهما كان الـ host المذكور في
سطر الطلب.
توضح بطاقة الـ collector أسفل الـ nav ما إذا كان الـ daemon يرد:
Checking collector… حتى أول فحص، ثم Collector running أو
Collector unreachable، مع URL الـ daemon تحتها. ويستمر الفحص بشكل
دوري. وما دام الـ daemon متوقفًا، تعرض كل شاشة تعتمد عليه الأمر الذي يشغّله
بدلًا من خطأ، وتحتفظ بالـ URL الخاص بها، وتستعيد البيانات بنفسها بمجرد أن يرد
الـ daemon. ولا تحتاج شاشة Agents وruns الـ Playground إلى الـ daemon.
الشاشات
Agents
الـ builder: انظر جولة أول agent. يفتح#/agents/<id> هذا الـ agent؛ وإذا غادرت الشاشة (أو بدّلت الـ agent)
ولديك تعديلات لم تُحفظ، فإنه يسألك أولًا. والـ runs التي تبدأها هنا تبلّغ الـ
observe daemon، ويفتح رابط Open trace في pill حالة الـ Run الـ run في
شاشة Trace.
Playground
يجرّب#/playground (Build > Playground) رسائل على model بدون تعديل
agent:

- Messages: بطاقات رسائل system وuser وassistant. يحصل كل placeholder
{name}في أي رسالة على حقل إدخال في Variables ضمن بطاقة الإعدادات على اليسار، بترتيب أول ظهور للأسماء. - Model: provider (من لديهم مفتاح تحت Settings > Provider keys، إضافةً إلى
ollamaوmock؛ وmockعندما لا يكون شيء مضبوطًا) واسم model، يُرسلان كـprovider/model. - Tools: اختر agent محفوظًا لكي تستعير الـ tools الخاصة به، ثم فعّل أو عطّل كل واحدة.
- يبث Run (أو Ctrl/Cmd+Enter في الرسائل) الرد أولًا بأول؛ ويلغيه Stop. تظهر الـ tool calls كبطاقات تنفتح على الـ arguments الخاصة بها. وعندما ينتهي الـ run، تعرض المخرجات الـ tokens الداخلة والخارجة والـ latency والتكلفة (عندما يكون سعر الـ model معروفًا)، وينقلك Open trace إلى الـ trace الخاص به.
- يفتح Save prompt (في header الصفحة) بطاقة فيها Save as new prompt version يدفع رسالة الـ system (والـ variables الخاصة بها) إلى سجل الـ prompts، تحت اسم الـ prompt المحمّل أو اسم تكتبه. ويكون معطّلًا ما دامت لا توجد رسالة system.
#/playground?trace=<traceId>&fromObs=<obsId>،
ويحمّل رسائل هذا الـ generation والـ model الخاص به. و#/playground?prompt=<name>[@<label or version>] (زر Open in Playground في شاشة Prompts) يحمّل prompt من
السجل (الأحدث افتراضيًا) كرسالة system ويسجّله على trace الـ run.
كلاهما يقرأ من الـ observe daemon: عندما يكون متوقفًا، يذكر الـ Playground
ذلك ويُبقي المحرر فارغًا، وتعمل الـ runs بشكل طبيعي. وتمر الـ runs عبر
الـ endpoint الخاص بتشغيل الـ playground وتبلّغ
كـ agent playground.
Traces


#/traces runs الـ daemon، الأحدث أولًا: الحالة، والاسم، والـ agent،
ومعاينة المدخلات والمخرجات، ورسالة الخطأ، والـ model، والبداية، والمدة، والـ
tokens والتكلفة (تُخفي النوافذ الضيقة الأعمدة الأقل أهمية). فلتر بمربع
البحث (الاسم أو المدخلات أو المخرجات)، والـ facets Agent وStatus
وModel وProject، وفترة زمنية (15m أو 1h أو 24h أو 7d أو 30d أو
Custom؛ الافتراضي آخر 24 ساعة). اضغط Duration أو Tokens أو
Cost لكي ترتب عليه. 50 صفًا في الصفحة. أيقونة التحديث في header الصفحة
(Refresh) تجلب القائمة من جديد الآن، وLive (toggle) يحدّثها كل 5
ثوانٍ حتى تعطّله أو يتوقف الـ daemon. ويظهر فلتر prompt (يضبطه رابط “Runs
using this version” في شاشة Prompts) كـ chip تستطيع إزالته.
Trace
#/traces/<trace id> هو run واحد. يحتوي الـ header على اسمه، وحالته، والـ agent
(رابط إلى traces الـ agent)، والـ model، والبداية، والمدة، والـ tokens،
والتكلفة والـ session (رابط إلى الـ thread الخاص به)، إضافةً إلى Copy link وAdd to
dataset وAdd to queue، وOpen in Playground عندما يحتوي الـ run على
model call. ويعيدك All traces في header الصفحة إلى القائمة.

?obs= في الـ URL. ويعرض الـ inspector،
بالترتيب:
- Error: رسالة الفشل، عندما تكون الخطوة قد فشلت.
- Input وOutput: تُعرض الرسائل كفقاعات chat والـ tool calls كـ chips؛ بدّل بين Rendered وRaw وJSON (للمحتوى الذي هو JSON)، وانسخ أيًّا من الاثنين.
- Feedback: درجات الخطوة، وإعجاب / عدم إعجاب مع تعليق اختياري،
يُحفظ كدرجة
feedback(1أو0، والمصدرhuman). وعلى خطوة الجذر يقيّم الـ trace كاملًا. - الـ tokens والتكلفة والـ model.
- Attributes: الـ attributes الخام للخطوة كشجرة JSON.
Threads

#/threads الـ sessions: الحالة، والـ session id، والـ agent، وآخر
مدخل، والـ turns، والبداية، والمدة، والـ tokens والتكلفة، مفلترة بالـ agent
والحالة والفترة الزمنية (الافتراضي 30 يومًا). تظهر الـ session بمجرد أن
تحمل runs الـ agent قيمة sessionId. ويعرض #/threads/<session id> المحادثة:
كل turn (run) من الأقدم إلى الأحدث، مع مدخلاته ومخرجاته (أو الخطأ) ورابط
Open trace.
Monitoring

#/monitoring هي شاشة “هل الـ fleet الخاص بي يعمل” وتحدّث نفسها كل 15 ثانية.
يعرض جدول الـ fleet كل agent أبلغ: الحالة، وآخر heartbeat، وruns اليوم،
ونسبة الأخطاء، والـ p95 latency على 24 ساعة، وعدد الأحداث التي أسقطها الـ
reporter، ورابطًا إلى الـ traces الخاصة به. وتحته، اختر window (1h، 24h، 7d، 30d)
وagent، واقرأ خمسة رسوم: Runs وLatency p95 وError rate (لكل
agent)، وCost وTokens. اضغط على bucket في رسم لكي تفتح Traces
مفلترة على وقت هذا الـ bucket (والـ agent).
Evaluations
يفتح Evaluations في الـ nav الـ#/evals/scores. ويتنقل sub-navigation أعلى كل
شاشة Evaluations (Scores وDatasets وEvaluators وAnnotation
queues) بينها.
Scores

eval، judge، human، online)
والفترة الزمنية (الافتراضي 30 يومًا). اضغط على eval لكي توسّعه: عدد الـ
runs ونسبة نجاح الـ runs، واتجاه نسبة النجاح، ونسبة نجاح كل check (الأسوأ
أولًا) وآخر حالات الفشل، وكل منها فيه رابط إلى الـ trace الخاص بها (والخطوة).
تُحتسب الدرجة نجاحًا عندما تكون قيمتها 1 بالضبط. وتنجح درجات eval وjudge (الـ
assertions الخاصة بالـ eval والـ checks llmJudge / t.judge()، التي تكتب
تعليقًا فقط عند الفشل) أيضًا عندما لا يكون لها تعليق فشل. أما درجات human
وonline فيُحكم عليها بالقيمة وحدها، فتُعتبر القيمة 0 (عدم إعجاب، أو rule أرجعت 0)
أو 0.9 أو القيمة الفارغة فشلًا. ويستخدم الجدول والتفاصيل الموسّعة القاعدة
نفسها. من أين تأتي درجات الـ eval: Evals.
Datasets

#/evals/datasets الـ datasets مع عدد الأمثلة في كل منها، وفيه
نموذج New dataset (اسم ووصف اختياري). افتح واحدًا لكي ترى أمثلته
(المدخل، والقيمة المتوقعة، والـ trace المصدر)؛ وافتح مثالًا لكي تراه كاملًا،
أو Delete لكي تحذفه (يسألك أولًا). تأتي الأمثلة من Add to dataset في
trace، أو يدويًا عبر الـ datasets API. ويعمل الـ
eval على dataset بـ defineEval({ dataset: 'name' }) (انظر
Datasets).
Evaluators

#/evals/evaluators rules الـ evaluators
الأونلاين: وهي rules تعطي درجات
للـ traces الجديدة بمجرد انتهائها. تحمل درجاتها اسم الـ rule وتظهر في Scores
بالمصدر online.
تعرض القائمة لكل rule اسمها، ونوعها (code أو judge)، والفلتر (أو “All
traces”)، والـ sample rate، وswitch Enabled (يفعّل الـ rule أو يعطّلها
فورًا)، وLast run وRuns (24h)، محسوبة من أحدث 1000 درجة أونلاين
(+ بعد العدد يعني أن القراءة كانت ممتلئة، فالعدد حد أدنى). فلتر بـ
Kind وState (?kind=، ?enabled=)، 50 rule في الصفحة.
يفتح New evaluator النموذج؛ وافتح rule (#/evals/evaluators/<rule id>) لكي تعدّلها في النموذج نفسه، وهناك يرسل Save changes الحقول
التي غيّرتها فقط، ويزيل Delete الـ rule بعد تأكيد (تبقى درجاتها
السابقة). يحتوي النموذج على اسم، وsample rate (0-1)، ومربع enabled، والفلتر (الـ
agent، والحالة ok أو error، والاسم يحتوي على)، والنوع:
- rule من نوع code هي دالة
(trace) => number | { value, comment }، معبّأة مسبقًا بمثال يعمل. يشغّلها الـ observe daemon في الـ isolate sandbox الخاص به، فتعمل الـ code rules سواء كان الـ Studio مفتوحًا أم لا (انظر الـ evaluators الأونلاين). - rule من نوع judge هي provider وmodel وrubric. لا يملك الـ daemon
مفاتيح providers، لذا فإن الـ Studio هو الذي يشغّل الـ judges، بمفتاح محفوظ في
Settings أو بمتغير البيئة الخاص بالـ provider في المكان الذي يعمل فيه الـ
Studio (المفتاح المحفوظ يغلب)؛ وتعرض قائمة الـ providers من لديهم واحد
من الاثنين، إضافةً إلى
ollamaوmock. وبدون أي مفتاح، يكون خيار الـ judge معطّلًا، مع رابط إلى Settings. ولا تعمل الـ judges إلا ما دامlousho studioيعمل؛ وحتى ذلك الحين تنتظر الـ jobs الخاصة بها في الـ daemon (انظر Judge rules). اضبطLOUSHO_STUDIO_JUDGE=0على سيرفر الـ Studio لكي تعطّل حلقة الـ judge الخاصة به.
?trace= مسبقًا) ويعرض القيمة والتعليق؛ ولا تُكتب أي درجة. يشغّل الـ
Studio الـ rule من نوع judge بنفسه ويمرّر الـ rule من نوع code إلى الـ daemon. ويعرض الـ
trace غير المعروف “Trace not found”.
Annotation queues

#/evals/queues الـ queues (pending، done، skipped) وفيه نموذج New
annotation queue: اسم وrubric، وصف لكل درجة (الاسم، ووصف اختياري، وmin وmax
اختياريان). أضف traces من Add to queue في trace (أو مجموعة دفعة واحدة
عبر الـ queue API). افتح queue لكي
تراجعه: trace العنصر الـ pending التالي في الـ trace viewer، وبجانبه حقل
رقم واحد (ضمن حدود الـ rubric) وتعليق اختياري لكل عنصر في الـ rubric.
يحفظ Submit (Enter) الدرجات المعبّأة كدرجات human على الـ trace وينتقل
إلى العنصر التالي؛ ويتخطاه Skip (S). ولا يُحتسب الحقل الفارغ درجة. وعندما
لا يوجد شيء pending، تذكر الشاشة أن الـ queue فارغ.
Prompts

#/prompts السجل، صفًا لكل prompt: أحدث إصدار، والـ labels، وعدد
الإصدارات، والـ runs التي استخدمته، ومتى حُدّث؛ ويفلتر مربع البحث القائمة
بالاسم. افتح واحدًا (#/prompts/<name>، أو @<version> /
@<label> لكي تحدد إصدارًا):
- الـ header: اسم الـ prompt مع labels الإصدار المحدد، وRuns using
this version (Traces مفلترة بـ
prompt=<name>@<version>) وOpen in Playground. - نص الإصدار المحدد، مع أرقام الأسطر، وMove
<label>here لكل label من labels الـ prompt يشير إلى مكان آخر: يشير الـ label إلى إصدار واحد بالضبط، فهذا ينقله (مثلlousho prompt label، انظر CLI). - Compare versions: اختر إصدارين لـ diff (
?diff=a,b)، يُعرض Unified أو Side by side. - تاريخ الإصدارات، timeline بجانب النص؛ اختر إصدارًا لكي تحدده (
j/kيتنقلان بين الإصدارات).
Context Hub
يعرض#/hub namespaces الـ context hub.
لا يقدّم الـ daemon عناصر الـ hub إلا نيابة عن agent، فاختر أنت من في
Viewing as (الافتراضي أول agent بالاسم)، واختياريًا scope (private
أو fleet). افتح namespace لكي ترى عناصره كبطاقات (المفتاح، والـ scope،
ومعاينة القيمة، ومن كتبه، وآخر تحديث والـ TTL)؛ وافتح بطاقة لكي ترى القيمة
كاملة (الـ JSON كشجرة) بجانب القائمة. ولعنصر الـ fleet زر Edit يعيد
نشره (وهذا يعيد بدء الـ TTL الخاص به).
Settings
#/settings عمود واحد من البطاقات: Appearance (الثيم Light أو Dark
أو System، وكثافة الجداول Compact أو Comfortable، ويُحفظ الاثنان في
هذا المتصفح؛ وإلى أن تختار كثافة، يبقى كل جدول على الافتراضي الخاص بشاشته)،
وProvider keys، وSettings profile، وDeploy target، وCollector
(هل يرد الـ observe daemon، وعنوانه، وlousho observe start عندما يكون
متوقفًا) وKeyboard shortcuts (قائمة الـ ? نفسها). ويعرض tab Settings في
drawer الـ builder بطاقات مفاتيح الـ providers والـ profile والـ
deploy فقط؛ انظر الإعدادات وsecrets وربط الـ deploy.
جولة أول agent
-
أنشئ agent. في tab Agents في شريط الـ agents، اضغط New agent، وسمّه،
واختر قالب بداية. أسرع طريق للتجربة بدون مفاتيح API هو Blank
graph — node
llmواحد يستخدم الـmockprovider المدمج. ينشئ Agent Forge الـ agent بهذا الاسم (.lousho/agents/<name>.yaml، معname: <name>في الـ spec) ويفتحه على الـ canvas. وتحتوي بطاقة الـ agent المفتوح على Rename وDelete. ينقل الـ Rename الـ spec إلى الاسم الجديد؛ وتبقى المحادثات والـ traces والـ checkpoints السابقة تحت الاسم القديم. -
انظر إلى الـ graph. الـ agent الفارغ هو node
llmواحد. اسحب nodes إضافية من tab Nodes في الشريط (Trigger، LLM step، Tool call، Approval gate، Response / output)، أو اضغط على عنصر في Nodes (أو اضغط Enter عليه) لكي تضيفه في وسط الـ canvas، وصِل بينها بالسحب بين الـ handles. تعرض كل بطاقة node اسمه، وchip الـprovider/modelوعدد الـ tools إذا كان node من نوع LLM، وحالة الـ node في الـ run الحالي (idleحتى يصل إليه run). اضغط على node لتعدّل إعداداته (prompt، provider/model، tools، breakpoints) في الـ Inspector على اليمين؛ وأقسامه Node وDebug وHooks قابلة للطي، ويبقى كل قسم على الحالة التي تركته عليها. والـ agent الذي لا يحتوي الـ canvas الخاص به على nodes يعرض القوالب على الـ canvas: اختيار واحد منها يعبّئ الـ canvas (بدون حفظ حتى يحدث autosave، مثل أي تعديل) ويحتفظ باسم الـ agent. -
شغّله. اضغط Run في الشريط العلوي. مع الـ
mockprovider لا يوجد ما يحتاج إلى إعداد — فهو يُرجع مخرجات جاهزة وثابتة، وهذا بالضبط المطلوب لكي تجرب بقية الواجهة بدون مفتاح API لـ LLM حقيقي. يتتبع الـ status pill في الشريط العلوي الـ run (running→done، أوstoppedبعد أن تضغط Stop، أوerror، أوawaiting approval)، وبمجرد أن يصبح trace id الخاص بالـ run معروفًا، يظهر بجانبه رابط Open trace يفتح الـ run على#/traces/<traceId>(في العرض الضيق يكون في قائمة More). تبلّغ runs الـ builder الـ observe daemon كـ agent<agent id>، بالطريقة نفسها التي يتبعها الـ Playground: عندما يكونLOUSHO_OBSERVEمضبوطًا، يُستخدم الـ reporter الخاص به (فلا يُبلَّغ عن شيء مرتين)، والـ daemon المتوقف يُسقط الأحداث فقط ولا يُفشل الـ run أبدًا، ولا يُرسل محتوى الرسائل إلا إلى daemon على loopback (ولا يُرسل أبدًا إلى ملفات الـ trace ولا إلى tab Trace الحي). يرسل الـ Run prompt ثابتًا، ويعرضه tab الـ Chat كفقاعة Run input بدلًا من عرضه كرسالة منك. وإذا توقف سيرفر الـ studio، يظهر banner يذكر أن الاتصال انقطع، ويعيد الـ studio الاتصال عندما يعود السيرفر. -
تابعه في الـ debug console. افتح tab Logs في الـ drawer
السفلي للحصول على سجل حي تستطيع فلترته حسب أحداث الـ run
(trigger/llm/tool/sandbox/checkpoint/approval)، أو Trace لخطوات الـ
run في الـ trace viewer نفسه الذي تستخدمه شاشة Traces (شجرة أو
waterfall (مخطط شلالي)، مع inspector للخطوة المحددة). فعّل Debug من الشريط العلوي —
أو ضع breakpoint على node في الـ Inspector — لكي توقف الـ run عند
حدود الـ LLM والـ tool وتتقدم فيه خطوة خطوة بأزرار Step و
Continue في شريط الـ debug. وسّع “Live message array” هناك لتفحص
قائمة الرسائل الجارية. ويعرض tab Output الـ
ExecutionResultكاملًا (messages، tool calls، usage، steps) كشجرة JSON قابلة للطي بمجرد أن ينتهي الـ run أو يتوقف. اسحب الحافة العلوية للـ drawer (أو ضع عليها الـ focus واستخدم الأسهم) لكي تغيّر حجمه؛ ويُحفظ الارتفاع. سجل الـ traces. يُحفظ كل run كملف trace، فيحتفظ tab Trace بـ runs الـ agent حتى بعد reload للصفحة أو إعادة تشغيل السيرفر. تعرض قائمة على اليسار الـ runs السابقة للـ agent، الأحدث أولًا (وقت البداية، والمدة، وmodel calls، والـ tokens الداخلة والخارجة، والتكلفة، والحالة)، وفوقها عنصر Live ما دام هناك run يعمل. اختر واحدًا لترى خطواته في الـ viewer نفسه: نوع كل خطوة (model call أو tool call أو span)، والـ model، والـ tokens، والمدة، والخطوات الفاشلة بلون الخطأ مع رسالة الفشل في الـ inspector، والخطوات التي لا تزال تعمل تتحدث مباشرة. ويظلّل تحديد خطوة الـ node الخاص بها على الـ canvas. وتتحدث القائمة عندما ينتهي run. والملفات هي نفسها التي يقرؤهاlousho traces، في.lousho/agents/<agent id>/traces/<day>/<trace id>.jsonlتحت المجلد الذي بدأتlousho studioمنه (انظر التتبّعات المحلية): يعرضnpx lousho traces --dir .lousho/agents/<agent id>/tracesالـ runs نفسها في الـ terminal، وحذف مجلد الـ agent يحذف الـ traces الخاصة به. يعرض الـ tab محتوى الـ spans: أسماء الـ models والـ tools، وأعداد الـ tokens، والتكلفة، والمدد، ورسائل الخطأ؛ وفي أقسام Input وOutput وAttributes في الـ inspector تظهر الـ attributes التي تحمل محتوى الـ prompt والـ tools. ولا يقرأ السيرفر الـ traces إلا من هذا المجلد (id فيه فاصل مسار = 400)، ولا يرسل مسار الملف إلى المتصفح أبدًا. أبقِ.lousho/خارج الـ version control. -
حاوره. tab Chat هو transport محادثة منفصل (
POST /agents/:id/message، ويصل الرد streaming عبر الـ WebSocket نفسه الذي يخدم كل شيء آخر) — أرسل إليه رسالة فيرد عليك في الـ thread، مستقلًا عن زر “Run” الخاص بالـ graph في الأعلى. ويحتفظ كل agent بتاريخ محادثاته (يبدأ+ New chatsession (جلسة) جديدة، وتبقى القديمة قابلة للتصفح). - وافق على tool call متوقف. أضف node Tool call، وافتحه في الـ Inspector، واختر tool — بعض الـ tools (أو policy الـ agent نفسه) قد تطلب approval (موافقة بشرية) قبل التشغيل. عندما يصل run أو chat إلى واحدة منها، تظهر بطاقة approval مدمجة — في الشريط العلوي إذا كان run من الـ graph، أو كفقاعة رسالة في الـ chat — تعرض اسم الـ tool والـ arguments الخاصة به. اضغط Approve لكي يكمل أو Reject لكي تلغي هذا الـ call، ويستأنف الـ run تلقائيًا في الحالتين.
Hooks
الـ hooks دوال صغيرة تعمل داخل sandbox، وتعمل مباشرة قبل tool call أوgenerate لـ LLM أو بعده — وهي الآلية نفسها التي يعرضها قلب الـ SDK باسم
HookRegistry/AgentHook (انظر نظرة عامة على الـ
API)، لكنها مكتوبة بشكل مرئي ومرتبطة بـ node محدد على الـ
canvas.
لإرفاق hook:
- اختر node
llmأوtoolعلى الـ canvas — تنطبق الـ hooks على هذين النوعين فقط، لأنهما النقطتان الوحيدتان اللتان يستدعي فيهماAgentExecutorالخارج فعليًا. - افتح قسم Hooks في الـ Inspector. اسحب Pre-hook أو
Post-hook من tab Nodes في الشريط وأفلته على الـ node — أو أفلته
مباشرة في قسم Hooks — أو اضغط على العنصر في اللوحة والـ node محدد،
لإرفاق hook جديد. يتيح لك ذلك الاختيار من قوالب بداية
(
redact-pii،rate-limit،audit-log،inject-context) تبدأ منها وتعدّلها. - اضغط على chip الـ hook لتحدده، وعدّل كوده في محرر CodeMirror. الكود
هو جسم دالة async، ويستدعيها السيرفر بـ
hook(ctx)داخل subprocess معزولة (server/hookSandbox.ts) — ولا يستدعيها أبدًا في المتصفح ولا في عملية الـ API server نفسها:- لـ hook خاص بـ tool call:
ctxهو{ toolName, args, result?, error? }. يستطيع الـ pre-hook تعديلctx.args، ويستطيع الـ post-hook فحصctx.resultوctx.errorأو تعديلهما. أرجِعctx. - لـ hook خاص بـ
generateلـ LLM:ctxهو{ messages, model }. عدّلctx.messagesأو أضف إليها، وأرجِعctx. - رمي exception يلغي الخطوة — فـ hook الـ rate-limit مثلًا يرمي exception لكي يمنع الـ tool call نهائيًا بدلًا من تركه يُنفَّذ.
- لـ hook خاص بـ tool call:
- بدّل الـ switch على chip الـ hook لتفعيله أو تعطيله بدون إزالته، أو اضغط x لإزالته كليًا. ولا تدخل في الـ run إلا الـ hooks المفعّلة.
redact-pii:
spec.policy.hooks في ملف الـ
YAML الخاص به، ويعمل السيرفر compile للـ hooks المفعّلة إلى
HookRegistry حقيقي للـ run (server/compileHooks.ts)، ويوجّهها عبر
الـ SandboxAdapter نفسه الذي تستخدمه الـ tool داخل sandbox.
Time travel
يحتفظ Agent Forge بكل الـ checkpoints لكل run، لا بالأخيرة فقط. ويحتفظ الـ file store الخاص به (server/checkpointStore.ts) بالسجل المحدود نفسه الذي
يحتفظ به LocalStorageCheckpointStore في الـ SDK — أحدث 50 حفظة لكل run،
تحت .lousho/agents/<id>/checkpoint-history/ (انظر سجل الـ
checkpoints). ومن هذا
السجل تستطيع أن تعمل fork (تفريع) لـ run عند أي خطوة، وتغيّر ما حدث فيها،
وتعيد تشغيله بجانب الأصل —
AgentExecutor.fork()
وcompareTrajectories() هما اللتان تؤديان العمل.
tab History
- شغّل الـ agent — زر Run في الشريط العلوي أو رسالة في الـ Chat.
- افتح tab History في الـ drawer السفلي. يسرد خطوات الـ run: رقم الخطوة، والحالة، وسبب إنهاء الـ model، والـ tool calls التي حدثت، وعدد الـ tokens وتكلفة استدعاء الـ model في الخطوة عندما تكون معروفة.
- اضغط Edit and replay from here على خطوة. اختر Append a user message واكتب رسالة، أو اختر أحد الـ tool calls في الخطوة وعدّل نتيجته — يكون الحقل معبّأً مسبقًا بالنتيجة المسجلة، وإذا كان النص JSON صالحًا يُرسل كـ JSON.
- اضغط Fork and replay. يعمل النظام fork للـ run عند تلك الخطوة مع
تعديلك ويبدأه كـ run جديد باسم
<id>.fork-<n>. - يُفتح الـ fork بجانب الأصل في عرض trajectory جنبًا إلى جنب: كل model turn من الـ runين — النص، والـ tool calls ونتائجها — وأول turn يختلفان فيه مظلّل بوسم diverged، وتحته عناصر الـ drift (ترتيب الـ tools، والـ arguments، وعدد الخطوات، وسبب الإنهاء). ويتحدث العرض عندما ينتهي الـ fork.
Routes
معرّف الـ run هو الـ checkpoint session id الخاص به: id الـ agent للـ runs الخاصة بالـ agent نفسه، و<id>.fork-<n> لـ fork من الـ run <id>.
لدى سيرفر التحكم بالـ runtime ثلاث routes لها (يستخدمها tab History)،
وroutان آخران للـ traces المحفوظة للـ agent (يستخدمهما tab Trace):
التسلسل لـ agent اسمه
weather شغّلته مرة واحدة:
الـ endpoint الخاص بتشغيل الـ playground
يشغّلPOST /playground/run prompt لمرة واحدة على model ويبث الرد كـ
server-sent events. ويتطلب رمز الوصول نفسه الذي يتطلبه بقية الـ API. الـ body:
messages(مطلوب): من 1 إلى 200{ role, content }، وroleأحدsystemأوuserأوassistant. تُرسل كما هي مكتوبة؛ ولا يضيف السيرفر أي system prompt من عنده.variables: قيم نصية. يُستبدل كل{name}في محتوى أي رسالة بـvariables.name؛ ويبقى الـ placeholder الذي ليس له variable كما هو.model(مطلوب):provider/model، أو provider وحده (mock). يأتي مفتاح الـ provider من Settings > Provider keys، ثم من البيئة، بالطريقة نفسها التي تحلّه بها runs الـ agents.tools: أسماء tools يحلّها الـ Studio للـ agents (current-date،day-name،http،web-fetch،demo-approval). والـ tool التي تحتاج approval تنهي الـ run بـfinishReason: "awaiting-approval"؛ إذ لا يوجد في الـ playground مسار approval.promptRef: الـ prompt من السجل الذي جاءت منه الرسائل (name،name@labelأوname@3). يُسجَّل على الـ trace فقط؛ ولا يجلب السيرفر الـ prompt.
400 { error }. وفي غير ذلك يكون الرد 200 مع
content-type: text/event-stream، وframe واحد data: <json> لكل event:
ينتهي كل stream بـ
done أو error واحد بالضبط، حتى الـ run الذي يتوقف
بدون نتيجة. ولـ usage شكل الـ usage نفسه في event run.done
(AgentEventUsage).
إغلاق الاتصال يلغي الـ run. يبلّغ كل run الـ observe daemon الذي يقرأ منه
الـ Studio (LOUSHO_OBSERVE_URL، الافتراضي http://127.0.0.1:7777، أو
LOUSHO_OBSERVE عندما يكون مضبوطًا) كـ agent playground، مع
lousho.prompt.ref على الـ root span الخاص بالـ run عندما يكون promptRef
موجودًا. ويُرسل LOUSHO_OBSERVE_TOKEN كـ bearer token، لـ daemon مربوط على
ما هو أبعد من loopback. والـ daemon المتوقف لا يبطئ الـ run ولا يُفشله.
الإعدادات وsecrets وربط الـ deploy
تتشارك شاشة Settings (#/settings، آخر شاشة في الـ nav) وtab Settings في
drawer الـ builder ثلاثة أجزاء: مفاتيح API للـ providers (OpenAI
وAnthropic) — يخزنها Agent Forge مشفّرة تحت .lousho/ ولا يعرضها مرة أخرى
أبدًا؛ يعرض كل مفتاح Set مع آخر حروفه مخفية جزئيًا، أو From
environment عندما يكون OPENAI_API_KEY / ANTHROPIC_API_KEY وحده مضبوطًا،
أو Not set — وprofiles إعدادات مسمّاة (provider، وdeploy
adapter، وtimeout للـ hook، وtoggle لـ OpenTelemetry، تُحفظ في
.lousho/settings.json الذي لا يحتوي على secrets)، وقسم Deploy يختار
adapter — node-server أو docker أو cloudflare-worker — ويشغّل
lousho build للـ agent المحدد. وتقرأ بقية الـ providers الـ env vars
الخاصة بها، بطريقة lousho dev وlousho build نفسها (انظر
الإعداد)، ولا يحتاج الـ mock provider إلى credentials.
المفاتيح المخزّنة مشفّرة بـ AES-256-GCM في .lousho/secrets.json. ويُولَّد مفتاح
التشفير أول مرة تحتاج إليه ويُحفظ بجانبه في .lousho/secrets.key
(كلاهما بصلاحية 0600 على POSIX). وهذا يُبعد المفاتيح عن أي شيء ينسخ النص
المشفّر وحده — backup، أو zip للمشروع، أو YAML لـ agent تشاركه — لكن أي
شخص يستطيع قراءة الملفين باسم مستخدمك يستطيع فك تشفيرهما. هذا ليس keychain
النظام. أبقِ .lousho/ خارج الـ version control وخارج الأرشيفات التي
تشاركها، وفضّل متغيرات البيئة على الأجهزة المشتركة.
الـ agent الذي ليس للـ provider الخاص به مفتاح (لا مفتاح مخزّن ولا متغير
بيئة) لا يعمل. يفشل Run وChat بـ
LOUSHO_PROVIDER_MISSING_API_KEY ورسالة تذكر الحل: أضف المفتاح في
Settings، أو اضبط متغير البيئة، أو غيّر provider الـ agent إلى mock. ولا
يبدّل الـ studio أبدًا إلى الـ mock provider من تلقاء نفسه. ويعرض الـ provider pill في
الشريط العلوي الـ provider/model الذي يعمل عليه الـ agent فعليًا،
وعلى الـ agent الذي يستخدم mock شارة MOCK.
وضع التطوير
إذا كنت تعمل داخل الـ monorepo الخاص بالـ SDK نفسها — تساهم في Agent Forge ذاته، لا تستخدمه فقط — فإنlousho studio يعود إلى وضع dev تلقائيًا ما دام
apps/agent-forge/dist-server لم يُبنَ بعد:
tsx)، ومعه Vite dev
server حقيقي مع hot-module reload لـ apps/agent-forge/src/**، كعمليتين
تعملان جنبًا إلى جنب. افتح الرابط المطبوع http://localhost:5173/?token=...؛
Vite مثبّت على port 5173 والـ API server يقبل هذا الـ origin. ولكي تبني حزمة الـ production التي يستخدمها الآخرون —
وتتحقق مما يُشحن فعلًا:
npm run build:studio تلقائيًا أيضًا ضمن سكربت prepublishOnly في
جذر الـ repo، فلا يستطيع npm publish أبدًا شحن studio قديم أو غير مبني.
E2E smoke test
apps/agent-forge/e2e/studio.spec.ts هو اختبار Playwright headless يقود
lousho studio الحقيقي المبني — سيرفر الـ production نفسه
dist-server/index.cjs، لا Vite dev server — عبر متصفح. ينشئ agent من
قالب “Support bot”، ويوجّه الـ tool node فيه إلى tool اسمها
demo-approval محلية على السيرفر (needsApproval: true دائمًا — انظر
تعليق التوثيق في server/buildAgent.ts لتعرف سبب وجودها، لأن أي tool
مدمجة في الـ SDK قابلة للتحديد من الـ spec لا تطلب approval)، ويرسل إليه
رسالة chat تفعّل الـ tool-call heuristic في الـ mock provider، وينتظر
توقف الـ run عند الـ approval gate، ويوافق عليه من بطاقة الـ approval
المدمجة في tab Chat، ثم يتحقق من أن الـ run يكتمل. شغّله بالأمر:
build:studio)، ثم يشغّل Playwright عليه:
studio.spec.ts المذكور أعلاه إضافةً إلى بقية الـ specs في apps/agent-forge/e2e/،
ومنها revamp.spec.ts (فحوصات القبول الخاصة بالـ revamp: يظهر خطأ الـ run الفاشل
خلال تفاعلين، ويصمد كل route بعد الـ reload مع فلاتره) وa11y.spec.ts
(فحص axe لكل route في routeTable.ts). وتعمل شاشات الـ daemon على
daemon وهمي (e2e/observeStub.ts وe2e/fixtures/seedObserve.ts)، فلا
تحتاج إلى lousho observe.
لقطات شاشة التوثيق
تأتي لقطات الشاشة في هذه الصفحة منapps/agent-forge/e2e/docShots.spec.ts،
الذي يتخطى نفسه ما لم يكن LOUSHO_DOC_SHOTS مضبوطًا. بعد npm run build:studio، أعد توليدها من جذر الـ repo بالأمر:
docs/images/studio-<screen>.png (1280x800، الثيم الفاتح) من الـ daemon
الوهمي نفسه. والصور ليست جزءًا من حزمة npm. وتأتي الأمثلة الداكنة
(studio-{agents,traces,trace,monitoring}-dark.png) من الأمر نفسه مع
الـ scheme الداكن:
docs/images يتخطى الـ spec لقطات المراجعة x- الخاصة به، ولا يكتب التشغيل الداكن
إلا هذه الأربع.
يوجد متغيران اختياريان يساعدان على مراجعة إعادة تصميم قبلها وبعدها:
يكتب LOUSHO_DOC_SHOTS_OUT=<dir> الـ PNGs في مجلد آخر (مسار مطلق، أو
نسبي إلى المكان الذي تشغّل منه الأمر)، ويصوّر LOUSHO_DOC_SHOTS_SCHEME=dark
الثيم الداكن (light هو الافتراضي؛ وأي قيمة أخرى تُفشل التشغيل). ومع مجلد
مخرجات، تُكتب كل لقطة باسمها، ومعها لقطات المراجعة x-.