@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/agent-mentions.md

@@ -0,0 +1,164 @@
+---
+title: "إشارات الوكيل"
+description: "ضع علامة على الوكلاء المخصصين والوكلاء المتصلين والملفات في الدردشة باستخدام الإشارات @."
+---
+
+# إشارات الوكيل
+
+اكتب `@` في مؤلف الدردشة لذكر الوكلاء المخصصين والوكلاء المتصلين والملفات والموارد.
+
+## نظرة عامة {#overview}
+
+يقوم نظام الإشارة `@` بربط مؤلف الدردشة بالنظام البيئي للوكيل الأوسع. عندما تكتب `@`، تظهر نافذة منبثقة تدرج الوكلاء المخصصين المتاحين والوكلاء المتصلين وملفات قاعدة التعليمات البرمجية والموارد.
+
+هذه هي الطريقة التي تقوم بها بتنسيق سير العمل متعدد الوكلاء من دردشة واحدة. اطلب من وكيل `@design` المحلي مراجعة التصميم، ومن `@analytics` الحصول على أحدث الأرقام من تطبيق آخر، ويمكن للوكيل الرئيسي دمج كليهما في محادثة واحدة.
+
+## ذكر الوكلاء {#mentioning-agents}
+
+للإشارة إلى وكيل في مؤلف الدردشة:
+
+1. اكتب `@` لفتح القائمة المنبثقة للإشارة
+2. تصفح أو ابحث في قائمة الوكلاء المتاحين
+3. حدد وكيلًا — يظهر كعلامة في رسالتك
+4. أرسل الرسالة — يقوم الخادم بحل الإشارة ويتضمن استجابة ذلك الوكيل في سياق المحادثة
+
+هناك مساران للوكيل:
+
+- **الوكلاء المخصصون** — ملفات تعريف وكيل مساحة العمل المحلية في `agents/*.md`. يتم تشغيلها داخل التطبيق/وقت التشغيل الحالي باستخدام تعليمات ملف تعريف الوكيل وتجاوز النموذج الاختياري.
+- **الوكلاء المتصلون** — أقران A2A عن بعد. يتم استدعاؤها عبر [A2A protocol](/docs/a2a-protocol).
+
+في كلتا الحالتين، يرى وكيلك الرئيسي الاستجابة ويمكنه الرجوع إليها أو البناء عليها.
+
+```an-diagram title="Where an @-mention routes" summary="The server splits each mention by type: custom agents run locally, connected agents go over A2A — both responses fold back into the main agent's context."
+{
+  "html": "<div class=\"diagram-mention\"><div class=\"diagram-node\">@-mention<br><small class=\"diagram-muted\">in the composer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Server resolves</span><small class=\"diagram-muted\">extract refs by type</small></div><div class=\"diagram-col\"><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Custom agent<br><small class=\"diagram-muted\">agents/*.md &middot; runs local</small></div></div><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">Connected agent<br><small class=\"diagram-muted\">A2A peer &middot; remote call</small></div></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box diagram-accent\">&lt;agent-response&gt;<br><small class=\"diagram-muted\">injected into main agent</small></div></div>",
+  "css": ".diagram-mention{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-mention .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-mention .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mention .row{display:flex;align-items:center;gap:8px}.diagram-mention .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## كيفية العمل {#how-it-works}
+
+عند إرسال رسالة تحتوي على إشارة `@`، يحدث ما يلي على الخادم:
+
+1. يستخرج الخادم المراجع المذكورة من الرسالة
+2. لكل وكيل مذكور:
+   - يعمل الوكلاء المخصصون محليًا باستخدام تعليمات ملفاتهم الشخصية
+   - يتم استدعاء الوكلاء المتصلين عبر A2A
+3. يتم تغليف استجابة الوكيل في كتلة `<agent-response>` XML وإدراجها في سياق المحادثة
+4. يقوم الوكيل الرئيسي بمعالجة الرسالة المثرية، ويرى كلاً من نص المستخدم واستجابة الوكيل المذكور
+
+ما يراه الوكيل الرئيسي في سياقه:
+
+```text
+User: Draft an email with the latest signup numbers. @analytics
+
+<agent-response agent="analytics">
+Last week's signups: 1,247 total
+  - Organic: 623
+  - Paid: 412
+  - Referral: 212
+</agent-response>
+```
+
+يمكن للوكيل الرئيسي بعد ذلك استخدام هذه البيانات بشكل طبيعي في استجابته - على سبيل المثال، دمج الأرقام في مسودة بريد إلكتروني.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Mentioned-agent output arrives as an `<agent-response agent=\"…\">` block in the **main agent's** context — not as separate chat bubbles. The main agent decides how to weave it into the reply."
+}
+```
+
+## إضافة وكلاء {#adding-agents}
+
+يصبح الوكلاء متاحين للإشارة من خلال عدة آليات:
+
+- **وكلاء مساحة العمل المخصصة** — أنشئ ملفات تعريف الوكلاء في علامة تبويب مساحة العمل باسم `agents/*.md`
+- **الاكتشاف التلقائي** — يكتشف إطار العمل تلقائيًا الوكلاء المتصلين الذين يعملون على منافذ معروفة أو URLs التي تم تكوينها
+- **البيانات البعيدة** — إضافة بيانات الوكيل المتصل كـ `remote-agents/*.json`
+
+### وكلاء مساحة العمل المخصصة
+
+الوكلاء المخصصون هم ملفات Markdown مخزنة في مساحة العمل:
+
+```markdown
+---
+name: Design
+description: Reviews layouts, product UX, and visual direction.
+model: inherit
+---
+
+You are a focused design agent.
+```
+
+راجع [Workspace — Custom Agents](/docs/workspace#custom-agents) للتعرف على التنسيق الكامل (بما في ذلك `tools`، و`delegate-default`، وتجاوزات النماذج).
+
+يمكنك إنشاؤها من علامة التبويب "مساحة العمل" باستخدام:
+
+- `Create Agent` -> `Describe It`
+- `Create Agent` -> `Fill Form`
+
+### بيانات الوكيل المتصل
+
+لا يزال وكلاء A2A البعيدون يستخدمون بيانات JSON:
+
+```json
+// remote-agents/analytics.json
+{
+  "name": "Analytics Agent",
+  "url": "https://analytics.example.com",
+  "apiKey": "env:ANALYTICS_A2A_KEY",
+  "description": "Runs analytics queries and returns data",
+  "skills": ["run-query", "generate-chart"]
+}
+```
+
+---
+
+## للمطورين: توسيع الإشارات {#extending-mentions}
+
+يمكن للقوالب تسجيل موفري الإشارات المخصصة لإضافة عناصر قابلة للذكر خاصة بالمجال بخلاف الوكلاء والملفات. يقوم موفر الإشارة بتنفيذ واجهة `MentionProvider`:
+
+```an-annotated-code title="A custom MentionProvider"
+{
+  "filename": "server/mentions/contacts.ts",
+  "language": "ts",
+  "code": "import type { MentionProvider } from \"@agent-native/core/server\";\n\nconst contactsProvider: MentionProvider = {\n  id: \"contacts\",\n  label: \"Contacts\",\n\n  // Search for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: \"contact\",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: \"context\",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};",
+  "annotations": [
+    { "lines": "4-5", "label": "Identity", "note": "`id` namespaces the provider; `label` is the section heading shown in the `@` popover." },
+    { "lines": "8-9", "label": "search", "note": "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`." },
+    { "lines": "23-24", "label": "resolve", "note": "Called when the message is sent. Turns a picked id into `{ type: \"context\", text }` that is injected into the agent's context." }
+  ]
+}
+```
+
+تسجيل الموفرين في تكوين البرنامج المساعد للدردشة الوكيل:
+
+```ts
+// server/plugins/agent-chat.ts
+import { createAgentChatPlugin } from "@agent-native/core/server";
+
+export default createAgentChatPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  mentionProviders: { contacts: contactsProvider },
+});
+```
+
+يظهر موفرو الإشارات المخصصة جنبًا إلى جنب مع الوكيل المضمن وموفري الملفات في القائمة المنبثقة للإشارة.
+
+## الملفات المرجعية {#referencing-files}
+
+لا يقتصر العنصر المنبثق `@` على الوكلاء. يمكنك أيضًا الرجوع إلى:
+
+- **ملفات Codebase** — اكتب `@` وابحث عن اسم ملف. يتم تضمين محتويات الملف في سياق الوكيل حتى يتمكن من قراءة الملف أو تحليله أو تعديله.
+- **موارد مساحة العمل** — الملفات المرجعية المحددة في علامة التبويب مساحة العمل. يمكن أن تكون هذه ملفات بيانات، أو تكوينات، أو أي محتوى منظم آخر.
+- **Skills** — اكتب `/` للإشارة إلى إحدى المهارة. توفر Skills تعليمات منظمة ترشد كيفية تعامل الوكيل مع المهمة.
+
+تتبع جميع أنواع المراجع نفس النمط: حدد من القائمة المنبثقة، وسيتم حل المحتوى المشار إليه وإدخاله في سياق الوكيل عند إرسال الرسالة.
+
+## اختيار الوكيل الفرعي {#sub-agent-selection}
+
+يمكن للوكيل الرئيسي أيضًا استخدام الوكلاء المخصصين عند نشر الوكلاء الفرعيين باستخدام `agent-teams` (الإجراء: "النشر").
+
+قم بتمرير المعلمة `agent` لاختيار ملف تعريف من `agents/*.md`. تتم إضافة تعليمات ملف التعريف هذا إلى التشغيل المفوض، ويمكن للمادة الأمامية `model` الخاصة به تجاوز النموذج الافتراضي لذلك الوكيل الفرعي.

package/docs/content/locales/ar-SA/agent-surfaces.md

@@ -0,0 +1,397 @@
+---
+title: "أسطح الوكيل"
+description: "استخدم Agent-Native بشكل مستقل، كدردشة غنية، داخل تطبيق موجود، أو كتطبيق أصلي كامل للوكيل."
+search: "التطبيق الكامل للدردشة الغنية للوكيل مقطوع الرأس BYO وقت تشغيل الوكيل AgentChatRuntime تضمين actions MCP A2A HTTP CLI"
+---
+
+# أسطح الوكيل
+
+Agent-Native قابل للتأليف بشكل متعمد. يمكنك استخدام الوكيل بدون الكثير من UI،
+استخدم UI بدون وقت تشغيل الوكيل المضمن، أو استخدمهما معًا بشكل كامل
+التطبيق.
+
+الطريقة المفيدة للاختيار ليست عن طريق البروتوكول أولاً. اختر سطح المنتج
+الذي تريده، ثم استخدم البدائية المطابقة.
+
+| السطح                           | استخدمه عندما                                                                                          | ابدأ بـ                                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| **العميل مقطوع الرأس**          | يجب على التعليمات البرمجية أو الوظائف أو البرامج النصية أو تطبيق آخر أو وكيل آخر استدعاء العمل مباشرة. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **دردشة غنية على Agent-Native** | تريد دردشة مستقلة أو مضمنة مدعومة بحلقة الوكيل المضمنة.                                                | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **دردشة غنية مع وكيلك**         | لقد أنشأت الوكيل في مكان آخر وتريد مؤلف Agent-Native والنص وبطاقات الأدوات والأدوات الأصلية.           | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **عربة جانبية مضمنة**           | لديك بالفعل تطبيق SaaS وتريد وكيلًا بجانبه يتضمن سياق الصفحة وأوامر المضيف.                            | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **الطلب الكامل**                | يجب على البشر والوكلاء مشاركة الشاشات والبيانات والتنقل والتعاون الدائم.                               | النماذج، actions، حالة SQL، الوعي بالسياق                                                   |
+
+تلك مراحل وليست منتجات منفصلة. يمكن أن يبدأ سير العمل بدون رأس
+وكيل بإجراء واحد، يظهر في الدردشة كجدول أو مخطط، ويصبح فيما بعد
+ملء الشاشة في التطبيق دون تغيير العملية التي يستدعيها الوكيل.
+
+```an-diagram title="The surface spectrum" summary="One action surface, four product shapes — each adds UI without changing the operation underneath."
+{
+  "html": "<div class=\"diagram-spectrum\"><div class=\"diagram-card\"><strong>Headless</strong><small class=\"diagram-muted\">actions, jobs, scripts, other agents</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Rich chat</strong><small class=\"diagram-muted\">composer, transcript, tool cards</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embedded sidecar</strong><small class=\"diagram-muted\">agent beside an existing app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">most UI</span><strong>Full application</strong><small class=\"diagram-muted\">durable screens, data, collaboration</small></div></div><div class=\"diagram-base\" data-rough><span class=\"diagram-muted\">same actions · same SQL · same agent loop</span></div>",
+  "css": ".diagram-spectrum{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-spectrum .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px;flex:1}.diagram-spectrum .diagram-arrow{align-self:center;font-size:22px;line-height:1}.diagram-base{margin-top:12px;padding:10px 14px;text-align:center}"
+}
+```
+
+## عميل بلا رأس {#headless}
+
+استخدم المسار بدون رأس عندما لا يحتاج أحد إلى التحديق في شاشة التطبيق المخصصة أثناء
+تشغيل العمل: المهام المجدولة، وعمليات التكامل، وسير عمل الواجهة الخلفية، وحلقات CLI،
+وكيل آخر، أو منتج موجود يتصل بـ Agent-Native.
+
+هذا أيضًا هو الشكل الذي يجب الوصول إليه عندما يكون **الوكيل*هو*المنتج** —
+حلقة وكيل التطبيق هي الباب الأمامي، وليست لوحة القيادة. قمت بإرسال طلب من
+المحطة الطرفية، أو Slack، أو البريد الإلكتروني، أو مهمة مجدولة، أو وكيل آخر، أو الدردشة - "تلخيص
+رسائل البريد الإلكتروني غير المقروءة"، "انشر المقاييس اليومية على Slack"، "ابحث عن المرشحين الذين
+أجاب الأسبوع الماضي" - ويعمل الوكيل ويعيد النتيجة أينما كانت
+ينتمي. لا يزال تطبيقًا حقيقيًا، وليس مطالبة عديمة الحالة: actions، جلسات المصادقة،
+حالة التطبيق، وسجل سلسلة المحادثات/التشغيل، والإعدادات، وبيانات الاعتماد، وسجلات المشاركة كلها مباشرة
+في SQL.
+
+اختر هذا النمط عندما:
+
+- **يتم العمل في الخلفية.** يتم إنشاء معظم القيمة دون أن يراقب المستخدم — وكلاء الفرز، ووكلاء التقارير اليومية، والمستجيبون عند الطلب.
+- **الإخراج يغادر التطبيق.** يقوم الوكيل بالنشر على Slack، أو يرسل بريدًا إلكترونيًا، أو يقوم بتحديث نظام تابع لجهة خارجية؛ لا يوجد شيء لتصفحه داخل التطبيق.
+- **المجال عبارة عن طلقة واحدة.** روبوت البحث، ومولد الملخص، وكاتب التقارير — لا يوجد كائن ثابت يحتاج إلى عرض القائمة.
+- **أنت تقوم بإعداد النماذج الأولية.** اشحن الوكيل الآن؛ قم بإضافة UI الأكثر ثراءً لاحقًا إذا أراد المستخدمون واحدًا.
+
+إذا كان منتجك مبنيًا على كائنات ثابتة يتصفحها المستخدمون ويدورون حولها
+المشاركة - رسائل البريد الإلكتروني، والأحداث، والمستندات، والمخططات - اختر [full application](#full-application)
+أو [template](/docs/cloneable-saas) بدلاً من ذلك؛ يضيف هؤلاء UI _plus_ الوكيل الكامل.
+
+### ما الذي يأتي في الصندوق {#in-the-box}
+
+يتخطى التطبيق بدون مراقبة أسابيع من عمل لوحة التحكم، وهو لا يلتزم بالقناة منذ اليوم
+واحد — يتم تشغيل نفس الوكيل من الويب وSlack وTelegram والبريد الإلكتروني والوكلاء الآخرين
+لأن كل شيء يمر عبر الوكيل، وليس UI. المقايضة موجودة
+لا يوجد عرض "تصفح كل شيء بلمحة سريعة"؛ إذا احتاج المستخدمون إلى ذلك، فامزج الأنماط و
+أضف صفحة حالة صغيرة أو عرض قائمة.
+
+عند إضافة Chat Shell المضمن، يوفر إطار العمل خمس إدارة
+الأسطح التي لا يتعين عليك إنشاؤها: **الدردشة** (الإدخال الرئيسي)، **مساحة العمل**
+(skills، الذاكرة، التعليمات، الوكلاء الفرعيون، خوادم MCP المتصلة، مجدولة
+الوظائف)، **سجل الوظائف**، **سجل سلسلة المحادثات**، و **الإعدادات**. تلك عادة
+كافي — تحدث معه، وشاهد ما تم إنجازه، وقم بتكوين كيفية تصرفه. الوصول إلى
+[Chat](/docs/template-chat) عندما تكون مستعدًا لإضافة هذا المتصفح UI، أو
+[Dispatch template](/docs/template-dispatch) لبدء نمط مساحة العمل
+أشر باستخدام Slack/Telegram والمهام المجدولة والأسرار المشتركة خارج الصندوق.
+
+أصغر مسار محلي هو سقالة وكيل مقطوعة الرأس بالإضافة إلى إجراء واحد:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+ثم حدد العملية الدائمة:
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+يمكن بعد ذلك استدعاء إجراء واحد كـ:
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **وكيل التطبيق CLI** — `pnpm agent "Summarize form_123"`
+- **MCP** — من Claude، وChatGPT، وCodex، وCursor، وOpenCode، وCopilot، ومضيفي MCP الآخرين
+- **A2A** — من تطبيق وكيل آخر أو نظير وكيل
+- **UI** — من خلال `useActionQuery` أو `useActionMutation` أو `callAction`
+- **أداة الوكيل** — من حلقة الدردشة المضمنة
+
+```an-api title="Calling an action over HTTP"
+{
+  "method": "POST",
+  "path": "/_agent-native/actions/summarize-week",
+  "summary": "Invoke any action by name over HTTP",
+  "description": "Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes.",
+  "request": {
+    "contentType": "application/json",
+    "example": "{ \"formId\": \"form_123\" }"
+  },
+  "responses": [
+    { "status": "200", "description": "The action's return value as JSON", "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }" },
+    { "status": "400", "description": "Input failed schema validation" }
+  ]
+}
+```
+
+هذا ليس وضعًا بلا قاعدة بيانات أو عديم الحالة. تقوم حلقة وكيل التطبيق بتخزين الجلسات
+سلاسل المحادثات، وعمليات التشغيل، والإعدادات، وبيانات الاعتماد، وحالة التطبيق، ومشاركة السجلات في
+زكسق0قكسز. التطوير المحلي الافتراضي هو SQLite؛ يجب أن تستخدم التطبيقات مقطوعة الرأس المستضافة
+قاعدة بيانات SQL المستمرة.
+
+إذا كنت بحاجة إلى تكرار حلقة الوكيل بالكامل من مجلد المشروع، فاستخدم:
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+إذا احتاج تطبيق أو برنامج نصي آخر إلى استدعاء الوكيل بالكامل، فاستخدم
+`agentNative.invoke("analytics", "...")` أو `agent-native invoke` CLI. ذلك
+يحتفظ بالعمل عبر التطبيقات على مسار A2A بينما يظل العمل المحلي على actions.
+
+يمكن للعمال والوظائف والتكامل webhooks والمضيفين المخصصين قيادة حلقة الوكيل
+مباشرة من خلال الخادم API. وهذا مستوى أقل من actions — الذي تقدمه
+المحرك والنموذج والرسائل وactions ومخزن الحدث بنفسك:
+
+```ts
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
+```
+
+بالنسبة لمعظم التطبيقات، تستدعي المطالبات المجدولة والتكامل webhooks هذه الحلقة بالفعل
+لك. يمكنك الوصول إليه مباشرةً فقط عند إنشاء مضيف مخصص بدون رأس، بالتقييم
+المشغل، أو سطح التنسيق من جانب الخادم - راجع [الخادم - وكيل الإنتاج
+المعالج](/docs/server#agent-handler) للتوقيع الكامل.
+
+### التشغيل ضد مجلد {#folder-loop}
+
+إذا كان هدفك هو "تشغيل وكيل ضد هذا المجلد"، فابدأ بوكيل التطبيق
+قم بالتكرار في هذا المجلد: قم بتركيب التطبيق بدون رأس، وأضف actions/التعليمات، وقم بتشغيل
+`pnpm agent "..."`. وهذا يبقي العمل داخل نفس الإجراء/وقت التشغيل/الحالة
+العقد الذي سيستخدمه التطبيق في الإنتاج.
+
+تعد أدوات الترميز الخارجية بمثابة سطح منتج منفصل لتضمين Claude
+الرمز أو Codex أو Pi أو Cursor أو Mastra أو أوقات التشغيل المماثلة داخل تطبيق Agent-Native.
+استخدمها عند إنشاء منتج وكيل ترميز، وليس كطريقة افتراضية
+ابدأ سير عمل الوكيل المحلي الأصلي.
+
+### الوصول إلى الريبو السحابي {#cloud-repo-access}
+
+بالنسبة للتطبيقات السحابية بدون رأس والتي تحتاج إلى الوصول إلى المستودع، استخدم موصل GitHub
+نموذج الرمز المميز CRUD: سرد المستودعات أو البحث في الملفات أو قراءة الملفات أو إنشاءها أو
+تحرير الملفات، وحذف الملفات، وإبطال الوصول من خلال نطاق الموفر
+بيانات الاعتماد. في التطوير المحلي، قم بتعيين المستودع المستهدف بشكل صريح:
+
+```bash
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+```
+
+لا تعامل استنساخ VM أو الخروج المعزول طويل الأمد باعتباره السحابة الأساسية
+نموذج الوصول إلى الريبو. لا تزال صناديق الحماية مهمة لتنفيذ التعليمات البرمجية المعزولة، ولكن
+يجب أن يكون الوصول إلى المستودع صريحًا ومرخصًا وقابلاً للتدقيق وقابلاً للإلغاء
+من خلال طبقة الموصل.
+
+### مشاركة الجلسات والتشغيل {#sharing-runs}
+
+الجلسات والجري بدون رأس هي أشياء متينة. يجب أن تتم إمكانية المشاركة على مراحل:
+قراءة/مشاركة الروابط أولاً، حتى يتمكن أعضاء الفريق من فحص المطالبات والمخرجات المعقمة
+وحالة التشغيل؛ يُسمح بالتعاون القابل للكتابة لاحقًا، لذا استمر في التشغيل،
+الموافقة على actions أو تعديل الجداول الزمنية أو تغيير التكوين
+فحوصات الوصول الصريحة.
+
+## دردشة غنية على Agent-Native {#rich-chat}
+
+استخدم الدردشة المضمنة عندما يتعين على المستخدم التحدث إلى الوكيل، راجع استدعاءات الأداة،
+الموافقة على العمل، وفحص النتائج الأصلية، والاحتفاظ بسجل سلاسل المحادثات الدائم.
+
+للحصول على نقطة بداية كاملة للتطبيق، استخدم [Chat template](/docs/template-chat):
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
+أبسط دردشة بصفحة كاملة:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+عندما يحتوي التطبيق على علامة تبويب دردشة بملء الصفحة و`AgentSidebar`، استخدم نفس الشيء
+`storageKey` على كلا السطحين، قم بتمكين `chatViewTransition`، ثم قم بتثبيت
+مساعدو تسليم الدردشة الرئيسية في التخطيط. روابط عادية داخل التطبيق خارج الدردشة
+بعد ذلك تحويل الدردشة الكاملة إلى الشريط الجانبي مع الحفاظ على نشاطها
+الخيط:
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
+أبسط دردشة مضمنة مع الكروم الخاص بك:
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+يمكن لـ Actions عرض نتائج عناصر واجهة مستخدم أصلية صريحة، لذا لا يقتصر الأمر على إخراج الدردشة
+نص. يتم عرض الجداول والمخططات وبطاقات المنتجات المكتوبة كـ React للطرف الأول
+مكونات في الدردشة، بدون إطارات iframe. انظر [Native Chat UI](/docs/native-chat-ui).
+
+## دردشة غنية مع وكيلك {#byo-agent}
+
+استخدم هذا المسار عندما يكون وكيلك مبنيًا بالفعل باستخدام إطار عمل آخر أو
+وقت التشغيل وتريد دردشة Agent-Native UI حوله. `AgentChatRuntime` هو
+الحدود: يقوم وقت التشغيل الخاص بك ببث الأحداث الطبيعية، ويعرض Agent-Native
+الملحن والنص واستدعاءات الأدوات والموافقات والأدوات الأصلية وتخطيط التطبيق.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/support-agent/chat",
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+توجد مساعدات وقت التشغيل الجاهزة لوكلاء OpenAI واستجابات OpenAI وClaude
+الوكيل SDK، وVercel AI SDK، وAG-UI، بالإضافة إلى وقت تشغيل HTTP الذي تمت تسويته أعلاه
+لأي وكيل آخر (Mastra، أو Flue، أو Eve، أو LangGraph، أو خدمة مخصصة). ACP هو
+ليست دردشة تطبيق المستخدم النهائي أو نقل A2A، ولا Agent-Native حاليًا
+المطالبة بدعم A2UI. يتم دعم ACP في مكان واحد محدد - قيادة سيارة محلية
+وكيل الترميز (Gemini CLI، Claude Code، ...) من خلال
+[harness layer](/docs/harness-agents#acp)، وليس وقت تشغيل الدردشة هنا.
+
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+هو الموطن الأساسي لأشكال الأحداث، ومساعدي وقت التشغيل، و`chatUI`
+البيانات التعريفية لنتيجة الأداة. ابدأ من هنا عند توصيل وكيل خارجي بالدردشة.
+
+## عربة جانبية مضمنة {#embedded-sidecar}
+
+استخدم العربة الجانبية المضمنة عندما يكون المنتج الرئيسي موجودًا بالفعل وتريد
+الوكيل بجانبه.
+
+يقوم المكون الإضافي للخادم بتوصيل مسارات Agent-Native إلى تطبيقك المضيف ويحلها
+جانب خادم هوية المضيف:
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+يقوم الجانب React بتمرير سياق الصفحة وأوامر المضيف:
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+```an-diagram title="How the sidecar bridges to a host app" summary="The plugin mounts Agent-Native routes server-side; the React sidecar streams page context in and host commands out."
+{
+  "html": "<div class=\"diagram-sidecar\"><div class=\"diagram-panel\"><strong>Host app</strong><small class=\"diagram-muted\">your existing SaaS</small><div class=\"diagram-node\">getContext()<br><small class=\"diagram-muted\">route · selection</small></div><div class=\"diagram-node\">onNavigate / onRefresh<br><small class=\"diagram-muted\">host commands</small></div></div><div class=\"diagram-col-arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div></div><div class=\"diagram-panel accent-panel\"><span class=\"diagram-pill accent\">AgentNativeEmbedded</span><small class=\"diagram-muted\">agent + workspace</small><div class=\"diagram-box\" data-rough>Agent-Native routes<br><small class=\"diagram-muted\">mounted by the server plugin</small></div></div></div>",
+  "css": ".diagram-sidecar{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sidecar .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:200px}.diagram-sidecar .diagram-col-arrows{display:flex;flex-direction:column;gap:6px}.diagram-sidecar .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+راجع [Embedding SDK](/docs/embedding-sdk) للتعرف على مصادقة المضيف وعزل قاعدة البيانات
+وضع iframe/المنتقي وجسر المستوى الأدنى API.
+
+## التطبيق الكامل {#full-application}
+
+استخدم مسار التطبيق الكامل عندما يحتاج المستخدمون إلى كائنات ومهام سير عمل متينة: النماذج،
+لوحات التحكم، أو التقويمات، أو صناديق البريد الوارد، أو برامج التحرير، أو المستندات، أو الأصول، أو التقارير.
+
+تضيف التطبيقات الكاملة المنتج UI حول نفس الإجراء وعقد الوكيل:
+
+- **حالة SQL** — بيانات التطبيق، والتنقل، والإعدادات، وسجل الدردشة دائمة.
+- **الوعي بالسياق** — يعرف الوكيل المسار الحالي والتحديد والكائن الذي يتم التركيز عليه.
+- **المزامنة المباشرة** — تعمل تغييرات الوكيل على تحديث UI، كما تعمل تغييرات UI على تحديث سياق الوكيل.
+- **روابط لمواضع معينة** — يمكن لنتائج الإجراء فتح عرض التطبيق المناسب.
+- **أدوات الدردشة الأصلية** — تظهر الجداول والمخططات والبطاقات والموافقات والنتائج المكتوبة مضمنة.
+
+ابدأ من [Chat template](/docs/template-chat) عندما تريد تطبيقًا بسيطًا
+حول actions، أو من النطاق [template](/docs/cloneable-saas) عندما
+تريد شكلًا كاملاً للمنتج.
+
+## كيفية الاختيار {#how-to-choose}
+
+| إذا كنت تفكر...                                                  | اختر                        |
+| ---------------------------------------------------------------- | --------------------------- |
+| "أحتاج فقط إلى أداة قابلة للاستدعاء أو سير عمل."                 | عميل مقطوع الرأس            |
+| "أريد وكيل إطار العمل، ولكن يجب أن تكون الدردشة هي UI الرئيسية." | دردشة غنية على Agent-Native |
+| "لدي وكيل بالفعل؛ وأحتاج إلى دردشة مصقولة UI من أجل ذلك."        | دردشة غنية مع وكيلك         |
+| "لدي بالفعل تطبيق SaaS؛ أضف وكيلًا بجانبه."                      | عربة جانبية مضمنة           |
+| "يجب أن يتطور الوكيل وUI معًا ليكونا المنتج."                    | التطبيق الكامل              |
+
+اجعل العقد صغيرًا: حدد العمليات الدائمة كـ actions، وإرجاع صريح
+نتائج الأدوات عندما تحتاج الدردشة إلى UI، وإضافة شاشات كاملة فقط عند المستخدمين
+تحتاج إلى تصفح الكائنات الثابتة أو مقارنتها أو تكوينها أو التعاون عليها.
+
+## المستندات ذات الصلة {#related-docs}
+
+- [Actions](/docs/actions) — حدد عملية مقطوعة الرأس مرة واحدة.
+- [Native Chat UI](/docs/native-chat-ui) — عرض نتائج الإجراءات المكتوبة في الدردشة.
+- [Drop-in Agent](/docs/drop-in-agent) — قم بتثبيت الدردشة أو الشريط الجانبي أو أسطح اللوحات.
+- [Component API](/docs/components) — مقطوعات الدردشة/الملحن React ذات المستوى الأدنى.
+- [Embedding SDK](/docs/embedding-sdk) — أضف Agent-Native إلى تطبيق موجود.
+- [External Agents](/docs/external-agents) — توصيل الأجهزة المضيفة المتوافقة مع MCP بأحد التطبيقات.
+- [A2A Protocol](/docs/a2a-protocol) — استدعاء الوكلاء من الوكلاء الآخرين.