ملفات تعريف الـ agent (AgentSpec)
تصف هذه الصفحة الإصدار 1 من ملف المواصفات. ملفات المواصفات الجديدة تستخدم Agent spec v2؛ وupgradeSpec() يحوّل ملف مواصفات v1.
الـ agent التصريحي (declarative) ملف YAML (.yaml/.yml) أو JSON (.json)،
تتحقق منه loadSpec() بمكتبة zod (src/spec/schema.ts). هي الصيغة التي
يخدمها lousho dev وينشرها lousho build.
المقتطفات في هذه الصفحة تترك لك بعض الأسماء:providerهو أيLLMProvider(دون اتصال:createMockProvider()).
الحقل الناقص أو غير الصالح يفشل بخطأ يسمّي الحقل نفسه، مثل
'prompt': Required.
الـ tools التي يمكن للـ spec الإشارة إليها
github وjira تحتاج بيانات اعتماد لا يوجد لها حقل في الـ spec؛ الإشارة
إليها ترمي خطأ يطلب منك تبني الـ agent بـ createAgent() وتمرّر tool
مضبوط بدلًا منها.
السياسة (policy)
تحوّل specToAgent() الحقل policy إلى خيارات لـ createAgent()، فالـ spec
يفرض ما يصرّح به. الحقول المعروفة تتحقق منها loadSpec()؛ والمفاتيح الأخرى
تبقى لمولّدات الـ harness الأخرى (Claude Code وCodex وPi)، وهي تقرأ الـ
policy الخام.
كل guardrail يقبل أيضًا
on: input أو output أو tools (وسائط الـ
tool call)، أو قائمة منها. الافتراضي [input, output]. الاسم أو الخيار غير
المعروف يفشل الـ validation، ويذكر الـ guardrails المتاحة مع اقتراح “did you
mean”:
'policy.guardrails.0': unknown guardrail 'deny-topic' (did you mean 'deny-topics'?).
يوقف requiresApproval الـ run (finishReason: 'awaiting-approval') حتى
تستدعي agent.approvals.resolve()؛ وقبل هذا التغيير، الـ spec الذي يضبطه
كان يشغّل أدواته دون أن يسأل. ويطبع lousho doctor agent.yaml سطرًا واحدًا
لكل قسم من الـ policy.
سيرفرات MCP (mcpServers)
يصرّح mcpServers بسيرفرات MCP التي يستخدمها الـ agent: خريطة من اسم
السيرفر (الاسم يعمل namespace لأدواته) إلى سيرفر stdio (command، ومعها
اختياريًا args وenv) أو سيرفر HTTP (url، ومعها اختياريًا headers).
كل مدخل يضبط واحدًا فقط من command / url؛ وargs/env لـ stdio فقط
وheaders لـ HTTP فقط. تتحقق loadSpec() من الحقل، والمدخل غير الصالح
يفشل برسالة تذكر اسمه، مثل
'mcpServers.files': missing 'command' (stdio server) or 'url' (HTTP server).
والحقل الاختياري approval (always، وهو الافتراضي، أو annotations أو never) يحدد أي أدوات السيرفر تطلب موافقة؛ انظر الموافقة على أدوات MCP.
والاختياري deferLoading: true يحجب أدوات السيرفر عن الـ model حتى يجدها بـ tool_search؛ انظر Tool search.
والاختياري optional: true يستبعد السيرفر الذي يتعذّر الاتصال به (مع تحذير) بدل أن يُفشل كل send؛ انظر استخدام سيرفرات MCP داخل agent.
ومدخل HTTP يستطيع ضبط oauth (redirectUri، واختياريًا clientId وclientSecret وscopes وclientName) ليسجّل الدخول للسيرفر بـ OAuth بدل header Authorization ثابت؛ انظر سيرفرات MCP مع OAuth.
ويتأكد lousho doctor أن كل command لسيرفر stdio يمكن الوصول إليه.
specToAgent() السيرفرات إلى createAgent({ mcpServers })، الموصوفة في
MCP، فأي agent من lousho dev أو lousho mcp يحصل على أدواتها.
الـ MCP clients وconnectMcp() وموافقة الـ tools وتقديم agent عبر MCP لها صفحة مستقلة: MCP (Model Context Protocol).
بيانات اعتماد الـ providers
الـ providers الحقيقيون يُحلّون عبرresolveProvider('<provider>/<model>')
(المستخدمة أيضًا لملفات الـ spec)، وهي تقرأ بيانات الاعتماد من البيئة:
الـ
mock provider لا يحتاج بيانات اعتماد ويرجع ردودًا جاهزة؛ وهو ما
تستخدمه الأمثلة والـ Quick Start افتراضيًا.
الـ retry والـ fallback عند الـ provider
تعيدcreateAgent() محاولة استدعاءات الـ model الفاشلة من تلقاء نفسها،
وتقدر ترجع إلى models أخرى كـ fallback. بادئة vendor/ في اسم الـ model
تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل
openrouter/openai/gpt-4o-mini).
retryيأخذ خياراتwithRetry()المذكورة أدناه. يسري على سلسلةmodel(أو الـ model المختار من البيئة) وعلى كل مدخل فيfallbackModels. تبنيcreateAgentهؤلاء الـ providers مع إطفاء الـ retries الخاصة بـaiSDK (maxRetries: 0)، فيحصل الـ retry في مكان واحد، والافتراضي{ maxRetries: 2 }يجري نفس عدد الـ calls كما في السابق.- نسخة provider مدمجة (
OpenAIProviderأوAnthropicProviderأوOpenRouterProviderأوOllamaProvider) أو provider منfromAiSdk()تُغلَّف أيضًا بـwithRetry()حتى بدونretry: وحينها بـmaxRetriesالخاص بالـ provider نفسه (الافتراضي 2)، فتطلق محاولاتها أحداثprovider.retryمثل سلسلة الـ model. وتخرج استدعاءاتها مع إطفاء الـ retries الخاصة بـaiSDK، فـ{ maxRetries: 2 }يرسل 3 طلبات على الأكثر، وretry: falseيرسل كل call مرة واحدة. أما أي نسخةproviderأخرى (الـLLMProviderالخاص بك) فلا تُغلَّف إلا إذا ضبطتretry. وfallbackModelsتعمل معها كلها. - قيم
fallbackModelsسلاسل بالصيغةprovider/model، تُحلّ مثلmodelعند إنشاء الـ agent. يشغّل الـ agentwithFallback([withRetry(primary), withRetry(fallback1), ...]): كل call يبدأ بالـ model الأساسي. - تبلّغ
stream()وsession.stream()عن كل إعادة محاولة كحدثprovider.retryوعن كل تبديل كـprovider.fallback؛ وفيهfromوtoأسماء الـ providers (مثلopenai) وfromModel/toModelمعرّفات الـ models (انظر Streaming). أماsend()فترجع النتيجة النهائية كما في السابق.
withRetry(provider, options) وwithFallback(providers, options) أي
LLMProvider وترجعان provider آخر، فتتركّب معًا وتُمرَّر في أي مكان يُقبل
فيه provider:
- تعيد
withRetryمحاولةgenerate()وstream()(الافتراضيmaxRetries: 2) عند rate limits وانتهاء المهلة وأخطاء الشبكة (ومنها انقطاع الـ socket) والردود المشوّهة أو المبتورة وردود 5xx، بنفس التصنيف الذي تستخدمهcompactProviderError(). لا تُعاد المحاولة عند فشل المصادقة ولا الطلبات غير الصالحة ولا أخطاء طول السياق؛ ولا عند الإلغاء. وتلميحretryAfterMsمن الـ provider (retry-after-msأوRetry-After، مع 429 أو 503) يحل محل تأخير الـ backoff، إلا إذا كان أطول منbackoff.maxMs(الافتراضي 30 ثانية): عندها يفشل الـ call فورًا بـCompactedLLMProviderErrorيحمل التلميح فيcompacted.retryAfterMs، فيقرر الكود الخاص بك هل ينتظر. مرّرretryOn(error, attempt)لتغيّر القاعدة، وtimeoutMsلمهلة لكل محاولة، وsignalلإيقاف الـ retry. معstream()لا يحدّtimeoutMsإلا انتظار أول chunk: الـ stream الذي بدأ لا يقطعه أبدًا. وidleTimeoutMs(للـ stream فقط) يُفشل الـ stream الذي يسكت بين chunk وآخر أطول من ذلك، بـTimeoutError(ولا يُعاد إلا إذا لم يخرج بعد أي نص أو tool call). - استدعاء
stream()يُعاد إذا رُفض، وإذا فشل الـ stream قبل أي مخرجات: chunks الـ reasoning والـ text deltas الفارغة لا تُحتسب، فالـ runtime المحلي الذي يرسلreasoning-endفارغًا ثم 500 (LM Studio) يُعاد. أما الفشل بعد نص أو tool call أو بعد الانتهاء فلا يُعاد. والـ agent يبث استدعاءات الـ model كلما كان له event listener، فهذا ما يجعلagent.stream()بنفس متانةsend(). - الـ reasoning الذي بُثّ قبل فشل كهذا يكون قد بُلِّغ عنه سلفًا. في run الـ
agent ينتهي reasoning المحاولة الفاشلة بـ
reasoning.doneالخاص بها، ثم يأتي حدثprovider.retry، ثم يبدأ reasoning المحاولة المعادة من جديد بـreasoning.start. وreasoningالخاص بالخطوة (وبالـ run) هو reasoning المحاولة الناجحة وحدها. - تجرّب
withFallbackالـ providers واحدًا تلو الآخر، وترمي آخر خطأ إذا فشلوا جميعًا. افتراضيًا تنتقل للـ fallback عند أي خطأ ما عدا الإلغاء (ويغيّرfallbackOnهذا). كل fallback يعمل بـdefaultModelالخاص فيه. كل call يحتفظ بحالة fallback خاصة به، فالـ calls المتزامنة لا ترى تبديلات بعضها. وnameوdefaultModelهما للـ provider الأول؛ ونتيجة الـ call (والـ stream) تسمّي الـ provider والـ model اللذين خدماه فيservedBy، ويسجّل الـ run استهلاك ذلك الـ call وتكلفته تحت ذلك الـ model فيusage.byModel. - تطبّق
resilientProvider(provider, { maxRetries, timeout })حقلَيLLMProviderConfigاللذين يحملان الاسمين نفسيهما. withRetryهي طبقة الـ retry الوحيدة: الـ providers المدمجون يرسلون استدعاءاتها مع إطفاء الـ retries الخاصة بـaiSDK، أيًّا كانت قيمةmaxRetriesفي إعداداتهم. وتلك الـmaxRetries(الافتراضي 2) هي عدد محاولاتaiSDK للـ provider المستخدم دون تغليف (يُستدعى مباشرة)، وهي عددwithRetry()الذي تستخدمهcreateAgent()لذلك الـ provider حين لا يكونretryمضبوطًا.- الـ call الذي يصطدم بـ rate limit (429) يفشل، بعد استنفاد المحاولات، بـ
LOUSHO_PROVIDER_RATE_LIMITED؛ والـ calls الفاشلة الأخرى بـLOUSHO_PROVIDER_REQUEST_FAILED(انظر الأخطاء). - كل إعادة محاولة تُسجَّل على span الـ
chatالخاص بالـ call كـlousho.retry.countوlousho.retry.errors(انظر Observability).
حدود المعدّل (rate limits)
تضعwithRateLimit(provider, limits) استدعاءات generate() وstream()
الخاصة بالـ provider في طابور كي تبقى تحت حدود من جهة العميل، فلا يستطيع
تفرّع الـ sub-agents ولا موجات الـ flows ولا مجموعات الـ evals على إطلاق
استدعاءات model بلا حد. كل حد اختياري:
- تُقبَل الـ calls بترتيب الوصول (الأول يدخل أولًا). والـ call الذي ينتظر
دوره يُرفَض بسبب الـ
signalالخاص به فور إلغائه، ولا يبدأ أبدًا. - يحجز
tokensPerMinuteلكل call قيمةestimateTokens()لرسائله وتعريفات الـ tools مضافًا إليهاmaxTokensالخاص به، ثم يعيد حجزه بالاستهلاك الذي يبلّغ عنه الـ provider. والـ call الواحد الأكبر من الحد يعمل مع ذلك، وحده في نافذته. - يحتفظ
stream()بخانةmaxConcurrentالخاصة به حتى ينتهي الـ stream. - الحدود غير الصالحة (ليست عددًا موجبًا، أو
maxConcurrentليس عددًا صحيحًا) ترميLOUSHO_CONFIG_INVALID. - غلّف خارج
withRetry()لتحسب الـ call ومحاولاته المعادة كواحد، أو داخلها لتحسب كل محاولة. - مرّر
createRateLimiter(limits)بدل الحدود لتتشارك عدة providers ميزانية واحدة.
createAgent({ rateLimit }) الحدود نفسها (أو limiter). ميزانية واحدة
تغطي كل استدعاءات الـ model في runs الـ agent، بما فيها الـ sub-agents
وأهداف الـ handoff التي يبدأها الـ run (الـ sub-agent يرث ميزانية run الـ
lead، فيدخل الـ provider الخاص به الطابور أيضًا). أعطِ عدة agents نفس
createRateLimiter() ليتشاركوها.
خيارات createAgent()
إذا لم تمرّر
model ولا provider، تحل createAgent() من البيئة:
LOUSHO_MODEL (سلسلة 'provider/model') إن كانت مضبوطة، وإلا أول provider
متغيّره مضبوط، ويُفحص بهذا الترتيب: OPENAI_API_KEY
(openai/gpt-4o-mini)، ثم ANTHROPIC_API_KEY
(anthropic/claude-sonnet-4-5)، ثم OPENROUTER_API_KEY
(openrouter/openai/gpt-4o-mini)، ثم OLLAMA_BASE_URL (ollama/llama3).
وإذا لم يكن أي منها مضبوطًا ترمي خطأً يسرد بالضبط أي خيارات أو متغيرات
تحل المشكلة.
أخطاء سوء الإعداد تقول لك كيف تُصلَح: المفتاح الناقص يسمّي المتغير
(createAgent: OPENAI_API_KEY is not set. ...)، والبادئة غير المعروفة تسرد
البادئات المدعومة وتقترح أقربها، والـ peer dependency الاختيارية الناقصة
تطبع أمر npm install كاملًا.
الخيار الذي لا تعرفه createAgent() يُعتبر خطأً (LOUSHO_CONFIG_INVALID)،
ولا يُتجاهَل بصمت، لذلك يفشل الخطأ الإملائي من JavaScript أو YAML أيضًا.
تقترح الرسالة أقرب خيار، أو اسم Lousho لخيار تستخدمه SDKs أخرى:
'maxOutputTokens' is not a known option (did you mean 'modelSettings.maxTokens'?)،
وsystem تشير إلى instructions. المفتاح المضبوط على undefined يُتجاهَل،
والـ manifest الخاص بنتيجة claudeProject() المفرودة (spread) مقبول.
إعدادات الـ model
يضبطmodelSettings خيارات الـ sampling لكل call يجريه الـ agent للـ model.
واستدعاء send() أو stream() يستطيع تمرير إعداداته الخاصة، وهي تتقدّم على إعدادات
الـ agent مفتاحًا بمفتاح:
maxTokens وtemperature وtopP وfrequencyPenalty
وpresencePenalty وstop وseed وtoolChoice ('auto' أو 'required' أو 'none' أو { type: 'function', function: { name } }؛ ولا يُرسَل في call بلا tools). المفتاح الذي تتركه لا يُرسَل أصلًا،
فتسري القيمة الافتراضية للـ provider نفسه، وكذلك القيمة التي يضيفها provider
مغلِّف إلى الطلب. الـ sub-agents وأهداف الـ handoff تستخدم modelSettings
الخاصة بها، لا الخاصة بالـ lead. ومجلد الوكيل يستطيع ضبط الكائن نفسه كـ
modelSettings في ملف agent.json الخاص به.
تُفحص القيم قبل أي call للـ model، عند createAgent() وعند كل
send() / stream(): temperature من 0 إلى 2، وtopP من 0 إلى 1،
وfrequencyPenalty وpresencePenalty من -2 إلى 2، وmaxTokens عدد صحيح
لا يقل عن 1، وseed عدد صحيح، وstop مصفوفة نصوص. القيمة خارج المدى، أو
المفتاح غير المعروف (مثل maxOutputTokens الخاص بـ AI SDK)، ترمي
ConfigurationError بالكود LOUSHO_CONFIG_INVALID ويسمّي الحقل field فيه
المفتاح، مثل modelSettings.temperature. والـ provider ذو المدى الأضيق
(temperature عند Anthropic من 0 إلى 1) يظل يرفض القيمة الخارجة عنه.
خيارات كل استدعاء
إلى جانبmodelSettings، يستطيع استدعاء send() أو stream() أن يضبط
maxSteps الخاص به (بدل الخاص بالـ agent؛ عدد صحيح لا يقل عن 1، ويُفحص مثل
الخاص بـ createAgent) وinstructions، وهي تُلحَق بتعليمات الـ agent لذلك
الـ run:
instructions الملحقة تذهب مع كل call للـ model في الـ run (وكذلك
calls هدف الـ handoff) لكنها لا تُكتب في الـ transcript، فالـ call اللاحق
بنفس sessionId يعمل بدونها ما لم يمرّرها مجددًا. والـ run الذي يُستكمل
عبر agent.approvals.resolve() أو agent.resume() يستخدم maxSteps
والتعليمات الخاصة بالـ agent.
لتتشارك الخيارات بين عدة agents، اجعل نوعها CreateAgentBase وانشرها
(spread) داخل createAgent(). لا تستخدم Partial<CreateAgentConfig>: هذا
النوع يُبقي model / provider وinstructions / prompt متنافيَين، فيرفض
TypeScript نشره بجانب literal يضبط أحدهما.
الميزانيات
يضعlimits سقفًا لما يجوز للـ run أن ينفقه. اضبطه في createAgent() (لكل
run للـ agent) أو في AgentExecutor.execute() / stream():
تُفحص الحدود قبل كل call للـ model (أي بعد كل دفعة tools) وبعد call الـ
model التي تطلب tools؛ و
maxDurationMs يلغي أيضًا call model أو tool
جارية عبر signal الـ run. الحد يُستوفى فور بلوغ الـ run له. والـ run الذي
ينتهي بنفسه داخل الخطوة التي بلغت الحد يحتفظ بسبب انتهائه هو، مثل maxSteps.
الـ sub-agents تتشارك ميزانية الـ lead الخاص بها. استهلاك الـ sub-agents
يُحتسب من حدود الـ lead، والـ sub-agent يلتزم بها أثناء عمله: قبل كل call
له للـ model (وبعد call للـ model يطلب tools) يفحص حدود الـ tokens والتكلفة
والمدة الخاصة بالـ lead مقابل ما أنفقه الـ lead، والـ sub-agents الأخرى
التابعة له التي ما زالت تعمل، والـ sub-agent نفسه - فوق limits الخاصة به.
وبمجرد بلوغها يتوقف الـ sub-agent بـ 'budget-exceeded' (دائمًا 'stop'؛
وonExceeded الخاص بالـ lead يقرر كيف ينتهي الـ lead)، ويبلّغ call الـ task
بـ Sub-agent '<name>' stopped at the <limit> limit، ويتوقف الـ lead قبل
call الـ model التالي. الـ sub-agents المتوازية قد تتجاوز مع ذلك بقدر
استدعاءات الـ model التي كانت جارية عند بلوغ الحد (واحد على الأكثر لكل
منها)، لا بقدر run كامل لكل منها. والـ sub-agent المتداخل يلتزم بحدود كل
lead فوقه. أما الـ sub-agent الذي يُستأنف بعد موافقة فيلتزم بحدوده هو فقط.
حد الإنفاق (tokens، تكلفة، مدة) إيقاف صارم: الـ run الذي فيه output ويبلغ
أحدها لا يجري call إجابة إجبارية (ذلك الـ call سينفق فوق الحد)، فتبقى
result.object غير مضبوطة. وما أرجعته tool calls الـ run قبل استيفاء الحد -
ومعه إجابات الـ sub-agents التي انتهت - يبقى في result.messages كنتائج
tools. نفاد الخطوات وحده (maxSteps أو limits.maxSteps) يحصل على call
الإجابة الإجبارية.
عند استيفاء حد، يتوقف الـ run بـ finishReason: 'budget-exceeded' ومعه
result.budget ({ limit, value, max, scope }). الـ tool calls التي طلبها
الـ model في تلك الخطوة تأخذ نتيجة “cancelled”، فيبقى الـ transcript
صالحًا، ومع checkpoint store يُحفَظ في checkpoint كمنتهٍ، مثل
'max-steps'. وتطلق stream() حدث budget.exceeded قبل run.done. ومع
onExceeded: 'throw' يُرفَض الـ run بـ BudgetExceededError
(LOUSHO_BUDGET_EXCEEDED، مع نفس budget) بدلًا من ذلك.
createAgent({ limits }) على كل run
وحده: كل send()، وكل turn في session، يبدأ من صفر. ويضيف
agent.session({ id, limits }) حدودًا تشمل كل turns الـ session: الـ turn
يتوقف فور أن يبلغ مجموع ما أنفقته الـ session في turnsها كلها حدًّا (وعندها
تصبح budget.scope مساوية لـ 'session')، والـ turns اللاحقة تتوقف قبل استدعاء
الـ model. ما أنفقته الـ turns (tokens وتكلفة وخطوات وزمن run) يُحفَظ مع
الـ transcript، في metadata.sessionUsage على آخر رسالة فيه، فالـ session
التي تُستكمل من الـ store تحتفظ بميزانيتها. الاثنان يسريان معًا؛ وأول حد
يُبلَغ يوقف الـ turn. والـ turn الملغى لا يُحتسب.
تعليمات المشروع
كثير من الـ repos تحتفظ بإرشادات للـ coding agents في ملفAGENTS.md (أو
CLAUDE.md). تستطيع createAgent إلحاقه بتعليمات الـ agent:
## Project instructions (from AGENTS.md). ويُقرأ مرة واحدة، عند إنشاء الـ
agent. يصعد البحث من cwd (الافتراضي process.cwd()) ويأخذ أقرب مجلد فيه
أحد files (الافتراضي ['AGENTS.md', 'CLAUDE.md']، وأول تطابق يفوز)،
ويتوقف عند أقرب مجلد يحوي .git أو عند جذر نظام الملفات. المحتوى فوق 32,000
حرف يُقتطع مع علامة تدل على الاقتطاع. وإذا لم يجد ملفًا لا يُضاف شيء.
هذا opt-in عن قصد: قراءة الملفات من القرص افتراضيًا ستفاجئ من يضمّن الـ
SDK في سيرفر، حيث مجلد العمل ليس المشروع الذي يخص الـ agent. ولتجد الملف
بنفسك (مثلًا لعرضه)، استخدم
loadProjectInstructions({ cwd, files, stopAt, maxChars })، وهي ترجع
{ path, content } أو undefined.
خيارات AgentExecutor.execute()
خيارات AgentExecutor.execute()، نقطة الدخول الأدنى مستوى، مدرجة في صفحة executor API.
CLI
الأوامرlousho dev وlousho build وlousho mcp وباقي الأوامر، مع
flagsها، موصوفة في CLI؛ وlousho mcp مغطّى أيضًا في MCP.