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-defining.mdx
View on GitHub---
title: "تعريف Actions"
description: "تشريح defineAction(): المخطط، وrun، وإعداد HTTP، بالإضافة إلى كيفية إبقاء سطح actions صغيرًا."
---
# تعريف Actions
يبدأ كل action باستدعاء `defineAction()`. فهو يجمع وصفًا للوكيل، ومخططًا يتحقق من صحة المدخلات، ودالة `run` تقوم بالعمل الفعلي، بحيث تستدعي واجهة المستخدم والوكيل الكود نفسه تمامًا.
<AnnotatedCode
id="doc-block-actions-defining-1"
title="تشريح action"
filename="actions/reply-to-email.ts"
language="ts"
code={
'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n description: "Reply to an email thread in the user\'s voice.",\n schema: z.object({\n emailId: z.string().describe("The id of the email to reply to."),\n body: z.string().describe("The reply body, in markdown."),\n }),\n run: async ({ emailId, body }) => {\n const db = getDb();\n await db.insert(schema.replies).values({ emailId, body });\n return { ok: true, emailId };\n },\n});'
}
annotations={[
{
lines: "7",
label: "سطح الأداة",
note: "`description` هو ما يقرأه الوكيل ليقرر متى يستدعي هذا. تتدفق استدعاءات `.describe()` لكل حقل إلى JSON Schema أيضًا.",
},
{
lines: "8-11",
label: "عقد محدد الأنواع",
note: "يتحقق مخطط واحد من صحة المدخلات من **كل** سطح، ويُحوَّل إلى JSON Schema للنموذج. لا تصل المدخلات غير الصالحة أبدًا إلى `run`.",
},
{
lines: "12-16",
label: "تطبيق واحد",
note: "جسم `run` هو المصدر الوحيد للحقيقة. ينفّذ كل من زر واجهة المستخدم وأداة الوكيل هذا الجسم بالضبط. يأتي `getDb()` و`schema` من `server/db/index.ts` الخاص بتطبيقك. راجع [قاعدة البيانات](/docs/server-database).",
},
]}
/>
يكتشف إطار العمل تلقائيًا كل ملف في `actions/` ويركّبه عند بدء التشغيل. لا يوجد شيء آخر يجب تسجيله يدويًا.
<Signature
id="doc-block-actions-defining-2"
name="defineAction"
params={[
{
name: "config",
type: "DefineActionConfig<TSchema, TReturn, TOutputSchema>",
description:
"كل ما يلي هو كائن تكوين واحد. description وschema وrun فقط مطلوبة.",
fields: [
{
name: "description",
type: "string",
description: "ما يقرأه الوكيل ليقرر متى يستدعي هذا الـ action.",
},
{
name: "schema",
type: "StandardSchemaV1",
description:
"يتحقق من صحة المدخلات على كل سطح. راجع خيارات المخطط أدناه.",
},
{
name: "run",
type: "(args, ctx?) => Promise<TReturn> | TReturn",
description:
"التطبيق الوحيد الذي يستدعيه كل سطح. راجع سياق التشغيل لمعرفة وسيطة ctx.",
},
{
name: "http",
type: "ActionHttpConfig | false",
optional: true,
description:
"يتجاوز طريقة/مسار التركيب، أو يعطّل نقطة نهاية HTTP بالكامل. راجع إعداد HTTP أدناه.",
},
{
name: "readOnly",
type: "boolean",
optional: true,
default: "false",
description:
"يصبح صحيحًا تلقائيًا عندما تكون http.method هي GET. يتخطى إعادة تحديث الاستقصاء الخاصة بواجهة المستخدم وتدقيق الكتابة. ليس تحكمًا في الوصول.",
},
{
name: "outputSchema",
type: "StandardSchemaV1",
optional: true,
description:
"يتحقق من صحة ما تُرجعه run(). راجع التحقق من صحة القيمة المرجعة أدناه.",
},
{
name: "outputErrorStrategy",
type: '"strict" | "warn" | "fallback"',
optional: true,
default: '"strict"',
description: "ما الذي يحدث عند عدم تطابق الإخراج.",
},
{
name: "outputFallback",
type: "TReturn",
optional: true,
description:
'مُهمَل. تُرجَع بدلاً من نتيجة غير صالحة عندما تكون outputErrorStrategy هي "fallback".',
},
{
name: "errors",
type: "ActionErrors",
optional: true,
description:
"المجموعة المغلقة من رموز الخطأ الخاصة بالـ action، من defineActionErrors. راجع إعلان رموز الخطأ أدناه.",
},
{
name: "mcpOutputSchema",
type: "boolean",
optional: true,
default: "false",
description:
'يعلن outputSchema لعملاء MCP ويتحقق من كل نتيجة مقابله. يتطلب outputErrorStrategy بالقيمة "strict".',
},
{
name: "parallelSafe",
type: "boolean",
optional: true,
description:
"يسمح لـ action يغيّر البيانات بالعمل بالتزامن مع استدعاءات أدوات أخرى في الدور نفسه.",
},
{
name: "retrySafe",
type: "boolean | ((input) => boolean)",
optional: true,
description:
"عندما تكون true (أو عندما تُرجع الدالة الشرطية true)، يكون الفشل بعد كتابة هذا الإجراء نفسه فشلًا معروفًا يمكن للنموذج تصحيحه وإعادة المحاولة، بدلًا من حظر الأداة لبقية الدور الحالي. اخصصه للإجراءات الآمنة لإعادة التشغيل بعد أي خطأ. الرفض قبل أي كتابة لا يحتاج إلى هذا الخيار. راجع الكتابات الآمنة لإعادة المحاولة أدناه.",
},
{
name: "agentTool",
type: "boolean",
optional: true,
default: "true",
description:
"اضبطه على false لإخفائه عن كل قائمة أدوات الوكيل. راجع الوصول والتخويل.",
},
{
name: "mcpTool",
type: "boolean",
optional: true,
default: "agentTool",
description:
"يرث `agentTool`. اضبطه على false لإخفائها عن الوكلاء الخارجيين عبر MCP وA2A، أو على true لإعلان انتمائها إلى الفهرس المنتقى. راجع الوصول والتخويل.",
},
{
name: "endsTurn",
type: "boolean",
optional: true,
default: "false",
description:
"اضبطه على true عندما يسلّم استدعاء ناجح التحكم إلى المستخدم (نموذج سؤال، حوار استقبال)؛ اجعله أول استدعاء أو الاستدعاء الوحيد في الدورة. مخفي عن MCP وWebMCP وA2A ما لم يُضبط mcpTool: true — لا يمكن لمستدعٍ خارجي أن يتلقى إجابة داخل التطبيق. راجع الوكلاء الخارجيون.",
},
{
name: "link",
type: "(result) => { url, label }",
optional: true,
description:
"مُنشئ رابط عميق نقي ومتزامن، تقرؤه مضيفات MCP وتطبيق سطح المكتب. راجع أسطح أخرى.",
},
{
name: "mcpApp",
type: "object",
optional: true,
description:
"يضمّن مسار التطبيق الحقيقي مضمّنًا داخل مضيفات MCP-App. راجع أسطح أخرى.",
},
{
name: "deferLoading",
type: "boolean",
optional: true,
description:
"اضبطه على false لإبقاء الـ action في أول قائمة أدوات للوكيل، أو على true ليُحمَّل عند الحاجة عبر tool-search. راجع «أبقِ سطح actions صغيرًا» أدناه.",
},
{
name: "toolCallable",
type: "boolean",
optional: true,
default: "true",
description:
"اضبطه على false لحظر جسر iframe المعزول الخاص بالامتداد. راجع الوصول والتخويل.",
},
{
name: "publicAgent",
type: "PublicAgentActionConfig",
optional: true,
description:
"{ expose: true } يضيف الـ action إلى أسطح MCP/A2A/OpenAPI العامة. راجع الوصول والتخويل.",
},
{
name: "needsApproval",
type: "boolean | ((args, ctx?) => boolean | Promise<boolean>)",
optional: true,
default: "false",
description:
"يوقف حلقة الوكيل مؤقتًا لانتظار موافقة الإنسان قبل run(). راجع موافقات الإنسان في الحلقة.",
},
{
name: "authorize",
type: "ActionAuthorize<TInput>",
optional: true,
description:
"دالة حارسة تقرر ما إذا كان يجوز لهذا المستدعي تشغيل الـ action أصلًا. راجع الوصول والتخويل.",
},
{
name: "audit",
type: "ActionAuditConfig",
optional: true,
description:
"يضبط التقاط التدقيق التلقائي الذي يحصل عليه بالفعل كل action يغيّر البيانات. راجع سجل التدقيق.",
},
{
name: "chatUI",
type: "ActionChatUIConfig",
optional: true,
description:
"يعلن عن عارض واجهة محادثة أصلية لنتيجة الـ action. راجع أسطح أخرى.",
},
],
},
]}
returns={{
type: "ActionDefinition<TInput, TReturn>",
description: "تعريف action محدد الأنواع. صدّره كتصدير افتراضي للملف.",
}}
/>
## خيارات المخطط {#schemas}
يقبل `schema` أي مكتبة متوافقة مع [Standard Schema](https://standardschema.dev):
- **Zod** (v4): الخيار الأكثر شيوعًا، مع أفضل استنتاج للأنواع وتحويل تلقائي إلى JSON Schema.
- **Valibot**: خيار جيد عندما يهم حجم الحزمة.
- **ArkType**: خيار جيد إذا كنت تفضّل صيغته.
يقوم المخطط بمهمتين. يحوّل إلى JSON Schema لتعريف أداة Claude API، ويتحقق من صحة المدخلات في وقت التشغيل قبل إطلاق `run()`. لا تصل المدخلات غير الصالحة أبدًا إلى المعالج الخاص بك.
يجب أن تكون الوسائط بعد التحقق بيانات بسيطة: كائنات ومصفوفات وسلاسل نصية وأرقام وقيم منطقية و`null` و`undefined` وBigInt وقيم Date صالحة. ينسخها الإطار مرة واحدة ويحسب تجزئة تلك النسخة، وترتبط بها الموافقات وإعادات التشغيل. يحصل كل فحص يقرأ الوسائط، و`run()` نفسها، على نسخة خاصة به، لذا يمكن للمعالج تعديل `args` بأمان. إذا احتوى ناتج المخطط على أي شيء آخر (getter أو setter، أو `Map` أو `Set`، أو نسخة من فئة مثل `URL` أو `Buffer`، أو دالة)، يفشل كل استدعاء باعتباره غير صالح قبل الموافقة أو `run()`، مع خطأ يسمّي الوسيط. يجب أن تعيد التحويلات في مخططك، أو في مخطط خارجي تستخدمه، بيانات بسيطة؛ أنشئ القيم الأغنى داخل `run()`. تنطبق هذه القواعد على الاستدعاءات التي توجّهها حلقة الوكيل ووضع التخطيط ومسارات إجراءات HTTP وMCP؛ أما الاستدعاء المباشر لـ `action.run()`، مثل إجراء يستدعي إجراءً آخر أو جسر إجراءات التطوير، فلا يحصل إلا على التحقق من المخطط.
اذكر قيم enum والقيم الافتراضية في `.describe()`، وحافظ على تطابق اسم المعرّف الأساسي عبر عائلة الأدوات (`id`، وليس مزيجًا من `id`/`deckId`)، واجعل الوصف المكوَّن من سطر واحد كافيًا لاستدعاء الأداة من فهرس مُختصر — سكِل `actions` المُضمَّنة في كل تطبيق تحمل قائمة التحقق.
## التحقق من صحة القيمة المرجعة {#output-schema}
يتحقق `schema` من صحة _المدخلات_. للتحقق أيضًا مما **تُرجعه** action، مرّر `outputSchema` (أي مخطط متوافق مع Standard Schema: Zod، أو Valibot، أو ArkType، السطح نفسه المستخدم في `schema`). يتحقق إطار العمل من صحة المدخل قبل `run()` ومن صحة النتيجة بعد أن يُحلّ `run()`.
```ts
export default defineAction({
description: "Summarize a thread.",
schema: z.object({ threadId: z.string() }),
outputSchema: z.object({
summary: z.string(),
messageCount: z.number(),
}),
run: async ({ threadId }) => {
/* ...returns { summary, messageCount } ... */
},
});
```
يأتي نوع القيمة المرجعة للـ action من `outputSchema`، ويجب أن تُرجع `run` قيمة يقبلها المخطط، لذا فإن النتيجة التي تنحرف عن المخطط تكون خطأ في الترجمة قبل أن تكون خطأ في وقت التشغيل.
`outputErrorStrategy` controls what happens on a mismatch:
| الاستراتيجية | السلوك عند عدم التطابق |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| `"strict"` | **الافتراضي.** يطرح `ActionOutputContractError`، بحيث يفشل أي خلل في الـ action بوضوح. |
| `"warn"` | ينفّذ `console.warn` للمشكلات ويُرجع النتيجة **الأصلية** دون تغيير. استخدمه أثناء إصلاح المخطط. |
| `"fallback"` | **مُهمَل.** يُرجع `outputFallback` بدلاً من النتيجة غير الصالحة، ولا يستطيع المستدعون تمييزها عن نتيجة حقيقية. |
عندما تنجح `run()`، يُرجع إطار العمل القيمة التي تم التحقق من صحتها، بحيث تسري أي قيم افتراضية أو تحويلات على `outputSchema`، بالطريقة نفسها التي تسري بها على المدخل. عندما لا تمرّر `outputSchema`، تبقى القيمة المرجعة دون تغيير.
يجري التحقق الصارم بعد `run()`، لذا يصف الخطأ (`ActionOutputContractError`، `errorCode: "output_contract_violation"`) ما حدث بالفعل: تكون قيمة `effect` هي `"committed"` بمجرد أن تدخل عملية كتابة إلى معالجها، في الاستدعاء نفسه أو في action استدعاها (حتى من action للقراءة فقط)، ويجب ألا يعيد المستدعون محاولتها؛ وفي غير ذلك تكون `"none"`. لا تذكر الرسالة سوى مسارات الحقول المعلنة ورموز المشكلات، ولا تتضمن القيم المُعادة أبدًا.
### إعلان رموز الخطأ {#error-codes}
يعلن `defineActionErrors` المجموعة المغلقة من قيم `errorCode` التي قد تفشل بها الـ action. لا تقبل الدالتان `fail` و`noWrite` سوى هذه الرموز، لذا لا يُترجَم رمز مكتوب بشكل خاطئ، ويؤدي تمريرها بوصفها `errors` إلى نشر الرموز بوصفها `errorCodes` على التعريف.
```ts
const errors = defineActionErrors("thread_not_found", "thread_locked");
export default defineAction({
description: "Archive a thread.",
schema: z.object({ threadId: z.string() }),
outputSchema: z.object({ archived: z.literal(true) }),
errors,
run: async ({ threadId }) => {
const thread = await findThread(threadId);
if (!thread) {
errors.noWrite("Thread not found.", "thread_not_found", {
statusCode: 404,
});
}
/* ... */
return { archived: true };
},
});
```
### إعلان العقد عبر MCP {#mcp-output-schema}
لا يرى عملاء MCP أي `outputSchema` افتراضيًا، لأن المخطط في وضع `"warn"` غير مُلزِم. بعد أن تتحقق من أن كل نتيجة حقيقية مطابقة، اضبط `mcpOutputSchema: true` مع `outputErrorStrategy: "strict"`. عندها تعلن الأداة المخطط بالشكل الذي يتلقاه عملاء MCP — يُغلَّف الجذر من نوع المصفوفة في صورة `{ items }`، وتحصل الإجراءات التي لها `link` على `openLink` و`url` — وتتحقق من كل `structuredContent` مقابله قبل إعادته. يجب أن يكون الجذر كائنًا، أو اتحادًا من الكائنات فقط، أو مصفوفة؛ ولا يمكن للمخططات التي تحتوي على تحويلات الاشتراك. يراعي المخطط المُعلن أيضًا ما يحجبه MCP: تُحذف حقول تذاكر التضمين، ويصل النص الذي يحمل رابط بدء تضمين بالقيمة `"[hidden embed URL]"`، فتبقى الحقول المطلوبة مطلوبة. لا يمكن للمخطط الاشتراك إذا استخدم كلمة مفتاحية أو `format` لا يستطيع التحقق فرضها، مثل `not` أو `$async` أو تنسيق غير معروف؛ أو إذا كان الحجب قد يكسر أحد قيوده `const` أو `enum` أو `uniqueItems`؛ أو إذا كان للإجراء `link` وكان جذر المخطط يقيّد أسماء خصائصه أو عددها.
## عقود النتيجة {#result-contracts}
تُقرأ نتيجة الإنشاء أو التحديث من قِبل أكثر من مستدعيها. أرجِع `id` (حتى يتمكن `link` من بناء رابط عميق إلى واجهة التحرير)، و`message` من سطر واحد، و — عندما تكون العملية خطوة واحدة ضمن تدفق ينبغي على الوكيل مواصلة قيادته — `nextRequiredAction` يسمّي الأداة التالية. لا تصغه أبدًا وكأنه ينتظر المستخدم: لا يمكن لمستدعي MCP/WebMCP/A2A تلقي إجابة داخل التطبيق. تحافظ حلقة الوكيل على `nextRequiredAction` في مطالبات المتابعة حتى عندما تُقتطَع نتيجة كبيرة، ويراها مستدعو MCP كـ `Next: …`.
## إعداد HTTP {#http}
بشكل افتراضي، يُعرَض كل action كـ `POST /_agent-native/actions/<name>`. تجاوز ذلك عبر خيار `http`:
```ts
export default defineAction({
description: "Get details for a lead.",
schema: z.object({ leadId: z.string() }),
http: { method: "GET" },
run: async ({ leadId }) => {
return await db.select().from(leads).where(eq(leads.id, leadId));
},
});
```
بالنسبة إلى action من نوع `GET`، يُمرَّر `leadId` كمعلمة استعلام: `/_agent-native/actions/get-lead?leadId=abc`.
<Endpoint id="doc-block-actions-defining-3" title="نقطة نهاية action المثبَّتة تلقائيًا" method="GET" path="/_agent-native/actions/get-lead" summary={"يتم تركيب كل action هنا تلقائيًا. اسم الملف هو اسم الـ action."} auth={"ملف تعريف ارتباط الجلسة (تحمل استدعاءات الواجهة الأمامية `X-Agent-Native-Frontend: 1`)، أو `Authorization: Bearer <token>` للمستدعين الخارجيين"} params={[
{
"name": "leadId",
"in": "query",
"type": "string",
"required": true,
"description": "تصل وسائط GET كمعلمات استعلام. تصل وسائط POST في جسم JSON."
}
]} responses={[
{
"status": "200",
"description": "القيمة المرجعة لـ action بصيغة JSON."
},
{
"status": "400",
"description": "فشل المدخل في التحقق من صحة المخطط قبل إطلاق run()."
}
]}>
POST هو الافتراضي، ويجعله `http: { method: "GET" }` GET. تستدعي خطافات React و`callAction()` دائمًا هذا المسار بالاسم، بغض النظر عن أي تجاوز لـ `http.path`. يمكن للأنظمة الخارجية استدعاء المسار نفسه برمز حامل طويل الأمد. راجع [HTTP API](/docs/http-api).
</Endpoint>
- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`**: الافتراضي `POST`. تُعلَّم actions من نوع `GET` تلقائيًا بـ `readOnly`، لذا لا يؤدي الاستدعاء الناجح إلى تحفيز إعادة تحديث الاستقصاء في واجهة المستخدم.
- **`http: { path: "..." }`**: يتجاوز عنوان URL المثبَّت تحت `/_agent-native/actions/`. الافتراضي هو اسم الملف. لا يغيّر هذا التجاوز العنوان إلا للمستدعين المباشرين عبر HTTP. تستدعي `useActionQuery()` و`useActionMutation()` و`callAction()` دائمًا `/_agent-native/actions/<name>`، بغض النظر عن هذا التجاوز، لذا فإن تجاوز المسار يجعل هذه الخطافات تُرجع 404. استخدم تجاوز المسار فقط للمستدعين الخارجيين عبر HTTP. لاحظ أيضًا أن أجزاء المسار `:param` في مسار التجاوز لا تُحلَّل إلى وسائط `run()`. فقط معلمات سلسلة الاستعلام وحقول جسم JSON تُحلَّل.
- **`http: false`**: يعطّل نقطة نهاية HTTP بالكامل. فقط الوكيل وCLI يمكنهما استدعاء الـ action.
- **`readOnly: true`**: يتخطى إعادة تحديث الاستقصاء صراحة، حتى لأجل actions من نوع POST لا تغيّر أي شيء. هذا ليس تحكمًا في الوصول. فهو لا يقيّد من يمكنه استدعاء الـ action، ولا يؤثر على `useActionQuery()` أو `useActionMutation()` أو أي خطاف عميل. تأثيراه الوحيدان هما كبت حدث إعادة التحديث بعد الاستدعاء، واستبعاد الـ action من تدقيق الكتابة. ومع ذلك تبقى action الكتابة التي يستدعيها عملية كتابة: بمجرد تشغيلها يُطلق الاستدعاء إعادة التحديث، ويُبلغ الاستدعاء الفاشل عن `effect: "committed"`. لإخفاء action عن النموذج، استخدم `agentTool: false`. للتحكم في من يمكنه استدعاءه، استخدم خيارات المصادقة والوصول في [الوصول والتخويل](/docs/actions-access-control).
- **`parallelSafe: true`**: يسمح لـ action يغيّر البيانات بالعمل في الوقت نفسه مع استدعاءات أدوات أخرى في الدور نفسه. لا تضبط هذا إلا عندما يكون تشغيل الـ action بالتزامن آمنًا ولا يعتمد على الترتيب. تُسلسَل actions التي تغيّر البيانات بشكل افتراضي.
## إفشال إجراء {#failing}
يبلّغ الإجراء عن الفشل عبر الطرح. أما إعادة `{ error: "..." }` فتبدو نجاحًا لكل جزء من إطار العمل، لذا لا تحسبها قواطع إعادة المحاولة لدى الوكيل أبدًا، ويُسجَّل الاستدعاء كأثر جانبي مكتمل.
ما تطرحه هو ما يحدد مقدار ما يبقى من الرسالة. يطرح `fail()` خطأ `ActionContractError`، وهذا النوع تحديدًا هو السبب الوحيد لوصول النص إلى المستدعي. أما `throw new Error("No such email")` المجرد فلا يمكن تمييزه عن عطل في Postgres أو في خدمة أعلى السلسلة، لذا يستبدله مسار الإجراء بخطأ 500 عام `"Internal server error"`، ويُبقي الرسالة الحقيقية في سجل الخادم، ويبلّغ عنها إلى تتبّع الأخطاء. احتفظ بالطرح المجرد للأعطال الداخلية الحقيقية. فهذا ما وُجد الخطأ 500 من أجله.
يقبل `fail()` رسالة وكائن خيارات:
- **message**: النص الذي يقرأه المستدعي. اكتبه لشخص، لا لسجلّ.
- **options.errorCode**: رمز ثابت مقروء آليًا. القيمة الافتراضية `"action_failed"`.
- **options.statusCode**: حالة HTTP لمسار الإجراء. القيمة الافتراضية `400`.
- **options.details**: سياق منظَّم وآمن للمستدعي، مثل المعرّف الذي تحتاجه إعادة المحاولة. يتلقّاه كل من المتصفح والوكلاء. لا تضع هنا أسرارًا أو مخرجات خام من مشغّل قاعدة البيانات.
أبسط استدعاء لا يحتاج سوى رسالة:
```ts
import { defineAction, fail } from "@agent-native/core/action";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { getDb, schema } from "../server/db/index.js";
export default defineAction({
description: "Reply to an email thread in the user's voice.",
schema: z.object({
emailId: z.string().describe("The id of the email to reply to."),
body: z.string().describe("The reply body, in markdown."),
}),
run: async ({ emailId, body }) => {
const db = getDb();
const [email] = await db
.select()
.from(schema.emails)
.where(eq(schema.emails.id, emailId));
if (!email) fail("That email is no longer in the mailbox.");
await db.insert(schema.replies).values({ emailId, body });
return { ok: true, emailId };
},
});
```
تسمية السبب هي ما يتيح لواجهة المستخدم التفرّع على الفشل بدلًا من طباعته فقط. ويبقى كل من الرمز والحالة عبر طبقة النقل:
```ts
if (!email) {
fail("That email is no longer in the mailbox.", {
errorCode: "email_not_found",
statusCode: 404,
});
}
```
يستقبل المتصفح `{ error, errorCode, details }`. وتُظهرها `useActionQuery()` و`useActionMutation()` و`callAction()` جميعًا ككائن `Error` يحمل `status` و`errorCode` و`details` و`actionMessage`.
يحتفظ `error.message` بالبادئة `Action <name> failed:`، وهي بادئة تناسب سجل الطرفية وتبدو في غير موضعها داخل إشعار منبثق. تعيد `actionErrorMessage()` النص الذي كتبه الإجراء فقط، أو `undefined` إن لم يكتبه أحد:
```tsx
import {
actionErrorMessage,
useActionMutation,
} from "@agent-native/core/client/hooks";
const reply = useActionMutation("reply-to-email", {
onError: (error) =>
toast.error(actionErrorMessage(error) ?? t("email.replyFailed")),
});
```
انقطاع الشبكة، وصفحة الخطأ بصيغة HTML من وسيط، وسطر الحالة المجرد لا يكتب أي منها رسالة. لذا تعيد `undefined` بدلًا من نص قد تعرضه الواجهة عن طريق الخطأ. اقرنها دائمًا بنصوصك أنت.
### ما ينتجه كل طرح {#failure-shapes}
| مطروح من `run()` | حالة HTTP | جسم الاستجابة | مُبلَّغ إلى تتبّع الأخطاء |
| ------------------------------------------------------------ | --------------------------- | ---------------------------------------------- | ------------------------- |
| `fail(msg)` | 400 | `{ error: msg, errorCode: "action_failed" }` | لا |
| `fail(msg, { errorCode, statusCode, details })` | الـ `statusCode` الذي تحدده | `{ error, errorCode, details }` | لا |
| `new ActionContractError(msg, { errorCode })` | 409 | `{ error, errorCode, details }` | لا |
| `new AgentActionStopError(msg)` | 500 | `{ error: msg }` | لا |
| حالة deadlock في PostgreSQL (`40P01`) أو فشل تسلسل (`40001`) | 409 | `{ error, errorCode: "transaction_conflict" }` | لا |
| `new Error(msg)` | 500 | `{ error: "Internal server error" }` | نعم |
| مدخل يفشل في `schema` | 400 | `{ error: "Invalid action parameters..." }` | لا |
اطرح `AgentActionStopError` عندما ينبغي للوكيل إنهاء دوره بدل قراءة الفشل والمحاولة مجددًا. أما `ActionContractError` فهو ما يطرحه `fail()` نيابة عنك، فلا تستخدمه مباشرة إلا حين تكون 409 هي الحالة المطلوبة.
### اختر حالة يمكن لسياسة إعادة المحاولة أن تتصرف بناءً عليها {#failure-status}
تعيد `useActionQuery()` المحاولة مع `429` و`502` و`503` و`504` فقط، حتى ثلاث مرات، بتراجع مقداره 500 مللي ثانية ثم ثانية واحدة ثم ثانيتان. أما كل حالة أخرى فتُعامَل كحالة حتمية وتظهر مع أول استجابة. وإعادة إرسال طلب رُفض لأنه خاطئ لا تشتري سوى الرفض نفسه مرة أخرى. ولا تعيد `useActionMutation()` المحاولة إطلاقًا.
لذا فالحالة ليست زينة. الرفض المُرسَل بوصفه `404` يكلّف رحلة ذهاب وإياب واحدة. والرفض نفسه مُرسَلًا بوصفه `500`، أو مطروحًا مجردًا، يكلّف أربع رحلات وأربعة تقارير أخطاء مكررة.
لا يرى المستدعون من جهة الوكيل رمز الحالة. فالوكيل ينفّذ `run()` داخل العملية نفسها، ومن ثم يتلقى الرسالة مباشرة أيًا كان نوعها، بالصيغة `Error running <action>: <message>`. ويُلحق أي `errorCode` غير القيمة الافتراضية `action_failed` بالصيغة `(errorCode: not_found)`، ليتفرّع النموذج بناءً عليه دون تحليل النص. وتأتي `details` في سطر مستقل بصيغة JSON مضغوطة، مثل `Error details: {"importId":"imp_1"}`، فلا يلزم كتابة المعرّف الذي يحتاجه النموذج في استدعائه التالي داخل الرسالة. ويحصل الوكلاء الخارجيون عبر MCP على النص نفسه، وعلى التفاصيل نفسها في `structuredContent.error`. أما الأداة التي تعلن مخطط إخراج (`mcpOutputSchema: true`) فتُرجع النص فقط، لأن العميل قد يتحقق من نتيجة الخطأ أيضًا مقابل ذلك المخطط. ويقتصر حجم التفاصيل على 2,000 حرف: وبعد ذلك تُبقى المدخلات الصغيرة ذات المستوى الأعلى وتُدرج البقية على أنها محذوفة. أما الأسرار الواردة في الرسالة والتفاصيل فتُحجب أولًا، وقواطع الوكيل الخاصة بالأخطاء المتكررة هي ما يحدّ من عدد محاولاته.
## الكتابات الآمنة لإعادة المحاولة {#retry-safe}
يصنّف الإطار إجراء الكتابة الفاشل حسب الكتابات التي رأى الاستدعاء ينفّذها: كل عبارة SQL قد تكتب بحسب نصها وكل `fetch` بطريقة غير GET أو HEAD أو OPTIONS. الرفض الذي يُثار قبل أي منها، مثل تعديل لا يطابق شيئًا، أو هدف مفقود، أو رفض تحقق 422، هو فشل معروف أيًّا كانت طريقة طرحه: `fail()`، أو `Error` عادي، أو خطأ من مكتبة. يتلقى النموذج الخطأ، ويصحّح وسائطه، ثم يعيد المحاولة.
عندما يفشل استدعاء بعد كتابة نفّذها، تسجّل حلقة الوكيل نتيجة غير معروفة وتحظر تلك الأداة لبقية **الدور الحالي**. يرى النموذج الخطأ، لكنه لا يستطيع استدعاء الإجراء نفسه مرة أخرى في هذا الدور لتصحيح وسائطه. رسالة المستخدم التالية تشغّل الأداة بصورة طبيعية.
- قبل كتابة لا يراها الإطار، مثل الكتابة على القرص، أو عملية فرعية، أو طلب `node:http`، أو استدعاء SDK لمورّد، أو دالة قاعدة بيانات خاصة بتطبيقك يستدعيها `SELECT`، استدعِ `noteExternalWrite(channel)` من `@agent-native/core/action`، مثل `noteExternalWrite("local-disk")`. من دونه، يبدو الاستدعاء الذي يفشل بعد تلك الكتابة كأنه لم يحفظ شيئًا.
- `NoWriteError`، أو `noWrite()` من `defineActionErrors`، تجاوزٌ وليس شرطًا. استخدمه عندما تكون الكتابة الوحيدة قبل الرفض كتابةً تكررها إعادة المحاولة دون ضرر، مثل طلب رفضه الخادم برمز 4xx قبل أن ينفّذ شيئًا، أو رفع ملف لا يشير إليه شيء بعد. لا يقبله الإطار إلا إذا لم يدخل أي إجراء كتابة متداخل إلى معالج الاستدعاء. قاعدة المؤلف هي بند `NoWriteError` في `.agents/skills/actions/SKILL.md`. راجع [إعلان رموز الخطأ](#error-codes) لـ `noWrite()`.
عيّن `retrySafe: true` (أو دالة شرطية على المدخلات) عندما لا يمكن لإعادة التشغيل بعد أي خطأ أن تكرّر البيانات أو تفسدها: كل كتابة ينفّذها الإجراء تضبط حالة نهائية، مثل الاستبدال حسب المعرّف، فلا يغيّر تكرار كتابة تمّت بالفعل شيئًا. عندئذٍ يبقى الاستدعاء الذي يفشل بعد كتابته نفسها فشلًا معروفًا. يتلقى النموذج الخطأ، ويصحّح وسائطه، ثم يعيد المحاولة.
```ts
export default defineAction({
description: "Replace a dashboard panel by id.",
schema: z.object({
dashboardId: z.string().describe("Dashboard id."),
panelId: z.string().describe("Panel id to replace."),
title: z.string().describe("New panel title."),
}),
// Safe: the write is an end-state replace. Running it again after
// an error sets the same state, so the model can fix its args and retry.
retrySafe: true,
run: async ({ dashboardId, panelId, title }) => {
/* validate, then replace-by-id … */
},
});
```
**لا** تعيّنه عندما يُلحق الإجراء أو يرسل أو يفرض رسومًا بعد التحقق، إلا للمدخلات التي تحمل مفتاح تكرار يعيد الإجراء عليه نتيجته الأولى. التحقق أولًا لا يكفي وحده إذا كانت خطوة لاحقة قد تكون نفذت بالفعل قبل الرفض. بعض الحدود الأخرى:
- يغطي **كتابة هذا الإجراء نفسه**. بمجرد أن يكتب إجراء متداخل يستدعيه، يظل الفشل يسجّل نتيجة غير معروفة.
- يتخطى اعتماد MCP تحذير «سبق تشغيله» للاستدعاء الذي يغطيه `retrySafe`.
- عندما يتعافى تشغيل من انهيار ويصدر من جديد استدعاءً آمنًا لإعادة المحاولة قُطع في المنتصف بالمدخلات نفسها، يُشغَّل ذلك الاستدعاء مرة أخرى بدل أن تبقى نتيجته غير معروفة.
- تجاوز المهلة أو الإلغاء بعد استدعاء الإجراء لا يزال يحظر الأداة لبقية الدور الحالي. لا يُعامَل كفشل معروف وقابل لإعادة المحاولة إلا الخطأ الذي يُرجعه الإجراء نفسه.
## أبقِ سطح actions صغيرًا {#small-surface}
يشغل كل action يمكن للوكيل رؤيته فتحة في قائمة أدوات النموذج، وتجعل القائمة الطويلة والمتداخلة اختيار النموذج للأداة الصحيحة أصعب. صمّم سطح actions مثل API تصونه، وليس action واحدًا لكل زر في واجهة المستخدم:
- فضّل **action واحد بأسلوب CRUD باسم `update`** يأخذ تصحيحًا (patch) من الحقول الاختيارية، بدلاً من actions عديدة لكل حقل مثل `update-name` و`update-order` و`update-color`. لا يرسل المستدعي إلا الحقول التي تغيّرت.
- قبل إضافة action قراءة جديد لكل استعلام أو عامل تصفية، ضع في اعتبارك خيارًا أكثر عمومية أولاً: [ثلاثي provider API](/docs/template-dispatch-developers#calling-a-provider-directly) (`provider-api-catalog` و`provider-api-docs` و`provider-api-request`) لبيانات الموفر، أو أداة `db-query` للتطوير لبيانات التطبيق.
- علّم actions الخاصة بواجهة المستخدم فقط أو البرمجية بـ [`agentTool: false`](/docs/actions-access-control#agent-tool). تبقى قابلة للاستدعاء من الواجهة الأمامية أو عبر HTTP، دون أن تشغل فتحة في قائمة أدوات النموذج.
- ضع `deferLoading: false` على الحفنة القليلة من actions التي يلجأ إليها الوكيل باستمرار. هذه هي المخططات التي تُرسَل في أول طلب إلى النموذج؛ وكل ما عداها يُحمَّل عند الحاجة عبر `tool-search`. وبمجرد أن تخرج action واحدة بهذه الطريقة، تُؤجَّل كل action غير معلَّمة، لذا علّم مجموعة البداية كاملة دفعة واحدة لا action تلو الأخرى. المسألة هنا كلفة الدور الأول، لا الصلاحية: تبقى الـ action المؤجَّلة قابلة للاستدعاء فور أن يعيدها `tool-search`. لا تزال actions المؤجَّلة تظهر بالاسم في فهرس الأدوات الخاص بـ prompt، مجمّعة حسب الاسم التالي للفعل الأول، لذا فإن أسماء `verb-noun` مثل `list-dashboards` و`create-dashboard` هي ما يتيح للوكيل العثور عليها. وهذا هو الشكل الخاص بكل action من مصفوفة `initialToolNames` في الملحق، ويمكن للتطبيق استخدام أيٍّ من الشكلين.
- أضف `searchHints` إلى action عندما يسمّي المستخدمون وظيفته بكلمات لا يذكرها اسمه ولا وصفه، مثل `["auto-archive rule", "inbox rule"]` على action لقواعد البريد الوارد. يرتّب `tool-search` هذه الكلمات بعد الاسم مباشرة، ولا تُرسَل إلى النموذج أبدًا، فلا تستهلك شيئًا من السياق. اجعلها قصيرة وواقعية (12 على الأكثر، وكل منها حتى 60 حرفًا)، لا قائمة بكل طلب قد يخدمه الـ action.
- احذف أو أخفِ actions التي لم تعد واجهة المستخدم تستخدمها، بدلاً من تركها مكشوفة للنموذج.
يتضمن المستودع مساعدًا استشاريًا، `node scripts/audit-template-actions.mjs [template ...]` (بالاسم المستعار `pnpm actions:audit`). يفحص مجلد `actions/` الخاص بالقالب ويشير إلى actions قد لا تستخدمها واجهة المستخدم بعد الآن، إلى جانب مجموعات actions لكل حقل يمكن دمجها في واحد. يخرج دائمًا برمز 0 ولا يُفشل CI أبدًا، وقواعده الاستدلالية متحفظة، لذا تعامل مع مخرجاته على أنها اقتراح، لا خطأ.
## ما هي الخطوة التالية
- [**نظرة عامة**](/docs/actions-overview) — ما هو action وجولة hello-world
- [**الوصول والتخويل**](/docs/actions-access-control) — `agentTool` و`toolCallable` وauthorize ونطاق `ctx`
- [**سياق التشغيل**](/docs/actions-run-context) — جدول حقول `ctx` الكامل
- [**أسطح أخرى**](/docs/actions-other-surfaces) — واجهة المحادثة الأصلية، وCLI، وA2A، وMCP، وactions القياسية
- [**قاعدة البيانات**](/docs/server-database) — `getDb()`/`schema` المستخدمة داخل `run()`
- [**البيانات والمزامنة**](/docs/client-data) — استدعاء هذا الـ action من واجهة المستخدم
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 |