SDK المتصفح لـVoice Agent
انضم إلى مكالمة Voice Agent من المتصفح بـ@humain-voice/agent، وعالج أدوات العميل، وتفاعل مع الحالة والنصوص المنسوخة والتحذيرات وأسباب الإنهاء.
ينضم @humain-voice/agent إلى مكالمة Voice Agent من صفحة ويب. يعمل فوق
livekit-client، ويشاركه مع أي مكونات LiveKit في الصفحة. ولا يرى مفتاح API أبدًا:
يحصل على رمز دخول من خادمك الخلفي.
التثبيت
npm install @humain-voice/[email protected] livekit-clientاستخدمه من تطبيق ويب مجمّع (Vite أو Next.js أو esbuild وغيرها). تحتاج الصفحة إلى الوصول إلى
الميكروفون، فقدّمها من localhost أو عبر HTTPS.
ابدأ مكالمة
يجلب AgentSession.start(options) رمز دخول، وينضم إلى المكالمة، ويشغّل الميكروفون، ويُحل
عندما تصبح المكالمة ready. استدعه من نقرة أو لمسة ليسمح المتصفح بالصوت:
import { AgentSession } from '@humain-voice/agent';
const call = await AgentSession.start({
token: () => fetch('/agent-session', { method: 'POST' }).then((res) => res.json()),
onStatusChange: (status) => console.log('status:', status),
onEnd: ({ reason }) => console.log('ended:', reason),
});| الخيار | النوع | الافتراضي | المعنى |
|---|---|---|---|
token | () => Promise<{ server_url: string; participant_token: string }> | مطلوب | يستدعي مسار خادمك الخلفي. يعمل قبيل الانضمام، فلا يكون رمز الدخول قديمًا أبدًا. |
clientTools | Record<string, (args) => unknown | Promise<unknown>> | {} | معالج واحد لكل أداة معرّفة؛ راجع أدوات العميل. |
onStatusChange | (status) => void | غير مضبوط | connecting، ready، ending، ended؛ راجع الحالة. |
onModeChange | (mode) => void | غير مضبوط | listening، thinking، speaking؛ راجع وضع الوكيل. |
onMessage | (message) => void | غير مضبوط | تحديثات النص المنسوخ؛ راجع النصوص المنسوخة. |
onWarning | ({ cause, seconds_left }) => void | غير مضبوط | راجع التحذيرات. |
onEnd | ({ reason }) => void | غير مضبوط | يُستدعى مرة واحدة؛ راجع أسباب الإنهاء. |
onError | (error: AgentSessionError) => void | غير مضبوط | مشكلات لا تنهي المكالمة، مثل فشل معالج أداة. |
onAudioBlocked | () => void | غير مضبوط | حجب المتصفح صوت الوكيل؛ اعرض زرًا يستدعي startAudio(). |
microphone | boolean | MediaTrackConstraints | true | إعدادات الميكروفون، أو false للانضمام مكتومًا. |
audio | boolean | true | يشغّل صوت الوكيل. اضبطه على false إذا كنت تشغّله بنفسك، مثلًا باستخدام RoomAudioRenderer من LiveKit. |
إذا تعذر بدء المكالمة، يُرفض الوعد بـAgentSessionError ولا يُستدعى onEnd.
الطرق والخصائص
| العضو | ما يفعله |
|---|---|
sendText(text) | يرسل رسالة مكتوبة. يجيب الوكيل كأن المستخدم قالها، ويتوقف عن الكلام أولًا عند الحاجة. |
interrupt() | يوقف الرد الحالي للوكيل. |
updateContext(values) | يخبر الوكيل بحقائق جديدة لبقية المكالمة، مثل الصفحة التي فتحها المستخدم. أنواع القيم نفسها في variables. |
setMicMuted(muted) | يكتم الميكروفون أو يلغي كتمه. |
startAudio() | يستأنف الصوت المحجوب. استدعه من نقرة. |
end() | ينهي المكالمة ويُحل عندما تصبح المكالمة ended. وتنتهي المكالمة بـuser_left. |
status، mode | الحالة الحالية ووضع الوكيل. |
sessionId | قيمة session_id للمكالمة. |
room | كائن Room الأساسي في LiveKit، لمكونات واجهة LiveKit أو أي شيء آخر يقدمه LiveKit. |
بعد انتهاء المكالمة، لا تفعل sendText() وinterrupt() وupdateContext() وsetMicMuted() شيئًا وتسجّل
تحذيرًا.
الأخطاء
يحمل AgentSessionError الحقل code:
code | المعنى |
|---|---|
TOKEN_FETCH_FAILED | أطلقت دالة token خطأ أو أعادت شيئًا آخر. |
CREDENTIALS_EXPIRED | استُخدم رمز الدخول بعد expires_at؛ راجع الاستجابة. |
CONNECTION_FAILED | تعذر اتصال المكالمة؛ راجع استكشاف الأخطاء وإصلاحها. |
AGENT_UNAVAILABLE | لم ينضم الوكيل خلال 20 ثانية، أو انتهت المكالمة قبل أن تصبح جاهزة. إذا كان endReason غير مضبوط وتكرر ذلك فتواصل مع الدعم وأرسل session_id. |
MIC_PERMISSION_DENIED | رُفض الوصول إلى الميكروفون أو لا يوجد ميكروفون متاح. |
CLIENT_TOOL_FAILED | أطلق معالج أداة خطأ أو انتهت مهلته. يُبلغ عنه عبر onError؛ وتستمر المكالمة، وقد أخبر الوكيل المستخدم. |
CLIENT_TOOL_NOT_HANDLED | استدعى الوكيل أداة بلا معالج. يُبلغ عنه عبر onError. |
عندما تنتهي المكالمة قبل أن تصبح ready، تحمل الخاصية endReason في الخطأ
سبب الانتهاء الذي أرسله الوكيل، مثل concurrency_limit أو credits_exhausted. ولا يُضبط في غير ذلك.
React
يعمل call.room مع مكونات React وAgents UI من LiveKit:
<RoomContext.Provider value={call.room}>{/* control bar, visualizer, transcript */}</RoomContext.Provider>وإذا أضفت RoomAudioRenderer، فمرّر audio: false حتى لا يُسمع الوكيل مرتين. راجع
عملاء LiveKit.