Skip to content

BuilderIO/agent-native / packages/core/docs

agent-native-docs

Unverified

How 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.

FileKindSize
AGENTS.mdmarkdown6.0 KB
SKILL.mdskill md2.2 KB
content/a2a-protocol.mdxmarkdown37.6 KB
content/actions-access-control.mdxmarkdown28.9 KB
content/actions-advanced.mdxmarkdown13.1 KB
content/actions-agent-tools.mdxmarkdown5.6 KB
content/actions-defining.mdxmarkdown31.2 KB
content/actions-other-surfaces.mdxmarkdown10.3 KB
content/actions-overview.mdxmarkdown8.3 KB
content/actions-run-context.mdxmarkdown9.1 KB
content/add-ui-to-your-agent.mdxmarkdown5.0 KB
content/administered-deployments.mdxmarkdown7.7 KB
content/agent-mentions.mdxmarkdown10.2 KB
content/agent-native-config.mdxmarkdown34.9 KB
content/agent-native-toolkit.mdxmarkdown17.3 KB
content/agent-resources.mdxmarkdown27.0 KB
content/agent-surfaces.mdxmarkdown33.8 KB
content/agent-teams.mdxmarkdown13.4 KB
content/agent-web-surfaces.mdxmarkdown10.7 KB
content/agentkit.mdxmarkdown14.0 KB
content/audit-log.mdxmarkdown14.3 KB
content/authentication.mdxmarkdown30.7 KB
content/automation-connectors.mdxmarkdown7.8 KB
content/automations.mdxmarkdown26.7 KB
content/aws-amplify.mdxmarkdown10.7 KB
content/aws-lambda.mdxmarkdown13.9 KB
content/aws-rds.mdxmarkdown1.7 KB
content/azure-postgresql.mdxmarkdown1.8 KB
content/azure-static-web-apps.mdxmarkdown9.1 KB
content/blueprint-installer.mdxmarkdown6.3 KB
content/cli-adapters.mdxmarkdown5.7 KB
content/client-advanced.mdxmarkdown13.1 KB
content/client-agent-chat.mdxmarkdown17.7 KB
content/client-data.mdxmarkdown19.3 KB
content/client-entry-points.mdxmarkdown1.2 KB
content/client-overview.mdxmarkdown10.6 KB
content/client-routing.mdxmarkdown5.7 KB
content/client-sync-internals.mdxmarkdown5.2 KB
content/cloneable-saas.mdxmarkdown16.6 KB
content/cloud-sql.mdxmarkdown2.3 KB
content/cloudflare.mdxmarkdown8.3 KB
content/code-agents-ui.mdxmarkdown26.6 KB
content/components.mdxmarkdown42.9 KB
content/context-awareness.mdxmarkdown24.9 KB
content/create-with-an-agent.mdxmarkdown8.8 KB
content/creating-templates.mdxmarkdown21.6 KB
content/cross-app-connect-design.mdxmarkdown8.4 KB
content/cross-app-sso.mdxmarkdown8.7 KB
content/custom-design-system.mdxmarkdown17.3 KB
content/data-programs.mdxmarkdown25.0 KB
content/decisions.mdxmarkdown7.9 KB
content/deno-deploy.mdxmarkdown7.2 KB
content/deploy-an-app.mdxmarkdown5.0 KB
content/deployment-environment-variables.mdxmarkdown16.3 KB
content/deployment.mdxmarkdown11.3 KB
content/dispatch.mdxmarkdown18.6 KB
content/docker.mdxmarkdown8.1 KB
content/docs-components.mdxmarkdown28.9 KB
content/doctor.mdxmarkdown21.3 KB
content/drafts/clips-experimental-features.mdmarkdown5.4 KB
content/drop-in-agent.mdxmarkdown16.0 KB
content/durable-background-runs.mdxmarkdown13.8 KB
content/durable-resume.mdxmarkdown10.0 KB
content/embedding-sdk.mdxmarkdown31.3 KB
content/environment-variables.mdxmarkdown29.9 KB
content/evals.mdxmarkdown12.4 KB
content/extensions.mdxmarkdown34.8 KB
content/external-agents-catalog.mdxmarkdown40.5 KB
content/external-agents.mdxmarkdown29.3 KB
content/file-uploads.mdxmarkdown10.7 KB
content/generative-ui.mdxmarkdown10.8 KB
content/getting-started-actions.mdxmarkdown2.7 KB
content/getting-started-pages.mdxmarkdown2.6 KB
content/getting-started.mdxmarkdown7.2 KB
content/harness-agents.mdxmarkdown16.9 KB
content/http-api.mdxmarkdown20.9 KB
content/integrations.mdxmarkdown33.8 KB
content/internationalization.mdxmarkdown6.2 KB
content/key-concepts.mdxmarkdown30.6 KB
content/koyeb.mdxmarkdown7.3 KB
content/locales/ar-SA/a2a-protocol.mdxmarkdown48.5 KB
content/locales/ar-SA/actions-access-control.mdxmarkdown40.8 KB
content/locales/ar-SA/actions-advanced.mdxmarkdown16.3 KB
content/locales/ar-SA/actions-agent-tools.mdxmarkdown8.1 KB
content/locales/ar-SA/actions-defining.mdxmarkdown42.2 KB
content/locales/ar-SA/actions-other-surfaces.mdxmarkdown14.5 KB
content/locales/ar-SA/actions-overview.mdxmarkdown11.3 KB
content/locales/ar-SA/actions-run-context.mdxmarkdown11.1 KB
content/locales/ar-SA/add-ui-to-your-agent.mdxmarkdown3.7 KB
content/locales/ar-SA/administered-deployments.mdxmarkdown6.4 KB
content/locales/ar-SA/agent-mentions.mdxmarkdown11.8 KB
content/locales/ar-SA/agent-native-toolkit.mdxmarkdown17.3 KB
content/locales/ar-SA/agent-resources.mdxmarkdown36.8 KB
content/locales/ar-SA/agent-surfaces.mdxmarkdown48.4 KB
content/locales/ar-SA/agent-teams.mdxmarkdown18.5 KB
content/locales/ar-SA/agent-web-surfaces.mdxmarkdown14.3 KB
content/locales/ar-SA/audit-log.mdxmarkdown15.9 KB
content/locales/ar-SA/authentication.mdxmarkdown39.8 KB
content/locales/ar-SA/automations.mdxmarkdown31.3 KB
content/locales/ar-SA/aws-amplify.mdxmarkdown14.9 KB
content/locales/ar-SA/aws-lambda.mdxmarkdown18.9 KB
content/locales/ar-SA/aws-rds.mdxmarkdown319 B
content/locales/ar-SA/azure-postgresql.mdxmarkdown344 B
content/locales/ar-SA/azure-static-web-apps.mdxmarkdown12.4 KB
content/locales/ar-SA/blueprint-installer.mdxmarkdown8.4 KB
content/locales/ar-SA/cli-adapters.mdxmarkdown6.7 KB
content/locales/ar-SA/client-advanced.mdxmarkdown17.8 KB
content/locales/ar-SA/client-agent-chat.mdxmarkdown23.0 KB
content/locales/ar-SA/client-data.mdxmarkdown23.8 KB
content/locales/ar-SA/client-entry-points.mdxmarkdown1.6 KB
content/locales/ar-SA/client-overview.mdxmarkdown13.9 KB
content/locales/ar-SA/client-routing.mdxmarkdown7.2 KB
content/locales/ar-SA/client-sync-internals.mdxmarkdown7.3 KB
content/locales/ar-SA/cloneable-saas.mdxmarkdown23.2 KB
content/locales/ar-SA/cloud-sql.mdxmarkdown317 B
content/locales/ar-SA/cloudflare.mdxmarkdown11.9 KB
content/locales/ar-SA/code-agents-ui.mdxmarkdown34.2 KB
content/locales/ar-SA/components.mdxmarkdown51.5 KB
content/locales/ar-SA/context-awareness.mdxmarkdown33.1 KB
content/locales/ar-SA/create-with-an-agent.mdxmarkdown12.2 KB
content/locales/ar-SA/creating-templates.mdxmarkdown26.8 KB
content/locales/ar-SA/cross-app-connect-design.mdxmarkdown1.5 KB
content/locales/ar-SA/cross-app-sso.mdxmarkdown9.7 KB
content/locales/ar-SA/custom-design-system.mdxmarkdown21.6 KB
content/locales/ar-SA/data-programs.mdxmarkdown33.3 KB
content/locales/ar-SA/decisions.mdxmarkdown9.1 KB
content/locales/ar-SA/deno-deploy.mdxmarkdown10.1 KB
content/locales/ar-SA/deploy-an-app.mdxmarkdown7.1 KB
content/locales/ar-SA/deployment-environment-variables.mdxmarkdown21.3 KB
content/locales/ar-SA/deployment.mdxmarkdown13.9 KB
content/locales/ar-SA/dispatch.mdxmarkdown27.3 KB
content/locales/ar-SA/docker.mdxmarkdown11.3 KB
content/locales/ar-SA/doctor.mdxmarkdown3.4 KB
content/locales/ar-SA/drop-in-agent.mdxmarkdown20.8 KB
content/locales/ar-SA/durable-resume.mdxmarkdown15.4 KB
content/locales/ar-SA/embedding-sdk.mdxmarkdown41.3 KB
content/locales/ar-SA/evals.mdxmarkdown13.3 KB
content/locales/ar-SA/extensions.mdxmarkdown34.0 KB
content/locales/ar-SA/external-agents.mdxmarkdown89.3 KB
content/locales/ar-SA/file-uploads.mdxmarkdown13.4 KB
content/locales/ar-SA/getting-started-actions.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started-pages.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started.mdxmarkdown9.7 KB
content/locales/ar-SA/harness-agents.mdxmarkdown22.3 KB
content/locales/ar-SA/internationalization.mdxmarkdown8.2 KB
content/locales/ar-SA/key-concepts.mdxmarkdown42.0 KB
content/locales/ar-SA/koyeb.mdxmarkdown10.2 KB
content/locales/ar-SA/mcp-apps.mdxmarkdown33.7 KB
content/locales/ar-SA/mcp-clients.mdxmarkdown35.0 KB
content/locales/ar-SA/mcp-protocol.mdxmarkdown27.6 KB
content/locales/ar-SA/messaging.mdxmarkdown59.2 KB
content/locales/ar-SA/multi-app-workspace.mdxmarkdown36.2 KB
content/locales/ar-SA/multi-tenancy.mdxmarkdown7.5 KB
content/locales/ar-SA/native-chat-ui.mdxmarkdown21.3 KB
content/locales/ar-SA/neon.mdxmarkdown244 B
content/locales/ar-SA/netlify.mdxmarkdown15.2 KB
content/locales/ar-SA/node-docker.mdxmarkdown878 B
content/locales/ar-SA/node-js.mdxmarkdown8.4 KB
content/locales/ar-SA/notifications.mdxmarkdown16.2 KB
content/locales/ar-SA/observability.mdxmarkdown45.2 KB
content/locales/ar-SA/observational-memory.mdxmarkdown10.9 KB
content/locales/ar-SA/onboarding.mdxmarkdown16.9 KB
content/locales/ar-SA/organizations-teams-permissions.mdxmarkdown5.9 KB
content/locales/ar-SA/package-lifecycle.mdxmarkdown3.0 KB
content/locales/ar-SA/plan-plugin.mdxmarkdown23.0 KB
content/locales/ar-SA/portal.mdxmarkdown636 B
content/locales/ar-SA/postgres.mdxmarkdown487 B
content/locales/ar-SA/pr-visual-recap.mdxmarkdown53.9 KB
content/locales/ar-SA/privacy-and-data-rights.mdxmarkdown6.2 KB
content/locales/ar-SA/processors.mdxmarkdown8.7 KB
content/locales/ar-SA/progress.mdxmarkdown10.7 KB
content/locales/ar-SA/pure-agent-apps.mdxmarkdown5.0 KB
content/locales/ar-SA/real-time-collaboration.mdxmarkdown55.6 KB
content/locales/ar-SA/recorder.mdxmarkdown16.7 KB
content/locales/ar-SA/recurring-jobs.mdxmarkdown23.8 KB
content/locales/ar-SA/render.mdxmarkdown11.2 KB
content/locales/ar-SA/sandbox-adapters.mdxmarkdown18.0 KB
content/locales/ar-SA/security.mdxmarkdown31.5 KB
content/locales/ar-SA/server-database.mdxmarkdown27.6 KB
content/locales/ar-SA/server-middleware.mdxmarkdown7.9 KB
content/locales/ar-SA/server-overview.mdxmarkdown12.2 KB
content/locales/ar-SA/server-plugins.mdxmarkdown9.1 KB
content/locales/ar-SA/server-routes.mdxmarkdown14.3 KB
content/locales/ar-SA/sharing.mdxmarkdown28.6 KB
content/locales/ar-SA/skills-guide.mdxmarkdown27.0 KB
content/locales/ar-SA/ssr-caching.mdxmarkdown7.4 KB
content/locales/ar-SA/supabase.mdxmarkdown264 B
content/locales/ar-SA/syncing-template-changes.mdxmarkdown11.7 KB
content/locales/ar-SA/telemetry.mdxmarkdown21.9 KB
content/locales/ar-SA/template-analytics.mdxmarkdown26.4 KB
content/locales/ar-SA/template-assets.mdxmarkdown31.9 KB
content/locales/ar-SA/template-brain.mdxmarkdown29.7 KB
content/locales/ar-SA/template-calendar-agent.mdxmarkdown10.2 KB
content/locales/ar-SA/template-calendar-developers.mdxmarkdown33.4 KB
content/locales/ar-SA/template-calendar-features.mdxmarkdown14.4 KB
content/locales/ar-SA/template-calendar-integrations.mdxmarkdown6.2 KB
content/locales/ar-SA/template-calendar.mdxmarkdown4.4 KB
content/locales/ar-SA/template-chat-agent.mdxmarkdown4.7 KB
content/locales/ar-SA/template-chat-developers.mdxmarkdown31.3 KB
content/locales/ar-SA/template-chat-features.mdxmarkdown9.9 KB

content/locales/ar-SA/client-advanced.mdx

View on GitHub
---
title: "متقدم"
description: "بدائيات (primitives) app/ ذات المستوى الأدنى ومخارج الطوارئ: الوصول المباشر إلى حالة التطبيق، الإرسال في الخلفية للمحادثة، شرائح الاقتراحات المخصصة، وجسر استضافة MCP App."
---

# متقدم

تغطي نظرة عامة، والبيانات والمزامنة، ومحادثة الوكيل، والتوجيه الحالة النموذجية: الخطافات والأدوات المساعدة التي تحتاجها معظم الصفحات. تغطي هذه الصفحة البدائيات ذات المستوى الأدنى ومخارج الطوارئ الأضيق الموجودة تحتها. لا تلمس معظم التطبيقات هذه مباشرة أبدًا. استخدم واحدة منها عندما تبني شيئًا أكثر تخصيصًا من الخطافات الافتراضية التي تدعمها، مثل مزامنة تحديد مخصصة أو MCP App مضمّن. لمزامنة `useQuery` خام بمفتاح مصنوع يدويًا، راجع [آليات المزامنة الداخلية](/docs/client-sync-internals) بدلًا من ذلك.

## حالة التطبيق {#application-state}

`application_state` هو مخزن مفتاح/قيمة مدعوم بـ SQL يقرأه الوكيل لمعرفة ما تنظر إليه واجهة المستخدم حاليًا، بما في ذلك التنقل، والتحديد، وسياق الكائن المُركَّز عليه الآخر (راجع [الوعي بالسياق](/docs/context-awareness)). يُغلِّف `useAgentRouteState` و`useSemanticNavigationState` (المُغطّيان أيضًا في الوعي بالسياق) هذه البدائيات بالفعل لحالة التنقل الشائعة. استخدم البدائيات أدناه مباشرة عندما تكون تُزامن شيئًا لا تغطيه، مثل تحديد مخصص، أو الكتابة من خارج عرض مكون.

### readClientAppState {#read-client-app-state}

اقرأ القيمة الحالية لمفتاح. يُحل إلى آخر ما تمت كتابته لهذا المفتاح، أو `null` إذا لم تتم كتابة المفتاح مطلقًا.

```ts
import { readClientAppState } from "@agent-native/core/client/hooks";

const selection = await readClientAppState("selection");
// selection is exactly what was last written to that key, e.g.:
// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
//
// or, if nothing has written "selection" yet:
// null
```

### writeClientAppState {#write-client-app-state}

اكتب قيمة لمفتاح. على عكس `setClientAppState` أدناه، تكتب دائمًا، حتى إذا مررت `null`. تمرير `undefined` يرمي خطأ بدلًا من ذلك، لأن `undefined` ليس JSON صالحًا. استخدم `setClientAppState(key, undefined)` أو `deleteClientAppState()` لمسح مفتاح.

```ts
import { writeClientAppState } from "@agent-native/core/client/hooks";

await writeClientAppState(
  "selection",
  { id: recordId },
  { requestSource: TAB_ID },
);
```

### setClientAppState {#set-client-app-state}

الغلاف المناسب الذي يجب أن تستخدمه معظم كود واجهة المستخدم: يكتب القيمة، أو يحذف المفتاح عندما تمرر `null`/`undefined`. استخدم هذا بدلاً من `writeClientAppState` إلا إذا كان موقع الاستدعاء يحتاج فعليًا إلى "الكتابة دائمًا، عدم الحذف مطلقًا".

```ts
import { setClientAppState } from "@agent-native/core/client/hooks";

await setClientAppState(
  "selection",
  { id: recordId },
  { requestSource: TAB_ID },
);
await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
```

### deleteClientAppState {#delete-client-app-state}

احذف مفتاحًا بالكامل.

```ts
import { deleteClientAppState } from "@agent-native/core/client/hooks";

await deleteClientAppState("pending-selection-context");
```

### readClientAppStateMany {#read-client-app-state-many}

اقرأ عدة مفاتيح في طلب واحد. تُعيد `{ values, missing }`. تحتفظ `values` بإدخال لكل مفتاح يملك الخادم صفًا له، بما في ذلك مفتاح تمت كتابته صريحًا كـ `null`. تسرد `missing` المفاتيح التي لم تتم كتابتها مطلقًا. هذه هي الطريقة التي يبقى بها "لم تتم الكتابة مطلقًا" قابلًا للتمييز عن "مكتوب كـ null".

```ts
import { readClientAppStateMany } from "@agent-native/core/client/hooks";

const { values, missing } = await readClientAppStateMany([
  "selection",
  "pending-selection-context",
]);
```

يتم تجميع الطلبات التي تتجاوز 100 مفتاح تلقائيًا في مجموعات. يُبنى `readClientAppState()` نفسها على هذا: تُدمَج الاستدعاءات الصادرة في نفس اللحظة (tick) في طلب مُجمَّع واحد خلف الكواليس، لذا يكلف استدعاءها عدة مرات في تمريرة عرض واحدة رحلة ذهاب وعودة واحدة، لا رحلة لكل استدعاء.

### الخيارات {#application-state-options}

يُقبَل `signal` من قِبل جميع الدوال الخمس أعلاه، لإلغاء استدعاء قيد التنفيذ. ينطبق `requestSource` و`keepalive` فقط على دوال الكتابة الثلاث، لأنهما لا يعنيان شيئًا بالنسبة للقراءة.

| الخيار          | النوع          | ينطبق على                                                          | الوصف                                                                                                   |
| --------------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `requestSource` | `string?`      | `writeClientAppState`، `setClientAppState`، `deleteClientAppState` | يُضيف علامة على الكتابة بمعرِّف حتى يتمكن `useDbSync({ ignoreSource })` المطابق من تخطي إعادة الجلب لها |
| `keepalive`     | `boolean?`     | `writeClientAppState`، `setClientAppState`، `deleteClientAppState` | يسمح للطلب بالاستمرار بعد تفريغ الصفحة (unload). استخدمه لكتابات التنظيف مثل مسح التحديد                |
| `signal`        | `AbortSignal?` | جميع الدوال الخمس                                                  | يلغي الطلب                                                                                              |

### سلوك الفشل {#failure-behavior}

ترمي جميع الدوال الخمس خطأ عند فشل الطلب، أو استجابة غير 2xx، أو نص لا يمكن تحليله. يحمل `Error` المرمي خاصية `.status` عندما يستجيب الخادم، لذا يمكن للمستدعي التفريع بناءً على حالة HTTP إذا لزم الأمر. غلِّف الاستدعاء بـ `try`/`catch`، أو دعه ينتشر إلى حدود خطأ، تمامًا مثل أي استدعاء شبكة آخر.

### ما هو TAB_ID {#tab-id}

يُضبَط `requestSource` بشكل شائع على `TAB_ID`، وهو ثابت عادي يُصدِّره كل قالب من `app/lib/tab-id.ts`: سلسلة عشوائية قصيرة تبقى نفسها طوال عمر علامة تبويب وتختلف بين علامات التبويب. إقران `requestSource: TAB_ID` على كتابة مع `useDbSync({ ignoreSource: TAB_ID })` على جانب القراءة هو كيف تتجنب علامة التبويب إعادة جلب كتابتها الخاصة بينما تظل تتفاعل مع كل الآخرين. راجع [الوعي بالسياق](/docs/context-awareness#jitter-prevention) للحصول على الشرح الكامل.

## جلسات الوكيل الخلفية المعزولة {#isolated-background-agent-sessions}

استخدم `startBackgroundAgentSession()` عندما يحتاج كل استدعاء إلى سلسلة محادثة
جديدة وثابتة من دون إضافة علامة تبويب ظاهرة أو مخفية، أو حالة للشريط الجانبي، أو
إدخال في لوحة التشغيل. تستخدم الدالة مسار محادثة الوكيل المعتاد والمصادق عليه،
لذلك يظل مدير التشغيل المشترك مسؤولًا عن الاستمرارية والأدوات وإعادة المحاولة
والتنفيذ الدائم المستضاف.

```ts
import { startBackgroundAgentSession } from "@agent-native/core/client/agent-chat";

const session = startBackgroundAgentSession({
  message: "Analyze this import and create any missing records",
  instructions: `Import batch id: ${batchId}`,
  scope: { type: "import-batch", id: batchId },
  model: "gpt-5.6-sol",
  effort: "medium",
});

await session.accepted;
const latest = await session.status();
session.open({ prefill: "Show me what changed" });
```

يوفر المقبض `operationId` و`threadId` و`turnId` فورًا. ينتظر `accepted` قبول
التشغيل، ويتابع `completion` تدفق الاستجابة، بينما يقرأ `status()` حالة التشغيل
الدائمة بصورة مستقلة. يوقف `cancel()` الدور. عند إعادة المحاولة بعد فقدان الإقرار،
مرّر قيمتي `operationId` و`threadId` الأصليتين.

## sendToAgentChat: الإرسال في الخلفية {#background-send}

استخدم `background: true` عندما ينبغي لإجراء واجهة مستخدم أن يبدأ عمل وكيل حقيقي دون
فتح أو تركيز الشريط الجانبي. لا يزال هذا يُنشئ سلسلة محادثة/تشغيل عادية،
ويستخدم أدوات/actions/سياق الوكيل، ويحافظ على إمكانية ملاحظة العمل من خلال
علبة التشغيل. إنه ليس استدعاء نموذج فوري خام لمرة واحدة.

```ts
import { sendToAgentChat } from "@agent-native/core/client/agent-chat";

const tabId = sendToAgentChat({
  message: "Analyze this import and create any missing records",
  context: `Import batch id: ${batchId}`,
  submit: true,
  newTab: true,
  background: true,
  openSidebar: false,
});
```

يُقصد إقران `background` مع `newTab` حتى لا يُغطّي العمل المخفي
محادثة المستخدم النشطة. استخدم `tabId` المُعاد إذا كانت واجهة المستخدم تحتاج إلى
ربط حالة المتابعة أو الربط العميق بالتشغيل لاحقًا.

توجد بعض خيارات `AgentChatMessage` الإضافية بعيدًا عن الخيارات المُغطّاة في [محادثة الوكيل](/docs/client-agent-chat#agentchatmessage)، معظمها لحالات التضمين أو التكامل اللاحق:

| الخيار                | النوع       | الوصف                                                                 |
| --------------------- | ----------- | --------------------------------------------------------------------- |
| `background`          | `boolean?`  | مع `newTab`، يعمل دون تركيز علامة التبويب ويعرض التشغيل في `RunsTray` |
| `projectSlug`         | `string?`   | ارتباط ثابت اختياري للمشروع لسياق منظّم                               |
| `preset`              | `string?`   | اسم إعداد مسبق اختياري للمستهلكين اللاحقين                            |
| `referenceImagePaths` | `string[]?` | مسارات صور مرجعية اختيارية                                            |

## جسر استضافة MCP App {#mcp-app-host-bridge}

ينبغي أن تكون المسارات المُضمَّنة كتطبيقات MCP أولوية عنوان URL: تحميل العنصر الحالي من
معلمات المسار/الاستعلام، وعرض مسار React الحقيقي أو مكون مشترك مُركَّز، واستخدام
الجسر المضيف فقط للسلوك المملوك للمضيف. يُصدِّر `@agent-native/core/client`
الأدوات المساعدة التي تستدعيها المسارات المُضمَّنة:

```ts
import {
  getMcpAppHostContext,
  openMcpAppHostLink,
  requestMcpAppDisplayMode,
  updateMcpAppModelContext,
  useMcpAppHostContext,
} from "@agent-native/core/client/agent-chat";
```

يقرأ `getMcpAppHostContext()` أحدث لقطة سياق مضيف مدفوعة.
يشترك `useMcpAppHostContext()` مكونات React في التغييرات. تُعيد أدوات الطلب
المساعدة (`openMcpAppHostLink`، `requestMcpAppDisplayMode`،
`updateMcpAppModelContext`) `false` خارج إطار MCP App مُضمَّن، أو
`Promise<boolean>` داخل إطار.

يستخدم `sendToAgentChat()` (راجع [محادثة الوكيل](/docs/client-agent-chat#sendtoagentchat)) نفس الجسر للمطالبات المُرسَلة تلقائيًا من المسارات المُضمَّنة. داخل تضمين MCP App تم إنشاؤه بـ `embedApp()`، يتم توجيه الرسائل المُرسَلة تلقائيًا (حُذف `submit` أو `true`) إلى الجسر، الذي يطلب من المضيف المحتوي إضافة سياق مخفي وإرسال الدور المرئي للمستخدم. يبقى `context` مرئيًا للنموذج دون أن يُنشَر كمحادثة مواجهة للمستخدم. يحتفظ `submit: false` بسلوك التعبئة/المراجعة المسبقة المحلي لأن تطبيقات MCP لا تُعرِّف واجهة برمجة قياسية لتعبئة المسودة مسبقًا. داخليًا هذا هو مسار المحادثة المُرسَلة الذي يظهر أحيانًا كـ `agentNative.submitChat`. يجب أن يستمر كود التطبيق في استدعاء `sendToAgentChat()` بدلًا من نشر ذلك الحدث مباشرة.

الجسر نفسه، ورسائل `ui/*` JSON-RPC، وترحيل الغلاف (wrapper relay) `agentNative.mcpHost.*`،
والزرع (transplant) مقابل عرض الإطار المتحكم فيه، وسياق المضيف، و
طلبات وضع العرض، مملوك لـ
[الوكلاء الخارجيون](/docs/external-agents#mcp-app-bridge). راجع [تطبيقات MCP](/docs/mcp-apps) للتعرف على البروتوكول الكامل.

## شرائح الاقتراحات المخصصة {#custom-suggestions}

تدمج `dynamicSuggestions` الخاصة بـ `<AgentSidebar>` (راجع [محادثة الوكيل](/docs/client-agent-chat#dynamic-suggestions)) بالفعل `suggestions` الثابتة مع الاستدلال المدرك للسياق الخاص بإطار العمل. مرر دالة `getSuggestions` داخل `dynamicSuggestions` بدلًا من ذلك عندما يريد تطبيق شرائح حتمية خاصة بالمجال محسوبة من نفس سياق `application_state` بدلًا من استدلال إطار العمل الافتراضي.

```tsx
<AgentSidebar
  suggestions={["Summarize my inbox"]}
  dynamicSuggestions={{
    getSuggestions: ({ navigation }) => {
      if (
        typeof navigation !== "object" ||
        navigation === null ||
        (navigation as { view?: unknown }).view !== "inbox"
      ) {
        return [];
      }
      const label = (navigation as { label?: unknown }).label;
      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
    },
  }}
>
  <App />
</AgentSidebar>
```

تستقبل `getSuggestions` نفس لقطة `navigation`/`selection`/`pendingSelection` التي يقرأها الاستدلال المدمج، مكتوبة كـ `unknown` لأن شكلها يحدده التطبيق، لذا يجب تضييقها قبل قراءة حقولها. يمكن لتنفيذ مخصص أن يتفاعل مع الحالة نفسها التي يتفاعل معها الاستدلال الافتراضي بالضبط، فقط بقواعد خاصة بالتطبيق بدلًا من قواعد عامة.

## ما هي الخطوة التالية

- [**نظرة عامة**](/docs/client-overview) — تخطيط دليلَي `app/` و`public/` الذي تعيش فيه هذه البدائيات
- [**البيانات والمزامنة**](/docs/client-data) — خطافات actions الافتراضية و`useDbSync` التي ينبغي أن تستخدمها معظم الصفحات بدلًا من ذلك
- [**آليات المزامنة الداخلية**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` والمساران اللذان يمكن أن تسلكهما إعادة الجلب
- [**محادثة الوكيل**](/docs/client-agent-chat) — الأدوات المساعدة الافتراضية `sendToAgentChat`/`askUserQuestion` التي ينبغي أن تستخدمها معظم واجهات المستخدم بدلًا من ذلك، وواجهات برمجة حالة سياق محادثة الوكيل المرحلية
- [**نقاط الدخول**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` وتخصيص بث SSR
- [**الوعي بالسياق**](/docs/context-awareness) — دلالات `navigation`/`selection` المبنية على `application_state`، وشرح `TAB_ID`/منع الاهتزاز
- [**واجهة المستخدم التوليدية**](/docs/generative-ui) — عناصر تحكم أكثر ثراءً مضمّنة في المحادثة تتجاوز `askUserQuestion`
- [**الوكلاء الخارجيون**](/docs/external-agents#mcp-app-bridge) — آليات جسر استضافة MCP App الكاملة
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall