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/onboarding.mdx

View on GitHub
---
title: "مفاتيح الإعداد وAPI"
description: "قائمة التحقق من الإعداد للتهيئة التي يتم تشغيلها لأول مرة — مفاتيح API، وOAuth، واتصالات الموفر"
---

# التأهيل

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

<Diagram id="doc-block-f2r0l0" title={"قائمة التحقق من الإعداد"} summary={"مطلوب فقط توصيل محرك AI. تقوم اللوحة بتتبع الإكمال والإخفاء التلقائي بمجرد الانتهاء من كل ما هو مطلوب."}>

```html
<div class="ob">
  <div class="diagram-card">
    <span class="diagram-pill warn">required</span><strong>وصل محرك AI</strong
    ><small class="diagram-muted"
      >استخدم Builder.io (one click) or paste an LLM key</small
    >
  </div>
  <div class="diagram-card">
    <span class="diagram-pill">optional</span><strong>Database</strong
    ><small class="diagram-muted">set <code>DATABASE_URL</code></small>
  </div>
  <div class="diagram-card">
    <span class="diagram-pill">optional</span><strong>Authentication</strong
    ><small class="diagram-muted">OAuth / access token</small>
  </div>
  <div class="diagram-card">
    <span class="diagram-pill">optional</span
    ><strong>تسليم البريد الإلكتروني</strong
    ><small class="diagram-muted">Resend / SendGrid</small>
  </div>
  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
  <div class="diagram-box ok">all required done &rarr; panel auto-hides</div>
</div>
```

```css
.ob {
  display: flex;
  align-items: center;
  gap: 10px;
  flex-wrap: wrap;
}
.ob .diagram-card {
  display: flex;
  flex-direction: column;
  gap: 3px;
  padding: 12px 14px;
}
.ob .diagram-arrow {
  font-size: 22px;
}
```

</Diagram>

## للمستخدمين النهائيين

### ما ستراه

- لوحة **إعداد** أعلى دردشة الوكيل مع قائمة تحقق مثل "Connect an AI"
  المحرك"، "تسليم البريد الإلكتروني"، وما إلى ذلك.
- يوضح العداد الموجود في الأعلى (على سبيل المثال، "1 من 4") عدد الخطوات الجاهزة.
- تم توسيع الخطوة الحالية؛ تظهر الخطوات النهائية علامة الاختيار الخضراء والبقاء
  يمكن قراءتها إذا قمت بفتحها.
- تظهر الخطوات المطلوبة حبة حمراء صغيرة **مطلوبة**. تظل اللوحة مرئية
  حتى اكتمال كل الخطوات المطلوبة.
- بمجرد الانتهاء من كل ما هو مطلوب، تخفي اللوحة نفسها تلقائيًا.
- يمكن طي اللوحة بأكملها بحيث تكون الشيفرون في أعلى اليمين، أو
  مخفي بالكامل مع **إخفاء الإعداد** في الأسفل.

### كيفية إكمال كل خطوة

تقدم الخطوات واحدة أو أكثر من **الطرق** — طرق مختلفة لتحقيق نفس الهدف
المتطلبات. يظهر المسار الأساسي أولاً؛ يتم الاحتفاظ بالمسارات الثانوية مضغوطة
خلف المنتقي أو الكشف عندما تحتوي الخطوة على عدة موفري خدمات مكافئين.

- **إعداد خدمة (بنقرة واحدة)** — مثل _استخدم Builder.io_ لبوابة الذكاء الاصطناعي المُدارة. أنشئ حساب Builder.io أو فعّله مباشرةً داخل التطبيق. إذا كان لديك حساب بالفعل، اختر خيار تسجيل الدخول. لا حاجة إلى نسخ مفاتيح.
- **الصق مفتاح API أو املأ نموذجًا** — على سبيل المثال اختر موفر LLM وقاعدة البيانات
  موفر OAuth، أو موفر البريد الإلكتروني، الصق القيمة (القيم)، وانقر على **حفظ**.
  تستخدم الحقول السرية إدخال كلمة المرور، لذا لا تظهر القيمة على الشاشة. تم الحفظ
  تنتقل القيم إلى `.env` المحلي (أو إعدادات مساحة العمل) - راجع
  [Security](/docs/security) للمكان الذي يعيشون فيه.
- **فتح رابط** — تشير بعض الخطوات إلى صفحة تسجيل الدخول أو المستندات. انقر
  **تابع** وأكمل التدفق في علامة التبويب الجديدة.
- **اسأل الوكيل** — توفر بضع خطوات خيار "السماح للوكيل بإعداده".
  انقر عليه وسيقوم الوكيل بالرد عليك في الدردشة، ويرشدك خلال أي منها
  الإعداد الخارجي (إنشاء بيانات اعتماد OAuth، وما إلى ذلك).

### الخطوات المضمنة التي ستراها عادةً

- **توصيل محرك الذكاء الاصطناعي** (مطلوب) — الخطوة الإلزامية الوحيدة. الاتصال
  Builder لبوابة مُدارة بنقرة واحدة، أو افتح مفتاح الموفر الثانوي
  منتقي ولصق مفتاح LLM الخاص بك.
- **قاعدة البيانات** (اختياري) — قم بتعيين `DATABASE_URL` عندما تريد استخدام محدد
  سلسلة اتصال PostgreSQL.
- **المصادقة** (اختياري) — تعمل حسابات البريد الإلكتروني/كلمة المرور المضمنة بواسطة
  افتراضي. قم بإضافة OAuth أو تسجيل الدخول برمز الوصول فقط عندما تريد هذه المسارات.
- **تسليم البريد الإلكتروني** (اختياري) — مفيد قبل النشر لإعادة تعيين كلمة المرور،
  دعوات الفريق وإشعارات المشاركة. استخدم الموفر الذي تستخدمه بالفعل؛
  يمكن تحقيق التنمية المحلية بدونها.

يمكن للقوالب إضافة خطواتها الخاصة فوق هذه الخطوات - على سبيل المثال. قد يكون قالب CRM
أضف "Connect Gmail"، وقد يضيف قالب المستندات "اختر مساحة عمل افتراضية". انظر
[Authentication](/docs/authentication) للحصول على تفاصيل إعداد تسجيل الدخول.

### الرجوع إلى قائمة التحقق

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

## للمطورين

إذا كنت تقوم بإنشاء نموذج، فعليك تسجيل خطوات الإعداد حتى تظهر في
قائمة التحقق من الشريط الجانبي للمستخدم. يعالج الإطار العرض والإكمال
التتبع والفصل - ما عليك سوى الإعلان عن الخطوة وكيف تتم
راضي.

النظام **مثبت تلقائيًا**. لا تحتاج القوالب إلى توصيل أي شيء للحصول عليها
الخطوات الأربع المضمنة (LLM، قاعدة البيانات، المصادقة، البريد الإلكتروني). لإضافة تطبيق محدد
الخطوات (Gmail، Slack، Notion، وما إلى ذلك)، اتصل بـ `registerOnboardingStep()` من
المكون الإضافي للخادم.

### المسارات المثبتة تلقائيًا

جميع المسارات موجودة ضمن `/_agent-native/onboarding/`:

| المسار                                              | الغرض                               |
| --------------------------------------------------- | ----------------------------------- |
| `GET /_agent-native/onboarding/steps`               | أدرج الخطوات مع حالة الإكمال        |
| `POST /_agent-native/onboarding/steps/:id/complete` | وضع علامة على الخطوة مكتملة (تجاوز) |
| `POST /_agent-native/onboarding/dismiss`            | رفض شعار الإعداد                    |
| `POST /_agent-native/onboarding/reopen`             | مسح الرفض (إعادة إظهار اللوحة)      |
| `GET /_agent-native/onboarding/dismissed`           | قراءة الفصل + العلامة الكاملة       |

<Endpoint id="doc-block-1n92aj8" title={"قم بإدراج خطوات الإعداد"} method="GET" path="/_agent-native/onboarding/steps" summary={"قم بإدراج جميع الخطوات المسجلة مع حالة اكتمالها"} responses={[
  {
    "status": "200",
    "description": "Array of steps with completion status for the current user/app."
  }
]}>

Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.

</Endpoint>

### إضافة خطوة من القالب

<AnnotatedCode
  id="doc-block-icnf07"
  title={"تسجيل خطوة تأهيل مخصصة"}
  filename="server/plugins/my-onboarding.ts"
  language="ts"
  code={
    'import { defineNitroPlugin } from "@agent-native/core/server";\nimport { registerOnboardingStep } from "@agent-native/core/onboarding";\nimport { listOAuthAccounts } from "@agent-native/core/oauth-tokens";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: "gmail",\n    order: 100,\n    title: "Connect Gmail",\n    description: "Grant read/send access so the agent can work with email.",\n    methods: [\n      {\n        id: "oauth",\n        kind: "link",\n        primary: true,\n        label: "Sign in with Google",\n        payload: { url: "/_agent-native/google/auth-url?scope=mail", external: false },\n      },\n      {\n        id: "delegate",\n        kind: "agent-task",\n        label: "Let the agent set it up",\n        badge: "beta",\n        payload: { prompt: "Walk me through connecting Gmail. Set env vars as needed." },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts("google");\n      return accounts.length > 0;\n    },\n  });\n});'
  }
  annotations={[
    {
      lines: "5",
      label: "مثبتة تلقائيًا",
      note: "قم بالتسجيل من مكون إضافي Nitro - يعالج إطار العمل العرض وتتبع الإكمال والفصل.",
    },
    {
      lines: "7",
      label: "معرف المكدس",
      note: "إعادة التسجيل بنفس `id` بعد تحميل الإعدادات الافتراضية يتجاوز خطوة مضمنة.",
    },
    {
      lines: "12-19",
      label: "الطريقة الأساسية",
      note: '`primary: true` marks the big CTA. `kind: "link"` sends the user into the OAuth flow.',
    },
    {
      lines: "20-26",
      label: "مسار التفويض",
      note: '`kind: "agent-task"` يسلّم الإعداد إلى دردشة الوكيل مع مطالبة.',
    },
    {
      lines: "28-31",
      label: "التحقق من الإكمال",
      note: "`isComplete` يعمل من جانب الخادم. رموز OAuth موجودة في متجر `oauth_tokens` - تحقق منها، وليس `process.env.GMAIL_REFRESH_TOKEN`.",
    },
  ]}
/>

### التحقق من اتصالات مساحة العمل أثناء الإعداد

عند إنشاء قوالب تتفاعل مع الخدمات الخارجية (مثل Slack أو Google Workspace أو GitHub أو HubSpot)، يجب عليك التحقق مما إذا كانت مساحة العمل متصلة بالفعل ومنحت اتصال الموفر هذا بتطبيقك. وهذا يمنع المستخدمين من الاضطرار إلى تكرار بيانات الاعتماد (مثل مفاتيح API أو الرموز المميزة للتحديث) في متغيرات البيئة المحلية الخاصة بهم عند وجود اتصال مركزي مُدار.

يمكنك التحقق من جاهزية الاتصال في رد الاتصال `isComplete` باستخدام كتالوج الاتصال APIs:

```ts
import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
import {
  getRequestOrgId,
  getRequestUserEmail,
} from "@agent-native/core/server";

// Inside registerOnboardingStep:
isComplete: async () => {
  // Check if a managed workspace connection exists and is ready
  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
    appId: "mail",
    templateUse: "mail",
    provider: "gmail",
  });
  const connection = catalog.providers[0];

  if (
    connection?.readiness.status === "ready" &&
    connection.workspaceConnection.grantState === "granted"
  ) {
    return true;
  }

  // If there is no reusable connection, check the caller-scoped credential
  // store - never a deployment environment variable.
  const { resolveCredential } = await import("@agent-native/core/credentials");
  return Boolean(
    await resolveCredential("GMAIL_REFRESH_TOKEN", {
      userEmail: getRequestUserEmail(),
      orgId: getRequestOrgId(),
    }),
  );
};
```

راجع وثائق [Workspace Connections](/docs/workspace-connections) للحصول على القائمة الكاملة لطرق كتالوج موفر الاتصال.

### أنواع الطرق

| النوع              | الحمولة                                               | يستخدم لـ                                        |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------ |
| `link`             | `{ url, external? }`                                  | أرسل المستخدم إلى صفحة التدفق أو المستندات OAuth |
| `form`             | `{ fields, writeScope? }`                             | اجمع env vars (المفاتيح، الأسرار، URLs)          |
| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | استخدم Builder.io (unlocks shared infra)         |
| `agent-task`       | `{ prompt }`                                          | أرسل مطالبة إلى دردشة الوكيل للتعامل معها        |
| `file-storage`     | -                                                     | اعرض نموذج التخزين المشترك المتوافق مع S3        |

تشير علامة `primary: true` إلى الطريقة باعتبارها CTA الكبيرة لخطوتها.
استخدم `badge: "soon"` بالإضافة إلى `disabled: true` عندما يكون مسار الإعداد مرئيًا
قبل أن يصبح متاحًا.

### الخطوات المضمنة

| المعرف     | مطلوب | الوصف                                                          |
| ---------- | ----- | -------------------------------------------------------------- |
| `llm`      | نعم   | اتصال Builder أو مفتاح LLM للموفر                              |
| `database` | لا    | عنوان PostgreSQL مستضاف أو اتركه فارغًا لاستخدام PGlite المحلي |
| `auth`     | لا    | حسابات مدمجة، OAuth اختياري أو رمز وصول                        |
| `email`    | لا    | إعادة إرسال أو SendGrid للبريد الإلكتروني الخاص بالمعاملات     |

يمكن تجاوز أي من هذه العناصر عن طريق إعادة التسجيل بنفس `id` بعد
التحميل الافتراضي.

### استخدام العميل

اللوحة موجودة بالفعل داخل `<AgentPanel>`. لإنشاء تخطيط مخصص:

```tsx
import {
  OnboardingPanel,
  OnboardingBanner,
  useOnboarding,
} from "@agent-native/core/client/onboarding";

function MySidebar() {
  const { allComplete, dismissed, currentStepId } = useOnboarding();
  if (allComplete || dismissed) return <Chat />;
  return (
    <>
      <OnboardingPanel />
      <Chat />
    </>
  );
}
```

للحصول على معلومات أساسية عن مكان تخزين قيم الخطوات وكيفية التعامل مع الأسرار،
راجع [Security](/docs/security). بالنسبة لنقاط اتصال مراسلة المستخدم النهائي (الدعوات،
إعادة تعيين كلمة المرور) التي تعتمد على خطوة **تسليم البريد الإلكتروني**، راجع
[Messaging](/docs/messaging).
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