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/actions-access-control.mdx

View on GitHub
---
title: "الوصول والتخويل"
description: "من يمكنه استدعاء action: أعلام التعريض (agentTool، وmcpTool، وtoolCallable)، وخيار access التصريحي، والنطاق المستند إلى ctx، وaccessFilter/assertAccess، وحارس authorize."
---

# الوصول والتخويل

تحدد سبعة إعدادات من يمكنه استدعاء action: الوكيل، أو الواجهة الأمامية، أو امتداد، أو مستدعي API خارجي، أو لا أحد من دون موافقة إنسان أولًا. لا تحتاج معظم actions أبدًا إلى لمس أي من هذه، لأن القيم الافتراضية تناسب بالفعل الاستخدام العادي لواجهة المستخدم والوكيل.

### أعلام التعريض {#exposure-flags}

تُضبط الأعلام السبعة جميعًا افتراضيًا على القيمة المتساهلة، ويأخذ `mcpTool` قيمته الافتراضية من `agentTool`، لذا لا تضبط أيًا منها إلا عندما تحتاج إلى تشديد سطح معيّن. الجدول أدناه ملخص سريع. تضيف الأقسام التي تليه التفصيل الوحيد الذي يحتاجه كل علم.

| العلم           | الافتراضي    | القيمة التقييدية ← من لا يزال بإمكانه الاستدعاء                             | الاستخدام النموذجي                                                    |
| --------------- | ------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `agentTool`     | `true`       | `false` ← واجهة المستخدم وHTTP وCLI فقط (مخفي عن النموذج وMCP وA2A)         | actions خاصة بواجهة المستخدم فقط أو برمجية لا ينبغي أن تشغل فتحة أداة |
| `mcpTool`       | `agentTool`  | `false` ← وكيل تطبيقك أنت فقط (مخفي عن MCP وA2A)                            | actions تحتاج إلى شاشة أو جلسة من التطبيق على الطرف الآخر             |
| `toolCallable`  | `true`       | `false` ← كل شيء **باستثناء** جسر iframe المعزول الخاص بالامتداد (403)      | تغييرات حساسة في الحساب أو المؤسسة (حذف حساب، تغيير عضوية)            |
| `publicAgent`   | معطَّل (خاص) | `{ expose: true }` ← يضيف الـ action إلى أسطح MCP/A2A/OpenAPI **العامة**    | أدوات قراءة أو استيعاب آمنة لا تتطلب مصادقة                           |
| `needsApproval` | `false`      | `true` ← **يتوقف** الوكيل مؤقتًا، ويجب أن يوافق إنسان على الاستدعاء المحدد  | تأثيرات جانبية ذات عواقب (إرسال بريد إلكتروني، شحن بطاقة، حذف)        |
| `access`        | لا شيء       | سياسة مُعلَنة ← فقط المستدعون الذين يحملون الدور الذي تسميه، على **كل** سطح | actions تقرأ موردًا مشتركًا واحدًا أو تغيّره (تعديل نموذج في Forms)   |
| `authorize`     | لا شيء       | دالة حارسة ← فقط المستدعون الذين تقبلهم، على **كل** سطح                     | عمليات مقيَّدة بدور (RBAC لكل تطبيق، عمليات خاصة بالمسؤول فقط)        |

هذه الأعلام مستقلة، باستثناء واحد: `mcpTool` غير المصرَّح به يرث `agentTool`. يتحكم `agentTool` بما يراه النموذج، راجع [الإخفاء عن النموذج](#agent-tool) أدناه. يضيّق `mcpTool` ذلك ليقتصر على الوكلاء الخارجيين، راجع [الإخفاء عن الوكلاء الخارجيين](#mcp-tool) أدناه. يتحكم `toolCallable` فقط بـ iframe الامتداد، راجع [حظر أطر الامتداد](#tool-callable) أدناه. يضيف `publicAgent` سطحًا عامًا بالاختيار، ولا يعني مسار ويب عام أبدًا تعريضًا عامًا للأداة، راجع [التعريض للوكلاء العامين](#public-agent) أدناه. يضبط `needsApproval` التنفيذ بعد إجراء الاستدعاء فعلًا، راجع [طلب موافقة الإنسان](#needs-approval) أدناه. يعلن `access` عن الدور الذي يجب أن يحمله المستدعي على مورد، ويُفحص على كل مسار إرسال قبل الدخول إلى `run()`، راجع [طلب الوصول إلى مورد](#access) أدناه. يقرر `authorize` ما إذا كان يجوز لهذا المستدعي تشغيل الـ action أصلًا، على كل مسار إرسال، قبل الدخول إلى `run()`، راجع [تقييد المستدعين حسب الدور](#authorize) أدناه.

## الإخفاء عن النموذج {#agent-tool}

بشكل افتراضي، كل action هو أداة وكيل قابلة للاستدعاء. اضبط `agentTool: false` لإزالته من كل قائمة أدوات وكيل، مع إبقائه خلف مصادقة إطار العمل وسطح actions. يبقى قابلًا للاستدعاء من واجهة المستخدم (`useActionMutation()` أو `callAction()`)، وCLI، و`/_agent-native/actions/<name>`:

```ts
export default defineAction({
  description: "Persist the user's sidebar width.",
  agentTool: false, // UI-only, not a tool in the model's context window
  schema: z.object({ widthPx: z.number() }),
  http: { method: "PUT" },
  run: async ({ widthPx }) => {
    /* ... */
  },
});
```

استخدم هذا عندما تضيف action خاصًا بواجهة المستخدم فقط أو برمجيًا بحتًا، أو عندما تتوقف واجهة المستخدم عن استخدام action كان سيبقى مكشوفًا للنموذج لولا ذلك.

## الإخفاء عن الوكلاء الخارجيين {#mcp-tool}

`agentTool` إما كل شيء أو لا شيء: الـ action إما أداة لكل وكيل، أو ليست أداة لأحد. يقسم `mcpTool` ذلك إلى نصفين، فتبقى الـ action أداة عادية لوكيل تطبيقك أنت، من دون أن تصل أبدًا إلى Claude أو Cursor أو تطبيق شقيق عبر MCP وA2A:

```ts
export default defineAction({
  description: "Open the record inspector beside the current selection.",
  mcpTool: false, // needs a live screen on the other end
  schema: z.object({ recordId: z.string() }),
  run: async ({ recordId }) => {
    /* ... */
  },
});
```

استخدمه مع actions لا تعني نتيجتها شيئًا إلا مع واجهة تطبيقك، أو جلسة مفتوحة، أو التحديد الحالي أمام المستدعي. لا يستطيع `mcpTool` إلا تضييق `agentTool`، ولا يوسّعه أبدًا: تبقى الـ action التي تحمل `agentTool: false` مخفية في كل مكان. فهو يحكم سطح الأدوات الخارجي نفسه، لا ما يجوز لوكيلك أنت فعله وهو يجيب عن سؤال `ask_app` — فتلك الجولة جولة وكيلك، ويحتفظ فيها بقائمة أدواته كاملة.

ومن دون تصريح، يتبع `mcpTool` قيمة `agentTool` بدلًا من `true` ثابتة، فإخفاء الـ action عن الوكيل يخفيها عن الوكلاء الخارجيين أيضًا، ويبقى العلم الواحد قرارًا واحدًا.

وللقيمة المعاكسة وظيفة ثانية. يُقدَّم للوكلاء الخارجيين افتراضيًا فهرس صغير منتقى بدلًا من سجل actions كامل، و`mcpTool: true` هو الطريقة التي تعلن بها الـ action انتماءها إليه:

```ts
export default defineAction({
  description: "List the databases connected to this workspace.",
  mcpTool: true, // served to external agents, not just discoverable
  http: { method: "GET" },
  run: async () => {
    /* ... */
  },
});
```

هذا هو الفهرس نفسه الذي تمثله قائمة `mcp: { connectorCatalog: [...] }` في الملحق، لكنه معلن على الـ action بدلًا من مصفوفة منفصلة يجب إبقاؤها متوافقة مع كل إعادة تسمية. كلا الشكلين يعمل، ويمكن للتطبيق الانتقال action تلو الأخرى. ويبقى كل ما استُبعد قابلًا للاكتشاف عبر `tool-search`.

أما الجمع المعاكس بين العلمين — `agentTool: false` مع `mcpTool: true` — فيجعل الـ action **خاصة بـ MCP فقط**: يحصل عليها الوكلاء الخارجيون، ولا يراها وكيل تطبيقك أنت أبدًا. استخدم ذلك لعمليات التصدير أو المزامنة أو التسليم التي تحتاجها أداة خارجية ولا سبب لوكيلك أن يستدعيها.

الانتماء إلى الفهرس ليس إذنًا. لا يزال على المستدعي الخارجي اجتياز فحص نطاق OAuth وسياسة `externalAgents`، وكذلك — في مسار A2A المباشر بلا نموذج — موافقة `publicAgent` أدناه.

## حظر أطر الامتداد iframe {#tool-callable}

تستدعي الامتدادات ([تطبيقات Alpine.js مصغّرة في إطارات iframe معزولة](/docs/extensions)) actions من خلال `appAction(name, params)`، وتعمل بصلاحيات المُشاهد نفسه وأسراره ونطاق SQL الخاص به. بالنسبة إلى العمليات الحساسة، هذه ثقة زائدة عن الحد بشكل افتراضي. اضبط `toolCallable: false` لجعل جسر الامتداد يُرجع 403، مع إبقاء الـ action قابلًا للاستدعاء من واجهة المستخدم والوكيل وCLI وMCP وA2A:

```ts
export default defineAction({
  description: "Delete the current user's account.",
  toolCallable: false, // never callable from an extension iframe
  schema: z.object({ confirm: z.literal("yes") }),
  run: async () => {
    /* ... */
  },
});
```

استخدمه لأجل actions تحذف أو تنقل حسابًا أو مؤسسة، أو تغيّر حالة المصادقة، أو تعدّل عضوية المؤسسة، أو تمنح وصول مشاركة. تُلغي actions المدمجة في إطار العمل — `share-resource` و`unshare-resource` و`set-resource-visibility` — الاشتراك بالفعل. يفرض إطار العمل هذا برأس يضبطه المضيف على استدعاءات iframe، رأس لا يمكن لـ iframe تزييفه. تبقى استدعاءات واجهة المستخدم والوكيل وCLI وMCP وA2A العادية غير متأثرة. راجع [الأمان](/docs/security) للتفاصيل.

## التعريض للوكلاء العامين {#public-agent}

يبقى كل action خارج أي سطح بروتوكول عام بشكل افتراضي، حتى لو كان مسار الويب الخاص به عامًا. جعل صفحة قابلة للزحف لا يعرّض أداة أبدًا. اضبط `publicAgent: { expose: true, readOnly: true, ... }` لإدخال action آمن واحد ضمن أسطح MCP وA2A وOpenAPI العامة:

```ts
export default defineAction({
  description: "Search published docs.",
  schema: z.object({ query: z.string() }),
  http: { method: "GET" },
  readOnly: true,
  publicAgent: {
    expose: true,
    readOnly: true,
    requiresAuth: false,
  },
  run: async ({ query }) => {
    /* ... */
  },
});
```

استخدمه فقط لأجل actions آمنة، للقراءة فقط، أو للاستيعاب فقط، من النوع الذي تسمح لغريب باستدعائه دون تسجيل الدخول. يخبر `requiresAuth: false` السطح العام أن هذا الـ action آمن للإدراج قبل المصادقة. اترکه `true` لأجل action ما زال يحتاج إلى هوية مستدعٍ متصل، مثل أداة استيعاب خاصة بكل حساب. راجع [الوكلاء الخارجيون](/docs/external-agents) و[بروتوكول MCP](/docs/mcp-protocol) للاطلاع على الكتالوج الكامل ونموذج المصادقة الذي يشترك فيه هذا.

## طلب موافقة الإنسان {#needs-approval}

عدد قليل من actions ذو عواقب كبيرة بحيث لا يمكن ترك الوكيل يشغّله بمفرده، مثل إرسال بريد إلكتروني، أو شحن بطاقة، أو حذف حساب. اضبط `needsApproval: true` (أو مسندًا `(args, ctx) => boolean | Promise<boolean>`) على `defineAction()`، وستتوقف الحلقة مؤقتًا قبل `run()`، ما يتطلب موافقة إنسان على ذلك الاستدعاء المحدد. الافتراضي هو **معطَّل**، ويجب أن يبقى كل action تقريبًا على هذا الحال.

<Callout tone="warning">
  أبقِ الموافقات نادرة. كل action خاضع لبوابة موافقة يمثّل توقفًا صارمًا في حلقة
  الوكيل. فهو يقاطع التشغيل ويستلزم جولة ذهاب وإياب مع إنسان. استخدم
  `needsApproval` فقط للعمليات الموجَّهة إلى الخارج التي تكون بالفعل عالية
  العواقب ويصعب التراجع عنها. إذا وجدت نفسك تضع بوابة على عمليات القراءة أو على
  كتابات روتينية، فهذا يعني أنك تستخدم `needsApproval` في غير موضعه الصحيح.
  الافتراضي هو **معطَّل**، ويجب أن يترك كل action تقريبًا هذا الإعداد على حاله.
</Callout>

<AnnotatedCode
  id="doc-block-13p4g9y"
  title="وضع بوابة على action الوحيد ذي العواقب"
  filename="actions/send-email.ts"
  language="ts"
  code={
    'export default defineAction({\n  description: "Send an email via Gmail.",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting and queueing are\n  // not affected. Only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});'
  }
  annotations={[
    {
      lines: "10",
      label: "البوابة كاملة",
      note: "علم واحد فقط. عندما تكون قيمته صحيحة (truthy) ولم تتم الموافقة بعد على الاستدعاء، تتوقف الحلقة مؤقتًا قبل `run`. لا يصل النموذج أبدًا إلى الأثر الجانبي بمفرده.",
    },
    {
      lines: "11-13",
      label: "`run()` بلا تغيير",
      note: "تبقى الدالة المعالجة كما هي دون تغيير. تُفرض الموافقة بواسطة الحلقة المحيطة بها، لا بأي شيء داخل `run`.",
    },
  ]}
/>

- **`needsApproval: true`** يتطلب الموافقة دائمًا.
- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** يتطلب الموافقة فقط عندما يُرجع المسند القيمة true. استخدم هذا لوضع بوابة بشرط معيّن، على سبيل المثال فقط للمستلمين الخارجيين أو فقط عند تجاوز مبلغ معيّن بالدولار:

  ```ts
  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
  ```

  حافظ على أن يكون المسند نقيًا (pure) وسريعًا. إذا طرح المسند خطأً، يتعامل إطار العمل مع الاستدعاء كما لو أن المسند أرجع القيمة true، بحيث يتوقف action مؤقتًا لانتظار الموافقة بدلًا من أن يعمل. هذا يعني أن مسندًا معطوبًا لا يمكن أبدًا أن يسمح بصمت لعملية عالية العواقب بالعمل من دون أن يوافق عليها إنسان أولًا.

عندما تُحذف `needsApproval`، يبقى السلوك دون أي تغيير حرفيًا. لا توجد أي تكلفة إضافية على المسار الشائع.

يعمل هذا بالطريقة نفسها للإجراءات القديمة بنمط `parameters` وللإجراءات القائمة على المخطط. يتوقف الوكيل داخل التطبيق ووكلاؤه الفرعيون ضمن حلقة الوكيل. يستخدم MCP وA2A مساري الموافقة الخاصين بهما.

الاستدعاء المباشر عبر [HTTP API](/docs/http-api) لا يمكنه تقديم موافقة بشرية. لا يشغّل المسار الإجراء المحمي إلا من واجهة التطبيق الموثوقة أو من أداة دليل MCP في التطبيق. تتلقى الاستدعاءات المباشرة الأخرى `409` مع `errorCode: "approval_required"`. لا يمكن لهوية خدمة أن توافق. يرسل العميل المشترك قدرة UI قصيرة العمر مع عمليات الكتابة من جلسة مسجّلة الدخول. يتلقى الاستدعاء دون إثبات `403` مع `errorCode: "ui_capability_required"`، ثم يصدر العميل القدرة ويعيد المحاولة مرة واحدة. تستخدم مهام A2A مسار موافقة منفصلًا، لا استجابة HTTP هذه. تتوقف المهمة حتى يوافق مالكها، ثم تعيد تشغيل استدعاء الأداة الموافق عليه. يقيّم أمر CLI المحلي `pnpm action ...` أيضًا `needsApproval` على الإدخال المُجهّز والمحلّل مع القيم الافتراضية والمستدعي `cli`. ويتطلب تأكيدًا في الطرفية أو إعادة التشغيل مع `--approved` بعد موافقة الشخص. راجع [موافقة CLI](/docs/actions-other-surfaces#cli). تعامل مع هذا الحقل كطلب موافقة، لا كحدّ للتفويض.

### كيف تتوقف الحلقة مؤقتًا {#loop}

عندما يستدعي الوكيل action خاضعًا لبوابة موافقة، ولم تتم الموافقة بعد على هذا الاستدعاء بالتحديد، لا تُنفِّذ الحلقة `run()`. بدلًا من ذلك، تقوم بما يلي:

1. تحلّ البوابة. تجهّز الحلقة الاستدعاء أولًا: تتحقق من الوسائط وتطبّق القيم الافتراضية والتحويلات التي يحددها المخطط. يتوقف الاستدعاء غير الصالح هنا بخطأ التحقق، ولا يُطلب من أحد الموافقة عليه. في حالة المسند، تستدعي الحلقة بعد ذلك `needsApproval(args, ctx)` بالوسائط المجهّزة، وهي نفسها التي ستصل إلى `run()`. إذا طرح هذا الاستدعاء خطأً، تتعامل الحلقة معه كما لو أنه أرجع النتيجة true، بحيث يتطلب action الموافقة.
2. تُصدر حدث `tool_start` (بحيث تعرض واجهة المستخدم الاستدعاء) يتبعه مباشرة حدث **`approval_required`**، ثم توقف الدور. لا يحدث الأثر الجانبي لـ action أبدًا.

يحمل حدث `approval_required` كل ما يحتاجه العميل لعرض عنصر تحكم للموافقة:

| الحقل         | النوع    | الملاحظات                                                                |
| ------------- | -------- | ------------------------------------------------------------------------ |
| `tool`        | `string` | اسم action الذي حاول الوكيل استدعاءه.                                    |
| `input`       | object   | الوسائط التي مررها الوكيل.                                               |
| `approvalKey` | `string` | **مفتاح ثابت** يعيد العميل إرساله للموافقة على _هذا الاستدعاء بالتحديد_. |
| `toolCallId`  | `string` | معرّف استدعاء الأداة من جهة النموذج، عند توفره.                          |

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

تُرجع الأداة المتوقفة مؤقتًا نتيجة تخبر النموذج أن الدور متوقف مؤقتًا وأنه يجب ألا يعيد المحاولة، بحيث لا يستمر النموذج في تكرار الاستدعاء من دون جدوى.

### كيف يوافق الإنسان {#approve}

عند وقوع `approval_required`، تعرض واجهة الدردشة عنصر تحكم **موافقة / رفض** على استدعاء الأداة المتوقف. هذا موصول تلقائيًا داخل `AssistantChat`. لست بحاجة إلى بنائه لكل قالب على حدة.

<WireframeBlock id="doc-block-humanapprovalwf1">
  <Screen
    surface="popover"
    html={
      "<div style='display:flex;flex-direction:column;box-sizing:border-box;padding:16px;gap:12px'><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill warn'>Needs approval</span><strong>send-email</strong></div><div style='display:flex;flex-direction:column;gap:2px'><span class='wf-muted'>to: alex@acme.com</span><span class='wf-muted'>subject: Following up on the proposal</span></div><div style='display:flex;gap:8px'><button>Deny</button><button class='primary'>Approve</button></div></div></div>"
    }
  />
</WireframeBlock>

- **الموافقة** تعيد إصدار الدور كرسالة استكمال عادية تحمل مفتاح الاستدعاء ضمن `approvedToolCalls: [approvalKey]`. في الدور المُعاد إصداره، ترى البوابة المفتاح ضمن مجموعة الموافقات المقبولة، فتسمح لذلك الاستدعاء المحدد بالعمل بشكل طبيعي.
- **الرفض** يُخفي عنصر التحكم محليًا. لا يُعاد إصدار أي شيء، لذا لا يعمل action أبدًا.

`approvedToolCalls` هو حقل في طلب الدردشة (`AgentChatRequest.approvedToolCalls`). المفاتيح غير الموجودة فيه تبقى متوقفة مؤقتًا. الموافقة على استدعاء واحد لا توافق أبدًا على أي استدعاء آخر. ولأن المفتاح مُعنوَن بحسب المحتوى (content-addressed)، فإن الموافقة تخوّل فقط ذلك الاستدعاء المحدد بتلك الوسائط بالذات. إذا اقترح النموذج لاحقًا عملية إرسال مختلفة، يصبح ذلك مفتاحًا جديدًا يحتاج إلى موافقة جديدة خاصة به.

### من البداية إلى النهاية {#flow}

<Diagram id="doc-block-2nor1g" title="مقاطعة الموافقة" summary={"يوقف الاستدعاء الخاضع لبوابة الدور مؤقتًا قبل تنفيذ run(). تعيد الموافقة إصدار الدور حاملةً مفتاح الاستدعاء. عندئذ فقط يحدث الأثر الجانبي."}>

```html
<div class="diagram-approve">
  <div class="diagram-box" data-rough>الوكيل يستدعي send-email</div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
  <div class="diagram-panel warn" data-rough>
    <strong>البوابة صحيحة، والاستدعاء لم يوافَق عليه بعد</strong
    ><small class="diagram-muted"
      >تُصدر الحلقة tool_start + approval_required { tool, input, approvalKey
      }</small
    ><span class="diagram-pill warn">لم يُنفَّذ run() بعد</span>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
  <div class="diagram-box" data-rough>
    ينقر الإنسان على زر الموافقة في الدردشة<br /><small class="diagram-muted"
      >يعيد العميل إصدار الدور مع approvedToolCalls: [approvalKey]</small
    >
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
  <div class="diagram-panel ok" data-rough>
    <span class="diagram-pill ok"
      >ترى البوابة المفتاح &rarr; يُنفَّذ run() &rarr; يُرسَل البريد
      الإلكتروني</span
    >
  </div>
</div>
```

```css
.diagram-approve {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.diagram-approve .diagram-panel {
  display: flex;
  flex-direction: column;
  gap: 6px;
  align-items: center;
  padding: 12px 16px;
  text-align: center;
}
.diagram-approve .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

action الخاص بـ `send-email` في قالب Mail هو الاستخدام المرجعي لهذه البوابة داخل إطار العمل، وهو نادر عن قصد. فهو يضبط `needsApproval: true` بحيث يمكن للوكيل صياغة رسائل البريد الإلكتروني وإدراجها في قائمة الانتظار بحرية. ولا يمكنه أبدًا إرسال رسالة فعليًا من دون أن يوافق إنسان على ذلك الإرسال المحدد.

## طلب الوصول إلى مورد {#access}

يعلن `access` عمّا يجب أن يحمله المستدعي قبل تشغيل الـ action. فهو بيانات على التعريف، لا كود داخل `run()`. وأكثر أشكاله شيوعًا يسمّي موردًا مشتركًا والحد الأدنى للدور عليه. يستخدمه action `update-form` في قالب Forms بحيث لا يستطيع تغيير أحد نماذج هذا القالب إلا محرر ذلك النموذج:

```ts
// actions/update-form.ts
export default defineAction({
  description: "Update an existing form.",
  access: {
    scope: "resource",
    resource: { type: "form", idFrom: "id", level: "editor" },
  },
  schema: z.object({
    id: z.string(),
    title: z.string().optional(),
  }),
  run: async (args) => {
    /* ...update the form... */
  },
});
```

يأخذ `resource` ثلاثة حقول:

- **type**: الاسم الذي سُجّل به المورد عبر `registerShareableResource()`، مثل `"form"` أو `"deck"`. راجع [المشاركة والخصوصية](/docs/sharing#building).
- **idFrom**: حقل المدخل الذي يحمل معرّف المورد. يقرأ المسار المنقّط مثل `"target.formId"` حقلًا متداخلًا. إذا كانت القيمة مفقودة أو ليست سلسلة نصية غير فارغة، يُرفض الاستدعاء.
- **level**: الحد الأدنى للدور الذي يحتاجه المستدعي، وهو أحد `"viewer"` أو `"commenter"` أو `"editor"` أو `"admin"` أو `"owner"`. وقيمته الافتراضية `"viewer"`.

مثل `authorize`، يغلّف الفحص `run()` نفسها، لذا تجتاز واجهة المستخدم ومستدعو HTTP والوكيل داخل التطبيق وعملاء MCP ومستدعو A2A وCLI جميعًا الفحص نفسه قبل تشغيل الجسم. ويحلّ دور المستدعي بالطريقة نفسها التي يفعلها `assertAccess()`، فتُحتسب الملكية والمشاركات والرؤية جميعًا. يحصل المستدعي الذي يقل دوره عن `level` على 403 مثل `Requires editor access to form <id>.` أما المورد غير الموجود فيحصل على الـ 403 نفسه.

استخدم `access` عندما يسمّي حقل مدخل واحد المورد الوحيد الذي يلمسه الـ action. واستخدم `assertAccess()` داخل `run()` عندما يأتي المعرّف من مكان آخر، مثل صف تحمّله أولًا، أو عندما يلمس استدعاء واحد عدة موارد. لا يوجد في استعلامات القوائم معرّف واحد لفحصه، لذا تستخدم `accessFilter()`. راجع [التحكم في الوصول داخل actions](#access-control) أدناه. يقبل فحص [Doctor](/docs/doctor) المسمى `resource-action-access` إما `access` مُعلَنًا أو استدعاء `assertAccess()`.

### نطاقات المؤسسة والتطبيق {#access-scopes}

تفحص الحقول الأخرى العضوية بدلًا من مورد واحد. يجب أن ينجح كل حقل تضبطه.

- **`scope: "org"`**: يجب أن يكون المستدعي عضوًا نشطًا في مؤسسته الحالية.
- **`scope: "app"`**: يجب أن يكون المستدعي قد قام بتسجيل الدخول، ويجب أن تكون مساحة العمل قد أتاحت له هذا التطبيق.
- **`permission`**: مفتاح إذن من خريطة `permissions` في `defineAppRoles()` الخاصة بهذا التطبيق. يجب أن يحمل المستدعي دور تطبيق يمنحه. ويُجري فحص `scope: "app"` أولًا.

يقرأ `scope: "app"` و`permission` سجل التطبيقات في مساحة العمل، لذا يناسبان التطبيقات المنشورة كجزء من مساحة عمل. في تطبيق مستقل، احمِ إذن التطبيق بدلًا من ذلك باستخدام `authorize` و`requirePermission()`، كما هو موضح في [أدوار التطبيق](/docs/organizations-teams-permissions#app-roles-per-app-rbac). يرفض ذلك الحارس أيضًا مفتاح إذن غير مُعلَن عند تحميل الوحدة. أما `access.permission` فيرفضه وقت الطلب فقط.

## تقييد المستدعين حسب الدور {#authorize}

يجيب `authorize` عن سؤال محدد واحد: **هل يجوز لهذا المستدعي تشغيل هذه العملية أصلًا؟** أعطه دالة حارسة، وستعمل قبل `run()` لدى كل مستدعٍ: أداة الوكيل، وHTTP، والواجهة الأمامية، وMCP، وA2A، وCLI.

أعلن مفردات الأدوار مرة واحدة باستخدام `defineAppRoles()`:

```ts
// server/lib/access.ts
import { defineAppRoles } from "@agent-native/core/org-team";

export const coachAccess = defineAppRoles({
  appId: "coach",
  roles: ["member", "coach-admin"] as const,
  defaultRole: "member", // display only, never satisfies a guard
});
```

بعد ذلك، احمِ الـ action بقائمة صريحة من الأدوار المقبولة:

```ts
// actions/archive-plan.ts
import { coachAccess } from "../server/lib/access.js";

export default defineAction({
  description: "Archive a training plan.",
  schema: z.object({ id: z.string() }),
  authorize: coachAccess.requireAny("coach-admin"),
  run: async ({ id }) => {
    /* ... */
  },
});
```

يغلّف الحارس `run()` نفسها، بدلاً من الارتباط بجزء آخر من الـ action. وذلك لأن `run()` هي الشيء الوحيد الذي تمر عبره كل مواقع الإرسال الستة، لذا لا توجد طريقة لكي يصل المستدعي إلى الجسم دون اجتياز الفحص. الحارس الذي يطرح خطأً يرفض الاستدعاء برسالة الخطأ الخاصة به. الحارس الذي يُرجع `false` يرفض الاستدعاء برمز 403 عام. أي شيء آخر، بما في ذلك `undefined`، يسمح بالاستدعاء. ولأن الفحص يحتاج إلى هوية مستدعٍ، يُرفض استدعاء CLI أو cron غير مراقَب لا يحمل بريد مستخدم بدلاً من السماح به.

تتركب الأغلفة بهذا الترتيب:

```text
validate input -> access -> authorize -> run -> validate output -> audit
```

يقع التخويل _داخل_ التحقق من صحة المدخل، لذا فإن الحارس الذي يفحص `args` يحصل على القيمة نفسها المحلَّلة والمتحقق من نوعها التي تستقبلها `run()`، لا أي شكل خام أرسله المستدعي. يقرأ `access` قيمة `idFrom` من القيمة المحلَّلة نفسها. التدقيق هو الطبقة الأكثر خارجية، لذا يُسجَّل الرفض أيضًا في actions الخاضعة للتدقيق. لا تُدقَّق actions للقراءة فقط افتراضيًا، راجع [تسجيل التدقيق](#audit) أدناه.

يفشل `requireAny()` في وقت التعريف، لا في وقت الطلب. استدعاؤه من دون أدوار، أو بدور خارج القائمة المُعلَنة، يطرح خطأً بمجرد تحميل الوحدة. بهذه الطريقة، ينكسر خطأ مثل `authorize: coachAccess.requireAny()` بوسيطة مفقودة تمامًا حيث وقع، بدلاً من أن يظهر لاحقًا كخطأ 403 غير مُفسَّر.

### التحكم في الوصول داخل actions {#access-control}

يجيب `authorize` فقط عمّا إذا كان يجوز للمستدعي تشغيل العملية أصلًا. فهو لا يقول شيئًا عن الصفوف التي يجوز له لمسها، وهذا فحص منفصل على مستوى الصف. يحصل الجدول المبني بـ `ownableColumns()` والمسجَّل بـ `registerShareableResource()` (راجع [المشاركة والخصوصية](/docs/sharing#building)) على مساعدَين لهذا: يحدّد `accessFilter()` نطاق استعلام القائمة أو القراءة إلى الصفوف التي يجوز للمستدعي رؤيتها، ويطرح `assertAccess()` خطأً قبل الكتابة إذا لم يكن المستدعي يحمل الدور المطلوب على ذلك الصف.

استخدم `accessFilter()` داخل استعلام action من نوع قائمة أو قراءة:

```ts
// actions/list-decks.ts
import { defineAction } from "@agent-native/core/action";
import { accessFilter } from "@agent-native/core/sharing";
import { z } from "zod";
import { getDb, schema } from "../server/db/index.js";

export default defineAction({
  description: "List the decks the current user can see.",
  schema: z.object({}),
  http: { method: "GET" },
  run: async () => {
    const db = getDb();
    return await db
      .select()
      .from(schema.decks)
      .where(accessFilter(schema.decks, schema.deckShares));
  },
});
```

استخدم `assertAccess()` قبل عملية تحديث أو حذف، لأن جملة `WHERE` وحدها لا يمكنها إيقاف كتابة إلى صف تستبعده:

```ts
// actions/rename-deck.ts
import { defineAction } from "@agent-native/core/action";
import { assertAccess } from "@agent-native/core/sharing";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { getDb, schema } from "../server/db/index.js";

export default defineAction({
  description: "Rename a deck.",
  schema: z.object({ id: z.string(), title: z.string() }),
  run: async ({ id, title }) => {
    await assertAccess("deck", id, "editor");
    const db = getDb();
    await db.update(schema.decks).set({ title }).where(eq(schema.decks.id, id));
    return { ok: true };
  },
});
```

عندما يأتي المعرّف مباشرة من المدخل، كما في `id` هنا، تُجري سياسة [`access`](#access) المُعلَنة الفحص نفسه من تعريف الـ action.

لا يستدعي action من نوع إنشاء أيًا من المساعدَين. فهو يحتاج فقط إلى ختم `ownerEmail` (و`orgId`) من سياق الطلب عند إدراج الصف الجديد، لأنه لا يوجد بعد صف موجود للتحقق من الوصول إليه. راجع [المشاركة والخصوصية](/docs/sharing#building) للاطلاع على نمط التسجيل والإنشاء الكامل، و[سياق التشغيل](/docs/actions-run-context) للاطلاع على الشكل الكامل للوسيطة الثانية `ctx` المستخدمة أعلاه.

الآليات الأربع غير قابلة للتبادل:

| الآلية                            | السؤال الذي تجيب عنه                                                  | تنطبق على                                               |
| --------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- |
| `access`                          | هل يحمل المستدعي الدور أو العضوية المُعلَنة؟                          | كل مواقع الإرسال الستة                                  |
| `authorize`                       | هل يجوز لهذا المستدعي تنفيذ العملية أصلًا؟                            | كل مواقع الإرسال الستة                                  |
| `needsApproval`                   | هل ينبغي أن يوافق إنسان على هذا الاستدعاء المسموح به تحديدًا؟         | الوكيل وMCP وA2A وCLI. تمنع HTTP الاستدعاءات دون إثبات. |
| `accessFilter()`/`assertAccess()` | ما الصفوف التي يجوز لهذا المستدعي المسموح له رؤيتها أو الكتابة إليها؟ | داخل `run()`، لكل استعلام أو صف                         |

يحتاج action كتابة مقيَّد عادةً إلى كل من `authorize` وفحص صف. يُبقي الأول غير المدربين خارج العملية. ويُبقي الثاني المدرب خارج خطة مؤسسة أخرى. فحص الصف هو `assertAccess()`، أو `access` عندما يكون معرّف الصف حقل مدخل. `needsApproval` محور منفصل. فهو لا يقيّد أبدًا من يجوز له الاستدعاء، بل فقط ما إذا كان يجوز للوكيل المضي قدمًا دون مراقبة.

يأتي `coachAccess` أعلاه من `defineAppRoles()`، طبقة الأدوار الخاصة بكل تطبيق فوق عضوية المؤسسة. راجع [المؤسسات والفرق والأذونات ← أدوار التطبيق](/docs/organizations-teams-permissions#app-roles-per-app-rbac) للاطلاع على نموذج الأدوار وضماناته.

## تسجيل التدقيق {#audit}

يُدقَّق كل action يغيّر البيانات تلقائيًا. يسجّل إطار العمل من شغّله، ومتى، ومن أي سطح، وعندما يكون الوكيل هو من شغّله، أي مسار وأي دور، مع مدخلات منقَّحة من بيانات الاعتماد. تُتخطى actions للقراءة فقط (`GET`). أنت لا تكتب أي كود لهذا. يحدث ذلك تلقائيًا داخل `defineAction()`.

أضف كتلة `audit` فقط لضبط الالتقاط بدقة. السبب الأكثر شيوعًا هو الإعلان عن المورد الذي غيّره الـ action، بحيث يظهر التغيير في مسار مالك ذلك المورد:

```ts
export default defineAction({
  description: "Delete a recording.",
  schema: z.object({ id: z.string() }),
  audit: {
    target: (args, result) => ({ type: "recording", id: args.id }),
    summary: (args) => `Deleted recording ${args.id}`,
  },
  run: async (args, ctx) => {
    /* ...delete... */
  },
});
```

خيارات أخرى قليلة. يُدقّق `audit: { onRead: true }` قراءة حساسة، مثل الوصول إلى سر أو تصدير مجمّع. يستبعد `audit: { enabled: false }` كتابة صاخبة. يتخطى `audit: { recordInputs: false }` التقاط الوسائط. اقرأ المسار مرة أخرى باستخدام actions المدمجَين `list-audit-events` و`get-audit-event`. راجع [سجل التدقيق](/docs/audit-log) للتفاصيل الكاملة.

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

- [**نظرة عامة**](/docs/actions-overview) — ما هو action وجولة hello-world
- [**تعريف Actions**](/docs/actions-defining) — تشريح `defineAction()`، والمخطط، وإعداد HTTP
- [**سياق التشغيل**](/docs/actions-run-context) — وسيطة `ctx` التي تقرأها هذه الفحوصات
- [**قالب Mail**](/docs/template-mail) — `send-email` هو المثال المرجعي لـ `needsApproval`
- [**سجل التدقيق**](/docs/audit-log) — المسار التلقائي لمن غيّر ماذا
- [**الأمان**](/docs/security) — `accessFilter`/`assertAccess` وحدود الثقة الخاصة بـ iframe الامتداد
- [**المشاركة والخصوصية**](/docs/sharing) — نظام المشاركة في إطار العمل الذي يدعم هذين المساعدَين
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