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

ابدأ مشروع جديد

أسرع طريقة أمر واحد. ينشئ مشروع جاهز للتشغيل (agent، وtool كمثال، واختبار offline، وملف .env.example للـ provider)، ويثبّت الـ dependencies، ويشغّل git init:
لتجرّب نسخة create-lousho محزومة محليًا (npm pack)، مرّر المسار المطلق لملف الـ tarball مع --package: npx --package=/abs/path/create-lousho-x.y.z.tgz create-lousho my-agent. أما npx ../x.tgz لوحده فيفشل على Windows. npx lousho init my-agent يفعل الشيء نفسه (مرّر --provider و--template، لأنه يعمل دون الأسئلة التفاعلية). وداخل مشروع مثبّت فيه الـ SDK أصلًا، يعمل npx lousho init أيضًا: أمر lousho يأتي من حزمة الـ SDK، لذلك npx lousho وحده خارج مشروع كهذا لا يجد شيئًا يشغّله. بدون arguments، يسألك init عن المجلد والـ provider والقالب. وnpx lousho init --help يعرض كل الـ flags. تفضّل تضيف الـ SDK إلى مشروع موجود؟ ثبّته يدويًا (راجع التثبيت):
هذا هو الـ major version الحالي من ai. ومع Ollama استخدم ai@^7.0.0 مع ollama-ai-provider-v2@^4.0.0 وzod 4 (راجع الأزواج).

1. Hello world

createAgent() هي نقطة الدخول بدون أي إعداد. تعطيها string بصيغة provider/model وتعليمات، وترجع لك agent فيه { send }. مفتاح الـ API يُقرأ من متغير البيئة المعتاد للـ provider (OPENAI_API_KEY هنا، وANTHROPIC_API_KEY أو OPENROUTER_API_KEY أو OLLAMA_BASE_URL للـ providers الباقين). الـ prefix vendor/ في الـ model هو الذي يحدد الـ provider. ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4.1-mini).
احذف model وخُذ قرار البيئة بدلًا عنك: LOUSHO_MODEL (string بصيغة provider/model) إذا كان موجودًا، وإلا أول واحد موجود من OPENAI_API_KEY وANTHROPIC_API_KEY وOPENROUTER_API_KEY وOLLAMA_BASE_URL. إذا نقص مفتاح أو كُتب الـ prefix خطأ، رسالة الخطأ تخبرك بالضبط ما تضبطه أو تصلحه. instructions اختيارية، وprompt مقبولة كـ alias لها.

2. أضف tool

عرّف الـ tool بـ defineTool(). وسائط execute وneedsApproval تكون typed من الـ zod input، والـ tool يدخل مباشرة في createAgent({ tools: [...] }). الـ mock provider يحاكي tool call كلما ذكرت رسالة المستخدم اسم tool، فهذا المثال يمر بـ tool call حقيقي كامل بدون LLM.
الأسماء يجب أن تكون من 1 إلى 64 حرف: حروف أو أرقام أو _ أو -. راجع الأدوات للـ validation والأخطاء والـ tools المدمجة.

3. اعمل streaming للرد

agent.stream() يشغّل الـ agent مثل send() ويرجع AgentRun. مرّ عليه بـ loop لتحصل على events typed (نص الـ model أول ما يصل، tool calls، حدود الـ steps). وawait run.result يعطيك نفس النتيجة التي ترجعها send().
راجع Streaming لقائمة الـ events الكاملة، والإلغاء، وإرسال الـ events إلى المتصفح.

4. احتفظ بالمحادثة

agent.send() تبدأ من history فارغ في كل استدعاء. أما agent.session() فتحتفظ بالمحادثة وتمررها للـ model مع كل send().
مرّر store لتحفظ الـ sessions بين إعادات التشغيل. راجع الجلسات.

5. اسأل قبل خطوة فيها مخاطرة

علّم الـ tool بـ needsApproval ويتوقف الـ run قبل استدعائها. send() تنتهي بـ finishReason: 'awaiting-approval' وapprovalId. بعدها يوافق كودك (أو إنسان) على الـ call أو يرفضه، ويكمل الـ run. هنا mockModel من lousho/testing يحدد turns الـ model بدقة، فالـ tool call مضمون.
مرّر approved: false (مع note) لرفض الـ call بدل الموافقة. راجع الموافقات للـ predicates والـ stores والقرار من process آخر.

6. اختبره offline

الـ agent من الخطوة السابقة جاهز للاختبار أصلًا. mockModel يسجّل كل طلب أرسله الـ agent، فتقدر تتحقق مما أُرسل للـ model وكذلك من النتيجة. بدون شبكة وبدون مفتاح.
في مشروع حقيقي، ضع نفس الـ assertions في اختبار vitest أو Jest. راجع الاختبار لتدفقات الـ tool calls وturns الأخطاء وrecordReplay.

7. Custom provider

model: 'provider/model' هو الطريق المختصر. مرّر provider بدلًا منه إذا كان عندك LLMProvider خاص بك أو تريد الـ mock للاختبارات. resolveProvider('<provider>/<model>') هي الدالة التي يستخدمها model من الداخل. هذا المثال يستخدم OpenAI إذا كان OPENAI_API_KEY موجودًا، ويرجع إلى الـ mock provider في غير ذلك. وهو نفس النمط الذي تستخدمه الأمثلة الجاهزة للتشغيل.

8. Declarative agents: ملفات spec

يمكنك وصف الـ agent كبيانات عادية، أي AgentSpec، وتحويله إلى agent قابل للتشغيل بـ specToAgent(). والشكل نفسه يُكتب كملف YAML أو JSON ويُحمّل بـ loadSpec().
احفظه باسم agent.yaml:
الـ spec نفسه يعمل في سيرفر التطوير المحلي (واجهة chat على /، وPOST /chat، وhot reload عند الحفظ) ويُبنى كسيرفر جاهز للنشر:

متقدم: executor API

createAgent() هي نقطة الدخول الموصى بها. وهي مبنية فوق AgentBuilder والدالة AgentExecutor.execute()، وهذه تقبل خيارات أدنى مستوى لا تقبلها createAgent()، مثل temperature وmaxTokens. راجع executor API.

الخطوات التالية