الجلسات المباشرة مع وكيل

الرابط الأساسي https://api.echonova.ai

الجلسة المباشرة هي الجلسة نفسها التي يشغّلها زر اختبار على الوكيل في البوابة. تبدأها عبر الواجهة البرمجية، وتنضم إليها من تطبيقك، وتتحدث إلى الوكيل أو تكتب له، ثم تنهيها. يحتاج المفتاح إلى صلاحية التحدث مع الوكلاء.

ما تحتاج إليه

مفتاح API له صلاحية التحدث مع الوكلاء (agents:talk). راجع امنح المفتاح صلاحية التحدث مع الوكلاء.
معرّف الوكيل كما تعيده GET /v1/agents.
حزمة livekit-client في التطبيق الذي ينضم إلى الجلسة.

امنح المفتاح صلاحية التحدث مع الوكلاء

في قسم الوصول إلى الوكلاء والأدوات من نموذج المفتاح، فعّل التحدث مع الوكلاء. المفتاح الذي يملك هذا الوصول وحده يستطيع بدء الجلسات وقراءتها وإنهاءها، ولا يستطيع تغيير الوكلاء. بدونه ترد الواجهة بالرمز 403 مع الرسالة This API key cannot talk to agents..

يتصرف المفتاح باسم العضو الذي أنشأه. يجب أن يحتفظ ذلك العضو بصلاحية عرض الوكلاء وصلاحية إدارة واجهة المطورين البرمجية.

البدء والانضمام والإنهاء

ابدأ الجلسة بمفتاحك. تحمل الإجابة token الخاص بالغرفة وwsUrl.
انضم إلى الغرفة من العميل بالرمز token.
أنهِ الجلسة حين ينتهي المستخدم.

ابدأ جلسة صوتية. اترك channel فارغًا لجلسة صوتية، أو أرسل "chat" لجلسة نصية.

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"voice"}'

تحمل الإجابة الحقول id وagentId وchannel وstatus وstartedAt وendedAt وtoken وwsUrl وgreeting. الحقل greeting هو أول رسالة للوكيل في الجلسة النصية، ويكون null في الجلسة الصوتية. راجع بدء جلسة مباشرة.

الانضمام إلى جلسة صوتية

افتح الميكروفون، واتصل بالعنوان wsUrl بالرمز token، وانشر الميكروفون وشغّل مسار صوت الوكيل.

import { Room, RoomEvent, createLocalAudioTrack } from 'livekit-client';

const mic = await createLocalAudioTrack();
const room = new Room({ adaptiveStream: true, dynacast: true });
const audio = new Audio();
audio.autoplay = true;

room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === 'audio') {
    track.attach(audio);
    audio.play().catch(() => undefined);
  }
});

await room.connect(session.wsUrl, session.token);
await room.localParticipant.publishTrack(mic);

مسار صوت الوكيل الموجود في الغرفة قبل انضمامك لا يُعلَن من جديد. بعد الاتصال، أرفق مسارات الصوت الموجودة أصلًا:

room.remoteParticipants.forEach((participant) =>
  participant.audioTrackPublications.forEach((publication) => {
    if (publication.track) publication.track.attach(audio);
  }),
);

الانضمام إلى جلسة نصية

الجلسة النصية تعمل بالنص فقط. أرسل رسالة المستخدم على الموضوع lk.chat. يرد الوكيل على الموضوع lk.transcription، بتدفق نصي واحد لكل دور. يحمل echonova.status ملاحظات تقدم قصيرة بصيغة JSON { "kind", "text" }. وهو اختياري: يستطيع العميل تجاهله.

import { Room } from 'livekit-client';

const room = new Room();

room.registerTextStreamHandler('lk.transcription', async (reader) => {
  let text = '';
  for await (const chunk of reader) {
    text += chunk;
    // Show `text` as it grows.
  }
});

await room.connect(session.wsUrl, session.token);
await room.localParticipant.sendText('What are your opening hours?', {
  topic: 'lk.chat',
});

اعرض greeting من إجابة البدء قبل أن يكتب المستخدم. قد يرسل الوكيل التحية نفسها كأول تدفق له؛ تجاهل ذلك التدفق حتى تظهر التحية مرة واحدة.

إنهاء الجلسة

اخرج من الغرفة، ثم أنهِ الجلسة لتُغلق الغرفة وتُحفظ المحادثة.

await room.disconnect();

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}/end" \
  -H "Authorization: Bearer YOUR_API_KEY"

إنهاء جلسة انتهت من قبل يُرجع 200 مع حالتها النهائية. تعيد GET /v1/agents/{agentId}/sessions/{sessionId} الحالة في أي وقت. راجع قراءة جلسة مباشرة وإنهاء جلسة مباشرة.

احتفظ بالرمز `token` عندك

يُرسل token مرة واحدة، في إجابة البدء. عمليات القراءة والإنهاء لا تعيده أبدًا.
سلّمه فقط للعميل الذي ينضم. لا تسجّله ولا تخزنه.
الرمز يفتح جلسة واحدة. للتحدث من جديد، ابدأ جلسة جديدة.
ابدأ الجلسات من خادمك، حتى لا يصل مفتاح API إلى المتصفح أبدًا.

إعادة محاولة البدء تفتح جلسة ثانية، فلا تعيد محاولة البدء بلا تفكير.

الحدود والأرصدة

البدء: 10 في الدقيقة لكل مفتاح. بعد ذلك ترد الواجهة بالرمز 429؛ انتظر عدد الثواني في Retry-After.
حدود الوكيل: تنطبق على الجلسات التي تبدأ هنا حدود المحادثات وحدود المكالمات الخاصة بالوكيل. الوكيل الذي بلغ حده يرد بالرمز 409 مع الرسالة This agent has reached its call limit. Try again later. عند بدء جلسة صوتية، أو بالرسالة This agent has reached its chat limit. Try again later. عند بدء جلسة نصية.
الأرصدة: تستهلك الجلسة أرصدة مساحة العمل، كما يفعل الاختبار في البوابة. ولا تُحتسب على حد الرصيد الخاص بالمفتاح. مساحة العمل بلا أرصدة ترد بالرمز 402 قبل بدء الجلسة، ولا يُخصم شيء.
الوكلاء المؤرشفون: الوكيل المؤرشف يرد بالرمز 409. استعده أولًا.

كل نص خطأ موجود في صفحة الأخطاء.

استخدم الصورة الرمزية الخاصة بك

إذا كان لتطبيقك صورة رمزية، فيستطيع أن يتحدث باسم الوكيل. انضم إلى الجلسة الصوتية بالرمز token، وخذ مسار صوت الوكيل، وشغّله عبر صورتك الرمزية. هذا كل شيء. لا ترسل إيكونوڤا أحداثًا إضافية للصورة الرمزية، ولا ترسم الوجه بنفسها. يتولى تطبيقك رسمه.