Dai un numero WhatsApp a un agente LangChain

Come carica gli strumenti di WhatsApp un agente LangChain?

Tramite MCPAdapter, il client MCP di LangChain, che passa a create_agent gli strumenti di un server MCP come normali strumenti LangChain. Richiede langchain[mcp] alla versione 1.4.0 o successiva ed è in beta.

L'autenticazione è delegata a FastMCP. Passando auth="oauth" al client si esegue l'intero flusso OAuth 2.1: discovery, registrazione dinamica del client, reindirizzamento nel browser e scambio del token. È ciò che si aspetta il server MCP di EasyCoexistence, quindi non c'è nessuna chiave da creare o incollare. Di default i token restano in memoria e a ogni esecuzione il passaggio nel browser si ripete; un provider OAuth di FastMCP con un token store li conserva tra un'esecuzione e l'altra.

Una volta caricati, l'agente vede gli strumenti con le loro descrizioni: prima list_numbers, perché tutti gli altri strumenti richiedono un connection_id che arriva da lì, poi send_message, send_template, list_templates, get_number_health e il resto.

from fastmcp.client import Client
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

URL = "https://easycoexistence.com/api/mcp"

async def build_agent(model: str):
    async with MCPAdapter(Client(URL, auth="oauth")) as adapter:
        tools = await adapter.list_tools()
        return create_agent(model, tools)

Come arriva all'agente un messaggio WhatsApp in entrata?

Tramite il webhook, perché MCP non può farlo. Il protocollo funziona a richiesta e risposta, quindi niente permette a un server di svegliare un client quando un cliente scrive.

Imposta la destinazione del webhook del numero su una route della tua applicazione, con un segreto lungo e casuale nel percorso dell'URL. La route risponde alla GET di verifica di Meta con il challenge così com'è, accetta ogni POST, restituisce subito 200 e mette il lavoro in coda. Un worker prende poi mittente e testo dal payload e invoca l'agente con questi dati, usando il numero del mittente come id del thread, così la memoria resta separata per cliente.

Controlla il segreto nell'URL anziché l'header X-Hub-Signature-256. Meta firma con l'app secret del Tech Provider, che non viene mai condiviso, quindi il cliente non può validare quell'header.

L'agente deve inviare tramite MCP o tramite la Cloud API?

Vanno bene entrambi, e la differenza sta in chi custodisce le regole. Gli strumenti MCP portano le regole di WhatsApp nelle loro descrizioni: send_message funziona solo dentro la finestra di 24 ore e send_template è il modo per raggiungere chi non ha scritto. Un modello che legge quelle descrizioni sceglie quello giusto nella maggior parte dei casi, ed è utile quando l'agente decide liberamente.

Uno strumento tuo che fa una POST sull'endpoint dei messaggi della Cloud API con il token del numero è più semplice quando il compito dell'agente è circoscritto, per esempio rispondere sempre a chi ha appena scritto. In quel caso il controllo della finestra sta nel tuo codice, che è il posto giusto per una regola che non deve mai essere violata. Il testo libero fuori dalla finestra torna con l'errore 131047, e il cliente non vede nulla.

Errori comuni

• Aspettarsi che MCP consegni i messaggi in arrivo. Senza una route per il webhook, l'agente non sente mai un cliente.
• Lasciare i token OAuth in memoria su un server. Ogni riavvio richiede un accesso dal browser: conservali con un token store.
• Usare un unico thread per tutti i clienti. Associa la memoria dell'agente al numero del mittente.

Domande frequenti

Continua a leggere