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/getting-started.mdx
View on GitHub---
title: "البدء"
description: "أنشئ وكيلاً بواجهة مستخدم للمحادثة واستدعِ الإجراء نفسه من الوكيل وواجهة المستخدم."
---
# البدء
<GettingStartedPaths />
Agent-Native هو إطار عمل TypeScript مفتوح المصدر لبناء وكلاء مستقلين بواجهات
استخدام بديهية. تعرّف كل قدرة مرة واحدة كـ [إجراء](/docs/actions-overview) — دالة
مكتوبة الأنواع يستخدمها الوكيل كأداة وتستدعيها واجهة المستخدم من الكود.
في هذا الدليل، ستنشئ وكيلاً بواجهة مستخدم للمحادثة وتستدعي إجراء `hello`
المضمّن فيه من الوكيل وواجهة المستخدم.
هل تفضّل أن يتولى وكيل ذكاء اصطناعي الإعداد؟ راجع
[إنشاء تطبيق باستخدام وكيل ذكاء اصطناعي](/docs/create-with-an-agent).
## المتطلبات الأساسية
- [Node.js](https://nodejs.org) 22.22 أو أحدث
- [pnpm](https://pnpm.io) مثبت ومتاح في `PATH`
- اختياري أثناء الإعداد، ومطلوب لتشغيل الوكيل: Builder.io، أو مفتاح Anthropic/OpenAI، أو Ollama محلي
## إنشاء وكيل
في دليل جديد، ابدأ من قالب Chat:
```bash
npx --yes @agent-native/core@latest create my-app --standalone --template chat
cd my-app
corepack enable
pnpm install
```
يوفّر القالب للوكيل واجهة مستخدم في المتصفح، ومصادقة، ومحادثات دائمة، ومزامنة
مباشرة، وسياقًا للتطبيق، ودليل `actions/`. كما يتضمن إجراء `hello` صغيرًا
ستستخدمه خلال هذا الدليل.
تجمع أداة سطر الأوامر بيانات استخدام مجهولة الهوية وتُعلمك بذلك عند أول تشغيل. تسرد صفحة [القياس عن بُعد](/docs/telemetry) ما ترسله وكيفية إيقافه.
<Callout tone="info">
إذا فشلت هذه الأوامر بأخطاء في التبعيات النظيرة، فقد يكون السبب نسخة قديمة من حزمة في ذاكرة npx المؤقتة. شغّل `npx clear-npx-cache` لمسح الذاكرة المؤقتة، ثم شغّل الأوامر مرة أخرى.
</Callout>
## بدء خادم التطوير
ابدأ خادم التطوير:
```bash
pnpm dev
```
تُفتح واجهة المستخدم تلقائيًا. إذا لم تُفتح، فاستخدم العنوان المحلي الذي يطبعه
`pnpm dev`؛ يزداد رقم المنفذ إذا كان تطبيق آخر يستخدم 8080.
<Callout tone="info">
في شاشة الترحيب، اختر **Continue as local dev**. لا تحتاج إلى إدخال بريد
إلكتروني أو كلمة مرور للتطوير المحلي.
</Callout>
## الاتصال بنموذج LLM (اختياري) {#connect-an-llm}
اختياري: اتصل باستخدام **Use Builder.io**، أو أضف مفتاحًا عبر **Custom keys**، أو ضع مفتاح موفّر في `.env` للتطوير المحلي. في عمليات النشر المستضافة ذاتيًا، يمكن استخدام مفتاح من جهة الخادم كخيار احتياطي على مستوى التطبيق. راجع [مفاتيح موفّري LLM](/docs/environment-variables#llm-provider-keys).
## تشغيل الإجراء من الوكيل
الإجراء هو دالة مكتوبة الأنواع يمكن لواجهة React استدعاؤها من الكود ويمكن
للوكلاء استخدامها كأداة. يتضمن قالب Chat إجراء `hello` بسيطًا لتجربة هذا
النمط قبل كتابة إجراء خاص بك.
في حقل الطلب في صفحة **ابدأ الآن**، اطلب:
> Call the hello action for Alex.
يعثر الوكيل على `hello` من وصفه ومخطط إدخاله، ويمرر `Alex` كإدخال `name`، ثم
يرد:
```text
Hello, Alex!
```
## فحص الإجراء
في دليل `my-app` المحلي، افتح `actions/hello.ts` في محرر الشفرة:
```ts filename="actions/hello.ts"
import { defineAction } from "@agent-native/core/action";
import { z } from "zod";
// One action powers every app surface: UI, agent, HTTP, MCP, A2A, and CLI.
export default defineAction({
description: "Return a friendly greeting.",
schema: z.object({
name: z.string().default("world").describe("Name to greet"),
}),
http: { method: "GET" },
run: async ({ name }) => {
return { message: `Hello, ${name}!` };
},
});
```
ركّز الآن على أربعة أجزاء:
- يوضح `description` للوكيل متى يستخدم الإجراء.
- يتحقق `schema` من الإدخال ويمنح الوكيل تعريف أداة مكتوب الأنواع.
- يعرّض `http` هذا الإجراء للقراءة فقط عبر `GET`، ما يسمح لـ
`useActionQuery` باستدعائه من React.
- يحتوي `run` على منطق التطبيق الذي يشترك فيه الوكيل وواجهة المستخدم.
راجع [تعريف الإجراءات](/docs/actions-defining) للاطلاع على واجهة API الكاملة.
## استدعاء الإجراء من React
يتضمن القالب `actions/hello.ts`، لكنه لا يتضمن صفحة له. أنشئ
`app/routes/hello.tsx`:
```tsx filename="app/routes/hello.tsx"
import { useActionQuery } from "@agent-native/core/client/hooks";
import { useState } from "react";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
export default function HelloRoute() {
const [name, setName] = useState("Alex");
const { data } = useActionQuery("hello", { name });
return (
<main className="mx-auto grid w-full max-w-xl gap-6 p-6">
<h1 className="text-2xl font-semibold">Hello action</h1>
<div className="grid gap-2">
<Label htmlFor="name">Name</Label>
<Input
id="name"
value={name}
onChange={(event) => setName(event.target.value)}
/>
</div>
<p className="text-xl font-medium">{data?.message}</p>
</main>
);
}
```
<Callout tone="info">
أعد تشغيل خادم التطوير كي يكتشف المسار الجديد، ثم افتح
`http://localhost:<port>/hello`.
</Callout>
أثناء كتابة اسم، يستدعي `useActionQuery` الإجراء `hello` ويعرض النتيجة. وهو
يستنتج أنواع إدخال الإجراء ونتيجته، لذلك لا تحتاج الصفحة إلى مسار API مخصص أو
تنفيذ ثانٍ للتحية.
## تغيير الإجراء
في `actions/hello.ts`، غيّر القيمة المرجعة:
```ts
return { message: `Welcome, ${name}.` };
```
حدّث `/hello`، ثم اطلب من الوكيل استدعاء `hello` مرة أخرى. سيعيد كلاهما
التحية المحدّثة لأنهما يستدعيان الإجراء نفسه.
## استدعاء الإجراءات بطرق أخرى
لقد استدعيت الإجراء نفسه من الوكيل وواجهة المستخدم. ويمكن أيضًا استدعاء
الإجراء نفسه من:
| الاستدعاء من | استخدمه من أجل |
| --------------------------------------- | -------------------------------------------------------------------- |
| [HTTP API](/docs/http-api) | استدعاء إجراء من نص برمجي أو خلفية أو تكامل. |
| [CLI](/docs/actions-other-surfaces#cli) | تشغيل إجراء أو اختباره من طرفية. |
| [MCP](/docs/actions-other-surfaces#mcp) | تمكين عميل ذكاء اصطناعي خارجي من اكتشاف الإجراءات واستدعائها كأدوات. |
| [A2A](/docs/actions-other-surfaces#a2a) | تمكين وكيل آخر من تفويض العمل إلى وكيلك. |
يستخدم كل مستدعٍ تعريف الإجراء نفسه. لا تحتاج إلى تنفيذ منفصل لكل واحد. يمثل
نموذج الإجراءات المشتركة هذا جوهر Agent-Native: إذ تبقى السلوكيات والتحقق
والصلاحيات متسقة بين واجهة المستخدم والوكلاء والتكاملات مع إضافة قدرات جديدة.
## ما أنشأته
أنشأت وكيلاً بواجهة مستخدم للمحادثة، واستدعيت إجراء `hello` نفسه من الوكيل ومن
واجهة React، ثم غيّرت التحية مرة واحدة وشاهدت كليهما يتحدثان. يتبع كل إجراء
تكتبه من الآن فصاعدًا النمط نفسه.
## الخطوات التالية
<Cards>
### [ما هو Agent-Native؟](/docs/what-is-agent-native)
تعرّف على سبب مشاركة واجهة المستخدم والوكيل للإجراءات والبيانات والسياق.
### [المفاهيم الأساسية](/docs/key-concepts)
تعرّف على كيفية توافق الإجراءات وبيانات SQL وسياق التطبيق والوصول والمزامنة
المباشرة معًا.
### [الإجراءات](/docs/actions-overview)
عرّف إجراءات للقراءة والكتابة والموافقات، ثم استدعها من واجهة المستخدم والوكلاء
والعملاء الخارجيين.
### [نشر تطبيق](/docs/deploy-an-app)
انتقل من التطوير المحلي إلى قاعدة بيانات دائمة ومصادقة إنتاجية وهدف نشر مدعوم.
</Cards>
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 |