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

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

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

ابدأ هنا

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

بناء التكامل

  • بثّ الرسائل والأدوات والنتائج
  • أبقِ خادمك الخلفي متحكّمًا

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

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

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

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

بناء التكامل

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

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

عرض Markdown

حدود التطبيق

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

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

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

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

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

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

python
from contextlib import asynccontextmanager
import os

from fastapi import FastAPI
from wkala import AgentClient


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with AgentClient(
        api_key=os.environ["WKALA_API_KEY"],
    ) as agents:
        app.state.agents = agents
        yield


app = FastAPI(lifespan=lifespan)

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

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

python
from wkala import AgentClient


async def start_order_review(
    agents: AgentClient,
    *,
    user_id: str,
    owned_session_id: str,
    persisted_request_id: str,
    order_id: str,
    approved_company_tool_id: str,
):
    session = agents.sessions.handle(owned_session_id)
    return await session.send(
        f"Review order {order_id} and explain the next steps.",
        idempotency_key=persisted_request_id,
        subject={"id": user_id},
        context={"order_id": order_id},
        mcp_server_ids=[approved_company_tool_id],
    )

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

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

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

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

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

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

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

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

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

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

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

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