انتقل إلى المحتوى
وكلاء من أوكال

جارٍ تحميل دليل الاستخدام…

وكلاء من أوكال
للوكلاءالتواصل
وكلاء من أوكال
مسار دليل الاستخدام
دليل الاستخدام

ابدأ هنا

  • شغّل وكيلك الأول

بناء التكامل

  • بثّ الرسائل والأدوات والنتائج
  • أبقِ خادمك الخلفي متحكّمًا
  • بناء واجهة React تفاعلية مباشرة
  • ربط تطبيق Next.js

الأدوات والسلوك

  • ربط خادم MCP بعيد
  • إضافة مهارات وتعليمات قابلة لإعادة الاستخدام
  • التعامل مع الموافقات والأسئلة والنماذج

التشغيل الموثوق

  • الأخطاء والتعافي
  • فهم الاستخدام والحدود
فهرس دليل الاستخدام للوكلاءدليل الاستخدام الكامل للوكلاء

بناء التكامل

ربط تطبيق Next.js

أضف جسرًا للواجهة الخلفية من المصدر نفسه وأعد استخدام React SDK دون نموذج ثانٍ لحالة الوكيل.

عرض Markdown

تثبيت طبقة إطار العمل

bash
npm install "https://wkala.okal.io/downloads/wkala-client-0.1.0.tgz" "https://wkala.okal.io/downloads/wkala-react-0.1.0.tgz" "https://wkala.okal.io/downloads/wkala-next-0.1.0.tgz"

استخدم Next.js 16 وReact 19. تعيد نقطة الدخول الخاصة بالمتصفح تصدير AgentProvider وuseAgent وuseSession وAgentClient من طبقة React. وتفرض نقطة الدخول /server حدود Next التي تقصر الاستخدام على الخادم.

إضافة وكيل الواجهة الخلفية للعميل

typescript
// app/app/[...path]/route.ts
import { createAppProxy } from "@wkala/next/server"

export const runtime = "nodejs"
export const dynamic = "force-dynamic"

const route = createAppProxy({
  target: () => process.env.RELAY_CUSTOMER_URL!,
})
export { route as GET, route as POST, route as PATCH, route as DELETE }

RELAY_CUSTOMER_URL متغير بيئة ثابت على الخادم يشير إلى أصل تطبيق Python، مثل http://127.0.0.1:8081. أُبقي هذا الاسم عمدًا للتوافق. لا تضف إليه البادئة NEXT_PUBLIC_. ولا يتضمن مسارًا أو بيانات اعتماد أو استعلامًا أو جزءًا مرجعيًا. لا يمكن للمتصفح اختيار وجهته.

يتولى تطبيق Python تسجيل دخول المستخدمين النهائيين، وملكية الجلسات، والتحقق من Origin وCSRF، وحفظ مفتاح Wkala الخاص. اضبط أصل المتصفح المسموح به على عنوان URL العام لتطبيق Next.js. اضبط مسار ملف تعريف الارتباط على /app. استخدم ملفات تعريف ارتباط بخاصية Secure عند العمل عبر HTTPS. هذه الطبقة مستقلة عن تسجيل الدخول إلى لوحة تحكم خدمة Wkala.

عرض تكامل React نفسه

tsx
"use client"
import { AgentClient, AgentProvider, useSession } from "@wkala/next"

اتبع دليل React. لا تضع أي مفتاح خدمة في خاصية لمكوّن. أبقِ صفحات الهبوط والتوثيق ثابتة. وحدها واجهات التطبيق المحمية بالمصادقة تحتاج إلى سلوك خاص بكل طلب.

لقطة خادم اختيارية تعتمد على المصادقة

typescript
// In a Server Component, using an already authorized session ID.
import { cookies } from "next/headers"
import { getSessionSnapshot } from "@wkala/next/server"

const snapshot = await getSessionSnapshot({
  target: process.env.RELAY_CUSTOMER_URL!,
  sessionId: ownedSessionId,
  cookie: (await cookies()).toString(),
})

تظل الواجهة الخلفية للعميل مسؤولة عن التحقق من الملكية. لا يُخزَّن هذا الطلب مؤقتًا. مرّر النتيجة نفسها دون تغيير إلى useSession(id, { initialSnapshot: snapshot }) لضمان ترطيب متسق للواجهة. أنشئ مخازن محصورة في نطاق الطلب. ولا تخزّن اللقطات الخاصة مؤقتًا بحيث تتشاركها حسابات مستخدمين مختلفين.

البث دون تخزين مؤقت

يمرّر الوكيل حالة الاستجابة وترويساتها، ثم جسم الاستجابة مع مراعاة الضغط العكسي. تنتهي المهلة المحددة للاتصال بعد استلام الترويسات. ويؤدي قطع الاتصال إلى إلغاء المراقبة دون إصدار طلب لإلغاء التنفيذ. اضبط أي وكيل عكسي لتعطيل التخزين المؤقت لبث SSE ودعم الاتصالات طويلة الأمد.

لا تُمرَّر إلا مسارات تطبيق العميل المدرجة في قائمة السماح. ولا تُمرَّر ترويسة Authorization القادمة من المتصفح أو الترويسات الاعتباطية التي تحدّد هوية جهة موثوقة. ولا يقبل الوكيل مطلقًا مفتاح Wkala المخصّص للآلات. وتظل إدارة المشغّل ومزوّد الخدمة والمهارات وMCP مقتصرة على الواجهة الخلفية.

يوفّر المسار /dashboard/playground في الحزمة مثالًا كاملًا للواجهة الخلفية للعميل. أما /dashboard و/console فيُستخدمان لإدارة خدمة Wkala نفسها.

بناء واجهة React تفاعلية مباشرةالتعامل مع الموافقات والأسئلة والنماذج