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/native-chat-ui.mdx
View on GitHub---
title: "الدردشة الأصلية UI"
description: "برامج عرض الدردشة الأصلية المعلنة عن إجراء، ومخرجات DataTable/DataChart القابلة لإعادة الاستخدام، وكيف يجب أن تتصل أوقات تشغيل وكيل BYO بدردشة Agent-Native."
---
# الدردشة الأصلية UI
الدردشة الأصلية UI هي مسار العرض داخل التطبيق لمخرجات وكيل الطرف الأول.
يرجع الإجراء JSON منظمًا، ويتعرف وقت تشغيل الدردشة على عنصر واجهة المستخدم الصريح
المميز، ويعرض `<AssistantChat>` مكون React حقيقي في
محادثة. لا يمكنك إنشاء إطار iframe أو قطعة أثرية HTML لمرة واحدة لـ
دردشة التطبيق العادية.
استخدم الدردشة الأصلية UI عندما يتعين على المستخدم فحص المخرجات حيث يوجد الوكيل
أتحدث بالفعل: نتائج الاستعلام، ورؤى الاستجابة، وملخصات الإعداد،
عناصر التحكم في الموافقة/الرفض، أو الروابط إلى طرق عرض التطبيق. استخدم [MCP Apps](/docs/mcp-apps)
عندما يجب عرض مضيف خارجي مثل Claude أو ChatGPT أو Copilot أو Cursor
مسار مضمّن من تطبيقك.
<Diagram id="doc-block-c8ctoa" title={"مسار العرض الأصلي"} summary={"يقوم الإجراء بإرجاع JSON؛ يطابق وقت التشغيل أداة تمييز صريحة أو chatUI.renderer؛ يقوم AssistantChat بتثبيت مكون React حقيقي. لا يوجد إطار iframe ولا يوجد تنفيذ HTML."}>
```html
<div class="diagram-render">
<div class="diagram-node">
الإجراء يعمل<br /><small class="diagram-muted">يعيد JSON منظما</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center" data-rough>
<span class="diagram-pill accent">Match</span
><small class="diagram-muted"
>explicit widget · chatUI.renderer</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box">
<AssistantChat><br /><small class="diagram-muted"
>يركب ودجة React</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card col">
<div class="diagram-pill ok">DataTable</div>
<div class="diagram-pill ok">DataChart</div>
<div class="diagram-pill ok">DataInsights</div>
</div>
</div>
```
```css
.diagram-render {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.diagram-render .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
padding: 14px;
}
.diagram-render .col {
display: flex;
flex-direction: column;
gap: 6px;
padding: 12px;
}
.diagram-render .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
## الأدوات المصغّرة للإجراء {#action-declared-widgets}
يتكون المسار الأصلي من جزأين واضحين:
- يقوم `outputSchema` بالتحقق من صحة شكل استجابة الإجراء.
- يحدد `chatUI.renderer` عارض React الأصلي للنتيجة التي تم التحقق من صحتها.
تستخدم أجهزة عرض البيانات المضمنة نتيجة JSON عادية مع `widget` بالإضافة إلى
الحمولة المطابقة:
| القطعة | الحمولة المطلوبة | يتم عرضه كـ |
| ----------------- | -------------------------- | ------------------------------------------- |
| `"data-table"` | `table` | جدول بيانات أصلي وقابل لإعادة الاستخدام |
| `"data-chart"` | `chartSeries` | مخطط شريطي أو خطي أو مساحي أصلي |
| `"data-insights"` | `table` و/أو `chartSeries` | بطاقة معلومات مدمجة مع مخرجات المخطط/الجدول |
يجب على الخادم actions استيراد المخططات والمساعدات الآمنة للخادم من
`@agent-native/core/data-widgets`; client code can import the same types from
`@agent-native/core/client/widgets` أو `@agent-native/core/client`.
```ts
import { defineAction } from "@agent-native/core/action";
import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
import {
createDataInsightsWidgetResult,
dataInsightsWidgetResultSchema,
} from "@agent-native/core/data-widgets";
export default defineAction({
description: "Analyze form responses.",
readOnly: true,
outputSchema: dataInsightsWidgetResultSchema,
chatUI: {
renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
title: "Response insights",
},
run: async () =>
createDataInsightsWidgetResult({
title: "Response insights",
display: {
title: "42 responses",
description: "Completion rate rose this week.",
primaryAction: {
label: "Open response insights",
href: "/response-insights",
},
},
chartSeries: {
type: "bar",
title: "Responses by day",
xKey: "day",
series: [{ key: "responses", label: "Responses" }],
data: [
{ day: "Mon", responses: 8 },
{ day: "Tue", responses: 13 },
],
},
table: {
title: "Top answers",
columns: [
{ key: "answer", label: "Answer" },
{ key: "count", label: "Count", align: "right" },
],
rows: [
{ answer: "Yes", count: 31 },
{ answer: "No", count: 11 },
],
totalRows: 2,
},
}),
});
```
<Callout id="doc-block-14mzarh" tone="success">
يتولى العارض المسؤولية فقط عندما يعلن الإجراء `chatUI` **أو** تحمل النتيجة تمييزًا صريحًا معروفًا `widget`. لا يستنتج أبدًا شكلًا لكائنات عشوائية ولا ينفذ أبدًا HTML أو JavaScript من نتائج الأداة - لذا لا يمكن أن تصبح الأداة الأصلية متجهًا للحقن.
</Callout>
عندما يطلب المستخدم مخططًا أو رسمًا بيانيًا أو جدولًا أو اتجاهًا أو تقريرًا مضغوطًا، فإن وكلاء التطبيق
الإجراء الذي يعلن عن أحد هؤلاء العارضين الأصليين. النهائي
يجب أن يظل النص المساعد مختصرًا ويسمح للأداة بحمل البيانات؛ لا تنسخ
نفس الصفوف في جدول Markdown ما لم يطلب المستخدم نصًا صراحةً
تصدير.
في حالة عدم وجود إجراء مجال ولكن الوكيل قد قام بالفعل باسترداد مضغوط،
بيانات صادقة، يمكنها استدعاء الإجراء `render-data-widget` لإطار العمل باستخدام
نفس شكل `data-table` أو `data-chart` أو `data-insights` JSON. هذا الإجراء فقط
يقوم بالتحقق من صحة الأداة وعرضها؛ إنه ليس مصدر بيانات ويجب عدم استخدامه
لاختراع مقاييس العنصر النائب.
## إخراج DataTable {#data-table}
إن `table` بسيط عن عمد، لذلك يمكن إدراج SQL والتحليلات وإعداد actions
إعادة استخدامه:
```ts
{
title?: string;
columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
rows: Array<Record<string, unknown>>;
totalRows?: number;
sampledRows?: number;
truncated?: boolean;
}
```
تفضل مفاتيح الأعمدة الثابتة وقيم الصفوف الآمنة JSON. استخدم `totalRows`،
`sampledRows`، و`truncated` عندما يعرض الإجراء شريحة أكبر
مجموعة النتائج.
## إخراج مخطط البيانات {#data-chart}
يدعم `chartSeries` أشكال المخططات الشائعة المستخدمة في إجابات الوكيل بدون
مطالبة كل قالب بإرسال عارض الدردشة الخاص به:
```ts
{
type: "bar" | "line" | "area";
title?: string;
xKey: string;
series: Array<{ key: string; label: string; color?: string }>;
data: Array<Record<string, unknown>>;
sampled?: boolean;
}
```
حافظ على ضغط بيانات المخطط. بالنسبة لمجموعات البيانات الكبيرة، قم بتجميعها في الإجراء والارتباط
إلى العرض الكامل للتطبيق باستخدام البيانات التعريفية `display.primaryAction` أو الإجراء `link`.
## الأدوات الأصلية مقابل تطبيقات MCP {#native-vs-mcp-apps}
أدوات الدردشة الأصلية وتطبيقات MCP متكاملة:
- **الأدوات الأصلية** مخصصة لوقت تشغيل الدردشة الخاص بالتطبيق. نتيجة الإجراء هي
JSON، ويعرض إطار العمل عنصر واجهة المستخدم React المدمج.
- **تطبيقات MCP** مخصصة للمضيفين الخارجيين. يعلن الإجراء `mcpApp` وعادةً
`link`، ويعرض المضيف مسارًا حقيقيًا للتطبيق مضمنًا عند دعمه.
- **تظل الروابط العميقة** بمثابة البديل العام. استخدم الإجراء `link` أو
`display.primaryAction`، عملاء CLI، ومضيفو MCP الأقدم، والنص العادي
يمكن للقراء فتح عرض التطبيق الكامل.
عند وجود كل من حمولة عنصر واجهة المستخدم الأصلية والبيانات التعريفية لتطبيقات MCP، يظهر داخل التطبيق
تفضل الدردشة الأداة الأصلية. يستخدم المضيفون الخارجيون مورد MCP Apps أو
ارتباط احتياطي عميق.
## برامج العرض الأصلية المخصصة {#custom-native-renderers}
قم بتسجيل المكونات الخاصة بالمنتج حسب معرف العارض الدقيق، ثم أعلن عن هذا المعرف
في الإجراء:
```tsx
import { registerActionChatRenderer } from "@agent-native/toolkit/app/chat";
registerActionChatRenderer({
id: "crm.deal-card",
renderer: "crm.deal-card",
Component: ({ context }) => <DealCard result={context.resultJson} />,
});
```
```ts
export default defineAction({
description: "Show a deal card.",
outputSchema: dealCardSchema,
chatUI: { renderer: "crm.deal-card" },
run: async () => ({ dealId: "deal_123", amount: 42000 }),
});
```
استخدم هذا مع تطبيق الطرف الأول UI. احتفظ بإطار iframe UI للمضيف المشترك في `mcpApp`، واحتفظ
تنفيذ استعلام عشوائي خلف قراءة actions المكتوبة بدلاً من SQL الأولية في الدردشة.
قم بتحديد أبعاد الـ renderers بوحدات مطلقة وليس بنسب مئوية. ينمو سجل المحادثة
ليلائم رسائله، لذا لا يملك حاوي الـ renderer ارتفاعًا محددًا تُحسب النسبة المئوية
بالنسبة إليه — فتنهار `height: 40%` على عمود الرسم البياني إلى صفر بدلاً من أن تُصدر
خطأ، وهو ما يبدو كأن الـ renderer فشل في الرسم. امنح الرسوم البيانية وغيرها من
العناصر المعتمدة على الارتفاع أساسًا بالبكسل (أو `rem`)؛ أما العروض فلا بأس بها
كنسب مئوية لأن عمود المحادثة يملك عرضًا محددًا.
### اختيار وقت ظهور واجهة الإجراء {#conditional-native-ui}
قد يتعامل الإجراء مع عمليات متعددة، بينما تحتاج بعض النتائج فقط إلى بطاقة. أضف `when(args, result)` إلى `chatUI` لتحديد هذه الاستدعاءات. يشغّل الخادم هذا الشرط بعد نجاح الإجراء. إذا أعاد `false`، تبقى النتيجة ضمن سجل الأدوات العادي القابل للطي. لا يُحفظ الشرط ولا يُرسل إلى المتصفح.
يستخدم Mail هذا النمط في `manage-draft` لعرض بطاقة عند إنشاء مسودة، مع إبقاء التحديث والحذف كاستدعاءات أدوات عادية:
```ts
chatUI: {
renderer: "mail.draft-created",
when: (args, result) => {
if (
args.action !== "create" ||
!result ||
typeof result !== "object" ||
Array.isArray(result)
) {
return false;
}
const output = result as Record<string, unknown>;
return typeof output.deepLink === "string" && Boolean(output.draft);
},
},
```
في الإجراءات ذات عمليات الكتابة المتعددة، تحقّق من الوسيطات والنتيجة الناجحة. يختار إجراء فلاتر Gmail في Mail بطاقة القاعدة فقط للفلاتر التي أُنشئت أو استُبدلت وتحتوي على حقول الملخص:
```ts
when: (args, result) => {
if (
(args.operation !== "create" && args.operation !== "replace") ||
!result ||
typeof result !== "object" ||
Array.isArray(result)
) {
return false;
}
const output = result as Record<string, unknown>;
const filter = output.filter as Record<string, unknown> | undefined;
return output.ok === true && Boolean(filter?.criteriaSummary);
},
```
## أوقات تشغيل الوكيل BYO {#byo-agent-runtimes}
`AgentChatRuntime` هو عقد إحضار الوكيل الخاص بك لقشرة الدردشة، و
هذا القسم هو مرجعه الأساسي. فهو يتيح للوكيل الذي أنشأته في مكان آخر
بث الأحداث التي تمت تسويتها في محادثة Agent-Native UI مع الاحتفاظ بـ
المؤلف المشترك، وعرض النص، وبطاقات الأدوات، والموافقات، والأدوات الأصلية،
وتخطيط التطبيق المحيط. [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
نقاط تعليمية هنا لقصة وقت التشغيل، و[Component API](/docs/components#agent-chat-ui)
يسرد كل موصل ومحول مع مسار الاستيراد الخاص به؛ العقد نفسه هو
موضح أدناه.
<Diagram id="doc-block-1qei37v" title={"يحتفظ وقت تشغيل BYO بقشرة الدردشة Agent-Native"} summary={"يقوم وكيلك الخارجي ببث الأحداث التي تمت تسويتها من خلال موصل؛ Agent-Native يحتفظ بالمؤلف والنص وبطاقات الأدوات والموافقات والأدوات الأصلية."}>
```html
<div class="diagram-byo">
<div class="diagram-box" data-rough>
وكيلك<br /><small class="diagram-muted"
>OpenAI · Claude · Vercel AI · AG-UI ·
HTTP</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center">
<span class="diagram-pill accent">connector</span
><small class="diagram-muted">أحداث message-* / tool-* موحدة</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card col">
<div class="diagram-pill"><AssistantChat runtime=… /></div>
<small class="diagram-muted"
>composer · transcript · tool cards</small
><small class="diagram-muted">approvals · native widgets</small>
</div>
</div>
```
```css
.diagram-byo {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.diagram-byo .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
padding: 14px;
}
.diagram-byo .col {
display: flex;
flex-direction: column;
gap: 6px;
padding: 14px;
}
.diagram-byo .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
يتم تصدير كافة الموصلات من `@agent-native/core/client/agent-chat` (والجذر
إدخال `@agent-native/core/client`). استخدم وقت التشغيل HTTP العام عندما يكون وكيلك
يمكن أن يعرض نقطة نهاية POST التي تُرجع أحداث وقت التشغيل SSE أو NDJSON:
```tsx
import { AssistantChat } from "@agent-native/toolkit/app/chat";
import { createHttpAgentChatRuntime } from "@agent-native/core/client/agent-chat";
const runtime = createHttpAgentChatRuntime({
id: "external:mastra",
label: "Mastra",
endpoint: "/api/mastra/chat",
headers: async () => ({
Authorization: `Bearer ${await getAgentToken()}`,
}),
});
export function SupportChat() {
return <AssistantChat runtime={runtime} threadId="support" />;
}
```
إذا كانت نقطة النهاية لديك تقوم بالفعل ببث بروتوكول وكيل مشترك، فاستخدم المطابقة
الموصل وتخطي كتابة مخطط مخصص:
```ts
import {
createAgUiChatRuntime,
createClaudeAgentChatRuntime,
createOpenAIAgentsChatRuntime,
createOpenAIResponsesChatRuntime,
createVercelAiChatRuntime,
} from "@agent-native/core/client/agent-chat";
const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
endpoint: "/api/openai-agents/chat",
});
const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
endpoint: "/api/openai-responses/chat",
});
const claudeAgentRuntime = createClaudeAgentChatRuntime({
endpoint: "/api/claude-agent/chat",
});
const vercelAiRuntime = createVercelAiChatRuntime({
endpoint: "/api/vercel-ai/chat",
});
const agUiRuntime = createAgUiChatRuntime({
endpoint: "/api/ag-ui/chat",
});
```
قد تقوم نقطة النهاية ببث شكل الحدث المقيس مباشرة:
```text
data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
data: {"type":"done","reason":"complete"}
```
بالنسبة للوكلاء البسيطين جدًا، يتم قبول استجابة JSON `{ "text": "..." }` و
تم تحويلها إلى رسالة مساعد واحدة. بالنسبة للعملاء الأكثر ثراءً، قم بالبث
`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
أحداث `usage` و`error` و`done`. يمكن أن تحمل نتائج الأداة `mcpApp` أو
البيانات التعريفية `chatUI`، لذلك لا تزال عناصر واجهة المستخدم الأصلية المعلنة عن الإجراء يتم عرضها بدون
إطارات iframe.
عندما تريد نقل Agent-Native المدمج ككائن وقت التشغيل، استخدم:
```ts
import { createAgentNativeChatRuntime } from "@agent-native/core/client/agent-chat";
const runtime = createAgentNativeChatRuntime({
threadId: "forms-chat",
mode: "act",
});
```
استخدم `<AssistantChat createTransport={...} />` لنقل AgentKit مخصص، أو مرّر `runtime` عندما يدير المضيف تنفيذ الأدوار. يجب نقل تطبيقات `assistant-ui ChatModelAdapter` الحالية إلى `AgentTransport` أو `AgentChatRuntime` لاستخدام سجل محادثات AgentKit ومؤلفه. استخدم `PromptComposer` بمفرده عندما يمتلك منتجك السجل الخارجي بالكامل ويريد حقل Agent-Native فقط.
لخريطة واجهات API القديمة والجديدة وخطوات النقل، راجع [دليل نقل دردشة AgentKit](https://github.com/BuilderIO/agent-native/blob/main/packages/core/docs/migrations/agentkit-chat.md).
يمكن لتدفقات OpenAI وAG-UI وClaude Agent SDK وVercel AI SDK استخدام المعيار
مساعدو الموصل. يظل ACP قابلية التشغيل التفاعلي لعامل الترميز/المحرر، وليس
وقت التشغيل العام للدردشة التطبيقية للمستخدمين النهائيين. لم تتم المطالبة بـ A2UI على أنه مدعوم هنا؛
إذا نضجت، فيجب أن تتكيف مع نفس العقد الصريح لوقت التشغيل/الأداة.
## المستندات ذات الصلة {#related-docs}
- [Actions](/docs/actions-overview) — حدد العمليات التي تُرجع بيانات عنصر واجهة المستخدم الأصلية.
- [Agent Surfaces](/docs/agent-surfaces) - حدد ما إذا كنت بحاجة إلى التطبيق بدون رأس، أو الدردشة، أو السيارة الجانبية، أو التطبيق الكامل.
- [Drop-in Agent](/docs/drop-in-agent) — البرنامج التعليمي لتثبيت وقت التشغيل القياسي للدردشة.
- [Component API](/docs/components) — خريطة API لكل عملية تصدير لطبقات الدردشة، وأوقات التشغيل، وعارضي الأدوات.
- [MCP Apps](/docs/mcp-apps) — UI المضمّن لمضيفي MCP الخارجيين.
- [Key Concepts](/docs/key-concepts#protocols) — حالة البروتوكول وتحديد المواقع.
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 |