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

Como carrega um agente LangChain as ferramentas do WhatsApp?

Através do MCPAdapter, o cliente MCP do LangChain, que entrega as ferramentas de um servidor MCP ao create_agent como ferramentas LangChain comuns. Requer langchain[mcp] na versão 1.4.0 ou posterior e está marcado como beta.

A autenticação é delegada ao FastMCP. Ao passar auth="oauth" no cliente, executa-se o fluxo OAuth 2.1 completo: descoberta, registo dinâmico de cliente, redirecionamento no navegador e troca de token. É isto que o servidor MCP da EasyCoexistence espera, por isso não há nenhuma chave para criar ou colar. Por predefinição, os tokens ficam em memória e cada execução repete o passo no navegador; um fornecedor OAuth do FastMCP com um armazenamento de tokens mantém-nos entre execuções.

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

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 chega ao agente uma mensagem de WhatsApp recebida?

Através do webhook, porque o MCP não o consegue fazer. O protocolo é de pedido e resposta, pelo que nada nele permite a um servidor acordar um cliente quando um cliente escreve.

Defina o destino do webhook do número como uma rota da sua própria aplicação, com um segredo longo e aleatório no caminho do URL. A rota responde ao GET de verificação da Meta com o desafio em bruto, aceita cada POST, devolve 200 de imediato e coloca o trabalho em fila. Um worker retira então o remetente e o texto do payload e invoca o agente com esses dados, usando o número do remetente como identificador da conversa, para que a memória fique separada por cliente.

Verifique o segredo no URL em vez do cabeçalho X-Hub-Signature-256. A Meta assina com o segredo da app do Tech Provider, que nunca é partilhado, pelo que o cliente não consegue validar esse cabeçalho.

O agente deve enviar através do MCP ou da Cloud API?

Ambos funcionam, e a diferença está em quem guarda as regras. As ferramentas MCP trazem as regras do WhatsApp nas suas descrições, como o send_message só funcionar dentro da janela de 24 horas e o send_template ser o caminho para contactar 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 envia para o endpoint de mensagens da Cloud API com o token do número, é mais simples quando a tarefa do agente é estreita, por exemplo responder sempre a quem acabou de escrever. Nesse caso, a verificação da janela fica no seu código, que é o lugar de uma regra que nunca pode ser quebrada. Texto livre fora da janela devolve 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 em memória num servidor. Cada reinício exige um início de sessão no navegador; guarde-os num armazenamento de tokens.
• Usar uma única conversa para todos os clientes. Associe a memória do agente ao número do remetente.

Perguntas frequentes

Continue a ler