Runbook — Bases de conhecimento

As bases de conhecimento (KB) alimentam o contexto consultado pela IA. A UI da base fica em /kb e possui abas Artigos, Categorias, Métricas, Permissões e Configurações.

Configuração e associação

1. Criar/selecionar uma KB em /kb.
2. Organizar categorias e artigos; revisar permissões e privacidade.
3. Em Configurações, verificar IA habilitada, reindexação, ID público, exportação/clonagem, portal, domínio e zona de perigo.
4. No editor do assistente, abrir Bases de conhecimento e associar a KB.

APIs de associação:

GET /assistents/{assistantId}/kbs
GET /kb/configs
POST /assistents/{assistantId}/kbs
DELETE /assistents/{assistantId}/kbs/{kbConfigId}
POST /kb/reindex?kbId={kbConfigId}

Payload para associar: { "kbConfigId": 123 }.

Estados da associação: Pronta para uso, Processando…, Falha no processamento, Sem artigos e Aguardando.

Comportamento da IA e RAG

Em v4.20.3+, a IA consulta a KB e os dados do assistente antes de dizer que não sabe. Em v4.19.1+, considera as últimas 20 mensagens e dados salvos do contato. Não documentar como memória da conversa inteira.

O embedding/índice pode ficar pendente ou exigir reindexação. Não afirmar que apenas artigos published entram no RAG: isso não foi validado; histórico anterior observou embedding também em draft.

Compartilhar, exportar e clonar

Desde v4.20.0, é possível exportar/importar KB por link. A validade pode ser de 1 minuto a 12 horas ou permanente; links são revogáveis. A clonagem inclui categorias, artigos secretos, traduções, idiomas e links; mídias são copiadas e o índice vem pronto.

O ID público em Configurações permite vínculo cross-account. Trate links e IDs públicos como compartilháveis apenas quando a permissão e a privacidade da base permitirem.

Uso com assistentes e canais

Associe a KB no editor do assistente antes de ativar o agente em um canal. O recurso de KB funciona em todos os canais suportados pela IA. Mudanças na KB podem alterar respostas; valide com um agente de laboratório e uma pergunta conhecida antes de promover.

Checklist seguro vs. disparador

Seguro: consultar abas, métricas e estados; revisar artigos/categorias; reindexar uma KB de teste; associar ao assistente de laboratório.

Disparador: habilitar IA, alterar permissões/privacidade, publicar portal/domínio, exportar por link, tornar link permanente, clonar para outra conta, excluir artigos/categorias ou associar KB a agente/canal de produção. Registrar escopo, validade e responsável antes de aplicar.

Pendências honestas

• Não foi validado o critério exato de publicação para entrada no RAG.
• Não foi validado o contrato completo dos endpoints de artigos, categorias e métricas.
• Não assumir que uma clonagem preserva ACLs externas ou referências fora da KB sem revisar o resultado.