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

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

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

ابدأ هنا

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

بناء التكامل

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

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

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

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

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

بناء التكامل

أبقِ خادمك الخلفي متحكّمًا

ضع التحقّق من الهوية والملكية ومنطق العمل بين واجهتك الأمامية وحزمة Wkala SDK.

عرض Markdown

لتكامل Next.js ومتطلبات الواجهة الخلفية Python، راجع Next.js.

حدود التطبيق

يسجّل المستخدمون الدخول إلى تطبيقك. يتحقّق خادمك الخلفي من صلاحياتهم، ويحتفظ بمفتاح خدمة Wkala، ولا يرسل إلا الأعمال المصرّح بها. تتحقّق Wkala من مفتاح الخادم الخلفي وتفرض حدود الحساب؛ لكنها لا تحلّ محل نموذج المستخدمين في تطبيقك.

يوجد المثال الكامل القابل للتشغيل والمكتوب بلغة Python في apps/customer-backend. يتضمّن المثال:

  • مسارات FastAPI وتخزينًا دائمًا في PostgreSQL عبر SQLAlchemy.
  • جلسات HttpOnly وفحوصات Origin وCSRF والتحقق من ملكية الجلسات.
  • أدوات مدمجة موقّعة.
  • إيصالًا لعملية عمل يُسجَّل في المعاملة نفسها التي تسجّل تأثيرها الفعلي.

لا يتضمن الإصدار مثال خادم عميل خلفي مكتوبًا بلغة TypeScript. يتطلب وكيل Next المرفق خادم العميل المكتوب بلغة Python. يستخدم المسار /dashboard/playground في تطبيق Next ذلك الخادم الخلفي وحزمة React SDK المشتركة.

عميل واحد طوال دورة حياة التطبيق

أنشئ عميل الخادم مرة واحدة وأعِد استخدامه طوال دورة حياة التطبيق. يوفّر العميل نقطة نهاية الخدمة المستضافة داخليًا. لخدمة Go مباشرة، مرّر baseUrl: "http://localhost:8080/v1". يستخدم مدخل Compose العنوان http://localhost:8088/v1، ويستخدم التطوير الأصلي متعدد الخدمات العنوان http://localhost:18080/v1، ويستخدم الإنتاج أصلًا عامًا مُهيأً.

typescript
import { createServerClient } from "@wkala/client/server"

const apiKey = process.env.WKALA_API_KEY
if (!apiKey) {
  throw new Error("Set WKALA_API_KEY in your backend environment")
}
const agents = createServerClient({ apiKey })

أدرج منطق العمل قبل قبول التنفيذ

تمثّل هذه الدالة نقطة تكامل في خادمك الخلفي. استمد هوية المستخدم ومعرّف الجلسة المملوكة له ومعرّف طلب العمل المحفوظ بشكل دائم من تطبيقك الذي تحقّق من الهوية ومن قاعدة بياناتك. لا تثق في بيانات JSON التي يمرّرها المتصفح للحصول على هذه القيم.

typescript
import type { AgentClient } from "@wkala/client"

async function startOrderReview(
  agents: AgentClient,
  userId: string,
  ownedSessionId: string,
  persistedRequestId: string,
  orderId: string,
  approvedCompanyToolId: string,
) {
  const session = agents.sessions.handle(ownedSessionId)
  return session.send(
    `Review order ${orderId} and explain the next steps.`,
    {
      idempotencyKey: persistedRequestId,
      subject: { id: userId },
      context: { order_id: orderId },
      mcp_server_ids: [approvedCompanyToolId],
    },
  )
}

تحقّق من الملكية قبل الإرسال والقراءة والبثّ والإلغاء والردّ على التفاعلات وجلب الموارد التابعة. يجب ألّا يسمح وكيل المتصفح الوسيط المتاح للعامة للمستخدم بما يلي:

  • تسجيل نقاط نهاية MCP عشوائية.
  • تغيير ملف تعريف ذي امتيازات.
  • تقديم هوية موثوقة لمستخدم آخر.
  • اختيار مضيف الخدمة الذي تُمرَّر إليه الطلبات.

مرّر الحالة لا الأسرار

استخدم عقد المسارات /app المرفق عند ربط React أو Next.js. يتلقّى AgentClient في المتصفح عنوان URL أساسيًا من الأصل نفسه ودالة استدعاء للتحقّق من CSRF. ولا يتضمّن خيارًا لمفتاح API. يتحقّق خادمك الخلفي من هوية صاحب الطلب ومن الملكية، ثم يستخدم عميل SDK الخاص به لاستدعاء Wkala.

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

أدوات العمل المدمجة

استخدم أدوات MCP المصرّح بها للوصول إلى قاعدة بياناتك وخدماتك. يوفّر مثال Python المرفق مكوّنًا مساعدًا يستضيف الأدوات داخل FastAPI. لا يتوفر مكوّن استضافة مماثل في TypeScript. راجع أدوات الخادم الخلفي لإرشادات الخيارين. لا تُرفَع دوالك إلى البنية التحتية للوكيل.

اختبر حدود التطبيق

اختبر الحالات التالية على الأقل:

  • مستخدمَين مختلفَين للتطبيق.
  • محاولة قراءة جلسة المستخدم الآخر.
  • هوية مزوّرة.
  • طلب عمل مكرّرًا.
  • انقطاع البثّ.
  • تأثيرًا لأداة لم تتّضح نتيجته.

لا يكفي التحقّق من الملكية في الواجهة الأمامية وحدها. يجب أن تعيد إعادة الاتصال المراقبة دون قبول عملية تشغيل أخرى.

بثّ الرسائل والأدوات والنتائجربط خادم MCP بعيد