Como uma IA consome este RAG de conversas do HubSpot

• Ingestão executada ao menos uma vez (Painel → “Rodar ingestão agora”).
• Token de API do RAG (RAG_API_TOKEN) gerado no backend — é o bearer usado por qualquer agente externo.
• URL base do projeto publicado, por exemplo https://seu-projeto.lovable.app.

O endpoint /api/public/mcp fala JSON-RPC 2.0 no protocolo MCP e expõe a ferramenta buscar_conversas_hubspot. Claude Desktop, Cursor e agentes compatíveis conectam por HTTP remoto:

{
  "mcpServers": {
    "hubspot-rag": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://seu-projeto.lovable.app/api/public/mcp",
        "--header", "Authorization: Bearer ${RAG_API_TOKEN}"
      ],
      "env": { "RAG_API_TOKEN": "cole-o-token-aqui" }
    }
  }
}

Clientes com suporte nativo a MCP remoto podem apontar direto para a URL, enviando o header Authorization: Bearer ….

Para frameworks sem MCP (LangChain, n8n, function calling próprio), use o endpoint de busca:

curl -X POST https://seu-projeto.lovable.app/api/public/rag/search \
  -H "Authorization: Bearer $RAG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"cliente pedindo segunda via de boleto","top_k":5}'

Resposta:

{
  "query": "...",
  "top_k": 5,
  "results": [
    {
      "chunk_id": 1421,
      "document_id": 88,
      "hubspot_thread_id": "70123456",
      "inbox_id": "3210",
      "chunk_index": 2,
      "content": "trecho da conversa …",
      "similarity": 0.8241
    }
  ]
}

Recupere de 4 a 8 trechos, ordene por similaridade e injete como contexto antes da pergunta do usuário. Sugestão de system prompt:

Você é o assistente de atendimento. Responda APENAS com base nos
trechos de conversas anteriores fornecidos em <contexto>.
Cite o hubspot_thread_id quando afirmar algo específico.
Se o contexto não cobrir a pergunta, diga que não há histórico e
ofereça encaminhar para um humano.

<contexto>
{{trechos_recuperados}}
</contexto>

Descarte resultados com similaridade abaixo de ~0.75 para evitar contexto ruidoso e filtre por inbox_id quando o bot atende um canal específico.

• A ingestão é incremental por watermark: cada caixa de entrada retoma de onde parou.
• POST /api/public/ingest dispara o ciclo agendado (autenticado pelo agendador do backend).
• Acompanhe execuções, falhas e watermarks no Painel; a Landing Zone guarda o envelope bruto de cada thread para reprocessamento.
• Reindexação exige o mesmo provedor de embeddings usado na consulta — trocar de modelo obriga a regerar todos os chunks.

• Nunca embuta o token do RAG em código de front-end ou no prompt do modelo.
• Os trechos podem conter dados pessoais de clientes: aplique mascaramento antes de enviá-los a modelos de terceiros quando exigido pela sua política.
• Rotacione o token ao trocar de fornecedor de chatbot.