الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الأمثلة في هذه الصفحة تترك بعض الأسماء لك: mcpClient هو Client لـ MCP متصل، وprovider هو أي LLMProvider (بدون شبكة: createMockProvider()).
كيف تترابط القطع:

بناء الـ agents وتشغيلها

Dynamic config

model وinstructions وtools في createAgent() كل خيار منها يقبل القيمة الثابتة أو دالة على الـ run: (ctx) => value | Promise<value> (النوع PerRun<T>). الـ ctx هو { sessionId?, input, metadata?, principal? } (النوع RunConfigContext): فيه الـ sessionId الممرّر لـ send() / stream() أو معرّف agent.session()، وإدخال المستخدم في الـ run، وخيار الاستدعاء metadata في send() وstream() وsession.send() وsession.stream()، والمتصل الذي قبلته مصادقة الـ run (principal، يغيب إذا لم يمرّر الاستدعاء متصلًا). تُنفَّذ الدوال مرة واحدة عندما يبدأ الـ run، قبل أول model call، ومرة أخرى في كل turn في الـ session. وكل شيء آخر ينطبق على ما تعيده: fallbackModels وretry و projectInstructions والـ memory والـ skills والـ sub-agents وtools الـ MCP والصلاحيات والـ approvals والـ guardrails. وإذا استخدمت agent ديناميكيًا كـ sub-agent، يكون الـ input هو task prompt، ويأخذ sessionId وmetadata و principal من run الـ agent الرئيسي.
إذا رمت الدالة خطأً، يفشل الـ run بـ LOUSHO_CONFIG_RESOLVER_FAILED (error.field يسمّي الخيار، وerror.cause هو الخطأ المرمي): send() يرفض، وstream() ينتهي بحدث error، وتحتفظ الـ session بالـ transcript كما كان. الـ run المتوقف على approval أو سؤال يحتفظ بالـ ctx وبالـ model الذي حسمه في snapshot التوقف: استئنافه، حتى من process أخرى، يستخدم ذلك الـ model (لا يتبدّل أبدًا في منتصف الـ turn) ويستدعي دالة tools مرة أخرى بالـ ctx نفسه. أما الـ run المستأنف من checkpoint بعد crash (agent.resume(id)) فيُحسب من جديد مع input: [] ودون metadata. وإذا كانت كل القيم ثابتة، لا يتغير شيء: يُبنى الـ agent مرة واحدة عندما تنشئه.

UI bindings

lousho/react يصدّر useLoushoAgent(source, options?)، وهو React hook يشغّل agent داخل الـ process نفسه ({ agent, sessionId? }) أو عبر HTTP ({ url })، ويعيد messages وstatus وpendingApproval و send() وstop() وapprove() وreject(). أجزاؤه المحايدة عن الـ framework — reduceAgentEvents() وparseEventStream() — مُصدّرة أيضًا. راجع React. lousho/vue يصدّر useLoushoAgent() نفسه كـ composable لـ Vue 3، والحالة فيه refs. راجع Vue. و lousho/svelte يصدّر loushoAgent()، الحالة والأفعال نفسها كـ Svelte store ($agent). راجع Svelte.

Sub-agents

مرّر subagents: { researcher, writer } (agents من createAgent() لكل واحد منها description، أو catalog بصيغة { list, resolve }) إلى createAgent() أو AgentExecutor.execute(). الـ agent الرئيسي يحصل على tool باسم task للتفويض، وعلى tools المهام الخلفية الثلاث agent_status وagent_await وagent_cancel، وعلى قائمة بالـ sub-agents في الـ prompt. كل sub-agent يعمل على task prompt خاص به، ويرث من run الـ agent الرئيسي: الـ signal والـ hooks (ctx.subagent) والـ tracing وstore الـ approvals وevent listeners (event.subagent). maxSubagentDepth (الافتراضي 1) يحدّ عمق التداخل. راجع Sub-agents.

Approvals

الـ agent الذي تبنيه بـ createAgent() يتوقف مؤقتًا عند tool عليها needsApproval بدلًا من أن يفشل: send() (وsession.send()) يعيد finishReason: 'awaiting-approval' مع approvalId. agent.approvals.list() يعيد الاستدعاءات المعلّقة، و agent.approvals.resolve({ id, approved, note? }) ينفّذ الاستدعاء أو يرفضه ويعيد نتيجة الـ run بعد أن يكتمل (يكمل الـ session نفسها التي توقف فيها). تُحفظ التوقفات في InMemoryApprovalStore خاص بكل agent إلا إذا مرّرت approvalStore (مثل SqliteStore.approvals) أو store. والخيار approve: (request: PendingApproval) => boolean | string | Promise<boolean | string> يحسم كل استدعاء من الكود دون توقف (stream() يظل ينتهي عند التوقف) — request يحمل الاستدعاء مع kind وprincipal. ومع askQuestion: true يستطيع الـ agent أن يسأل المستخدم (kind: 'question')، وتجيب بـ agent.approvals.answer({ id, answer }). راجع Approvals.

Structured output

مرّر output: zodSchema إلى createAgent() (أو AgentExecutor.execute() / stream()): يجب أن يكون الرد الأخير كائن JSON يطابق الـ schema، و send() / run.result يعيده بعد الـ validation كـ result.object بالنوع z.output<typeof schema> (result.text يحتفظ بـ JSON الخام). الـ tools تعمل أولًا كالمعتاد. كل model call يحمل hint باسم responseFormat: { type: 'json', schema }، وتحوّله providers الـ ai SDK إلى JSON mode. الرد غير الصالح يحصل على خطوة repair واحدة تسرد المشكلات (تُحسب من maxSteps)؛ وإذا ظل غير صالح، ينتهي الـ run بـ finishReason: 'output-invalid' وoutputError: { message, issues }. راجع Structured output.

Skills

مرّر skills: [defineSkill({ name, description, content }), ...(await loadSkills(dir))] إلى createAgent() أو AgentExecutor.execute(): الأسماء والأوصاف فقط تدخل الـ system prompt، والـ model يحمّل محتوى كل skill عبر tool باسم load_skill تُسجَّل تلقائيًا. راجع Skills.

الذاكرة

مرّر memory: [defineMemory({ name, scope, provider })] إلى createAgent() لكي تحتفظ بعناصر عبر المحادثات: كل run يستحضر أحدث عناصر كل slot في الـ system prompt عند أول model call، والـ model يحصل على tools باسم remember_<name> / recall_<name>. الـ scope إما 'global' أو 'session' أو دالة على { sessionId, metadata }. inMemoryMemory() و fileMemory({ dir }) هما الـ providers المدمجة. راجع الذاكرة.

Durable execution

مع sessionId + checkpointStore يصبح الـ run آمنًا من الـ crash والـ session متعددة الـ turns: يُوضع للـ run checkpoint بعد كل رد من الـ model وكل نتيجة tool وكل توقف مؤقت، واستدعاء execute() مرة أخرى بالـ sessionId نفسه يكمل run لم ينتهِ (دون أن يعيد الـ model call لـ turn له رد بالفعل)، أو يواصل محادثة منتهية بالإدخال الجديد، أو يرمي SessionAwaitingApprovalError ما دام هناك approval معلّق. الـ tools تنفّذ at-least-once عبر الـ crash، وexecute يستقبل toolCallId الخاص بالاستدعاء لتستخدمه كـ idempotency key. راجع Durable execution للضمانات بالضبط. كيف ينتهي الـ run (أسباب الإنهاء)، وكيف تلغي run، وكيف تنفّذ الـ tool calls بالتوازي: راجع Runs.

Declarative specs

Providers

Message.content إما string أو قائمة ContentPart (text، image، file)؛ الـ providers المدمجة ترسل أجزاء الصور في رسائل المستخدم. راجع Multimodal input. راجع Providers لتعرف كيف يُحلّ الـ model string وأي model يعمل.

الاختبار

مُصدَّرة من lousho/testing (راجع اختبار الـ agents).

Tools

راجع Tools لدليل تعريف الـ tools وتسجيلها.
الحقول الاختيارية: displayName وneedsApproval (boolean أو predicate) وrequiresSandbox وsandboxExecute. تعريف الـ tool يتحقق فورًا من اسمها ووصفها والـ input بـ zod، وتسجيل tool بالاسم نفسه مرتين يرمي خطأً يذكر موضع التعارض. الـ tool المعرّفة تحمل الـ schema في inputSchema (الـ zod schema نفسها في input) ودالة execute مباشرة. هذان الحقلان هما المعتمدان في ToolDescriptor. أما كائن .tool ({ description, parameters, execute } بصيغة ai v4) فهو legacy: يُبنى للتوافق فقط، ولا يُستخدم إلا مع descriptors التي لا تحدد inputSchema / execute.
دعم الـ schema. inputSchema (بصيغة JSON Schema) لكل tool يتحوّل إلى zod schema، ووسائط الـ model تُفحَص مقابله قبل استدعاء السيرفر. المحوّل يعالج type (منها المصفوفات مثل ["string", "null"])، وenum بأنواع مختلطة، وconst، وanyOf / oneOf (union؛ anyOf: [X, { type: "null" }] تصبح X.nullable())، وallOf (دمج / intersection)، و$ref المحلي داخل $defs / definitions، وproperties / required، وadditionalProperties (boolean أو schema)، وitems، وdefault، والقيود minimum وmaximum وexclusiveMinimum وexclusiveMaximum وminLength وmaxLength وpattern وminItems و maxItems. وعندما يكون JSON Schema ملتبسًا، يكون التحويل متساهلًا: الكلمات المفتاحية غير المعروفة والـ schemas الفارغة وitems بصيغة tuple والـ refs التي لا تُحلّ تصبح z.any()، والـ $ref التعاودي يتوسّع مرة واحدة ويُستخدم z.any() للموضع الداخلي، والـ regex غير الصالح في pattern يُتخطّى، والكائنات تحتفظ بخصائص إضافية إلا إذا كان additionalProperties هو false. لا يرمي المحوّل خطأً أبدًا بسبب محتوى الـ schema. الـ tools المتخطّاة. إذا تعذّر تحويل tool واحدة، فهي وحدها التي تُتخطّى؛ وتُحمَّل بقية tools السيرفر. مرّر logger لكي يصلك تحذير يذكر السيرفر والـ tool والسبب، وonSkip لكي تجمع ما تُرك:
النتائج. نتيجة MCP التي فيها isError: true هي فشل tool عادي: الـ model يستقبل { "error": "McpToolError", "toolName": "...", "message": "..." } و message يحتوي المحتوى النصي الذي أعاده السيرفر. النتائج الناجحة قابلة للتسلسل كـ JSON: إذا أعاد السيرفر structuredContent، فهو كائن النتيجة؛ وإلا تكون النتيجة { text, content }، بحيث يجمع text كل الأجزاء النصية ويحتفظ content بكل جزء بترتيبه (text، image، audio، resource، resource_link؛ والجزء الذي نوعه غير معروف يُحتفظ به كـ { type: 'unknown', raw }). وإذا وصل structuredContent مع أجزاء غير نصية، تصبح النتيجة { structuredContent, text, content } ويحتوي content الأجزاء غير النصية فقط، لكي لا تُرمى الصور والصوت والموارد أبدًا. tools الـ todo وأخطاء الـ tools: راجع Tools.

الـ models والـ tokens والتكلفة

تقديرات الـ tokens، وجدول أسعار الـ models، واستهلاك الـ run وتكلفته: راجع الـ models والـ tokens والتكلفة. الـ context compaction له صفحة خاصة.

Flows وevals وobservability والأمان

  • FlowBuilder / FlowExecutor (lousho/flows) - graphs لمسارات عمل متعددة الخطوات؛ راجع Flows.
  • TriggerAdapter وTriggerRegistry (lousho/triggers) - نقطة التوسعة لآلية إيقاظ خاصة بك، ومعها verifySlackSignature() و parseCronExpression() وأدوات WebhookAuth المساعدة؛ راجع Triggers.
  • jwt() وoidc() وbasic() وapiToken() وanonymous() وrouteAuth() (lousho/auth) - auth على الـ routes كقائمة مرتبة؛ المتصل الذي تقبله يصل إلى الـ run كـ principal؛ راجع Route auth and principals.
  • defineEval()، وscorers مثل exactMatch وtoolCallOrder وbudget، وفحوص مثل includes وatLeast، وllmJudge() - evals للـ agents تعمل تحت vitest أو lousho eval؛ راجع Evals.
  • withSpan() وTraceExporter - tracing لـ AgentExecutor.execute(). TraceExporter واجهة BYO: لا تُشحن الحزمة مع أي exporter افتراضي. وللحصول على spans حقيقية في OpenTelemetry، استورد createOtelTraceExporter() من الـ subpath lousho/otel (يحتاج الـ peer dependency الاختيارية @opentelemetry/api) بدلًا من أن تكتب جسر OTel بنفسك - راجع examples/tracing/run-otel.ts. الـ spans تتبع الـ GenAI semantic conventions الخاصة بـ OpenTelemetry (والـ flows تتتبّع أيضًا)؛ راجع observability.
  • NoopSandbox / SubprocessSandbox - sandbox للـ tools التي تختاره عبر requiresSandbox؛ وrunPatchChecks() وفحوص الـ patch مثل createCommandCheck() وcreateDiffSizeCheck() و secretScanCheck. راجع Guardrails وsandboxing.
  • HookRegistry وAgentHook وHookContext وToolCallHookContext و GenerateHookContext - hooks تراقب الـ tool calls والـ model calls أو ترفضها أو تعيد كتابتها أو تحجب أجزاء منها. راجع Hooks.
  • EncryptionUtils وsha256 وStorageService (lousho/utils) - أدوات مساعدة داعمة؛ راجع Utilities.

النشر

  • DeploymentAdapter وregisterAdapter() وgetAdapter() وlistAdapters() - registry الـ adapters التي يقوم عليها lousho build (راجع النشر).