تشغيل وكيل OpenAI Agents SDK على WhatsApp

كيف تتحول رسالة WhatsApp إلى تشغيل للوكيل؟

عبر مسار في تطبيقك أنت تستدعيه Meta. اضبط وجهة webhook للرقم عليه، مع سر عشوائي طويل في المسار. يرد المسار على طلب GET للتحقق من Meta بإرجاع hub.challenge نصًا عاديًا، ويقبل كل طلب POST، ويرد بـ 200 فورًا ويضع العمل في قائمة انتظار، لأن Meta تعيد المحاولة عند بطء الاستجابة فتشغّل الوكيل مرتين.

بعد ذلك يقرأ عامل المعالجة المرسل والنص من الحمولة ويستدعي Runner.run. مرّر جلسة معرّفها رقم المرسل: يخزّن SDK المحادثة تحت ذلك المعرّف، فتكمل الرسالة التالية من العميل نفسه من حيث توقفت السابقة، ولا يتشارك عميلان السجل نفسه. يكفي SQLiteSession للبدء، ويوفر SDK أيضًا جلسات Redis وSQLAlchemy عند تعدد العمال.

السر في عنوان URL هو المصادقة هنا. توقّع Meta الرسائل بالسر الخاص بتطبيق Tech Provider، لذلك لا يستطيع العميل التحقق من ترويسة التوقيع.

import os, httpx
from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Front desk", instructions="Answer briefly and politely.")
URL = f"https://graph.facebook.com/v25.0/{os.environ['PHONE_NUMBER_ID']}/messages"

async def handle(sender: str, text: str) -> None:
    session = SQLiteSession(sender, "whatsapp.db")
    result = await Runner.run(agent, text, session=session)
    async with httpx.AsyncClient() as http:
        await http.post(
            URL,
            headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
            json={"messaging_product": "whatsapp", "to": sender,
                  "type": "text", "text": {"body": result.final_output}},
        )

لماذا ترسل شيفرتك الرد لا الوكيل؟

لأن القاعدة الوحيدة التي يجب ألا تُكسر هي قاعدة توقيت، والشيفرة تفرضها أفضل من أي موجّه. تفتح Meta نافذة خدمة العملاء مدتها 24 ساعة حين يكتب العميل. داخلها يمرّ النص الحر. وخارجها لا يمرّ إلا قالب معتمد، ويعود النص الحر بالخطأ 131047.

عامل المعالجة الذي يجيب عن الرسالة التي وصلت للتو يكون داخل النافذة دائمًا، فإرسال result.final_output نصًا آمن بحكم البنية. أما العمل الذي يحدث لاحقًا، كمتابعة صباح اليوم التالي أو تذكير، فيجب أن يمر عبر مسار منفصل يرسل قالبًا ولا يرسل نصًا حرًا أبدًا.

يمكن أن تكون للوكيل أدوات مع ذلك. امنحه أدوات دوال للبحث، مثل طلب أو حجز، وأبقِ إرسال WhatsApp في عامل المعالجة. وهذا يُبقي token بعيدًا عن أي شيء يستطيع النموذج استدعاءه بوسائط عشوائية.

هل يستطيع الوكيل استخدام خادم MCP الخاص بـ EasyCoexistence؟

نعم، عبر MCPServerStreamableHttp، لكن الإعداد أطول من ترويسة. يقبل SDK إما ترويسة Authorization وإما httpx.Auth في params["auth"] لمصادقة الخادم. يصدر خادم MCP الخاص بـ EasyCoexistence رموز OAuth الخاصة به بعد تسجيل دخول في المتصفح، مع تسجيل ديناميكي للعميل وPKCE، لذلك لا يوجد مفتاح ثابت. يوفر MCP Python SDK الفئة OAuthClientProvider، وهي معالج مصادقة HTTP ينفذ هذا المسار مع PKCE وتجديد token، وهذا ما يوضع في params["auth"] ضمن الإعداد.

يستحق ذلك حين يُراد أن يقرر الوكيل بنفسه: يفحص صحة رقم، أو يقرأ حالة قالب، أو يختار بين send_message وsend_template وفق القواعد الواردة في أوصاف الأدوات. أما مكتب استقبال يكتفي بالرد، فعامل المعالجة أعلاه أقصر وأقل عرضة للأعطال.

وفي الحالتين يبقى webhook. MCP نمطه طلب واستجابة، ولا تصل رسالة العميل إلى الوكيل إلا عبر المسار الذي تستدعيه Meta.

الأخطاء الشائعة

• تشغيل الوكيل قبل إعادة 200 إلى Meta. تُعاد المحاولة عند بطء الاستجابة، فيصل إلى العميل جوابان.
• استخدام جلسة واحدة لكل العملاء. اجعل المفتاح رقم المرسل، وإلا اختلطت السجلات.
• ترك متابعة متأخرة ترسل نصًا حرًا. بعد 24 ساعة تفشل بالخطأ 131047، فأرسل قالبًا بدلًا منه.

الأسئلة الشائعة

تابع القراءة