Dale un número de WhatsApp a un agente de LangChain

¿Cómo carga un agente de LangChain las herramientas de WhatsApp?

Mediante MCPAdapter, el cliente MCP de LangChain, que entrega las herramientas de un servidor MCP a create_agent como herramientas normales de LangChain. Requiere langchain[mcp] en la versión 1.4.0 o posterior y está marcado como beta.

La autenticación se delega en FastMCP. Pasar auth="oauth" en el cliente ejecuta el flujo completo de OAuth 2.1: descubrimiento, registro dinámico de clientes, redirección del navegador e intercambio de tokens. Es justo lo que espera el servidor MCP de EasyCoexistence, así que no hay ninguna clave que crear ni pegar. Por defecto los tokens viven en memoria y cada ejecución repite el paso del navegador; un proveedor OAuth de FastMCP con almacén de tokens los conserva entre ejecuciones.

Una vez cargadas, el agente ve las herramientas con sus descripciones: primero list_numbers, porque todas las demás toman de ella un connection_id, y después send_message, send_template, list_templates, get_number_health y el 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)

¿Cómo llega un mensaje entrante de WhatsApp al agente?

Por el webhook, porque MCP no puede hacerlo. El protocolo es de petición y respuesta, así que nada en él permite que un servidor despierte a un cliente cuando un cliente final escribe.

Configura el destino del webhook del número en una ruta de tu propia aplicación, con un secreto largo y aleatorio en la ruta de la URL. La ruta responde al GET de verificación de Meta con el desafío tal cual, acepta cada POST, devuelve 200 de inmediato y encola el trabajo. Después un worker toma el remitente y el texto del payload e invoca al agente con ellos, usando el número del remitente como id del hilo para que la memoria sea individual por cliente.

Comprueba el secreto en la URL en lugar de la cabecera X-Hub-Signature-256. Meta firma con el app secret del Tech Provider, que nunca se comparte, así que el cliente no puede validar esa cabecera.

¿Debe el agente enviar por MCP o por la Cloud API?

Ambas funcionan, y la diferencia está en quién guarda las reglas. Las herramientas MCP llevan las reglas de WhatsApp en sus descripciones: por ejemplo, send_message solo funciona dentro de la ventana de atención de 24 horas y send_template es la vía para contactar a quien no ha escrito. Un modelo que lee esas descripciones elige la correcta la mayoría de las veces, y eso ayuda cuando el agente decide con libertad.

Una herramienta propia sencilla que publique en el endpoint de mensajes de la Cloud API con el token del número es más simple cuando la tarea del agente es acotada, como responder siempre a la persona que acaba de escribir. Así la comprobación de la ventana queda en tu código, que es donde debe estar una regla que nunca puede romperse. El texto libre fuera de la ventana devuelve el error 131047, y el cliente final no ve nada.

Errores comunes

• Esperar que MCP entregue los mensajes entrantes. Sin una ruta de webhook, el agente nunca recibe noticias de un cliente.
• Dejar los tokens de OAuth en memoria en un servidor. Cada reinicio pide un inicio de sesión en el navegador; persístelos con un almacén de tokens.
• Usar un solo hilo para todos los clientes. Asocia la memoria del agente al número del remitente.

Preguntas frecuentes

Sigue leyendo