AI-translated from English; not yet reviewed by a fluent editor.

# تحقّق من إجراء Agent-Native واحد عبر الدردشة وصفحة React

> استدعِ إجراء hello من قالب Chat عبر دردشة الوكيل ومسار React، وعدّل قيمة إرجاع واحدة، ثم قارن النتائج الموثّقة مع التحقق من دليل استدعاء الأداة.

By BIG CHANGE Editorial

Published: 2026-10-19T10:08:15.758Z
Updated: 2026-10-19T10:08:15.758Z
Canonical: https://bigchange.ai/blog/agent-native-chat-react-action-parity-guide

![Conceptual charcoal illustration of one laptop showing two blank side-by-side work areas: conversation shapes on the left and a plain input and output area on the right.](https://bigchange.ai/api/media/file/agent-native-chat-react-comparison-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE; no actual product interface, action invocation or test result is depicted.

يتضمن قالب Chat في Agent-Native إجراء `hello` يمكن للوكيل استدعاؤه. يستطيع مطوّر TypeScript إضافة مسار React صغير يستدعي الإجراء نفسه، وتغيير قيمة إرجاع واحدة، ثم مقارنة النتيجتين. يتبع هذا الدليل [مثال Agent-Native الموثّق](https://www.agent-native.com/docs/)؛ راجعت BIG CHANGE الوثائق ومصدر القالب، لكنها لم تشغّل التطبيق.

## التغيير الكبير

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

## إعداد قالب Chat الموثّق

تحتاج إلى Node.js 22.22 أو أحدث، و `pnpm` ، ومحرّر كود، ومفتاح OpenAI API لاستدعاء الدردشة. يمكن إعداد الواجهة قبل توصيل نموذج. أظهرت [حزمة core التي فُحصت](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) وسجل npm الإصدار `0.209.2` في 18 أكتوبر 2026. يستخدم أمر الإنشاء الرسمي الوسم المتغيّر `@latest` ؛ تحقّق من إصداره مجددًا قبل اتباع الدليل.

1. أنشئ تطبيق Chat مستقلًا وشغّله في مجلد جديد:

```bash
   npx --yes @agent-native/core@latest create my-app --standalone --template chat
   cd my-app
   corepack enable
   pnpm install
   pnpm dev
```

 افتح عنوان URL المحلي الذي يطبعه `pnpm dev` ، واختر **Continue as local dev**. قد يرتفع رقم المنفذ إذا كان 8080 مشغولًا. يتضمن التطبيق الناتج `actions/hello.ts` .

2. صِل وكيل الدردشة عبر **Custom keys** ومفتاح OpenAI API الخاص بك، ثم اختر نموذجًا متاحًا في Settings. يوضح [دليل متغيرات البيئة](https://www.agent-native.com/docs/environment-variables/) أن Custom keys يحفظ بيانات الاعتماد محددة النطاق في مخزن التطبيق المشفّر المدعوم بقاعدة بيانات. لا تضع المفاتيح في مستودع الكود أو متغيرات `VITE_` المكشوفة للمتصفح. تستخدم طلبات النموذج حساب مالك المفتاح لدى المزوّد؛ راجع الأسعار الحالية و[ضوابط البيانات](https://developers.openai.com/api/docs/guides/your-data) قبل إرسال مواد حساسة. لم تُقَس هنا تكلفة المهمة أو آلية الاحتفاظ بالبيانات.
3. في دردشة Get started، اطلب: `Call the hello action for Alex.` يعرض [دليل البدء](https://www.agent-native.com/docs/) الرد المتوقع `Hello, Alex!` . إذا عرضت الواجهة تفاصيل الأدوات، فتحقّق من استدعاء `hello` باستخدام `name: "Alex"` وإرجاع تلك الرسالة. تطابق الجملة دون دليل الاستدعاء ليس حاسمًا.
4. افحص `actions/hello.ts` . يعرّف [قالب Chat المثبّت على هذه المراجعة](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) مُدخل Zod باسم `name` وإجراء GET و `mcpTool: true` . احتفظ بهذه الخصائص. أنشئ `app/routes/hello.tsx` بهذه الصفحة الصغيرة:

```typescript
   import { useActionQuery } from "@agent-native/core/client/hooks";
   import { useState } from "react";

   export default function HelloRoute() {
     const [name, setName] = useState("Alex");
     const { data } = useActionQuery("hello", { name });

     return (
       <main>
         <label htmlFor="greeting-name">Name</label>
         <input
           id="greeting-name"
           value={name}
           onChange={(event) => setName(event.target.value)}
         />
         <p>{data?.message}</p>
       </main>
     );
   }
```

 أعد تشغيل `pnpm dev` ليكتشف المسار، ثم أضف `/hello` إلى عنوان URL المحلي المطبوع. عندما يكون المُدخل `Alex` ، تكون النتيجة الموثّقة `Hello, Alex!` .

5. في الدالة `run` الموجودة في `actions/hello.ts` ، استبدل عبارة الإرجاع فقط:

```typescript
   return { message: `Welcome, ${name}.` };
```

 حدّث `/hello` واطلب من الدردشة استدعاء `hello` لـ Alex مجددًا. التوقع الموثّق هو `Welcome, Alex.` في الموضعين. قارن رسالة الصفحة بنتيجة الإجراء في الدردشة، بما في ذلك تفاصيل الأداة إن توفّرت. تحتفظ الصفحة بمُدخلها في حالة React؛ إجراء التحية هذا لا يقرأ سجلًا مشتركًا ولا يكتب فيه.

| الفحص | قبل تعديل الإرجاع | بعد تعديل الإرجاع |
| --- | --- | --- |
| `/hello` مع `Alex` | `Hello, Alex!` | `Welcome, Alex.` |
| نتيجة إجراء الدردشة لـ `name: "Alex"` | `Hello, Alex!` | `Welcome, Alex.` |

هذه هي القيم المتوقعة في الوثائق. سجّل القيم الظاهرة لديك وتفاصيل الاستدعاء المتاحة قبل اعتبار التجربة مكتملة.

إذا كان `pnpm` غير متوفر، فشغّل `corepack enable` في التطبيق الناتج. لأخطاء peer dependencies، يقترح الدليل الرسمي `npx clear-npx-cache` قبل المحاولة مجددًا. إذا عرضت الدردشة **Connect AI**، فأكمل إعداد المزوّد قبل تشخيص الإجراء. إذا غاب `/hello` ، فأعد تشغيل خادم التطوير بعد إنشاء المسار. هذه خطوات استرداد موثّقة وليست نتائج رصدناها.

## المصادر وقراءات إضافية

- [يوثّق دليل بدء Agent-Native](https://www.agent-native.com/docs/) الإنشاء وتعليمة الوكيل وReact hook والردود المتوقعة وخطوات الاسترداد. يحذف مقتطف الإجراء خاصية موجودة في القالب المثبّت، لذا عدّل الإجراء الناتج في موضعه.
- [يثبت إجراء Chat `hello` في المراجعة المحددة](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) خصائص المصدر، ومنها `mcpTool: true` ، عند commit `8e8419361fb415682cdf0e0e68538671dbb6aed3` . لا تثبت هذه اللقطة ما ستثبّته عملية إنشاء لاحقة.
- [تشرح متغيرات البيئة](https://www.agent-native.com/docs/environment-variables/) نطاق المفاتيح واختيار النموذج وحدود `VITE_` العامة. راجع شروط المزوّد منفصلة؛ لم يفحص هذا الدليل طلب دردشة فعليًا.

## Sources

- [دليل بدء Agent-Native](https://www.agent-native.com/docs/) — يوثّق [دليل بدء Agent-Native](https://www.agent-native.com/docs/) الإنشاء وتعليمة الوكيل وReact hook والردود المتوقعة وخطوات الاسترداد. يحذف مقتطف الإجراء خاصية موجودة في القالب المثبّت، لذا عدّل الإجراء الناتج في موضعه.
- [إجراء Chat hello في المراجعة المحددة](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) — يثبت [إجراء Chat `hello` في المراجعة المحددة](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) خصائص المصدر، ومنها `mcpTool: true`، عند commit `8e8419361fb415682cdf0e0e68538671dbb6aed3`. لا تثبت هذه اللقطة ما ستثبّته عملية إنشاء لاحقة.
- [حزمة core في المراجعة المحددة](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) — إصدار الحزمة ومتطلبات Node والترخيص.
- [متغيرات البيئة في Agent-Native](https://www.agent-native.com/docs/environment-variables/) — تشرح [متغيرات البيئة](https://www.agent-native.com/docs/environment-variables/) نطاق المفاتيح واختيار النموذج وحدود `VITE_` العامة. راجع شروط المزوّد منفصلة؛ لم يفحص هذا الدليل طلب دردشة فعليًا.
- [ضوابط بيانات OpenAI API](https://developers.openai.com/api/docs/guides/your-data) — مرجع لمعالجة المزوّد للبيانات؛ لم تُرصد حركة بيانات خاصة بهذه المهمة.