حزم SDK

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 }>مطلوبيستدعي مسار خادمك الخلفي. يعمل قبيل الانضمام، فلا يكون رمز الدخول قديمًا أبدًا.
clientToolsRecord<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().
microphoneboolean | MediaTrackConstraintstrueإعدادات الميكروفون، أو false للانضمام مكتومًا.
audiobooleantrueيشغّل صوت الوكيل. اضبطه على 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.

في هذه الصفحة