Voice Agent

دورة حياة الجلسة

تتبّع مكالمة Voice Agent من الاتصال حتى الانتهاء، واعرض النصوص المنسوخة المباشرة والتحذيرات، وأرسل نصًا أثناء المكالمة، وعالج كل سبب إنهاء.

يبلغ SDK المتصفح عن المكالمة عبر دوال استدعاء في AgentSession.start(). قائمة الخيارات الكاملة في صفحة SDK المتصفح.

الحالة

يبلغ onStatusChange عن مرحلة المكالمة:

الحالةالمعنى
connectingجلب رمز الدخول والانضمام إلى المكالمة.
readyانضم الوكيل إلى المكالمة.
endingالمكالمة تُغلق.
endedانتهت المكالمة، واستُدعي onEnd مع سبب الإنهاء.

وضع الوكيل

يبلغ onModeChange عما يفعله الوكيل بينما المكالمة في الحالة ready:

الوضعالمعنى
listeningينتظر المستخدم، أو يسمعه يتحدث.
thinkingيُعدّ ردًا أو ينتظر أداة عميل.
speakingيتحدث. يستطيع المستخدم مقاطعته بالكلام.

النصوص المنسوخة

يسلّم onMessage ما قاله المستخدم والوكيل كنص:

الحقلالنوعالمعنى
idسلسلةيبقى كما هو أثناء تحديث رسالة واحدة.
roleuser أو agentمن قالها.
textسلسلةالنص حتى الآن.
finalقيمة منطقيةtrue عندما لا يعود النص يتغير.

استبدل نص الرسالة ذات id نفسه حتى تصبح final مساوية لـtrue، ثم احتفظ به. يصل نص الوكيل متزامنًا مع كلامه.

الطرق

الطرق sendText() وinterrupt() وupdateContext() وsetMicMuted() وend() في صفحة SDK المتصفح.

التحذيرات

يُطلق onWarning قبل أن تُنهى المكالمة نيابةً عنك، لتتمكن من إخبار المستخدم:

causeمتى يُطلقseconds_left
max_durationقبل 60 ثانية من المدة القصوى للمكالمة في خطتك.60
creditsعندما يغطي رصيد حسابك الدقيقة الحالية فقط.الثواني المتبقية حتى نهاية تلك الدقيقة.

أسباب الإنهاء

يتلقى onEnd القيمة { reason }. وتظهر القيم نفسها في سجلات الاستخدام.

المجموعةreasonالمعنىالخصم
المستخدمuser_leftأنهى المستخدم المكالمة أو أغلق الصفحة.الدقائق التي بدأت
المستخدمuser_never_joinedلم يُستخدم رمز الدخول قبل expires_at.لا شيء
الوكيلagent_endedأنهى الوكيل المكالمة بـend_call.الدقائق التي بدأت
الوكيلidle_timeoutلم يتحدث أحد طوال زمن الخمول في خطتك.الدقائق التي بدأت
الحدودmax_durationبلغت المكالمة المدة القصوى في خطتك.الدقائق التي بدأت
الحدودcredits_exhaustedتعذر على الحساب دفع الدقيقة التالية.الدقائق التي بدأت
الحدودconcurrency_limitكانت المكالمات الجارية كثيرة جدًا عند انضمام هذه المكالمة.لا شيء
الحدودaccount_disabledVoice Agent معطّل للحساب.الدقائق التي بدأت
الأخطاءagent_errorفشل الوكيل.الدقائق التي بدأت
الأخطاءplatform_errorفشلت HUMAIN Voice. تواصل مع الدعم مع session_id.الدقائق التي بدأت

قبل idle_timeout وmax_duration وcredits_exhausted وaccount_disabled يقول الوكيل وداعًا قصيرًا. وإذا انقطع الاتصال دون سبب إنهاء، تُبلغ SDK المتصفح بالسبب platform_error.

قد تُضاف أسباب جديدة؛ فاعرض رسالة عامة لأي قيمة لا تعرفها. خصم الدقائق موضّح في الحدود والفوترة.

دون SDK

يستطيع أي عميل LiveKit الانضمام بـserver_url وparticipant_token؛ راجع عملاء LiveKit. يستخدم الوكيل إشارات الوكلاء القياسية في LiveKit إضافة إلى موضوع بيانات واحد خاص به:

ماذاكيف
وضع الوكيلسمة المشارك lk.agent.state على الوكيل: initializing أو listening أو thinking أو speaking.
النصوص المنسوخةتدفقات نصية على الموضوع lk.transcription؛ تعلّم السمة lk.transcription_final النص النهائي وتحدد lk.segment_id الرسالة.
إرسال النصتدفق نصي على الموضوع lk.chat.
التحذيرات وسبب الإنهاءرسائل بيانات من الوكيل على الموضوع humain.session (أدناه).
تحديث السياق، المقاطعةرسائل بيانات إلى الوكيل على الموضوع humain.session (أدناه).
أدوات العميلطريقة RPC باسم client_tool_call؛ راجع أدوات العميل.

الرسائل على humain.session بصيغة JSON بترميز UTF-8:

{ "type": "session_warning", "cause": "max_duration", "seconds_left": 60 }
{ "type": "session_end", "reason": "max_duration" }
{ "type": "context_update", "context": { "page": "checkout" } }
{ "type": "interrupt" }

يرسل الوكيل session_end قبيل إغلاق الغرفة. إذا انقطع الاتصال دونه، فاعتبر المكالمة منتهية.

في هذه الصفحة