الأمثلة في هذه الصفحة تترك بعض الأسماء لك:كيف تترابط القطع: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 الرئيسي.
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.
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 لكي تجمع ما تُرك:
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()من الـ subpathlousho/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(راجع النشر).