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/actions-other-surfaces.mdx
View on GitHub---
title: "أسطح أخرى"
description: "كل ما يستدعي action غير خطافات واجهة المستخدم: نتائج عناصر واجهة المحادثة الأصلية، وCLI، وA2A، وMCP، وactions القياسيان الاثنان اللذان يشحنهما كل قالب."
---
# أسطح أخرى
يُغطّى سطح خطافات واجهة المستخدم في [البيانات والمزامنة](/docs/client-data): `useActionQuery()` و`useActionMutation()` و`callAction()`. تغطي هذه الصفحة كل شيء آخر يمكنه استدعاء action أو أن يُدار بواسطته.
## عرض واجهة المحادثة الأصلية {#native-chat-ui}
يمكن لـ actions إرجاع بيانات عنصر واجهة منظَّمة تعرضها محادثة التطبيق أصليًا. هذا هو مسار المحادثة الأساسي للجداول والمخططات وملخصات الإعداد وبطاقات الرؤى القابلة لإعادة الاستخدام. استخدم [واجهة المستخدم التوليدية](/docs/generative-ui) عندما يحتاج الوكيل إلى توليد عناصر تحكم تفاعلية عشوائية داخل محادثة التطبيق، واستخدم [تطبيقات MCP](/docs/mcp-apps) لواجهة مستخدم مضمَّنة في مضيفي MCP الخارجيين.
```ts
import { defineAction } from "@agent-native/core/action";
import { ACTION_CHAT_UI_DATA_CHART_RENDERER } from "@agent-native/core/action-ui";
import {
createDataChartWidgetResult,
dataChartWidgetResultSchema,
} from "@agent-native/core/data-widgets";
export default defineAction({
description: "Summarize response trends.",
readOnly: true,
outputSchema: dataChartWidgetResultSchema,
chatUI: { renderer: ACTION_CHAT_UI_DATA_CHART_RENDERER },
run: async () =>
createDataChartWidgetResult({
title: "Response trends",
chartSeries: {
type: "line",
xKey: "day",
series: [{ key: "responses", label: "Responses" }],
data: [
{ day: "Mon", responses: 12 },
{ day: "Tue", responses: 18 },
],
},
}),
});
```
المُميِّزات المدمجة هي `"data-table"` و`"data-chart"` و`"data-insights"`، مع
أدوات بناء ومخططات آمنة من جانب الخادم في `@agent-native/core/data-widgets`.
استخدم `data-chart` للإجابات المخصصة للمخططات فقط، و`data-table` لنتائج
SQL/القوائم، و`data-insights` فقط عندما تكون بطاقة ملخص/مخطط/جدول مجمَّعة هي
المخرج الصحيح. راجع
[واجهة المحادثة الأصلية](/docs/native-chat-ui) للاطلاع على عقد النتيجة الكامل، أو
[أنظمة تشغيل وكيل خاصة بك](/docs/native-chat-ui#byo-agent-runtimes) إذا كنت
تربط نظام تشغيل وكيل مخصصًا بدلاً من حلقة المحادثة المدمجة. راجع
[واجهات الوكيل](/docs/agent-surfaces) لمعرفة كيف يمكن لـ action نفسه أن يبقى
ملائمًا للأتمتة، أو يُعرض في المحادثة، أو ينمو إلى شاشة كاملة.
## استدعاؤه من CLI {#cli}
كل action قابل للتشغيل عبر `pnpm action`:
```bash
pnpm action reply-to-email '{"emailId":"thread-123","body":"Thanks!"}'
```
مدخل JSON هو الشكل المفضَّل للوكلاء والكائنات المعقَّدة. تعمل الأعلام
بالطريقة نفسها للتشغيلات اليدوية البسيطة والنصوص البرمجية الحالية:
```bash
pnpm action reply-to-email --emailId thread-123 --body "Thanks!"
```
لاستدعاءات `defineAction()`، يقيّم CLI قيمة `needsApproval` على الوسائط المُجهّزة والمحلّلة بعد تطبيق القيم الافتراضية للمخطط، مع المستدعي `cli`. إذا كان كل من stdin وstdout طرفية TTY، يعرض اسم الإجراء والوسائط ويطلب `y/N`. لا يُنفّذ الإجراء إلا عند إدخال `y` أو `yes`.
عند غياب أي من طرفيتي TTY، يطلب CLI من الوكيل أن يسأل الشخص عن الموافقة. بعد موافقة الشخص على هذا الاستدعاء المحدد، أعد تشغيل وسائط أمر `pnpm action` الأصلي نفسها تمامًا مع إضافة `--approved` في النهاية:
```bash
pnpm action reply-to-email --emailId thread-123 --body "Thanks!" --approved
```
`--approved` بيانات وصفية محجوزة لـ CLI وتُحذف قبل تحليل الإدخال. ولا تأخذ قيمة: يُرفض الاستدعاء إذا تلاها شيء غير علامة أخرى أو كائن JSON، ويُكتب الإدخال المسمى `approved` بالصيغة `--approved=<value>`. وهي غير ضارة للإجراءات التي لا تتطلب موافقة. لا يستطيع CLI التحقق ممن أضافها: الوكيل الذي يضيفها دون أن يسأل يتخطى التأكيد. تُبقي هذه العلامة الموافقة ظاهرة في الأمر الذي يوافق عليه الشخص وفي سجل التدقيق، الذي يعرضها على أنها غير موثّقة. على Windows من دون `SHELL` من نوع POSIX، تعرض رسالة الرفض الأمر لـ PowerShell، ولـ cmd.exe أيضًا عندما تختلف علامات الاقتباس. وعلى Windows، يمرّر pnpm وسائط الإجراء عبر cmd.exe من أي shell، ويوسّع cmd.exe المتغيرات `%NAME%` حتى داخل علامات الاقتباس. فإذا احتوت إحدى الوسائط على متغير كهذا، لا تعرض رسالة الرفض أمر إعادة تشغيل مع `--approved`: يشغّل الشخص الأمر في الطرفية ويتحقق من القيم عند التأكيد. وإذا احتوت الوسائط على علامة اقتباس وأحد الرموز `&` أو `|` أو `<` أو `>` أو `^`، فلا يستطيع pnpm تمريرها عبر cmd.exe كما هي، لذلك لا تعرض رسالة الرفض أي أمر، ويوافق الشخص على الاستدعاء في التطبيق بدلًا من ذلك. ويحذف Windows PowerShell 5.1 كل `"` داخل الوسيطة، لذلك على Windows من دون `SHELL` من نوع POSIX، تذهب الوسيطة التي تحتوي على علامة اقتباس مزدوجة أيضًا إلى التأكيد بدلًا من إعادة التشغيل مع `--approved`.
يرسل جسر التطوير المحلي بيانات الموافقة الوصفية خارج `input` في متن JSON:
```ts
{ name, input, approved: true, approvalSource: "flag" }
```
لاستدعاء يتطلب موافقة ولم يحصل عليها، يعيد الجسر HTTP `409`:
```ts
{
ok: false,
errorCode: "approval_required",
error: 'Action "<name>" requires human approval. Ask the person, then rerun with --approved.',
arguments: preparedArgs,
argumentsHash: prepared.argumentsHash,
}
```
بعد التأكيد عبر TTY، تعيد CLI المحاولة باستخدام `argumentsHash` من استجابة طلب الموافقة:
```ts
{
name,
input,
approved: true,
approvalSource: "prompt",
approvalArgumentsHash: challenge.argumentsHash,
}
```
ينفّذ الجسر الاستدعاء الذي راجعه الشخص مرة واحدة فقط، لذا تحتفظ القيمة الافتراضية التي تتغير مع كل استدعاء، مثل الطابع الزمني، بالقيمة التي رآها. أما التأكيد الذي لا يجد استدعاءً محفوظًا لتنفيذه (لأنه نُفّذ من قبل، أو مرّت 10 دقائق، أو أُعيد تشغيل خادم التطوير) فيتلقى HTTP `409` مع `errorCode: "approval_expired"`. شغّل الأمر مجددًا لمراجعته.
تحتوي `arguments` على الوسائط المُجهّزة. لا يغيّر عقد جسر التطوير المحلي هذا [قواعد الموافقة لواجهة HTTP العامة للإجراءات](/docs/actions-access-control#needs-approval). يسجّل استدعاء CLI المحمي والموافق عليه `approval: "cli-prompt"` أو `approval: "cli-flag"` في صف التدقيق الخاص بالإجراء نفسه، مع المستدعي `cli`. ولأن CLI وحده يرى المطالبة، يعرض سجل التدقيق كليهما على أنهما غير موثّقين.
## استدعاؤه من وكيل آخر (A2A) {#a2a}
إذا كان تطبيقك نظيرًا في [A2A](/docs/a2a-protocol)، تكتشف تطبيقات agent-native أخرى actions الخاصة بك تلقائيًا ويمكنها استدعاءها بالاسم. تتخطى عمليات النشر من الأصل نفسه توقيع JWT. تستخدم عمليات النشر عبر الأصول `A2A_SECRET` مشتركًا بدلاً من ذلك.
## تعريضه عبر MCP {#mcp}
مع تفعيل MCP، تظهر actions الخاصة بك في خادم MCP التابع لإطار العمل عند `/mcp`. يحصل كل مستدعٍ على كتالوج مُختصر بشكل افتراضي (الأدوات المدمجة الموجَّهة للتطبيق بالإضافة إلى actions التطبيق المُعلَنة في القالب)، وتكون `tool-search` حاضرة دائمًا بحيث تبقى أي أداة أخرى قابلة للوصول عند الطلب. لا يُقدَّم سطح actions الكامل إلا بالاشتراك الصريح (رمز `--full-catalog` أو `AGENT_NATIVE_MCP_FULL_CATALOG=1`)، ويُدخل [`publicAgent.expose`](/docs/actions-access-control#public-agent) أداة قراءة/استيعاب آمنة إلى السطح العام. راجع [بروتوكول MCP](/docs/mcp-protocol) للاطلاع على مستويات الكتالوج، والمصادقة، وتفاصيل مورد `mcpApp`.
بالنسبة إلى مضيفي MCP القادرين على عرض واجهة المستخدم، يمكن لـ action الإعلان عن مورد تطبيقات MCP اختياري عبر حقل `mcpApp` (بالإضافة إلى `link` مطابق) بحيث تعرض المضيفات القادرة النتيجة مضمَّنة. عندما ينبغي أن يشير `link` و`mcpApp` إلى المسار نفسه، يبني `embedRoute()` كليهما من دالة بناء مسار نقية واحدة:
```ts
import { embedRoute } from "@agent-native/core";
export default defineAction({
description: "Create an email draft for review.",
schema: z.object({ body: z.string() }),
run: async ({ body }) => ({ body }),
...embedRoute({
title: "Review draft",
openLabel: "Open in Mail",
path: ({ result }) => ({
label: "Open draft in Mail",
url: "/_agent-native/open?app=mail&view=inbox",
}),
}),
});
```
أبقِ `link` كخيار احتياطي لـ CLI ومضيفي MCP غير القادرين على عرض واجهة المستخدم. وهو أيضًا هدف الإطلاق الخاص بالتضمين. جسر التضمين (جلسة بدء التضمين الموقَّعة، وعرض النقل مقابل الإطار المتحكَّم به، وجسر المضيف `ui/*`، وCSP، وتقييد الارتفاع) تملكه [الوكلاء الخارجيون](/docs/external-agents#mcp-app-bridge).
لا يوجد فحص تلقائي للتأكد من أن قالبًا ما يحتوي على `view-screen` أو `navigate` أو مجموعة create/read/update/list الخاصة بموردِه الأساسي؛ يشحن الهيكل الأساسي `view-screen` و`navigate`، ويرفض `pnpm guard:external-result-contract` أي صياغة "انتظر المستخدم" في `description` أو `nextRequiredAction` لإجراء مكشوف خارجيًا، ويشترط رابطًا عميقًا لأي إجراء `create-*` جديد مكشوف خارجيًا. وجودها بند مراجعة.
## Actions قياسية {#standard-actions}
ينبغي أن يتضمن كل قالب هذين الاثنين من أجل [الوعي بالسياق](/docs/context-awareness).
### view-screen {#view-screen}
يقرأ حالة التنقل الحالية، ويجلب بيانات سياقية، ويُرجع لقطة لما يراه المستخدم. يستدعي الوكيل هذا عندما يحتاج إلى نظرة حديثة على الشاشة.
```ts
// actions/view-screen.ts
import { defineAction } from "@agent-native/core/action";
import { readAppState } from "@agent-native/core/application-state";
import { z } from "zod";
export default defineAction({
description: "Read the current screen state for context.",
schema: z.object({}),
http: { method: "GET" },
run: async () => {
const navigation = await readAppState("navigation");
const screen: Record<string, unknown> = { navigation };
if (navigation?.view === "inbox") {
screen.emailList = await listEmailsForLabel(navigation.label);
}
return screen;
},
});
```
### navigate {#navigate}
يكتب أمر تنقل لمرة واحدة إلى حالة التطبيق. تقرأه واجهة المستخدم، وتتنقل، وتحذف الإدخال.
```ts
// actions/navigate.ts
import { defineAction } from "@agent-native/core/action";
import { writeAppState } from "@agent-native/core/application-state";
import { z } from "zod";
export default defineAction({
description: "Navigate the user to a view.",
schema: z.object({
view: z.string(),
threadId: z.string().optional(),
}),
run: async (args) => {
await writeAppState("navigate", args);
return { ok: true };
},
});
```
## ما هي الخطوة التالية
- [**البيانات والمزامنة**](/docs/client-data) — `useActionQuery` و`useActionMutation` و`callAction` من واجهة المستخدم
- [**نظرة عامة**](/docs/actions-overview) — ما هو action وجولة hello-world
- [**الوعي بالسياق**](/docs/context-awareness) — نمط `view-screen` + `navigate` بالتفصيل
- [**بروتوكول A2A**](/docs/a2a-protocol) — كيف تكتشف الوكلاء الآخرون actions الخاصة بك وتستدعيها
- [**بروتوكول MCP**](/docs/mcp-protocol) — مستويات الكتالوج، والمصادقة، وموارد `mcpApp`
- [**واجهة المستخدم التوليدية**](/docs/generative-ui) — عرض واجهة مستخدم مولَّدة مؤقتة أو محفوظة مضمَّنة في المحادثة
- [**الدردشة الأصلية UI**](/docs/native-chat-ui) — عقد نتيجة عنصر الواجهة الكامل
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: 472k | 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 |