الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.

ملفات تعريف الـ 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 الخام.
أسماء الـ guardrails (انظر Input and output guardrails): كل 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 الخاصة بـ ai SDK (maxRetries: 0)، فيحصل الـ retry في مكان واحد، والافتراضي { maxRetries: 2 } يجري نفس عدد الـ calls كما في السابق.
  • نسخة provider مدمجة (OpenAIProvider أو AnthropicProvider أو OpenRouterProvider أو OllamaProvider) أو provider من fromAiSdk() تُغلَّف أيضًا بـ withRetry() حتى بدون retry: وحينها بـ maxRetries الخاص بالـ provider نفسه (الافتراضي 2)، فتطلق محاولاتها أحداث provider.retry مثل سلسلة الـ model. وتخرج استدعاءاتها مع إطفاء الـ retries الخاصة بـ ai SDK، فـ { maxRetries: 2 } يرسل 3 طلبات على الأكثر، وretry: false يرسل كل call مرة واحدة. أما أي نسخة provider أخرى (الـ LLMProvider الخاص بك) فلا تُغلَّف إلا إذا ضبطت retry. وfallbackModels تعمل معها كلها.
  • قيم fallbackModels سلاسل بالصيغة provider/model، تُحلّ مثل model عند إنشاء الـ agent. يشغّل الـ agent withFallback([withRetry(primary), withRetry(fallback1), ...]): كل call يبدأ بالـ model الأساسي.
  • تبلّغ stream() وsession.stream() عن كل إعادة محاولة كحدث provider.retry وعن كل تبديل كـ provider.fallback؛ وفيه from وto أسماء الـ providers (مثل openai) وfromModel / toModel معرّفات الـ models (انظر Streaming). أما send() فترجع النتيجة النهائية كما في السابق.
لبناء نفس الشيء يدويًا، أو لـ providers تنشئهم بنفسك، تغلّف 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 الخاصة بـ ai SDK، أيًّا كانت قيمة maxRetries في إعداداتهم. وتلك الـ maxRetries (الافتراضي 2) هي عدد محاولات ai SDK للـ 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) بدلًا من ذلك.
حدود الـ run والـ session. يسري 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.