Βάλτε έναν agent του OpenAI Agents SDK στο WhatsApp

Πώς γίνεται ένα μήνυμα WhatsApp εκτέλεση του agent;

Μέσω μιας διαδρομής στη δική σας εφαρμογή, την οποία καλεί η Meta. Ορίστε την ως προορισμό webhook του αριθμού, με ένα μακρύ τυχαίο μυστικό στη διαδρομή. Η διαδρομή απαντά στο GET επαλήθευσης της Meta επιστρέφοντας το hub.challenge ως απλό κείμενο, δέχεται κάθε POST, απαντά αμέσως 200 και βάζει την εργασία σε ουρά, γιατί η Meta επαναλαμβάνει τις αργές αποκρίσεις και θα τρέχατε τον agent δύο φορές.

Ένας worker διαβάζει έπειτα τον αποστολέα και το κείμενο από το payload και καλεί το Runner.run. Περάστε μια συνεδρία με id τον αριθμό του αποστολέα: το SDK αποθηκεύει τη συνομιλία κάτω από αυτό το id, ώστε το επόμενο μήνυμα του ίδιου πελάτη να συνεχίζει από εκεί που σταμάτησε το προηγούμενο και δύο πελάτες να μη μοιράζονται ποτέ ιστορικό. Το SQLiteSession αρκεί για αρχή· το SDK περιλαμβάνει και συνεδρίες Redis και SQLAlchemy για περισσότερους workers.

Το μυστικό στο 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}},
        )

Γιατί να στέλνει την απάντηση ο κώδικάς σας και όχι ο agent;

Επειδή ο ένας κανόνας που δεν πρέπει να παραβιαστεί ποτέ είναι κανόνας χρόνου, και ο κώδικας τον επιβάλλει καλύτερα από ένα prompt. Η Meta ανοίγει ένα παράθυρο εξυπηρέτησης πελατών 24 ωρών όταν γράφει ένας πελάτης. Μέσα σε αυτό περνά ελεύθερο κείμενο. Έξω από αυτό περνά μόνο εγκεκριμένο template, και το ελεύθερο κείμενο επιστρέφει με το σφάλμα 131047.

Ένας worker που απαντά στο μήνυμα που μόλις έφτασε βρίσκεται πάντα μέσα στο παράθυρο, άρα η αποστολή του result.final_output ως κειμένου είναι ασφαλής εκ κατασκευής. Η εργασία που γίνεται αργότερα, όπως μια υπενθύμιση ή μια επανάληψη επικοινωνίας το επόμενο πρωί, πρέπει να περνά από ξεχωριστή διαδρομή που στέλνει template και ποτέ ελεύθερο κείμενο.

Ο agent μπορεί και πάλι να έχει εργαλεία. Δώστε του function tools για αναζητήσεις, όπως μια παραγγελία ή μια κράτηση, και κρατήστε την αποστολή WhatsApp στον worker. Έτσι το token πρόσβασης μένει μακριά από οτιδήποτε μπορεί να καλέσει το μοντέλο με αυθαίρετα ορίσματα.

Μπορεί ο agent να χρησιμοποιήσει τον MCP server του EasyCoexistence;

Μπορεί, μέσω του MCPServerStreamableHttp, με περισσότερη ρύθμιση από μια κεφαλίδα. Το SDK δέχεται είτε κεφαλίδα Authorization είτε httpx.Auth στο params["auth"]. Ο MCP server του EasyCoexistence εκδίδει δικά του OAuth tokens μετά από σύνδεση στον browser, με dynamic client registration και PKCE, επομένως στατικό κλειδί δεν υπάρχει. Το MCP Python SDK περιλαμβάνει το OAuthClientProvider, έναν χειριστή HTTP auth που εκτελεί αυτή τη ροή με PKCE και ανανέωση του token, και αυτός μπαίνει στο params["auth"].

Αξίζει όταν ο agent πρέπει να αποφασίζει μόνος του: να ελέγξει την υγεία ενός αριθμού, να διαβάσει την κατάσταση ενός template ή να διαλέξει ανάμεσα σε send_message και send_template με βάση τους κανόνες στις περιγραφές των εργαλείων. Για μια υποδοχή που απλώς απαντά, ο worker παραπάνω είναι πιο σύντομος και έχει λιγότερα σημεία αποτυχίας.

Εν πάση περιπτώσει, το webhook παραμένει. Το MCP είναι αίτημα και απόκριση, και το μήνυμα ενός πελάτη μπορεί να φτάσει στον agent μόνο μέσω της διαδρομής που καλεί η Meta.

Συνηθισμένα λάθη

• Εκτέλεση του agent πριν επιστραφεί 200 στη Meta. Η αργή απόκριση επαναλαμβάνεται και ο πελάτης παίρνει δύο απαντήσεις.
• Χρήση μίας συνεδρίας για όλους τους πελάτες. Βάλτε ως κλειδί τον αριθμό του αποστολέα, αλλιώς τα ιστορικά αναμειγνύονται.
• Αποστολή ελεύθερου κειμένου σε καθυστερημένη επανάληψη επικοινωνίας. Μετά από 24 ώρες αποτυγχάνει με 131047· στείλτε template.

Συχνές ερωτήσεις

Συνεχίστε την ανάγνωση