Coloque um agente OpenAI Agents SDK no WhatsApp

Como se transforma uma mensagem de WhatsApp numa execução do agente?

Através de uma rota na sua própria aplicação, chamada pela Meta. Defina-a como destino do webhook do número, com um segredo longo e aleatório no caminho. A rota responde à verificação GET da Meta devolvendo hub.challenge como texto simples, aceita cada POST, responde 200 de imediato e coloca o trabalho em fila, porque a Meta repete as respostas lentas e o agente seria executado duas vezes.

Depois, um worker lê o remetente e o texto do payload e chama Runner.run. Passe uma sessão cujo id seja o número do remetente: o SDK guarda a conversa sob esse id, pelo que a mensagem seguinte do mesmo cliente continua onde a anterior parou, e dois clientes nunca partilham o mesmo histórico. SQLiteSession chega para começar; o SDK inclui também sessões Redis e SQLAlchemy para vários workers.

O segredo no URL é aqui a autenticação. A Meta assina as entregas com o segredo da aplicação do Tech Provider, pelo que o cliente não consegue validar o cabeçalho da assinatura.

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

Porque deve ser o seu código a enviar a resposta, e não o agente?

Porque a única regra que nunca pode ser quebrada é uma regra de tempo, e o código cumpre-a melhor do que um prompt. A Meta abre uma janela de atendimento de 24 horas quando um cliente escreve. Dentro dela, o texto livre passa. Fora dela, só passa um template aprovado, e o texto livre devolve o erro 131047.

Um worker que responde à mensagem que acabou de chegar está sempre dentro da janela, pelo que enviar result.final_output como texto é seguro por construção. O trabalho que acontece mais tarde, como um acompanhamento na manhã seguinte ou um lembrete, deve seguir por um caminho separado que envia um template e nunca texto livre.

O agente pode, mesmo assim, ter ferramentas. Dê-lhe ferramentas de função para consultar dados, como uma encomenda ou uma reserva, e mantenha o envio por WhatsApp no worker. Isso também mantém o token de acesso fora do alcance de qualquer coisa que o modelo possa chamar com argumentos arbitrários.

O agente pode usar o servidor MCP da EasyCoexistence?

Pode, através de MCPServerStreamableHttp, com mais configuração do que um cabeçalho. O SDK aceita um cabeçalho Authorization ou um httpx.Auth em params["auth"]. O servidor MCP da EasyCoexistence emite os seus próprios tokens OAuth após um início de sessão no navegador, com registo dinâmico de clientes e PKCE, por isso não existe uma chave estática. O SDK Python do MCP inclui OAuthClientProvider, um gestor de autenticação HTTP que executa esse fluxo com PKCE e renovação do token, e é isso que se coloca em params["auth"].

Compensa quando o agente deve decidir por si: verificar o estado de um número, ler o estado de um template, ou escolher entre send_message e send_template segundo as regras nas descrições das ferramentas. Para um atendimento que apenas responde, o worker acima é mais curto e tem menos pontos de falha.

De qualquer forma, o webhook mantém-se. O MCP funciona por pedido e resposta, e a mensagem de um cliente só chega ao agente pela rota que a Meta chama.

Erros comuns

• Executar o agente antes de devolver 200 à Meta. Uma resposta lenta é repetida e o cliente recebe duas respostas.
• Usar uma única sessão para todos os clientes. Identifique-a pelo número do remetente, ou os históricos misturam-se.
• Deixar um acompanhamento atrasado enviar texto livre. Passadas 24 horas falha com 131047; envie antes um template.

Perguntas frequentes

Continue a ler