Connect tools & data

استخدم ThunderPhone من LiveKit Agents

شغّل وكيلًا صوتيًا من ThunderPhone بوصفه نموذج الوقت الفعلي (من الكلام إلى الكلام) لجلسة LiveKit Agents، مع غرف LiveKit وSIP والاتصال الهاتفي من حوله.

LiveKit Agents هو إطار عمل مفتوح المصدر للوكلاء الصوتيين في الوقت الفعلي فوق غرف LiveKit. يتكامل ThunderPhone بوصفه نموذج الوقت الفعلي: يرسل الإطار صوت المشارك، ويعيد ThunderPhone صوت الوكيل والنصوص المفرغة واستدعاءات الدوال، بينما تنقل غرفة LiveKit وقنوات SIP والاتصال الهاتفي الصوت. يعمل التعرّف على الكلام، ونموذج اللغة، والصوت، وتناوب الأدوار، و47 لغة، والأدوات كلها على ThunderPhone.

تظهر المكالمات التي تُجرى بهذه الطريقة في سجل المكالمات وتُحتسب بسعر الدقيقة الخاص بمنتجك، مثل أي مكالمة أخرى في الوقت الفعلي. لا يوجد اشتراك ولا يتضمن ذلك رقم هاتف من ThunderPhone.

التثبيت#

pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key

تغلف الإضافة نموذج OpenAI Realtime من LiveKit، لأن Realtime WebSocket من ThunderPhone يتحدث البروتوكول نفسه. وهي تتطلب livekit-agents بالإصدار 1.8 أو أحدث.

تشغيل وكيل محفوظ#

يُعدّ كل ما يفعله الوكيل (الموجّه، والصوت، والمحرك، واللغات، والأدوات، والتحية، ورسائل التحقق عند الصمت) على ThunderPhone. تنقل الجلسة الصوت فقط.

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import thunderphone
 
 
async def entrypoint(ctx: JobContext):
    session = AgentSession(llm=thunderphone.RealtimeModel(agent_id=12))
    await session.start(agent=Agent(instructions=""), room=ctx.room)
 
 
if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

يحيّي الوكيل المحفوظ ويشغّل أدواته الخاصة على ThunderPhone؛ ولا تُرسل تعليمات وأدوات Agent في LiveKit. تنتهي المكالمة عندما ينهي وكيل ThunderPhone الاتصال، وتُغلق الجلسة معه.

إعداد الجلسة مباشرةً في الشيفرة#

من دون agent_id، تأتي التعليمات والأدوات من Agent في LiveKit، بالطريقة نفسها التي تأتي بها مع OpenAI. يحدد product المحرك ويحدد voice صوت ThunderPhone.

from livekit.agents import Agent, AgentSession, RunContext, function_tool
from livekit.plugins import thunderphone
 
 
class Receptionist(Agent):
    def __init__(self):
        super().__init__(instructions="You are Acme Dental's receptionist. Be brief.")
 
    @function_tool
    async def check_availability(self, context: RunContext, date: str) -> dict:
        """Free appointment slots on a date."""
        return {"slots": await calendar.free_slots(date)}
 
 
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        llm=thunderphone.RealtimeModel(product="bolt", voice="olivia", language="es"),
    )
    await session.start(agent=Receptionist(), room=ctx.room)
    await session.generate_reply()   # the agent speaks first

يجمّد ThunderPhone التعليمات والأدوات عند بدء المكالمة، لذلك لا تُدعم update_instructions وupdate_tools وعمليات تسليم الوكيل التي تغيّرها أثناء المكالمة. تتحكم الجلسات المضمّنة بها جهة العميل: يتحدث الوكيل عند استدعاء generate_reply() أو عند إنهاء المشارك لدوره.

الخيارات#

الأحداث#

يضيف ThunderPhone أحداث المنصة فوق بروتوكول الوقت الفعلي. تصدرها الجلسة:

@session.llm.session.on("thunderphone_call_ended")  # or on the RealtimeSession you hold
def on_call_ended(event):
    print("call ended:", event["reason"])

يعرض RealtimeSession القيمة call_id بمجرد أن تصبح الجلسة نشطة. استخدمها مع GET /v1/calls/{call_id} لجلب التسجيل والنص المفرغ والتقييم بعد المكالمة. يصل كل حدث آخر من call.* (النقل، لوحة المفاتيح، تجاهل الكلام) بوصفه thunderphone_call_event.

الحدود#

• اكتشاف تبادل الأدوار يتم من جهة الخادم ويكون مفعّلاً دائماً؛ يُتجاهل اكتشاف تبادل الأدوار من جهة الإطار (turn_detection في AgentSession).
• لا يمكن تغيير التعليمات والأدوات بعد بدء المكالمة.
• الصوت بتنسيق PCM أحادي القناة و16 بت عند 24 كيلوهرتز في كلا الاتجاهين.
• تُتجاهل إطارات الفيديو.