Traga seu próprio agente de IA para o WhatsApp: conecte qualquer framework (LangGraph, ADK, personalizado) com um endpoint de webhook

Você pode conectar quase qualquer agente de IA ao WhatsApp sem reescrevê-lo. Execute seu agente, criado com LangGraph, Google ADK, CrewAI ou seu próprio código, atrás de um endpoint HTTPS e depois adicione-o na MonoChat como um Harness de IA com o provedor Personalizado: uma URL de endpoint e um segredo compartilhado. Coloque um nó de Agente de IA em um fluxo, conecte seu número do WhatsApp e seu agente passa a atender os clientes no WhatsApp e em todos os outros canais que a MonoChat conecta, com uma caixa de entrada compartilhada e transferência para atendimento humano ao redor.

Este guia é para equipes que já têm um agente, ou que querem controle total sobre como ele funciona. Ele cobre quando faz sentido trazer seu próprio agente, pelo que o seu endpoint é responsável, a configuração na MonoChat e os detalhes que importam em produção.

Por que trazer seu próprio agente?

A maioria das plataformas de mensagens para clientes vem com um agente de IA integrado. Isso é conveniente até que:

• Seu agente já esteja pronto. Seus desenvolvedores passaram meses em um grafo do LangGraph ou em uma configuração multiagente do ADK, com avaliações e testes. Refazê-lo dentro do criador de bots de um fornecedor joga esse trabalho fora.
• Você precise da sua própria lógica. Regras de preço, verificações de elegibilidade, etapas de conformidade ou sistemas internos que só o seu código alcança.
• Você queira escolher o framework. Os frameworks evoluem rápido. Hoje é o LangGraph; no ano que vem pode ser outro. Seus canais e sua caixa de entrada não deveriam precisar mudar junto.
• Os dados precisem ficar com você. Algumas organizações querem que o raciocínio e as chamadas de ferramentas do agente rodem na própria infraestrutura.

O Agent Harness da MonoChat foi criado para isso: traga seu próprio framework de agentes e mantenha tudo ao redor dele, os canais, a caixa de entrada, as pessoas, em um só lugar.

Como funciona o harness Personalizado

Pense nisso como uma divisão de trabalho.

A MonoChat cuida da camada de conversa:

• As conexões oficiais com WhatsApp, Instagram, Messenger, TikTok, Telegram, chat web, SMS e voz (a MonoChat é Meta Business Partner oficial).
• O fluxo que decide quando o agente é chamado, por meio do nó de Agente de IA.
• A caixa de entrada compartilhada da equipe, onde uma pessoa pode assumir com todo o histórico.

O seu endpoint cuida do agente:

• Receber a conversa da MonoChat.
• Executar seu agente: o raciocínio, as ferramentas, a memória.
• Devolver a resposta do agente.

Entre os dois fica um segredo compartilhado, um valor que os dois lados conhecem, para que o seu endpoint possa verificar que uma requisição vem da sua conta da MonoChat. A MonoChat define o formato exato de requisição e resposta que o seu endpoint implementa; se você ainda não o tem, fale conosco e o compartilharemos com seus desenvolvedores.

O que o seu endpoint deve fazer

Qualquer que seja o framework, um endpoint de agente pronto para produção tem algumas tarefas.

Verifique cada requisição

Confira o segredo compartilhado em cada chamada e rejeite tudo o que não corresponder. Guarde o segredo no seu gerenciador de segredos ou em variáveis de ambiente, não no código, e troque-o se alguma vez for exposto.

Mantenha cada conversa separada

Os clientes escrevem em paralelo. Garanta que o estado, a memória e quaisquer arquivos de trabalho do seu agente estejam restritos a uma conversa, para que os dados de um cliente nunca vazem para a resposta de outro.

Responda em mensagens do tamanho de um chat

Agentes criados para aplicativos web tendem a escrever respostas longas e formatadas. O WhatsApp é lido no celular. Peça ao seu agente mensagens curtas, uma pergunta por vez, e evite Markdown pesado nas respostas.

Falhe de forma explícita, não silenciosa

Se uma ferramenta expirar ou o seu provedor de modelo retornar um erro, devolva uma falha clara em vez de uma resposta pela metade. Uma falha previsível permite que o fluxo faça a coisa certa, por exemplo passar a conversa para uma pessoa.

Seja rápido

Os clientes esperam uma resposta em segundos. Mantenha trabalhos demorados fora do caminho da resposta sempre que possível e faça suas ferramentas serem rápidas ou assíncronas.

Passo a passo na MonoChat

1. Implante seu agente atrás de HTTPS

Hospede seu agente LangGraph, ADK, CrewAI ou personalizado no seu próprio servidor ou nuvem, acessível por HTTPS. Implemente o formato de requisição e resposta da MonoChat e a verificação do segredo compartilhado.

2. Adicione um Harness de IA com o provedor Personalizado

Na MonoChat, adicione um Harness de IA, escolha Personalizado e informe a URL do endpoint e o segredo compartilhado. Você adiciona o harness uma vez e pode usá-lo em quantos fluxos quiser.

3. Adicione um nó de Agente de IA a um fluxo

No fluxo que recebe as conversas, adicione um nó de Agente de IA e selecione seu harness personalizado. Use o fluxo ao redor para o que os fluxos fazem melhor: saudação, roteamento por idioma ou assunto, horário de atendimento e o caminho até uma pessoa.

4. Defina um orçamento por execução

Cada nó de Agente de IA aceita limites de orçamento por execução. Use-os como rede de segurança ao lado dos limites que você já aplica no seu próprio código.

5. Conecte o WhatsApp e outros canais

Conecte seu número do WhatsApp Business e depois associe o mesmo fluxo aos outros canais que você usa. Não há trabalho extra de integração por canal: seu endpoint vê conversas, não APIs de canais.

6. Teste e depois entre no ar

Reproduza mensagens reais de clientes pelo fluxo. Verifique chamadas de ferramentas, tempos de resposta, tom e transferência. Acompanhe de perto os primeiros dias de tráfego real e só depois amplie o que o agente pode fazer.

Notas sobre frameworks

LangGraph. Um grafo de nós e arestas combina naturalmente com jornadas de suporte (triagem, consulta, resolução, escalonamento). Envolva o grafo compilado em um pequeno serviço HTTP, carregue o estado da conversa a cada requisição e devolva a mensagem final.

Google ADK. As árvores multiagente do ADK, um coordenador com subagentes especialistas, se encaixam bem em equipes de suporte, vendas e cobrança. Exponha o agente raiz pelo seu endpoint e deixe o ADK fazer o roteamento internamente.

CrewAI. Equipes de agentes com funções definidas funcionam bem em tarefas com passagens claras, como pesquisar e depois responder. Mantenha as equipes pequenas para chat: cada agente extra adiciona latência.

Seu próprio código. Um ciclo simples com uma API de modelo e algumas funções muitas vezes basta. Você mantém controle total, e a MonoChat fornece os canais e a caixa de entrada.

Transferência: decida no fluxo

Decida no fluxo quais conversas vão para uma pessoa e qual equipe as recebe, e escreva seu agente para que ele diga ao cliente com honestidade quando não pode ajudar, em vez de adivinhar. O fluxo então passa a conversa à equipe certa na caixa de entrada compartilhada com todo o histórico. A Política de Mensagens Comerciais do WhatsApp também espera que as respostas automáticas ofereçam um caminho claro até uma pessoa.

Mantenha também seu agente dentro do seu negócio. Desde 15 de janeiro de 2026, o WhatsApp mantém assistentes de IA de uso geral fora da plataforma; agentes que atendem os seus próprios clientes são permitidos. Nosso guia da política de chatbots de IA do WhatsApp explica a regra.

Quando não criar o seu próprio

Um agente personalizado é a opção mais flexível e também a que você precisa manter. Se está começando do zero, uma opção integrada coloca você no ar mais rápido, sem nada para hospedar:

• O harness integrado da MonoChat, com seus modelos de IA da MonoChat.
• O OpenAI Agents SDK, executado dentro da MonoChat (guia).
• O Claude Agent SDK ou o Pi, executados no agent runner da MonoChat (guia do Claude).
• Agentes hospedados: a OpenAI Agents API ou o Claude Managed Agents, com a sua própria chave.

Como todas as opções usam o mesmo nó de Agente de IA, você pode começar com uma e migrar depois para o seu próprio agente sem mexer nos canais nem na transferência. Compare-as na página do Agent Harness.