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

يتضمن قالب Chat في Agent-Native إجراء hello يمكن للوكيل استدعاؤه. يستطيع مطوّر TypeScript إضافة مسار React صغير يستدعي الإجراء نفسه، وتغيير قيمة إرجاع واحدة، ثم مقارنة النتيجتين. يتبع هذا الدليل مثال Agent-Native الموثّق؛ راجعت BIG CHANGE الوثائق ومصدر القالب، لكنها لم تشغّل التطبيق.

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

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

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

تحتاج إلى Node.js 22.22 أو أحدث، و pnpm ، ومحرّر كود، ومفتاح OpenAI API لاستدعاء الدردشة. يمكن إعداد الواجهة قبل توصيل نموذج. أظهرت حزمة core التي فُحصت وسجل npm الإصدار 0.209.2 في 18 أكتوبر 2026. يستخدم أمر الإنشاء الرسمي الوسم المتغيّر @latest ؛ تحقّق من إصداره مجددًا قبل اتباع الدليل.

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

   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. يوضح دليل متغيرات البيئة أن Custom keys يحفظ بيانات الاعتماد محددة النطاق في مخزن التطبيق المشفّر المدعوم بقاعدة بيانات. لا تضع المفاتيح في مستودع الكود أو متغيرات VITE_ المكشوفة للمتصفح. تستخدم طلبات النموذج حساب مالك المفتاح لدى المزوّد؛ راجع الأسعار الحالية وضوابط البيانات قبل إرسال مواد حساسة. لم تُقَس هنا تكلفة المهمة أو آلية الاحتفاظ بالبيانات.
3. في دردشة Get started، اطلب: Call the hello action for Alex. يعرض دليل البدء الرد المتوقع Hello, Alex! . إذا عرضت الواجهة تفاصيل الأدوات، فتحقّق من استدعاء hello باستخدام name: "Alex" وإرجاع تلك الرسالة. تطابق الجملة دون دليل الاستدعاء ليس حاسمًا.
4. افحص actions/hello.ts . يعرّف قالب Chat المثبّت على هذه المراجعة مُدخل Zod باسم name وإجراء GET و mcpTool: true . احتفظ بهذه الخصائص. أنشئ app/routes/hello.tsx بهذه الصفحة الصغيرة:

   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 ، استبدل عبارة الإرجاع فقط:

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

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

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

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

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

• يوثّق دليل بدء Agent-Native الإنشاء وتعليمة الوكيل وReact hook والردود المتوقعة وخطوات الاسترداد. يحذف مقتطف الإجراء خاصية موجودة في القالب المثبّت، لذا عدّل الإجراء الناتج في موضعه.
• يثبت إجراء Chat hello في المراجعة المحددة خصائص المصدر، ومنها mcpTool: true ، عند commit 8e8419361fb415682cdf0e0e68538671dbb6aed3 . لا تثبت هذه اللقطة ما ستثبّته عملية إنشاء لاحقة.
• تشرح متغيرات البيئة نطاق المفاتيح واختيار النموذج وحدود VITE_ العامة. راجع شروط المزوّد منفصلة؛ لم يفحص هذا الدليل طلب دردشة فعليًا.