بناء التكامل
بناء واجهة React تفاعلية مباشرة
استخدم مخزن جلسة مشتركًا واحدًا للرسائل والأدوات والتفاعلات والاستخدام والتعافي.
لتكامل Next.js ومتطلبات الواجهة الخلفية Python، راجع Next.js.
التثبيت
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 إلى أصل خادمك الخلفي فقط، دون مسار.
"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 للاطلاع على الوكيل من المصدر نفسه والأداة المساعدة الاختيارية للقطات المحصورة في نطاق الطلب، والموافقات والأسئلة للتعامل مع إدخال المستخدم الصريح.