Skip to content

docs: add the comparison page (en + ar) #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LinuxDevil merged 1 commit into from
Nov 10, 2026
Merged

docs: add the comparison page (en + ar) #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions ar/comparison.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
1 change: 1 addition & 0 deletions ar/translations.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
"code-mode": "3b97ba05200c",
"coding-agents": "e9e0e98e6dfd",
"compaction": "d87af1f5ba11",
"comparison": "088891111b2f",
"configuration": "9c3d136710cc",
"connectors": "d1974d8c7cfb",
"decisions": "ab1bc01e2ca3",
Expand Down
82 changes: 82 additions & 0 deletions comparison.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 2 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
"introduction",
"quickstart",
"installation",
"comparison",
"troubleshooting",
"coding-agents",
"build-a-coding-agent"
Expand Down Expand Up @@ -239,6 +240,7 @@
"ar/introduction",
"ar/quickstart",
"ar/installation",
"ar/comparison",
"ar/troubleshooting",
"ar/coding-agents"
]
Expand Down
1 change: 1 addition & 0 deletions scripts/sync-sdk-docs.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading