Dê um número de WhatsApp a um agente LangChain

Como um agente LangChain carrega as ferramentas do WhatsApp?

Pelo MCPAdapter, o cliente MCP do LangChain, que entrega as ferramentas de um servidor MCP ao create_agent como ferramentas comuns do LangChain. Ele exige langchain[mcp] na versão 1.4.0 ou superior e está marcado como beta.

A autenticação é delegada ao FastMCP. Passar auth="oauth" no cliente executa o fluxo OAuth 2.1 completo: descoberta, registro dinâmico de cliente, redirecionamento no navegador e troca de token. É isso que o servidor MCP do EasyCoexistence espera, então não há chave para criar nem colar. Por padrão os tokens ficam na memória e cada execução repete a etapa do navegador; um provedor OAuth do FastMCP com armazenamento de tokens os mantém entre execuções.

Depois de carregadas, o agente vê as ferramentas com suas descrições: list_numbers primeiro, porque todas as outras pedem um connection_id vindo dela, depois send_message, send_template, list_templates, get_number_health e as demais.

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)

Como uma mensagem recebida do WhatsApp chega ao agente?

Pelo webhook, porque o MCP não consegue fazer isso. O protocolo é de requisição e resposta, então nada nele permite que um servidor acorde um cliente quando um cliente escreve.

Aponte o destino do webhook do número para uma rota da sua própria aplicação, com um segredo longo e aleatório no caminho da URL. A rota responde ao GET de verificação da Meta com o challenge bruto, aceita cada POST, retorna 200 imediatamente e enfileira o trabalho. Um worker então extrai o remetente e o texto do payload e invoca o agente com eles, usando o número do remetente como id da thread para que a memória fique separada por cliente.

Verifique o segredo na URL, e não o cabeçalho X-Hub-Signature-256. A Meta assina com o app secret do Tech Provider, que nunca é compartilhado, então esse cabeçalho não pode ser validado pelo cliente.

O agente deve enviar pelo MCP ou pela Cloud API?

Os dois funcionam, e a diferença está em quem guarda as regras. As ferramentas MCP carregam as regras do WhatsApp em suas descrições, como send_message funcionar só dentro da janela de atendimento de 24 horas e send_template ser o caminho para alcançar quem não escreveu. Um modelo que lê essas descrições escolhe a certa na maioria das vezes, e isso ajuda quando o agente decide livremente.

Uma ferramenta simples sua, que faz POST no endpoint de mensagens da Cloud API com o token do número, é mais simples quando a tarefa do agente é restrita, como sempre responder a quem acabou de escrever. Aí a checagem da janela fica no seu código, que é onde pertence uma regra que nunca pode ser quebrada. Texto livre fora da janela volta com o erro 131047, e o cliente nunca vê nada.

Erros comuns

• Esperar que o MCP entregue as mensagens recebidas. Sem uma rota de webhook, o agente nunca ouve um cliente.
• Deixar os tokens OAuth na memória em um servidor. Cada reinício pede um login no navegador; persista-os com um armazenamento de tokens.
• Usar uma única thread para todos os clientes. Associe a memória do agente ao número do remetente.

Perguntas frequentes

Continue lendo