diff --git a/ar/comparison.mdx b/ar/comparison.mdx new file mode 100644 index 0000000..a2d5a83 --- /dev/null +++ b/ar/comparison.mdx @@ -0,0 +1,69 @@ +--- +title: "مقارنة Lousho بغيرها" +description: "تقارن هذه الصفحة Lousho بأربع مكتبات وكلاء أخرى مكتوبة بـ TypeScript: Vercel AI SDK (ToolLoopAgent)، وOpenAI Agents SDK للغة JavaScript، وMastra، وLangGraph.js. كل خانة تخص مشروعًا آخر مأخوذة من توثيقه الرسمي." +--- +{/* Generated from docs/comparison.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */} + +آخر تحقق: 9 نوفمبر 2026. هذه المشاريع تتغير بسرعة، لذا قد تكون بعض الخانات قديمة. +نرحب بالتصحيحات: [افتح issue](https://github.com/LinuxDevil/agent-sdk/issues). + +## كيف تقرأ الجدول + +- ✅ تعني أن التوثيق الرسمي يعرض الميزة. +- partial تعني أن التوثيق يعرض جزءًا منها، أو أنها تحتاج منتجًا آخر. توضح الحاشية ما هو موجود. +- ❌ تعني أننا لم نجد الميزة في التوثيق الرسمي للمشروع. تربط الحاشية بالصفحة التي قرأناها. +- unverified تعني أن التوثيق الرسمي لم يسمح لنا بتأكيد الخانة في أي اتجاه. + +كل ✅ في عمود Lousho مربوطة بصفحة Lousho التي توثّق الميزة. + +## الجدول + +| | Lousho | Vercel AI SDK (ToolLoopAgent) | OpenAI Agents SDK (JS) | Mastra | LangGraph.js | +|---|---|---|---|---|---| +| يعمل داخل عمليتك (process) أنت | ✅ ([البدء السريع](/ar/quickstart)) | ✅ | ✅ | ✅ | ✅ | +| الاستئناف المتين بعد انهيار | ✅ ([التنفيذ المتين](/ar/durable-execution#الاستعادة-بعد-crash)) | partial[^v-durable] | ❌[^o-durable] | ✅ | ✅ | +| موافقة بشرية مع إيقاف واستئناف عبر عمليات مختلفة | ✅ ([الإيقاف وإعادة التشغيل والاستئناف](/ar/pause-and-resume)) | ✅ | ✅ | ✅ | ✅ | +| تقييمات بالتسجيل وإعادة التشغيل دون اتصال | ✅ ([التقييمات](/ar/evals#record-replay-and-drift)) | partial[^v-evals] | partial[^o-evals] | partial[^m-evals] | partial[^l-evals] | +| عميل MCP | ✅ ([MCP](/ar/mcp-integration#استخدام-سيرفرات-mcp-داخل-agent)) | ✅ | ✅ | ✅ | ✅ | +| خادم MCP | ✅ ([MCP](/ar/mcp-integration#تشغيل-agent-كسيرفر-mcp)) | partial[^v-mcp] | ❌[^o-mcp] | ✅ | partial[^l-mcp] | +| ربط مع React/Vue/Svelte | ✅ ([React](/ar/react)، [Vue](/ar/vue)، [Svelte](/ar/svelte)) | ✅ | ❌[^o-ui] | partial[^m-ui] | ✅ | +| OpenTelemetry | ✅ ([المراقبة](/ar/observability)) | ✅ | ❌[^o-otel] | ✅ | unverified[^l-otel] | +| استوديو أو أداة تصحيح محلية | ✅ ([Agent Forge](/ar/agent-forge)) | ✅ | ❌[^o-studio] | ✅ | partial[^l-studio] | +| مستقل عن المزوّد | ✅ ([المزوّدون](/ar/providers)) | ✅ | ✅ | ✅ | ✅ | +| الرخصة | MIT | Apache-2.0 | MIT | Apache-2.0، مع أجزاء تحت رخصة منفصلة[^m-licence] | MIT | + +[^v-durable]: يعمل `ToolLoopAgent` في الذاكرة ويفقد تقدّمه عند الانهيار. أما `WorkflowAgent` المنفصل من `@ai-sdk/workflow` فهو متين ويصمد أمام إعادة التشغيل، لكنه يعمل داخل بيئة تشغيل Workflow. راجع [WorkflowAgent](https://ai-sdk.dev/docs/agents/workflow-agent). +[^o-durable]: يعرض التوثيق حفظ حالة التشغيل واستئنافها فقط عندما يتوقف التشغيل بانتظار موافقة (`RunState`). لم نجد نقاط حفظ تسمح لتشغيل منهار بالاستئناف. راجع [Human-in-the-loop](https://openai.github.io/openai-agents-js/guides/human-in-the-loop/). +[^v-evals]: يوفّر AI SDK نماذج وهمية وأدوات مساعدة للبث في الاختبارات. لم نجد طريقة لتسجيل تشغيل حقيقي وإعادة تشغيله، أو للإبلاغ عن تغيّر مسار التنفيذ. راجع [Testing](https://ai-sdk.dev/docs/ai-sdk-core/testing). +[^o-evals]: يوفّر `@openai/agents/testing` نموذج `ScriptedModel` يعمل دون اتصال، ووصفة لاكتشاف تغيّر مسار العمل. لكن الخطوات المبرمجة تُكتب يدويًا، ولا تُسجَّل من تشغيل حقيقي. راجع [Testing](https://openai.github.io/openai-agents-js/guides/testing/). +[^m-evals]: يمكن للتجارب محاكاة مخرجات الأدوات على عناصر مجموعة البيانات، ويوجد مقياس لدقة مسار التنفيذ. لم نجد تسجيلًا لردود نموذج حقيقية لإعادة تشغيلها دون اتصال. راجع [Experiments](https://mastra.ai/docs/evals/experiments) و[Built-in scorers](https://mastra.ai/docs/evals/built-in-scorers). +[^l-evals]: يستطيع `agentevals` مطابقة تشغيل مع مسار تنفيذ تكتبه يدويًا، دون أي استدعاء للنموذج. التخزين المؤقت لطلبات HTTP في الاختبارات موثّق لـ Python (pytest)، وليس لتكامل JS مع Vitest/Jest. راجع [Evals](https://docs.langchain.com/oss/javascript/langchain/evals) و[Vitest/Jest](https://docs.langchain.com/langsmith/vitest-jest). +[^v-mcp]: توثّق Vercel حزمة منفصلة اسمها `mcp-handler` لبناء خوادم MCP. هي ليست جزءًا من AI SDK، ولا تتضمن أداة مساعدة لتقديم وكيل. راجع [Deploy MCP servers to Vercel](https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel). +[^o-mcp]: يغطي دليل MCP الاتصال بخوادم MCP. لم نجد واجهة لتقديم وكيل كخادم MCP. راجع [MCP](https://openai.github.io/openai-agents-js/guides/mcp/). +[^l-mcp]: يعرض Agent Server، بما فيه الخادم المحلي `langgraph dev`، الوكلاءَ على المسار `/mcp`. لم نجد طريقة لفعل ذلك من المكتبة وحدها. راجع [MCP endpoint in Agent Server](https://docs.langchain.com/langsmith/server-mcp). +[^o-ui]: لم نجد في التوثيق خطافات واجهة لـ React أو Vue أو Svelte. راجع [التوثيق الكامل](https://openai.github.io/openai-agents-js/llms-full.txt). +[^m-ui]: لدى Mastra حزمة React رسمية وحزمة SDK للعميل. يعمل Svelte عبر `@ai-sdk/svelte` من AI SDK مع `@mastra/ai-sdk`. لم نجد صفحة لـ Vue. راجع [Mastra Client](https://mastra.ai/docs/server/mastra-client) و[AI SDK UI](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui) و[SvelteKit](https://mastra.ai/integrations/frameworks/sveltekit). +[^o-otel]: تذهب مسارات التتبّع إلى لوحة OpenAI افتراضيًا، ويمكنك إضافة معالجات تتبّع خاصة بك. لا يذكر التوثيق OpenTelemetry. راجع [Tracing](https://openai.github.io/openai-agents-js/guides/tracing/). +[^l-otel]: يقبل LangSmith مقاطع تتبّع (spans) من OpenTelemetry، لكن كل أمثلة الإعداد مكتوبة بـ Python. لم نستطع تأكيد الإعداد في JS. راجع [Trace with OpenTelemetry](https://docs.langchain.com/langsmith/trace-with-opentelemetry). +[^o-studio]: تُفحص التشغيلات في لوحة Traces المستضافة. لم نجد واجهة محلية. راجع [Tracing](https://openai.github.io/openai-agents-js/guides/tracing/). +[^l-studio]: يشغّل `langgraph dev` خادمًا محليًا، ويتصل به Studio. لكن Studio يُقدَّم من smith.langchain.com ويحتاج حسابًا ومفتاح API في LangSmith. راجع [Studio](https://docs.langchain.com/oss/javascript/langgraph/studio) و[Local server](https://docs.langchain.com/oss/javascript/langgraph/local-server). +[^m-licence]: الشيفرة داخل مجلدات `ee/` تخضع لرخصة Mastra Enterprise Edition. هي متاحة المصدر، وليست مفتوحة المصدر. راجع [LICENSE.md](https://github.com/mastra-ai/mastra/blob/main/LICENSE.md). + +## ماذا تعني الصفوف + +- **يعمل داخل عمليتك أنت**: مكتبة تستدعيها من عملية Node.js الخاصة بك. لا حاجة لبيئة تشغيل مستضافة. +- **الاستئناف المتين بعد انهيار**: التشغيل الذي يتوقف في منتصفه يمكنه أن يكمل من نقطة حفظ (checkpoint)، دون إعادة عمل انتهى بالفعل. +- **موافقة بشرية مع إيقاف واستئناف عبر عمليات مختلفة**: يمكن لاستدعاء أداة أن ينتظر شخصًا، ويمكن حفظ هذا الانتظار، ويمكن لعملية أخرى أن تكمل التشغيل. +- **تقييمات بالتسجيل وإعادة التشغيل دون اتصال**: سجّل تشغيلًا حقيقيًا مرة واحدة، ثم أعد تشغيله في CI دون شبكة ودون مفتاح API، واعرف متى يتغير مسار استدعاءات الأدوات. +- **عميل MCP / خادم MCP**: استدعِ أدوات من خوادم MCP، أو قدّم وكيلك كخادم MCP. +- **ربط مع React/Vue/Svelte**: خطافات أو مخازن واجهة رسمية لهذه الأطر. +- **OpenTelemetry**: مقاطع تتبّع يمكنك إرسالها إلى أي خادم OpenTelemetry. +- **استوديو أو أداة تصحيح محلية**: واجهة على جهازك لفحص الوكلاء وتشغيلهم. +- **مستقل عن المزوّد**: يعمل مع نماذج من أكثر من مزوّد. + +## متى لا تستخدم Lousho + +- **تحتاج Python.** Lousho مكتوب بـ TypeScript فقط، ويحتاج Node 22.19 أو أحدث. +- **تريد منصة مُدارة.** لا يملك Lousho بيئة تشغيل مستضافة. أنت تشغّل الوكيل ومخزنه والاستوديو وتستضيفها بنفسك. +- **تحتاج واجهة برمجية مستقرة بإصدار 1.0 اليوم.** Lousho في مرحلة alpha (`1.0.0-alpha.*`). قد تتغير الواجهة قبل 1.0، لذا ثبّت إصدارًا محددًا. راجع [الترقية إلى 1.0](/ar/upgrading). +- **تحتاج استدعاء نموذج واحد فقط أو حلقة أدوات بسيطة.** Vercel AI SDK وحده أصغر. Lousho مبني عليه، لذا يمكنك الانتقال لاحقًا. راجع [الانتقال من AI SDK](/ar/migrating-from-ai-sdk). diff --git a/ar/translations.json b/ar/translations.json index 7bcad08..c5e3168 100644 --- a/ar/translations.json +++ b/ar/translations.json @@ -15,6 +15,7 @@ "code-mode": "3b97ba05200c", "coding-agents": "e9e0e98e6dfd", "compaction": "d87af1f5ba11", + "comparison": "088891111b2f", "configuration": "9c3d136710cc", "connectors": "d1974d8c7cfb", "decisions": "ab1bc01e2ca3", diff --git a/comparison.mdx b/comparison.mdx new file mode 100644 index 0000000..bcf1518 --- /dev/null +++ b/comparison.mdx @@ -0,0 +1,82 @@ +--- +title: "How Lousho compares" +description: "This page compares Lousho with four other TypeScript agent libraries: the Vercel AI SDK (ToolLoopAgent), the OpenAI Agents SDK for JavaScript, Mastra and LangGraph.js. Each competitor cell comes from that project's official docs." +--- +{/* Generated from docs/comparison.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */} + +Last checked: 9 Nov 2026. These projects move fast, so a cell may be out of +date. Corrections welcome: [open an issue](https://github.com/LinuxDevil/agent-sdk/issues). + +## How to read the table + +- ✅ means the official docs show the feature. +- partial means the docs show part of it, or it needs another product. The + footnote says what exists. +- ❌ means we did not find the feature in the project's official docs. The + footnote links the page we read. +- unverified means the official docs did not let us confirm the cell either way. + +Each Lousho ✅ links to the Lousho page that documents it. + +## The table + +| | Lousho | Vercel AI SDK (ToolLoopAgent) | OpenAI Agents SDK (JS) | Mastra | LangGraph.js | +|---|---|---|---|---|---| +| Runs in your own process | ✅ ([quick start](/quickstart)) | ✅ | ✅ | ✅ | ✅ | +| Durable resume after a crash | ✅ ([durable execution](/durable-execution#recovering-after-a-crash)) | partial[^v-durable] | ❌[^o-durable] | ✅ | ✅ | +| Human approval with pause/resume across processes | ✅ ([pause, restart, resume](/pause-and-resume)) | ✅ | ✅ | ✅ | ✅ | +| Offline record/replay evals | ✅ ([evals](/evals#record-replay-and-drift)) | partial[^v-evals] | partial[^o-evals] | partial[^m-evals] | partial[^l-evals] | +| MCP client | ✅ ([MCP](/mcp-integration#use-mcp-servers-in-an-agent)) | ✅ | ✅ | ✅ | ✅ | +| MCP server | ✅ ([MCP](/mcp-integration#serve-an-agent-over-mcp)) | partial[^v-mcp] | ❌[^o-mcp] | ✅ | partial[^l-mcp] | +| React/Vue/Svelte bindings | ✅ ([React](/react), [Vue](/vue), [Svelte](/svelte)) | ✅ | ❌[^o-ui] | partial[^m-ui] | ✅ | +| OpenTelemetry | ✅ ([observability](/observability)) | ✅ | ❌[^o-otel] | ✅ | unverified[^l-otel] | +| Local studio/debugger | ✅ ([Agent Forge](/agent-forge)) | ✅ | ❌[^o-studio] | ✅ | partial[^l-studio] | +| Provider-agnostic | ✅ ([providers](/providers)) | ✅ | ✅ | ✅ | ✅ | +| Licence | MIT | Apache-2.0 | MIT | Apache-2.0, with some parts under a separate licence[^m-licence] | MIT | + +[^v-durable]: A `ToolLoopAgent` runs in memory and loses its progress on a crash. The separate `WorkflowAgent` from `@ai-sdk/workflow` is durable and survives restarts, but it runs inside a Workflow runtime. See [WorkflowAgent](https://ai-sdk.dev/docs/agents/workflow-agent). +[^o-durable]: The docs show a run's state saved and resumed only when it stops for an approval (`RunState`). We found no checkpointing that lets a crashed run resume. See [Human-in-the-loop](https://openai.github.io/openai-agents-js/guides/human-in-the-loop/). +[^v-evals]: The AI SDK has mock models and stream helpers for tests. We found no way to record a real run and replay it, or to report trajectory drift. See [Testing](https://ai-sdk.dev/docs/ai-sdk-core/testing). +[^o-evals]: `@openai/agents/testing` has a `ScriptedModel` that runs offline, and a recipe to detect workflow drift. The scripted steps are written by hand, not recorded from a real run. See [Testing](https://openai.github.io/openai-agents-js/guides/testing/). +[^m-evals]: Experiments can mock tool outputs on dataset items, and there is a trajectory accuracy scorer. We found no recording of real model responses for offline replay. See [Experiments](https://mastra.ai/docs/evals/experiments) and [Built-in scorers](https://mastra.ai/docs/evals/built-in-scorers). +[^l-evals]: `agentevals` can match a run against a trajectory you write by hand, with no model calls. HTTP caching for tests is documented for Python (pytest), not for the JS Vitest/Jest integration. See [Evals](https://docs.langchain.com/oss/javascript/langchain/evals) and [Vitest/Jest](https://docs.langchain.com/langsmith/vitest-jest). +[^v-mcp]: Vercel documents a separate `mcp-handler` package for building MCP servers. It is not part of the AI SDK and has no helper to serve an agent. See [Deploy MCP servers to Vercel](https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel). +[^o-mcp]: The MCP guide covers connecting to MCP servers. We found no API to serve an agent as an MCP server. See [MCP](https://openai.github.io/openai-agents-js/guides/mcp/). +[^l-mcp]: Agent Server, including the local `langgraph dev` server, exposes agents at `/mcp`. We found no way to do it from the library alone. See [MCP endpoint in Agent Server](https://docs.langchain.com/langsmith/server-mcp). +[^o-ui]: We found no React, Vue or Svelte UI hooks in the docs. See the [full docs](https://openai.github.io/openai-agents-js/llms-full.txt). +[^m-ui]: Mastra has a first-party React package and a client SDK. Svelte works through the AI SDK's `@ai-sdk/svelte` with `@mastra/ai-sdk`. We found no Vue page. See [Mastra Client](https://mastra.ai/docs/server/mastra-client), [AI SDK UI](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui) and [SvelteKit](https://mastra.ai/integrations/frameworks/sveltekit). +[^o-otel]: Traces go to the OpenAI dashboard by default, and you can add your own trace processors. The docs do not mention OpenTelemetry. See [Tracing](https://openai.github.io/openai-agents-js/guides/tracing/). +[^l-otel]: LangSmith accepts OpenTelemetry spans, but every setup example is in Python. We could not confirm the JS setup. See [Trace with OpenTelemetry](https://docs.langchain.com/langsmith/trace-with-opentelemetry). +[^o-studio]: Runs are inspected in the hosted Traces dashboard. We found no local UI. See [Tracing](https://openai.github.io/openai-agents-js/guides/tracing/). +[^l-studio]: `langgraph dev` runs a local server, and Studio connects to it. Studio is served from smith.langchain.com and needs a LangSmith account and API key. See [Studio](https://docs.langchain.com/oss/javascript/langgraph/studio) and [Local server](https://docs.langchain.com/oss/javascript/langgraph/local-server). +[^m-licence]: Code in `ee/` folders is under the Mastra Enterprise Edition licence. It is source-available, not open source. See [LICENSE.md](https://github.com/mastra-ai/mastra/blob/main/LICENSE.md). + +## What the rows mean + +- **Runs in your own process**: a library you call from your own Node process. + No hosted runtime is needed. +- **Durable resume after a crash**: a run that dies part way through can carry + on from a checkpoint, without redoing work that already finished. +- **Human approval with pause/resume across processes**: a tool call can wait + for a person, the wait can be saved, and another process can finish the run. +- **Offline record/replay evals**: record a real run once, replay it in CI with + no network and no API key, and flag when the tool-call trajectory changes. +- **MCP client / MCP server**: call tools from MCP servers, or serve your agent + as one. +- **React/Vue/Svelte bindings**: first-party UI hooks or stores for those + frameworks. +- **OpenTelemetry**: spans you can send to any OpenTelemetry backend. +- **Local studio/debugger**: a UI on your machine to inspect and run agents. +- **Provider-agnostic**: works with models from more than one vendor. + +## When not to use Lousho + +- **You need Python.** Lousho is TypeScript only. It needs Node 22.19 or later. +- **You want a managed platform.** Lousho has no hosted runtime. You run and + host the agent, its store and the studio yourself. +- **You need a stable 1.0 API today.** Lousho is in alpha (`1.0.0-alpha.*`). + The API may change before 1.0, so pin a version. See + [Upgrading to 1.0](/upgrading). +- **You only need one model call or a simple tool loop.** The Vercel AI SDK on + its own is smaller. Lousho builds on it, so you can move over later. See + [Migrating from the AI SDK](/migrating-from-ai-sdk). diff --git a/docs.json b/docs.json index 1886dcd..729c8fb 100644 --- a/docs.json +++ b/docs.json @@ -47,6 +47,7 @@ "introduction", "quickstart", "installation", + "comparison", "troubleshooting", "coding-agents", "build-a-coding-agent" @@ -239,6 +240,7 @@ "ar/introduction", "ar/quickstart", "ar/installation", + "ar/comparison", "ar/troubleshooting", "ar/coding-agents" ] diff --git a/scripts/sync-sdk-docs.mjs b/scripts/sync-sdk-docs.mjs index d9406ad..4c0f286 100644 --- a/scripts/sync-sdk-docs.mjs +++ b/scripts/sync-sdk-docs.mjs @@ -96,6 +96,7 @@ const PAGES = { 'docs/self-healing.md': 'self-healing', 'docs/improve.md': 'improve', 'docs/agent-spec.md': 'agent-spec', + 'docs/comparison.md': 'comparison', 'CHANGELOG.md': 'changelog', // Example READMEs become full pages under the Examples tab. 'examples/waves/README.md': 'examples/waves',