Mettre un agent OpenAI Agents SDK sur WhatsApp

Comment un message WhatsApp devient-il une exécution de l'agent ?

Par une route de votre propre application que Meta appelle. Définissez-la comme destination webhook du numéro, avec un long secret aléatoire dans le chemin. La route répond à la requête GET de vérification de Meta en renvoyant hub.challenge en texte brut, accepte chaque POST, répond 200 immédiatement et met le traitement en file d'attente, car Meta relance les réponses lentes et vous exécuteriez l'agent deux fois.

Un worker lit ensuite l'expéditeur et le texte dans le payload, puis appelle Runner.run. Passez une session dont l'identifiant est le numéro de l'expéditeur : le SDK stocke la conversation sous cet identifiant, donc le message suivant du même client reprend là où le précédent s'est arrêté, et deux clients ne partagent jamais un historique. SQLiteSession suffit pour démarrer ; le SDK propose aussi des sessions Redis et SQLAlchemy pour plusieurs workers.

Le secret dans l'URL tient lieu d'authentification ici. Meta signe les envois avec le secret d'application du Tech Provider, donc le client ne peut pas valider l'en-tête de signature.

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

Pourquoi est-ce votre code qui doit envoyer la réponse, et non l'agent ?

Parce que la seule règle à ne jamais enfreindre est une règle de délai, et le code la fait respecter mieux qu'un prompt. Meta ouvre une fenêtre de service client de 24 heures quand un client écrit. À l'intérieur, le texte libre passe. À l'extérieur, seul un template approuvé passe, et le texte libre renvoie l'erreur 131047.

Un worker qui répond au message qui vient d'arriver est toujours dans la fenêtre, donc envoyer result.final_output en texte est sûr par construction. Le travail différé, une relance le lendemain matin ou un rappel, doit passer par un chemin séparé qui envoie un template et jamais de texte libre.

L'agent peut quand même avoir des outils. Donnez-lui des function tools pour consulter des informations, comme une commande ou une réservation, et gardez l'envoi WhatsApp dans le worker. Cela garde aussi le token d'accès hors de portée de tout ce que le modèle peut appeler avec des arguments arbitraires.

L'agent peut-il utiliser le serveur MCP d'EasyCoexistence ?

Oui, via MCPServerStreamableHttp, avec un peu plus de configuration qu'un simple en-tête. Le SDK accepte soit un en-tête Authorization, soit un httpx.Auth dans params["auth"]. Le serveur MCP d'EasyCoexistence émet ses propres tokens OAuth après une connexion dans le navigateur, avec enregistrement dynamique du client et PKCE, donc aucune clé statique n'existe. Le SDK Python MCP fournit OAuthClientProvider, un gestionnaire d'authentification HTTP qui exécute ce flux avec PKCE et renouvellement du token, et c'est lui qu'on place dans params["auth"].

Cela vaut la peine quand l'agent doit décider seul : vérifier la santé d'un numéro, lire le statut d'un template, ou choisir entre send_message et send_template d'après les règles des descriptions d'outils. Pour un accueil qui se contente de répondre, le worker décrit plus haut est plus court et comporte moins de risques de panne.

Dans les deux cas, le webhook reste nécessaire. MCP fonctionne par requête et réponse, et le message d'un client ne peut atteindre l'agent que par la route que Meta appelle.

Erreurs courantes

• Exécuter l'agent avant de renvoyer 200 à Meta. Une réponse lente est relancée, et le client reçoit deux réponses.
• Utiliser une seule session pour tous les clients. Indexez-la sur le numéro de l'expéditeur, sinon les historiques se mélangent.
• Laisser une relance différée envoyer du texte libre. Après 24 heures, elle échoue avec l'erreur 131047 ; envoyez un template à la place.

Questions fréquemment posées

Poursuivre la lecture