הפעלת סוכן OpenAI Agents SDK ב-WhatsApp

איך הודעת WhatsApp הופכת להרצה של הסוכן?

דרך נתיב באפליקציה שלכם ש-Meta קוראת לו. מגדירים אותו כיעד הוובהוק של המספר, עם סוד אקראי וארוך בנתיב. הנתיב עונה לבקשת האימות GET של Meta בהחזרת hub.challenge כטקסט פשוט, מקבל כל בקשת POST, מחזיר 200 מיד ומעביר את העבודה לתור. הסיבה: Meta שולחת שוב כשהתגובה איטית, ואז הסוכן ירוץ פעמיים.

עובד קורא מה-payload את השולח ואת הטקסט וקורא ל-Runner.run. מעבירים סשן שמזההו הוא מספר השולח: ה-SDK שומר את השיחה תחת המזהה הזה, ולכן ההודעה הבאה של אותו לקוח ממשיכה מהנקודה שבה עצרנו, ושני לקוחות לעולם לא חולקים היסטוריה. SQLiteSession מספיק להתחלה, וה-SDK כולל גם סשנים של Redis ושל SQLAlchemy למקרה של כמה עובדים.

הסוד בכתובת ה-URL הוא האימות כאן. Meta חותמת על המשלוחים באמצעות ה-app secret של ה-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 בעובד. כך גם האסימון נשאר רחוק מכל דבר שהמודל יכול להפעיל עם ארגומנטים שרירותיים.

האם הסוכן יכול להשתמש בשרת MCP של EasyCoexistence?

כן, דרך MCPServerStreamableHttp, אבל ההגדרה מורכבת יותר מכותרת. ה-SDK מקבל כותרת Authorization או httpx.Auth בשדה params["auth"]. שרת MCP של EasyCoexistence מנפיק אסימוני OAuth משלו אחרי התחברות בדפדפן, עם dynamic client registration ו-PKCE, ולכן אין מפתח סטטי. ה-SDK של MCP ל-Python כולל את OAuthClientProvider, מטפל אימות HTTP שמריץ את התהליך הזה עם PKCE ורענון אסימון, ומעבירים אותו בתוך params["auth"] בהגדרת השרת.

זה משתלם כשהסוכן צריך להחליט בעצמו: לבדוק את תקינות החיבור של מספר, לקרוא סטטוס של תבנית, או לבחור בין send_message ל-send_template לפי הכללים שבתיאורי הכלים. לקבלה שרק עונה, העובד שלמעלה קצר יותר ויש בו פחות מה שיכול להשתבש.

בכל מקרה הוובהוק נשאר. MCP הוא בקשה ותגובה, והודעה של לקוח יכולה להגיע לסוכן רק דרך הנתיב ש-Meta קוראת לו.

טעויות נפוצות

• הרצת הסוכן לפני החזרת 200 ל-Meta. תגובה איטית נשלחת שוב, והלקוח מקבל שתי תשובות.
• שימוש בסשן אחד לכל הלקוחות. צריך לבחור מפתח לפי מספר השולח, אחרת ההיסטוריות מתערבבות.
• מעקב מאוחר ששולח טקסט חופשי. אחרי 24 שעות הוא נכשל עם 131047, ולכן שולחים תבנית במקום זאת.

שאלות נפוצות

המשיכו לקרוא