Einen OpenAI-Agents-SDK-Agenten auf WhatsApp betreiben

Wie wird aus einer WhatsApp-Nachricht ein Agentenlauf?

Über eine Route in Ihrer eigenen Anwendung, die Meta aufruft. Setzen Sie das Webhook-Ziel der Nummer darauf, mit einem langen, zufälligen Secret im Pfad. Die Route beantwortet Metas Verifizierungs-GET, indem sie hub.challenge als Klartext zurückgibt, nimmt jeden POST an, antwortet sofort mit 200 und stellt die Arbeit in eine Warteschlange. Denn Meta wiederholt langsame Antworten, und Sie würden den Agenten doppelt ausführen.

Ein Worker liest dann Absender und Text aus der Payload und ruft Runner.run auf. Übergeben Sie eine Session, deren ID die Nummer des Absenders ist: Das SDK speichert die Unterhaltung unter dieser ID, sodass die nächste Nachricht desselben Kunden dort weitermacht, wo die letzte endete, und zwei Kunden nie einen Verlauf teilen. SQLiteSession reicht für den Anfang; für mehrere Worker liefert das SDK auch Redis- und SQLAlchemy-Sessions mit.

Das Secret in der URL ist hier die Authentifizierung. Meta signiert Zustellungen mit dem App-Secret des Tech Providers, daher kann der Kunde den Signatur-Header nicht validieren.

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}},
        )

Warum sollte Ihr Code die Antwort senden und nicht der Agent?

Weil die eine Regel, die nie gebrochen werden darf, eine Zeitregel ist, und Code sie besser durchsetzt als ein Prompt. Meta öffnet ein 24-Stunden-Kundenservice-Fenster, sobald ein Kunde schreibt. Darin geht Freitext durch. Außerhalb geht nur ein genehmigtes Template, und Freitext kommt mit dem Fehler 131047 zurück.

Ein Worker, der die gerade eingetroffene Nachricht beantwortet, liegt immer im Fenster, daher ist das Senden von result.final_output als Text konstruktionsbedingt sicher. Arbeit, die später stattfindet, etwa eine Nachfrage am nächsten Morgen oder eine Erinnerung, sollte über einen separaten Pfad laufen, der ein Template sendet und nie Freitext.

Der Agent kann trotzdem Tools haben. Geben Sie ihm Function-Tools zum Nachschlagen, etwa einer Bestellung oder einer Buchung, und lassen Sie das WhatsApp-Senden im Worker. So bleibt auch das Token außerhalb von allem, was das Modell mit beliebigen Argumenten aufrufen kann.

Kann der Agent den EasyCoexistence-MCP-Server nutzen?

Ja, über MCPServerStreamableHttp, mit mehr Einrichtung als bei einem Header. Das SDK akzeptiert entweder einen Authorization-Header oder ein httpx.Auth in params["auth"]. Der EasyCoexistence-MCP-Server stellt nach einer Anmeldung im Browser eigene OAuth-Tokens aus, mit dynamischer Client-Registrierung und PKCE, deshalb gibt es keinen statischen Schlüssel. Das MCP-Python-SDK liefert OAuthClientProvider, einen HTTP-Auth-Handler, der diesen Ablauf mit PKCE und Token-Erneuerung ausführt, und genau der gehört in params["auth"].

Das lohnt sich, wenn der Agent selbst entscheiden soll: den Zustand einer Nummer prüfen, den Template-Status lesen oder anhand der Regeln in den Tool-Beschreibungen zwischen send_message und send_template wählen. Für einen Empfang, der nur antwortet, ist der Worker oben kürzer und weniger fehleranfällig.

In beiden Fällen bleibt der Webhook. MCP ist Anfrage und Antwort, und die Nachricht eines Kunden erreicht den Agenten nur über die Route, die Meta aufruft.

Häufige Fehler

• Den Agenten ausführen, bevor 200 an Meta zurückgeht. Eine langsame Antwort wird wiederholt, und der Kunde erhält zwei Antworten.
• Eine Session für alle Kunden verwenden. Schlüsseln Sie sie auf die Nummer des Absenders, sonst vermischen sich die Verläufe.
• Eine verspätete Nachfrage Freitext senden lassen. Nach 24 Stunden scheitert sie mit 131047; senden Sie stattdessen ein Template.

Häufig gestellte Fragen

Weiterlesen