Consultar Base de Conhecimento

O que é

Consultar Base de Conhecimento é a ferramenta nativa que recupera trechos das bases vinculadas ao agente. Ela serve para responder a partir de materiais da organização — como produtos, preços, políticas, procedimentos, FAQs e manuais — em vez de depender apenas do conhecimento geral do modelo.

A ferramenta não é mais adicionada pela seção Ferramentas. Ela é ativada automaticamente quando pelo menos uma base é marcada em Conhecimento e desativada quando a última base é desmarcada.

Permissões e pré-requisitos

Para configurar o vínculo, a pessoa precisa poder editar o agente (agents.write) e editar bases (bases.write). Para criar ou revisar o conteúdo primeiro, abra Bases de Conhecimento em /admin/bases; veja a visão geral das bases.

Cada base deve ter:

• nome e descrição que expliquem claramente o que ela cobre;
• itens cujo processamento no índice foi concluído;
• conteúdo atual, sem duplicações ou instruções conflitantes.

A descrição da base é especialmente importante: ela entra no catálogo que o modelo lê para decidir se deve pesquisar. Quando uma base marcada não tem descrição, a interface avisa que o agente enxerga somente o nome.

Vincular bases ao agente

1. Abra Agentes, selecione o agente e entre em Conhecimento.
2. Na coluna Bases de conhecimento, identificada como Consulta quando precisa, marque uma ou mais bases.
3. Confira a quantidade de itens buscáveis. Esse número soma os itens das bases marcadas; ele não representa quantos trechos entram em cada resposta.
4. Expanda Instrução que o agente recebe para conferir a regra geral e o catálogo de bases.
5. Se necessário, preencha Regra só para este agente (opcional).
6. Se quiser registrar perguntas sem resposta, ative AutoLearn. Essa opção só aparece enquanto existe uma base marcada.
7. Selecione Salvar na barra de alterações.

Marcar uma base cria e ativa o contrato interno search_knowledge_base. A regra específica do agente é acrescentada depois da orientação geral e prevalece em caso de conflito; ela não substitui nem esconde o catálogo das bases.

Como orientar o agente

Sem regra específica, o agente recebe uma instrução para pesquisar antes de responder qualquer pergunta que os materiais da empresa possam esclarecer. O único parâmetro de chamada é query, uma pergunta ou conjunto de termos.

Use a regra opcional para restringir ou priorizar situações concretas. Por exemplo:

Consulte as bases para dúvidas sobre produto, preço, cancelamento e política comercial. Se o material não sustentar a resposta, diga que não encontrou a informação; não complete lacunas de memória.

No prompt principal, reforce três comportamentos:

• pesquise antes de afirmar fatos que pertencem à organização;
• responda apenas o que os trechos encontrados sustentam;
• quando não houver resultado relevante, peça contexto ou reconheça a ausência em vez de inventar.

Como a recuperação funciona

O caminho padrão usa busca híbrida: combina embedding semântico com busca lexical BM25, funde e reordena candidatos e pode tentar até duas variações determinísticas de grafia quando o primeiro passe fica incerto. A expansão por outro modelo existe no motor, mas está desativada na configuração de produção auditada.

A recuperação aplica o ID da organização e somente as bases vinculadas. Antes de responder, o motor também valida a procedência de todos os trechos; um resultado fora desse escopo invalida o contexto e aciona o fallback legado.

O contexto entregue ao modelo:

• contém no máximo oito trechos e 8.000 caracteres no caminho híbrido;
• remove trechos muito curtos e sobreposição forte;
• prefixa cada trecho com o nome do item e, quando disponível, sua trilha de títulos e subtítulos;
• não expõe a pontuação de similaridade nem uma URL de origem.

Por isso, o agente pode mencionar o documento e a seção que recebeu, mas só deve oferecer um link quando essa URL existir no próprio conteúdo recuperado. O tamanho total da base não é copiado para o prompt: entram apenas os trechos selecionados em cada consulta.

Sem resultado, erro e AutoLearn

Quando a busca funciona mas não encontra material suficiente, a ferramenta devolve a frase canônica “Nenhuma informação relevante encontrada na base de conhecimento.” Isso é diferente de uma falha técnica, que retorna uma mensagem de erro de busca.

Se AutoLearn estiver ativo, o agente recebe também a ferramenta de registro de lacunas e deve usá-la quando a busca devolver exatamente o estado sem resultado. As perguntas ficam em Bases de Conhecimento → Oportunidades de Aprendizado para revisão; veja Reportar Lacuna.

AutoLearn não transforma a pergunta em conteúdo publicado sozinho. Uma pessoa ainda revisa e aprova o que deve alimentar a base.

Limites e diagnóstico

• Não aparece em Ferramentas: comportamento esperado. Gerencie o vínculo em Conhecimento.
• Salvar falha: confirme agents.write e bases.write. A tela do editor é aberta com a primeira capacidade, mas o backend exige as duas.
• A busca não é chamada: confira se há base marcada, se a descrição de cada base delimita seu conteúdo e se a instrução exibida orienta o caso real.
• A busca não acha algo existente: confirme processamento, título, seções e termos do item. Busca híbrida melhora correspondência lexical e semântica, mas não garante recuperação de toda resposta existente.
• Trecho desatualizado: corrija ou remova o item na base. A validação de bases excluídas é fail-open quando a consulta de conferência falha; portanto, não use uma indisponibilidade parcial como prova de remoção imediata do índice.
• Consumo: as bases são consultadas sob demanda. O modelo de texto consome tokens da consulta, dos trechos selecionados e da resposta; a base inteira não entra em todo turno. Blocos de contexto, mostrados na coluna ao lado, têm outro contrato e são carregados em todas as respostas.