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

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

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

ابدأ هنا

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

بناء التكامل

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

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

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

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

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

بناء التكامل

بناء واجهة React تفاعلية مباشرة

استخدم مخزن جلسة مشتركًا واحدًا للرسائل والأدوات والتفاعلات والاستخدام والتعافي.

عرض Markdown

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

التثبيت

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"

تعمل حزمة React مع React 19، ولا تعتمد على Next.js أو موجّه مسارات أو shadcn أو مكتبة تنسيق. وهي تستخدم مخزن الجلسة نفسه الذي يعتمد عليه عميل TypeScript ويتحقق من صحة البيانات. ويستخدم تطبيق Next المرفق هذا المخزن مع مكوّنات shadcn مشتركة.

الاتصال من خلال واجهتك الخلفية

توفّر واجهتك الخلفية مسارات /app المحمية بالمصادقة، وملف تعريف ارتباط للجلسة من نوع HttpOnly، وحماية CSRF، والتحقق من الملكية. تأتي قيمة csrfToken أدناه من استجابة الهوية المحمية بالمصادقة في تلك الواجهة الخلفية. وهي ليست مفتاح خدمة Wkala الخاص بك.

يستخدم عميل المتصفح /app من الأصل نفسه افتراضيًا، وليس عنوان API العام المخصص لعملاء الخادم. يجب أن يشير هدف createAppProxy إلى أصل خادمك الخلفي فقط، دون مسار.

tsx
"use client"
import { useState } from "react"
import { AgentClient, isTerminal } from "@wkala/client"
import { AgentProvider, useSession } from "@wkala/react"

export function AgentWorkspace({ sessionId, csrfToken }: {
  sessionId: string
  csrfToken: string
}) {
  const [client] = useState(() => new AgentClient())
  client.csrfToken = csrfToken
  return (
    <AgentProvider client={client}>
      <Execution sessionId={sessionId} />
    </AgentProvider>
  )
}

function Execution({ sessionId }: { sessionId: string }) {
  const session = useSession(sessionId)
  const [message, setMessage] = useState("")
  const [error, setError] = useState<string | null>(null)
  const [submitting, setSubmitting] = useState(false)
  const busy = submitting || session.runs.some(run => !isTerminal(run.status))

  async function submit() {
    setSubmitting(true)
    setError(null)
    try {
      await session.send(message, { idempotencyKey: crypto.randomUUID() })
      setMessage("")
    } catch (cause) {
      setError(cause instanceof Error ? cause.message : "Unable to start work")
    } finally {
      setSubmitting(false)
    }
  }

  return (
    <section>
      <p role="status">{session.connection}</p>
      {session.error && <p role="alert">{session.error.message}</p>}

      {session.messages.map(message => (
        <article key={message.id}>
          <strong>{message.role}</strong>
          {message.parts.map(part => (
            <p key={part.id}>
              {part.type === "text" ? part.text : "[attached content]"}
            </p>
          ))}
        </article>
      ))}

      {session.tools.map(tool => (
        <article key={tool.id}>
          <strong>{tool.title}: {tool.status}</strong>
          <pre>{JSON.stringify(tool.output, null, 2)}</pre>
        </article>
      ))}

      {session.interactions.some(item => item.status === "pending") && (
        <p>Input is required. Present the offered interaction to the user.</p>
      )}

      <form onSubmit={event => {
        event.preventDefault()
        void submit()
      }}>
        <label htmlFor="task">Message</label>
        <textarea
          id="task"
          value={message}
          onChange={event => setMessage(event.target.value)}
        />
        <button disabled={busy || !message.trim()}>Send message</button>
        {error && <p role="alert">{error}</p>}
      </form>
    </section>
  )
}

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

واجهة الخطّاف

القيمة أو الإجراءالمعنى
snapshotحالة الجلسة كاملة، أو null قبل ترطيب الواجهة أو بعد فقدان صلاحية الوصول
connection, errorحالة المراقبة، وهي منفصلة عن حالة تنفيذ عملية التشغيل
messages, tools, invocations, interactions, runsمصفوفات من الحالة المتسقة نفسها
send(message, options)قبول عملية تشغيل واحدة بهوية تمنع تكرار التنفيذ
respond(id, response)إرسال خيار إذن محدّد بدقة أو رسالة أو نموذج ذي أنواع محدّدة
cancel(runId)طلب إلغاء التنفيذ صراحةً
reconnect()استئناف المراقبة دون قبول عمل جديد
updateSetting, close, deleteSession, forkعمليات على الجلسة تعتمد على الإمكانات المتاحة

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

تسجيل الخروج وترطيب الواجهة

استدعِ client.clear() عندما يسجّل مستخدم التطبيق خروجه أو يغيّر هويته. أزل من الواجهة المكوّنات الخاصة بتلك الهوية. لا تحتوي لقطة الخادم المحايدة على حالة تسجيل دخول مفترضة. ويجب أن تأتي لقطة SSR المعتمدة على المصادقة من مستخدم الطلب نفسه. لا تستخدم مطلقًا مخزنًا معتمدًا على المصادقة ومشتركًا على مستوى الوحدة البرمجية في الخادم.

راجع Next.js للاطلاع على الوكيل من المصدر نفسه والأداة المساعدة الاختيارية للقطات المحصورة في نطاق الطلب، والموافقات والأسئلة للتعامل مع إدخال المستخدم الصريح.

إضافة مهارات وتعليمات قابلة لإعادة الاستخدامربط تطبيق Next.js