Volume 7: Agentes Cognitivos, Servidor MCP & Evolution API v2

1. Fundamentos para Não-Técnicos: O Cabo USB-C da Inteligência Artificial

Até o final de 2024, a forma como os desenvolvedores conectavam modelos de IA aos sistemas das empresas era um verdadeiro caos:

• Se você usava OpenAI, precisava escrever ferramentas no formato proprietário de Function Calling da OpenAI;
• Se quisesse migrar para o Claude da Anthropic, precisava reescrever todos os esquemas JSON no formato de Tool Use da Anthropic;
• Se quisesse integrar com o ERP do cliente, criava um script engessado que só servia para aquele caso específico.

Os Três Pilares de um Servidor MCP:

1. Resources (Recursos de Dados): Documentos, manuais e tabelas que o agente pode ler para obter contexto passivo;
2. Tools (Ferramentas Executáveis): Ações com validação rigorosa de parâmetros (ex: consultar estoque, gerar chave PIX, calcular frete);
3. Prompts: Modelos prontos de instruções que orientam a IA em rotinas padronizadas da empresa.

2. Construindo um Servidor MCP Corporativo em TypeScript

Abaixo está a implementação completa de um servidor MCP industrial para uma distribuidora ou prestadora de serviços B2B, utilizando o SDK oficial @modelcontextprotocol/sdk.

Este servidor expõe duas ferramentas canônicas:

• consultar_estoque_preco: Consulta saldo e preço de um produto diretamente na base de dados;
• gerar_cobranca_pix: Cria uma cobrança instantânea com chave e QR Code.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

// Inicialização do servidor MCP com metadados do sistema
const server = new Server(
  {
    name: "ai-first-erp-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 1. Definição do catálogo de ferramentas disponíveis para os agentes
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "consultar_estoque_preco",
        description: "Consulta o estoque atual e a tabela de preços de um SKU no ERP corporativo.",
        inputSchema: {
          type: "object",
          properties: {
            sku: {
              type: "string",
              description: "Código identificador do produto (ex: TIG-TUB-100)",
            },
            filial_id: {
              type: "string",
              description: "Identificador da filial do galpão (padrão: 'matriz')",
            },
          },
          required: ["sku"],
        },
      },
      {
        name: "gerar_cobranca_pix",
        description: "Gera uma cobrança PIX com código Copia e Cola e QR Code para pagamento de orçamento.",
        inputSchema: {
          type: "object",
          properties: {
            valor_reais: {
              type: "number",
              description: "Valor total da fatura em reais",
            },
            numero_cotacao: {
              type: "string",
              description: "Número identificador da cotação aprovada",
            },
          },
          required: ["valor_reais", "numero_cotacao"],
        },
      },
    ],
  };
});

// 2. Execução das ferramentas quando invocadas pelo agente de IA
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "consultar_estoque_preco") {
    const sku = String(args?.sku);
    // Consulta simulada ao PostgreSQL / ERP legado
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            sku: sku,
            descricao: "Tubo PVC Soldável 100mm 6 Metros Tigre",
            estoque_disponivel: 340,
            unidade: "UN",
            preco_tabela_brl: 65.00,
            desconto_maximo_permitido: 0.12,
            localizacao_galpao: "Rua 4, Prateleira B",
          }),
        },
      ],
    };
  }

  if (name === "gerar_cobranca_pix") {
    const valor = Number(args?.valor_reais);
    const cotacao = String(args?.numero_cotacao);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            status: "criado",
            cotacao: cotacao,
            valor: valor,
            pix_copia_cola: "00020126580014br.gov.bcb.pix0136d84f1a23-4e89-4bc2-9e22-83b6f8490a125204000053039865404" + valor.toFixed(2),
            expiracao_minutos: 60,
          }),
        },
      ],
    };
  }

  throw new Error(`Ferramenta desconhecida: ${name}`);
});

// 3. Inicialização do transporte via Standard Input / Output (stdio)
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Servidor MCP AI-First conectado e aguardando chamadas de agentes.");
}

main().catch(console.error);

3. WhatsApp Industrial: Evolution API v2 e Protocolos Anti-Banimento

No Brasil, o WhatsApp é o sistema nervoso central dos negócios. Se o número da empresa for bloqueado pela Meta, as vendas param no mesmo minuto.

Por Que Extensões de Navegador Tomam Ban em 48 Horas

Amadores usam extensões de navegador gratuitas ou bibliotecas de automação que simulam cliques no WhatsApp Web (como Puppeteer ou Selenium). A Meta possui inteligência algorítmica sofisticada que detecta padrões não-humanos:

• Ausência de movimentação realista de mouse;
• Disparos com intervalos idênticos de exatamente 1.000 milissegundos;
• Falta de eventos de digitação (composing) e de leitura (read receipts).

O Padrão de Produção com Evolution API v2

A Evolution API v2 é a solução de código aberto mais robusta e escalável para integração de WhatsApp via APIs HTTP e WebSockets.

Abaixo está a configuração em Docker Compose para rodar a Evolution API v2 com persistência no PostgreSQL:

version: "3.8"

services:
  evolution-api:
    image: atendai/evolution-api:v2.1.2
    container_name: evolution-api-instance
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - SERVER_URL=https://whats.suaempresa.com.br
      - DOCKER_ENV=true
      - AUTHENTICATION_API_KEY=CHAVE_MESTRA_SUPER_SECRETA_EVOLUTION_123
      - DATABASE_ENABLED=true
      - DATABASE_CONNECTION_URI=postgresql://postgres:SENHA_DB@postgres-host:5432/evolution_db
      - REDIS_ENABLED=true
      - REDIS_URI=redis://default:SENHA_REDIS@redis-host:6379
      - WEBHOOK_GLOBAL_ENABLED=true
      - WEBHOOK_GLOBAL_URL=https://n8n.suaempresa.com.br/webhook/evolution-inbound
      - WEBHOOK_EVENTS_MESSAGES_UPSERT=true
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1024M

As 4 Regras de Ouro do Protocolo Anti-Banimento:

1. Simulação de Digitação Humana (composing): Nunca responda uma mensagem em 10 milissegundos. Envie primeiro o evento de "digitando..." por 2 a 4 segundos antes de disparar a resposta final;
2. Aquecimento Gradual de Números Novos (Warm-up): Nunca conecte um chip novo e envie 500 mensagens no primeiro dia. No dia 1 a 3, envie 20 mensagens para contatos conhecidos com respostas mútuas. Aumente o volume em 20% ao dia durante 2 semanas;
3. Inbound em Primeiro Lugar: IA comercial deve atender clientes que entraram em contato ativamente (inbound vindo de anúncios, site ou indicações). Disparos frios em massa para listas compradas geram denúncias de spam e banimento imediato;
4. Opção Transparente de Saída: Em qualquer contato de follow-up, inclua uma instrução amigável: "Se preferir não receber mais cotações por aqui, basta responder 'Parar'".

4. Observabilidade Completa com Langfuse: Rastreando Latência e Centavos

Rodar agentes de inteligência artificial em empresas sem uma ferramenta de observabilidade é o equivalente a pilotar um avião à noite com o painel de instrumentos desligado.

O Langfuse é uma plataforma open-source de engenharia de LLM que atua como a caixa-preta do sistema, registrando cada requisição com três níveis de detalhamento:

• Trace (Rastreio da Sessão): A conversa inteira do cliente com a cotação;
• Spans (Passos Intermediários): O tempo exato gasto na busca híbrida no PostgreSQL e na chamada da ferramenta MCP;
• Generations (Chamadas de LLM): O prompt enviado, a resposta recebida, os tokens exatos consumidos e o custo financeiro em dólares e reais.

Instrumentação Prática em Python com Langfuse SDK

# -*- coding: utf-8 -*-
import os
from langfuse import Langfuse

# Inicialização segura do cliente de observabilidade
langfuse = Langfuse(
    public_key=os.getenv("LANGFUSE_PUBLIC_KEY", "pk-lf-12345"),
    secret_key=os.getenv("LANGFUSE_SECRET_KEY", "sk-lf-67890"),
    host=os.getenv("LANGFUSE_HOST", "https://langfuse.suaempresa.com.br")
)

def processar_mensagem_com_observabilidade(tenant_id: str, contact_phone: str, user_text: str):
    # 1. Criação do Trace raiz associado ao tenant (cliente da consultoria)
    trace = langfuse.trace(
        name="atendimento_whatsapp_cotacao",
        user_id=contact_phone,
        metadata={"tenant_id": tenant_id, "canal": "whatsapp"},
        tags=["producao", "cotacao_b2b"]
    )

    # 2. Rastreamento do passo de busca híbrida no PostgreSQL (Span)
    span_db = trace.span(name="busca_hibrida_produtos_rrf")
    # Simulação da consulta no banco de dados
    produtos_encontrados = [{"sku": "TIG-100", "preco": 65.00}]
    span_db.end(output={"produtos_retornados": len(produtos_encontrados)})

    # 3. Rastreamento da inferência no modelo de linguagem (Generation)
    generation = trace.generation(
        name="geracao_resposta_comercial",
        model="claude-3-5-sonnet-20241022",
        model_parameters={"temperature": 0.2, "max_tokens": 800},
        input=[
            {"role": "system", "content": "Você é o assistente comercial da distribuidora."},
            {"role": "user", "content": user_text}
        ]
    )

    # Simulação da resposta do Claude
    resposta_modelo = "Temos 340 tubos de 100mm Tigre a R$ 65,00 cada. Deseja fechar o pedido?"
    prompt_tokens = 450
    completion_tokens = 85

    # Finalização da geração registrando o consumo exato de tokens
    generation.end(
        output=resposta_modelo,
        usage={
            "prompt_tokens": prompt_tokens,
            "completion_tokens": completion_tokens,
            "total_tokens": prompt_tokens + completion_tokens
        }
    )

    print(f"Atendimento registrado no Langfuse. Trace ID: {trace.id}")
    return resposta_modelo

5. Exercício Prático de Fixação do Volume 7

1. Arquitetura MCP: Suponha que um novo cliente da sua consultoria utilize um sistema ERP antigo que só exporta relatórios diários em arquivos CSV em uma pasta de rede compartilhada. Como você criaria um recurso (Resource) ou ferramenta (Tool) no seu servidor MCP para que seus agentes pudessem ler esses preços sem precisar alterar o código do ERP antigo?
2. Análise de Custos no Langfuse: Se uma empresa atende 5.000 clientes por mês e cada atendimento gera 3 chamadas de modelo consumindo em média 2.000 tokens de entrada e 300 tokens de saída no Claude 3.5 Sonnet: qual é o custo total mensal de inferência que o painel do Langfuse registrará?

No próximo volume (Volume 8), fecharemos o ciclo com a parte mais valiosa: O Playbook Comercial de Alta Renda. Aprenderemos o script de diagnóstico de 60 minutos, a minuta contratual B2B de 15 cláusulas jurídicas blindadas e o plano de ação de 30 dias para prospectar, fechar e instalar sistemas de R$ 30k a R$ 100k.