Como uma IA consome este RAG de conversas do HubSpot

• Ingestão executada ao menos uma vez (Painel → “Rodar ingestão agora”).
• API Key emitida no painel (seção “API Keys / Access Tokens”) — é o bearer usado por qualquer agente externo.
• URL base do CortexHub: https://cortexhub.alloyal.com.br.
• Use sempre essa URL pública. Endereços de pré-visualização (id-preview--….lovable.app) exigem sessão do editor e devolvem 401 Unauthorized para qualquer agente externo, mesmo com API Key válida.

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": {
    "cortexhub-hubspot-rag": {
      "type": "http",
      "url": "https://cortexhub.alloyal.com.br/api/public/mcp",
      "headers": { "Authorization": "Bearer <RAG_API_TOKEN>" }
    }
  }
}

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://cortexhub.alloyal.com.br/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.