BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/agent-surfaces.mdx
View on GitHub---
title: "واجهات الوكيل"
description: "اختر كيف ينمو تطبيق الوكيل من المحادثة إلى واجهة المستخدم المضمّنة، وصفحات التطبيق الدائمة، والشرائط الجانبية المضمّنة، والأتمتة، والوصول الخارجي للوكيل."
search: "تطبيق وكيل محادثة غنية واجهة مستخدم محادثة أصلية تطبيق كامل أتمتة بلا رأس وكيل BYO وقت تشغيل AgentChatRuntime تضمين إجراءات MCP A2A HTTP CLI"
---
# واجهات الوكيل
**الواجهة** هي الطريقة التي يتفاعل بها المستخدمون (أو الأنظمة الأخرى) مع تطبيقك: نافذة محادثة، أو صفحة لوحة تحكم، أو مهمة تعمل في الخلفية، أو استدعاء API من وكيل آخر. يتيح لك Agent-Native دمج هذه الواجهات وتنسيقها دون إعادة بناء منطقك الأساسي، لأن كل واجهة تُشغّل نفس الإجراءات الأساسية. إذا كنت جديدًا على Agent-Native، اقرأ [المفاهيم الأساسية](/docs/key-concepts) أولاً.
## كيف ترتبط الواجهات ببعضها
تقع الأشكال الأربعة الرئيسية للمنتج على طيف يمتد من الأكثر تفاعلاً إلى الأكثر تجريدًا. ما يجعلها قابلة للتركيب هو أنها تشترك في نفس الإجراءات وحالة التطبيق المدعومة بـ SQL. استخدم حلقة الوكيل عندما تحتاج الواجهة إلى وكيل. إضافة واجهة جديدة لا تعني إعادة كتابة ما هو موجود — بل تضيف فقط طريقة جديدة للوصول إلى نفس العمليات.
<Diagram id="doc-block-hvdxgh" title="طيف الواجهات" summary={"سطح إجراء واحد، أربعة أشكال للمنتج، كل منها يضيف واجهة مستخدم دون تغيير العملية الأساسية."}>
```html
<div class="diagram-spectrum">
<div class="diagram-card">
<strong>محادثة</strong
><small class="diagram-muted">محرر، سجل، استدعاءات الأدوات</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<strong>واجهة مستخدم مضمّنة</strong
><small class="diagram-muted">جداول، مخططات، بطاقات</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<strong>صفحة التطبيق</strong
><small class="diagram-muted">شاشات دائمة، بيانات SQL</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card accent-card">
<span class="diagram-pill accent">headless</span><strong>أتمتة</strong
><small class="diagram-muted">مهام، نصوص برمجية، وكلاء خارجيون</small>
</div>
</div>
<div class="diagram-base" data-rough>
<span class="diagram-muted"
>نفس الإجراءات · حالة مدعومة بـ SQL · حلقة الوكيل عند الحاجة</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;
}
```
</Diagram>
## اختر نقطة البداية
المحادثة هي نقطة الدخول الأكثر شيوعًا. تنمو التطبيقات عادةً لتضم واجهة مستخدم مضمّنة مع ازدياد ثراء المخرجات، ثم تُضاف صفحات تطبيق كاملة عندما يحتاج المستخدمون إلى كائنات دائمة للتصفح والمشاركة. نفس الإجراءات تشغّل الأزرار والمهام المجدولة والوكلاء الخارجيين التي تأتي لاحقًا. استخدم الشريط الجانبي المضمّن عند إضافة وكيل إلى منتج تمتلكه بالفعل، أو الأتمتة أولاً للعمل الذي يعمل بدون متصفح. إليك الصورة الكاملة:
| الواجهة | استخدمها عندما | ابدأ بـ |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **[محادثة غنية](#rich-chat)** | يتحدث المستخدمون مع الوكيل، ويرون استدعاءات الأدوات، ويحتفظون بسجل الخيط. | [قالب المحادثة](/docs/template-chat)، `<AgentChatSurface>` |
| **[واجهة مستخدم مضمّنة أصلية](#native-inline-ui)** | يجب أن تُعرض نتائج الإجراءات كجداول أو مخططات أو بطاقات أو موافقات في المحادثة. | [واجهة المحادثة الأصلية](/docs/native-chat-ui)، `chatUI.renderer` |
| **[واجهة مستخدم مضمّنة مولَّدة](#generated-inline-ui)** | يجب أن يُنشئ الوكيل عناصر تحكم مؤقتة أو قابلة لإعادة الاستخدام داخل المحادثة أثناء التشغيل. | [واجهة مستخدم توليدية](/docs/generative-ui)، `render-inline-extension` |
| **[تطبيق كامل](#full-application)** | يحتاج المستخدمون إلى شاشات دائمة وبيانات مشتركة وتنقل وتعاون. | القوالب، الإجراءات، حالة SQL، الوعي بالسياق |
| **[شريط جانبي مضمّن](#embedded-sidecar)** | لديك تطبيق SaaS بالفعل وتريد وكيلاً بجانبه مع سياق الصفحة. | `createAgentNativeEmbeddedPlugin()`، `AgentNativeEmbedded` |
| **[الأتمتة أولاً](#headless)** | تستدعي المهام أو النصوص أو الوكلاء الآخرون العمل مباشرة بدون واجهة متصفح. | `agent-native create --headless`، `defineAction`، HTTP، CLI، MCP، A2A |
| **[محادثة غنية على وكيلك](#byo-agent)** | لقد بنيت الوكيل في مكان آخر وتريد واجهة محادثة Agent-Native حوله. | `AgentChatRuntime`، `<AssistantChat runtime={runtime}>` |
## محادثة غنية على Agent-Native {#rich-chat}
استخدم المحادثة المدمجة عندما يجب أن يتحدث المستخدم مع الوكيل، ويرى استدعاءات الأدوات،
ويوافق على العمل، ويفحص النتائج الأصلية، ويحتفظ بسجل خيط دائم.
لنقطة بداية تطبيق كاملة، استخدم [قالب المحادثة](/docs/template-chat):
```bash
npx --yes @agent-native/core@latest create my-chat-app --template chat
```
أبسط محادثة على صفحة كاملة:
```tsx
import { AgentChatSurface } from "@agent-native/toolkit/app/chat";
export default function ChatRoute() {
return <AgentChatSurface mode="page" className="h-screen" />;
}
```
عندما يحتوي التطبيق على تبويب محادثة بصفحة كاملة و`AgentSidebar`، استخدم نفس
`storageKey` على كلتا الواجهتين، وفعّل `chatViewTransition`، وثبّت
مساعدي التسليم لصفحة المحادثة الرئيسية في التخطيط. يمكن للروابط العادية داخل التطبيق الخارجة من صفحة المحادثة
أن تحوّل المحادثة الكاملة إلى الشريط الجانبي مع الحفاظ على الخيط النشط:
```tsx
import { AgentChatSurface, AgentSidebar } from "@agent-native/toolkit/app/chat";
import {
useAgentChatHomeHandoff,
useAgentChatHomeHandoffLinks,
} from "@agent-native/core/client/agent-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/toolkit/app/chat";
export function ProjectChat({ threadId }: { threadId: string }) {
return <AssistantChat threadId={threadId} />;
}
```
يمكن للإجراءات إرجاع نتائج عناصر واجهة أصلية صريحة بحيث لا يكون مخرج المحادثة مجرد
نص. تُعرض الجداول والمخططات وبطاقات المنتج المكتوبة كمكونات React من الدرجة الأولى
في المحادثة، بدون iframes. انظر [واجهة المحادثة الأصلية](/docs/native-chat-ui).
عندما يحتاج الوكيل إلى عناصر تحكم مولَّدة عشوائية بدلاً من عنصر واجهة
React محدد مسبقًا، استخدم [واجهة المستخدم التوليدية](/docs/generative-ui): تُعرض واجهة
Alpine/Tailwind المحمية مضمّنةً، ويمكنها قراءة حالة التطبيق وسياق الفتحة، وإرسال
القيم المحددة مرة أخرى إلى المحادثة.
### واجهات إجراءات على مستوى الطلب
استخدم `resolveActionSurface` عندما يجب أن يعرض الوكيل أو سلسلة المحادثة
المحددة مجموعة فرعية فقط من الإجراءات الأصلية التي اعتمدها الخادم. يُشغّل
الاستدعاء لكل طلب محادثة تفاعلي بعد `prepareRequest`. تشكّل الأسماء المعادة
قائمة سماح صارمة: لا تظهر الإجراءات المحذوفة في مخططات المزوّد أو سجل التنفيذ
أو التحميل المسبق لوضع Plan أو نتائج بحث `tool-search`.
```ts
createAgentChatPlugin({
actions,
nativeActionsInDev: true,
resolveActionSurface: async ({ threadId, availableActionNames }) => ({
allowedActionNames: await loadAllowedActions(
threadId,
availableActionNames,
),
}),
});
```
إذا كان المحلّل نفسه يتعامل أيضاً مع المحادثة الافتراضية غير المقيّدة، فأعد
`{ mode: "default" }`. يحافظ ذلك على التصفية المعتادة عبر
`initialToolNames` والاكتشاف باستخدام `tool-search` بدلاً من تحميل كل المخططات
المتاحة في أول طلب للنموذج. ويستمر هذا الوضع الصريح عبر عمليات المتابعة الدائمة.
لا تعرض القائمة الفارغة أي إجراءات أصلية. تؤدي الأسماء غير المعروفة إلى فشل
الطلب بدلاً من توسيع الوصول. تُحمّل جميع الإجراءات المسموح بها مباشرة في أول
طلب للنموذج؛ أضف `tool-search` صراحةً فقط للبحث داخل الفهرس المعتمد مسبقاً.
يقيّد الاستدعاء محادثة الوكيل التفاعلية فقط ولا يغيّر HTTP أو MCP أو A2A أو
المهام أو المشغلات. ترث إرشادات الإطار الافتراضية والوكلاء الفرعيون المشغّلون
السطح نفسه. تُخفّض أدوات shell الموثوقة تلقائياً إلى sandbox المصفّى حسب الطلب،
لأن shell غير المقيّد لا يمكنه فرض حد صارم للإجراءات.
### إجراءات إضافية على مستوى الطلب
استخدم `resolveAdditionalActions` عندما لا تُعرف الإجراءات التي يمكن للمستدعي
استخدامها إلا وقت الطلب، مثل الأدوات التي يسجّلها المستخدم أثناء تشغيل الخادم.
يعمل الاستدعاء مرة واحدة لكل تشغيل محادثة تفاعلي موثَّق (في الإنتاج والتطوير)،
قبل `tool-search` و`resolveActionSurface`، فيرى كلاهما المدخلات المُرجَعة. وتنضم
هذه المدخلات إلى سجل ذلك المستدعي لهذا التشغيل فقط. أما مهام A2A واستدعاءات
`ask_app` في MCP فلا تتلقاها إلا إذا ذكرت هذه الواجهات في
`additionalActionSurfaces`؛ ويخبر `surface` الاستدعاء بالواجهة التي تطلبها.
```ts
createAgentChatPlugin({
actions,
additionalActionSurfaces: ["a2a"],
resolveAdditionalActions: async ({ surface, ownerEmail, orgId }) =>
loadUserTools(ownerEmail, orgId, {
includeEditorTools: surface === "chat",
}),
});
```
تعامل مع المدخلات المُرجَعة على أنها مدخلات غير موثوقة. يتجاهل الإطار المدخل
ويسجّل تحذيرًا مرة واحدة عندما لا يكون اسمه من 1 إلى 64 حرفًا أو رقمًا أو `_` أو
`-`؛ أو عندما ينتمي الاسم إلى أي إجراء من القالب أو الإطار أو التطوير أو MCP،
بما في ذلك الإجراءات المخفية عن الوكيل؛ أو عندما يكون اسمًا يبدأ بـ `mcp__` لا
يستطيع المستدعي رؤيته؛ أو عندما يكون تعريف أداته غير صالح للاستخدام. تُزال من
الأوصاف محارف التحكم المخفية ويُحدَّد طولها. يجب أن تكون `parameters` مخططًا
محدود الحجم لبيانات JSON عادية جذره `object`، ولا يستخدم إلا كلمات التحقق والتوصيف
الشائعة. تُرفض الكلمات المفتاحية غير المعروفة و`pattern` و`patternProperties`
و`uniqueItems` و`$async` و`$id` والمراسي وأي `$ref` تكراري أو يشير إلى خارج
المخطط. يرى النموذج النسخة المُتحقَّق منها من المخطط، ويُرفض أي استدعاء تكون
وسيطاته أكبر من أن يُتحقَّق منها مقابله. العلامات مثل `readOnly`
و`access` هي تصريحات تطبيقك الخاصة، ويثق بها الإطار كما يثق بـ `run`: اضبطها
بناءً على ما يفعله الكود الخاص بك، ولا تضبطها أبدًا من بيانات وصفية سجّلها مستخدم.
يرتبط كل مدخل بالمستدعي الذي حُلّ من أجله. يرفض كل استدعاء، أيًّا كان المُرسِل
الذي ينفّذه، العمل لمستخدم أو مؤسسة مختلفة، ويفرض سياسة `access` الخاصة بالمدخل،
ويتحقق من الوسائط وفق مخططه دون تحويل للأنواع.
لا تُثبَّت الأسماء إلا عندما يستمر دور محادثة مستضافة كتشغيل خلفي دائم. يعمل
الاستدعاء مرة أخرى، ويحتفظ الدور بأسمائه الأصلية لهذه المدخلات ولأدوات MCP
الخاصة بالمستدعي على حد سواء: تبقى المدخلات الجديدة خارجه، ويُرجع الاسم الذي
اختفى خطأً عند استدعائه، ويُشغّل الاسم الذي بقي تعريفه الحالي. وكل طلب آخر يُحَلّ
من جديد، بما في ذلك كل استمرار على شريط جانبي محلي، أما البث المنقطع الذي يعاود
الارتباط بتشغيله فلا يُحَلّ له شيء.
ضع هوية الربط في الاسم، مثل معرّف نافذة أو نطاق (`notes_window_42_insert`)، حتى
تبدو إعادة الربط كأداة تغادر وأخرى تظهر. تتبع موافقات "السماح دائمًا" اسم الأداة،
لذا تنتقل معه حين يصبح الاسم نفسه لاحقًا دالًّا على شيء جديد.
اضبط `revision` على مدخل لمنع ذلك: تسجّل الموافقات لمرة واحدة و"السماح دائمًا"
المراجعة التي مُنحت من أجلها، وتؤدي مراجعة مختلفة إلى سؤال المستخدم مرة أخرى.
ينبغي لمعالج "السماح دائمًا" المخصص أن يمرّر `askId` الخاص بالموافقة إلى
`set-tool-approval-policy` على أنه `approvalId`؛ وبدونه يقتصر المنح على المداخل
التي ليس لها مراجعة.
يفشل استدعاء أداة استخدمتها المحادثة أو حمّلتها سابقًا لكن لم تعد متاحة في هذا
التشغيل بالخطأ `Error: Tool no longer available` بدلًا من `Unknown tool`،
وتُخبر عملية التشغيل التي تبدأ بعد اختفاء أدوات محمّلة النموذج بأيّها اختفى.
وإذا كان المستخدم قد وافق على ذلك الاستدعاء، يتوقف التشغيل بدلًا من ترك النموذج
يواصل بدونه. وفي المحادثة يتلقى الاستدعاء أيضًا `threadId` و`requestedTurnId`
و`internalContinuation`، فيستطيع التطبيق الذي يريد مجموعة أدوات واحدة طوال الدور
أن يحتفظ بلقطته الخاصة.
هذه المدخلات أدوات أصلية لحلقة الوكيل فقط. وعلى غرار أدوات MCP الخاصة بالمستدعي،
لا يمكن الوصول إليها من `run-code` أو `tool-orchestration`.
يُضبط `event` في `chat` و`a2a`؛ ولا يوجد في استدعاءات `ask_app`. لا يُستدعى
الاستدعاء للطلبات المجهولة أو المهام المجدولة أو الأتمتة أو الوكلاء الفرعيين
لفريق الوكلاء. وأي خطأ يطلقه الاستدعاء يُفشل الطلب.
## واجهة مستخدم مضمّنة أصلية {#native-inline-ui}
استخدم هذا عندما تُرجع إجراءاتك بيانات منظمة — قائمة سجلات، أو مجموعة بيانات مخطط، أو ملخص حالة — يجب أن تُعرض كمكوّن واجهة مستخدم حقيقي داخل خيط المحادثة بدلاً من وصف نصي بسيط. تُعرّف مُصيِّر `chatUI` على الإجراء، ويُعرضه Agent-Native كمكوّن React من الدرجة الأولى: بدون iframes، بدون مسار عرض منفصل.
هذا هو الخيار الصحيح عندما يكون للمخرج شكل واضح وقابل لإعادة الاستخدام يمكنك تصميمه مرة واحدة واستخدامه عبر ردود الوكيل المتعددة. للعناصر التي يحتاج الوكيل إلى إنشائها ديناميكيًا أثناء التشغيل، انظر [واجهة مستخدم مضمّنة مولَّدة](#generated-inline-ui) بدلاً من ذلك.
انظر [واجهة المحادثة الأصلية](/docs/native-chat-ui) للاطلاع على واجهة API الكاملة للمُصيِّر، ومكتبة العناصر، وتكامل وقت تشغيل وكيل BYO.
## واجهة مستخدم مضمّنة مولَّدة {#generated-inline-ui}
استخدم هذا عندما يحتاج الوكيل إلى إنشاء عنصر تحكم غير موجود بعد كعنصر واجهة مبني مسبقًا — نموذج مخصص، أو أداة انتقاء مبنية حول السياق الحالي، أو آلة حاسبة لمرة واحدة. على عكس العناصر الأصلية، تُركَّب واجهة المستخدم المولَّدة من قِبل الوكيل أثناء التشغيل من Alpine.js وTailwind، وتعمل محمية في iframe، ويمكنها إرسال القيم المحددة مرة أخرى إلى خيط المحادثة.
يمكن أن تكون واجهة المستخدم المولَّدة عابرة (تُعرض مرة واحدة وتُهمل) أو محفوظة كامتداد قابل لإعادة الاستخدام يستمر للمستخدم.
انظر [واجهة المستخدم التوليدية](/docs/generative-ui) للاطلاع على واجهة API الكاملة، وقيود الحماية، ونموذج استمرارية الامتداد.
## تطبيق كامل {#full-application}
استخدم مسار التطبيق الكامل عندما يحتاج المستخدمون إلى كائنات وسير عمل دائمة: نماذج،
ولوحات تحكم، وتقاويم، وصناديق وارد، ومحررات، ومستندات، وأصول، أو تقارير.
تضيف التطبيقات الكاملة واجهة مستخدم للمنتج حول نفس عقد الإجراءات والوكيل:
<Cards>
### حالة SQL
بيانات التطبيق والتنقل والإعدادات وسجل المحادثة محفوظة بشكل دائم في SQL. يقرأ الوكيل ويكتب نفس الصفوف التي تفعلها واجهة المستخدم.
### الوعي بالسياق
يعرف الوكيل المسار الحالي والاختيار والكائن المركّز، لذا فإن "تعديل هذا" يعني دائمًا الشيء الصحيح.
### المزامنة الحية
تُحدّث تغييرات الوكيل واجهة المستخدم عبر المزامنة الحية، وتُحدّث تغييرات واجهة المستخدم سياق الوكيل. يستخدم الإطار SSE مع استطلاع احتياطي، لذلك لا يحتاج المستخدمون إلى التحديث يدوياً.
### الروابط العميقة
يمكن لنتائج الإجراءات فتح العرض الصحيح للتطبيق مباشرة: يرتبط المخطط بلوحة التحكم، ويرتبط المسودة بصندوق الوارد.
### عناصر المحادثة الأصلية
تُعرض الجداول والمخططات والبطاقات والموافقات والنتائج المكتوبة كمكونات React من الدرجة الأولى مضمّنةً في المحادثة.
### واجهة مستخدم توليدية وامتدادات
يمكن للوكيل إنشاء عناصر تحكم مضمّنة أثناء التشغيل، وحفظ تطبيقات مصغّرة قابلة لإعادة الاستخدام عندما يحتاج سير العمل إلى الاستمرار.
</Cards>
ابدأ من [قالب المحادثة](/docs/template-chat) عندما تريد تطبيقًا بسيطًا
حول إجراءاتك، أو من [قالب](/docs/cloneable-saas) نطاق معين عندما تريد
شكل منتج كاملاً.
### إدارة الوكيل بصفحة كاملة {#agent-page}
كل تطبيق Agent-Native يحتاج في نهاية المطاف إلى مكان يمكن للمستخدمين من خلاله تهيئة وكيلهم: وضع تعليمات دائمة، ومراجعة ما قام به، وتوصيل خوادم MCP، وإدارة الأتمتة، والتحكم في الوصول. بناء هذه الواجهة من الصفر يستلزم الكثير من العمل. يُشحن Agent-Native مع مكوّن بصفحة كاملة مبني مسبقًا، `AgentTabsPage`، يغطي كل ذلك عبر اثني عشر تبويبًا.
لا تثبّته القوالب الرسمية: تغطي الإعدادات الجوانب نفسها (Agent › Model وInstructions وMemory وSkills وFiles وSub-agents، إضافة إلى صفحتي Automations وMCP server الخاصتين بالتطبيق)، ويعيد `/agent` التوجيه إلى الإعدادات، ويفتح `agentPageHref="/settings/agent"` في `AgentSidebar` صفحة Settings › Agent › Model. ثبّت `AgentTabsPage` على مسار خاص به عندما يريد التطبيق عرض واجهة الوكيل كاملة في صفحة واحدة.
```tsx filename="app/routes/agent.tsx"
import { AgentTabsPage } from "@agent-native/toolkit/app/agent-page";
export default function AgentRoute() {
return <AgentTabsPage />;
}
```
توفر الصفحة المشتركة حاليًا اثني عشر تبويبًا عبر مجموعتين:
| المجموعة | التبويب | يعرض |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| الموارد | **Files** | لوحة `ResourcesPanel` الحالية للملفات الشخصية أو التنظيمية |
| الموارد | **Instructions** | قواعد دائمة التشغيل بأسلوب AGENTS.md |
| الموارد | **Agents** | ملفات تعريف الوكلاء الفرعيين المخصصة |
| الموارد | **Memory** | ملاحظات الاستدعاء طويل الأمد |
| الموارد | **Skills** | سير عمل قابلة لإعادة الاستخدام |
| الموارد | **Learnings** | التصحيحات والأنماط المُلتقطة بمرور الوقت |
| الموارد | **Remote agents** | اتصالات A2A بتطبيقات agent-native الأخرى (يحل محل ما كان يعرضه تبويب Connections سابقًا) |
| الوكيل | **Snapshots** | معاينة نطاق، وميزانية رموز، وأقسام نظام مرتبة مجمّعة حسب المصدر/الحوكمة/المرجع، وأحدث لقطة خيط حي. تمت إعادة تسميتها من "Context"؛ تُعيد روابط `#context` القديمة التوجيه إلى هنا. |
| الوكيل | **Connections** | إدارة خادم MCP فقط |
| الوكيل | **Automations** | أتمتة مجدولة/أحداث شخصية وتنظيمية مع تدفقات إيقاف مؤقت/استئناف وتفاصيل وحذف. يبقى عنوان URL للتوافق الثابت `/agent#jobs`. |
| الوكيل | **Settings** | نموذج الوكيل، ومفاتيح API، والحدود، والصوت، وإعدادات الأتمتة |
| الوكيل | **MCP** | عنوان URL لـ MCP للتطبيق، وبطاقة وكيل A2A عند الإتاحة، وأدلة الإعداد المشتركة لـ Claude وChatGPT وCursor وClaude Code وCodex وعملاء آخرين. ابحث عنه في **Settings → MCP server** أو استخدم `/mcp/connect` لتدفق الاتصال الكامل واحتياطي الرمز المميز. |
تعرض الصفحة بيانات شخصية (نطاق `user`) فقط. لا يوجد تبديل على مستوى المؤسسة اليوم. إنها غلاف رقيق على المكونات والفحوصات الموجودة، وليست وحدة تحكم إدارية جديدة: يصف Connections ما يمكن للتطبيق استدعاؤه؛ يصف MCP كيفية اتصال العملاء الخارجيين به.
غير مدرج بعد:
- عرض على نطاق المؤسسة
- تحرير المنح والنطاق
- واجهة مستخدم الإلغاء
- سجل المصدر لكل تكرار
## الشريط الجانبي المضمّن {#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/host";
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>
);
}
```
### كيف يتصل
يعمل الجزءان كجسر: يمرر تطبيق المضيف سياق الصفحة (المسار الحالي، والنص المحدد، والكائن المركّز) إلى `AgentNativeEmbedded`، ويُرسل الوكيل الأوامر مرة أخرى من خلال `onNavigate` و`onRefresh`. يتعامل المكوّن الإضافي للخادم مع الهوية — يحل جلسة المضيف بحيث يتصرف الوكيل كمستخدم صحيح بدون تسجيل دخول منفصل. لا يحتاج أي شيء في تطبيق المضيف إلى التغيير؛ يُرفق المكوّن الإضافي مسارات Agent-Native بجانب المسارات الموجودة لديك.
<Diagram id="doc-block-27ug5y" title="كيف يربط الشريط الجانبي بتطبيق مضيف" summary={"يُثبّت المكوّن الإضافي مسارات Agent-Native من جانب الخادم؛ يبث الشريط الجانبي React سياق الصفحة للداخل وأوامر المضيف للخارج."}>
```html
<div class="diagram-sidecar">
<div class="diagram-panel">
<strong>تطبيق المضيف</strong
><small class="diagram-muted">تطبيق SaaS الحالي لديك</small>
<div class="diagram-node">
getContext()<br /><small class="diagram-muted">المسار · التحديد</small>
</div>
<div class="diagram-node">
onNavigate / onRefresh<br /><small class="diagram-muted"
>أوامر المضيف</small
>
</div>
</div>
<div class="diagram-col-arrows">
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">←</div>
</div>
<div class="diagram-panel accent-panel">
<span class="diagram-pill accent">AgentNativeEmbedded</span
><small class="diagram-muted">الوكيل + الموارد</small>
<div class="diagram-box" data-rough>
مسارات Agent-Native<br /><small class="diagram-muted"
>مُثبَّتة بواسطة المكوّن الإضافي للخادم</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;
}
```
</Diagram>
انظر [SDK التضمين](/docs/embedding-sdk) للاطلاع على مصادقة المضيف وعزل قاعدة البيانات
ووضع iframe/المنتقي وواجهات برمجة الجسر ذات المستوى الأدنى.
## تطبيق الأتمتة أولاً {#headless}
استخدم مسار الأتمتة أولاً عندما لا يحتاج أحد إلى شاشة متصفح مخصصة بينما
يعمل العمل: المهام المجدولة، والتكاملات، وسير العمل الخلفية، وحلقات CLI،
ووكيل آخر، أو منتج موجود يستدعي Agent-Native.
هذا هو الشكل الذي يجب اللجوء إليه عندما تكون الأتمتة هي واجهة المنتج. ترسل طلبًا من الطرفية، أو Slack، أو البريد الإلكتروني، أو مهمة مجدولة، أو وكيل آخر، أو محادثة ("لخّص رسائلي الإلكترونية غير المقروءة"، "انشر المقاييس اليومية على Slack"، "ابحث عن المرشحين الذين ردوا الأسبوع الماضي") ويتصرف الوكيل ويُرجع النتيجة إلى حيث تنتمي. إنه لا يزال تطبيقًا حقيقيًا، وليس موجهًا عديم الحالة:
تعيش الإجراءات وجلسات المصادقة وحالة التطبيق وسجل الخيط/التشغيل والإعدادات وبيانات الاعتماد
وسجلات المشاركة في SQL.
اختر هذا النمط عندما:
- **يحدث العمل في الخلفية.** تُنشأ معظم القيمة بينما لا ينظر المستخدم: وكلاء الفرز، ووكلاء التقارير اليومية، والمستجيبون للمناوبة.
- **يغادر المخرج التطبيق.** ينشر الوكيل على Slack، أو يرسل بريدًا إلكترونيًا، أو يحدّث نظامًا خارجيًا؛ لا يوجد شيء للتصفح داخل التطبيق.
- **النطاق لقطة واحدة.** روبوت بحث، أو مولّد ملخصات، أو كاتب تقارير بدون كائن دائم يحتاج إلى عرض قائمة.
- **أنت تنشئ نموذجًا أوليًا للأتمتة.** أشحن العملية الآن؛ أضف المحادثة أو صفحات التطبيق عندما يحتاج المستخدمون إلى فحصها وتوجيهها.
إذا كان منتجك مبنيًا حول كائنات دائمة يتصفح المستخدمون فيها ويتمحور حولها ويشاركونها (رسائل إلكترونية، أحداث، مستندات، مخططات)، اختر [تطبيقًا كاملاً](#full-application) أو [قالبًا](/docs/cloneable-saas) بدلاً من ذلك؛ تلك تضيف واجهة مستخدم كاملة _بالإضافة إلى_ الوكيل.
### ما يأتي في الصندوق {#in-the-box}
يتخطى تطبيق الأتمتة أولاً عمل لوحة التحكم، وهو مستقل عن القناة منذ اليوم الأول. يعمل نفس الوكيل من الويب وSlack وTelegram والبريد الإلكتروني والوكلاء الآخرين لأن كل شيء يمر بنفس الإجراءات. المقايضة هي أنه لا يوجد عرض "تصفح كل شيء في لمحة"؛ إذا احتاج المستخدمون إلى ذلك، ابدأ من [المحادثة](/docs/template-chat) أو أضف صفحة حالة صغيرة أو عرض قائمة.
عند إضافة غلاف المحادثة المدمج، يوفر الإطار خمس واجهات إدارة لا يتعين عليك بناؤها: **المحادثة** (المدخل الرئيسي)، **الموارد** (المهارات والذاكرة والتعليمات والوكلاء الفرعيون وخوادم MCP المتصلة)، **الأتمتة**، **سجل الخيط**، و**الإعدادات**. هذه عادةً كافية: تحدث إليه، وانظر ما فعله، وهيّئ كيفية تصرفه. العب إلى [المحادثة](/docs/template-chat) عندما تكون مستعدًا لإضافة تلك الواجهة المتصفح، أو [قالب الإرسال](/docs/template-dispatch) كنقطة بداية بأسلوب مساحة العمل مع Slack/Telegram والمهام المجدولة والأسرار المشتركة خارج الصندوق.
أصغر مسار محلي بدون متصفح هو سقالة بالإضافة إلى إجراء واحد:
```bash
npx --yes @agent-native/core@latest create my-agent --headless
cd my-agent
pnpm install
```
ثم عرّف العملية الدائمة:
```ts filename="actions/summarize-week.ts"
import { defineAction } from "@agent-native/core/action";
import { z } from "zod";
// One action powers every app surface: UI, agent, HTTP, MCP, A2A, and CLI.
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`
- **App-agent CLI:** `pnpm agent "Summarize form_123"`
- **MCP:** من Claude وChatGPT وCodex وCursor وOpenCode وCopilot ومضيفي MCP الآخرين
- **A2A:** من تطبيق agent-native آخر أو نظير وكيل
- **واجهة المستخدم:** من خلال `useActionQuery` أو `useActionMutation` أو `callAction`
- **أداة الوكيل:** من حلقة المحادثة المدمجة
<Endpoint id="doc-block-kdx289" title="استدعاء إجراء عبر HTTP" method="POST" path="/_agent-native/actions/summarize-week" summary="استدعاء أي إجراء بالاسم عبر HTTP" request={{
"contentType": "application/json",
"example": "{ \"formId\": \"form_123\" }"
}} responses={[
{
"status": "200",
"description": "قيمة إرجاع الإجراء بصيغة JSON",
"example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }"
},
{
"status": "400",
"description": "فشل التحقق من صحة المدخلات وفق مخطط البيانات"
}
]}>
كل `defineAction` يُثبَّت تلقائيًا في `/_agent-native/actions/<name>`. يُتحقق من صحة نص JSON وفق مخطط zod الخاص بالإجراء قبل تنفيذ `run`. لاستدعائه من نظام خارجي برمز حامل طويل الأمد، انظر [HTTP API](/docs/http-api).
</Endpoint>
هذا ليس وضع بلا قاعدة بيانات أو وضع عديم الحالة. تخزّن حلقة تطبيق-الوكيل الجلسات
والخيوط والتشغيلات والإعدادات وبيانات الاعتماد وحالة التطبيق وسجلات المشاركة في
SQL. يعتمد التطوير المحلي على PGlite بشكل افتراضي؛ يجب على تطبيقات الأتمتة أولاً المستضافة
استخدام قاعدة بيانات SQL ثابتة.
إذا كنت بحاجة إلى حلقة الوكيل بالكامل بدون واجهة من مجلد المشروع، استخدم:
```bash
pnpm agent "Summarize this week's forms."
```
إذا احتاج تطبيق أو نص برمجي آخر إلى استدعاء الوكيل بالكامل، استخدم
`agentNative.invoke("analytics", "...")` أو واجهة CLI `agent-native invoke`. يبقي ذلك
العمل عبر التطبيقات على مسار A2A بينما يبقى العمل المحلي على الإجراءات.
يمكن للعمال والمهام وخطافات الويب للتكامل والمضيفين المخصصين تشغيل حلقة الوكيل
مباشرة من خلال واجهة برمجة تطبيقات الخادم. هذا أكثر انخفاضًا في المستوى من الإجراءات — تُوفّر
المحرك والنموذج والرسائل والأدوات والإجراءات وبالوعة الأحداث وإشارة الإلغاء
بنفسك:
```ts
import { runAgentLoop } from "@agent-native/core/server";
await runAgentLoop({
engine,
model,
systemPrompt,
tools,
actions,
messages,
send,
signal,
});
```
بالنسبة لمعظم التطبيقات، تستدعي الموجهات المجدولة وخطافات الويب للتكامل هذه الحلقة
بالفعل نيابةً عنك. العب إليها مباشرة فقط عند بناء مضيف مخصص بدون متصفح، أو مُشغّل تقييم،
أو سطح تنسيق من جانب الخادم. انظر [الخادم: معالج الوكيل في الإنتاج](/docs/server-plugins#agent-chat-plugin) للاطلاع على التوقيع الكامل.
### التشغيل على مجلد {#folder-loop}
إذا كان هدفك "تشغيل وكيل على هذا المجلد"، ابدأ بحلقة تطبيق-الوكيل
في ذلك المجلد: قم بسقالة تطبيق الأتمتة أولاً، وأضف الإجراءات/التعليمات، وشغّل
`pnpm agent "..."`. يبقي ذلك العمل داخل نفس عقد الإجراء/وقت التشغيل/الحالة الذي سيستخدمه التطبيق في الإنتاج.
تسخيرات الترميز الخارجية هي سطح منتج منفصل لتضمين Claude
Code وCodex وPi وCursor وMastra أو أوقات تشغيل مماثلة داخل تطبيق Agent-Native.
استخدمها عندما تبني منتج وكيل ترميز، وليس كالطريقة الافتراضية
لبدء سير عمل 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}
جلسات وتشغيلات الأتمتة أولاً هي كائنات دائمة. يجب أن تكون إمكانية المشاركة مرحلية: روابط القراءة/المشاركة أولاً، حتى يتمكن أعضاء الفريق من فحص الموجهات المُعقّمة والمخرجات وحالة التشغيل؛ والتعاون القابل للكتابة بالإذن لاحقًا، بحيث يمر الاستمرار في التشغيل والموافقة على الإجراءات وتعديل الجداول الزمنية أو تغيير التهيئة من خلال فحوصات وصول صريحة.
## محادثة غنية على وكيلك {#byo-agent}
استخدم هذا المسار عندما يكون وكيلك مبنيًا بالفعل بإطار عمل أو
وقت تشغيل آخر وتريد واجهة محادثة Agent-Native حوله. `AgentChatRuntime` هو
الحد الفاصل: يبث وقت تشغيلك أحداثًا موحدة، ويُعرض Agent-Native المحرر
وسجل النسخ واستدعاءات الأدوات والموافقات والعناصر الأصلية وتخطيط التطبيق.
```tsx
import { AssistantChat } from "@agent-native/toolkit/app/chat";
import { createHttpAgentChatRuntime } from "@agent-native/core/client/agent-chat";
const runtime = createHttpAgentChatRuntime({
endpoint: "/api/support-agent/chat",
});
export function SupportAgentChat() {
return <AssistantChat runtime={runtime} threadId="support" />;
}
```
توجد مساعدات وقت تشغيل جاهزة لـ OpenAI Agents وOpenAI Responses وClaude
Agent SDK وVercel AI SDK وAG-UI، بالإضافة إلى وقت تشغيل HTTP الموحد أعلاه
لأي وكيل آخر (Mastra، Flue، Eve، LangGraph، أو خدمة مخصصة). ACP ليس محادثة التطبيق للمستخدم النهائي أو نقل A2A، ولا يدّعي Agent-Native حاليًا دعم A2UI. ACP مدعوم في مكان واحد محدد: تشغيل وكيل ترميز محلي (Gemini CLI، Claude Code، ...) من خلال
[طبقة التسخير](/docs/harness-agents#acp)، وليس كوقت تشغيل المحادثة هنا.
[واجهة المحادثة الأصلية: أوقات تشغيل وكيل BYO](/docs/native-chat-ui#byo-agent-runtimes)
هو المرجع الرسمي لأشكال الأحداث ومساعدات وقت التشغيل وبيانات تعريف نتيجة أداة `chatUI`. ابدأ هناك عند توصيل وكيل خارجي بالمحادثة.
## ما التالي {#related-docs}
<Cards>
### [الإجراءات](/docs/actions-overview)
عرّف العملية مرة واحدة. كل واجهة أعلاه تستدعي نفسها.
### [واجهة المحادثة الأصلية](/docs/native-chat-ui)
اعرض نتائج الإجراءات المكتوبة كجداول ومخططات وبطاقات مباشرة في المحادثة.
### [واجهة المستخدم التوليدية](/docs/generative-ui)
أنشئ واجهة مستخدم محمية عابرة أو ثابتة مضمّنة في المحادثة.
### [تطبيقات الأتمتة أولاً](/docs/pure-agent-apps)
النمط الكامل بدون متصفح للمهام والطوابير والنصوص البرمجية والوكلاء الخارجيين.
### [الوكلاء الخارجيون](/docs/external-agents)
اتصل بمضيفي MCP المتوافقين بتطبيقك كخادم أدوات.
### [بروتوكول A2A](/docs/a2a-protocol)
استدع الوكلاء من تطبيقات agent-native الأخرى عبر معيار A2A.
</Cards>
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |