دورة حياة الجلسة
تتبّع مكالمة Voice Agent من الاتصال حتى الانتهاء، واعرض النصوص المنسوخة المباشرة والتحذيرات، وأرسل نصًا أثناء المكالمة، وعالج كل سبب إنهاء.
يبلغ SDK المتصفح عن المكالمة عبر دوال استدعاء في AgentSession.start(). قائمة الخيارات الكاملة
في صفحة SDK المتصفح.
الحالة
يبلغ onStatusChange عن مرحلة المكالمة:
| الحالة | المعنى |
|---|---|
connecting | جلب رمز الدخول والانضمام إلى المكالمة. |
ready | انضم الوكيل إلى المكالمة. |
ending | المكالمة تُغلق. |
ended | انتهت المكالمة، واستُدعي onEnd مع سبب الإنهاء. |
وضع الوكيل
يبلغ onModeChange عما يفعله الوكيل بينما المكالمة في الحالة ready:
| الوضع | المعنى |
|---|---|
listening | ينتظر المستخدم، أو يسمعه يتحدث. |
thinking | يُعدّ ردًا أو ينتظر أداة عميل. |
speaking | يتحدث. يستطيع المستخدم مقاطعته بالكلام. |
النصوص المنسوخة
يسلّم onMessage ما قاله المستخدم والوكيل كنص:
| الحقل | النوع | المعنى |
|---|---|---|
id | سلسلة | يبقى كما هو أثناء تحديث رسالة واحدة. |
role | user أو 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_disabled | Voice 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 قبيل إغلاق الغرفة. إذا انقطع الاتصال دونه، فاعتبر
المكالمة منتهية.