Bases de Conhecimento (RAG)

Nível de acesso requerido

Admin, Modelador, Gerente ou Super Admin

O módulo de Bases de Conhecimento permite que os administradores façam upload de documentos da empresa (PDF, Word, Excel, PowerPoint, OpenDocument, RTF, HTML, CSV, TXT e Markdown — e PDF digitalizado, quando a instalação tem OCR) para dar contexto aos Agentes de IA usando a tecnologia Retrieval-Augmented Generation (RAG).

A tela fica em Desenho de processos para o Admin e o Modelador, e em Trabalho para o Gerente — base de conhecimento é conteúdo que alimenta o agente, não configuração de plataforma.

O papel é exigido no servidor

A barreira não é só do menu: os endpoints de bases do tenant exigem Admin, Modelador ou Gerente (ou Super Admin) no próprio servidor, e quem chama a API direto sem esse papel recebe 403 — tanto na leitura da listagem quanto no upload, na exclusão e no vínculo com um processo. A base global continua com a exigência dela: só o Super Admin cria ou altera uma base global.

O mesmo vale para a base por processo, a que a aba RAG do catálogo alimenta em /a/definitions/{chave}/knowledge: subir e apagar documento, apagar a base inteira e mandar reindexar exigem os mesmos papéis, e ler a listagem também. É a mesma capacidade por outro caminho, e por isso o mesmo papel.

Ao anexar um documento a uma Base de Conhecimento, o Flowi Agentic realiza:

1. Extração de Texto: Leitura segura do conteúdo original.
2. Chunking: Divisão do texto em trechos de tamanho fixo, medido em tokens e não em parágrafos — um trecho pode começar no meio de uma frase, e é por isso que a orientação abaixo é escrever blocos que se sustentam sozinhos.
3. Embeddings: Conversão do texto em vetores matemáticos, salvos no banco de dados (pgvector).

Criando uma Base

1. Acesse o menu de Desenho de processos → Bases de Conhecimento (o Gerente encontra o mesmo item em Trabalho → Bases de Conhecimento).
2. Clique em Nova Base.
3. Defina um nome e uma descrição clara para o escopo dessa base.

A base criada aqui pertence ao seu tenant e só ele a enxerga.

Bases globais

Além das suas próprias bases, a listagem mostra as bases globais — fornecidas pela plataforma e lidas por todos os tenants, normalmente acompanhando um template de processo global. Elas aparecem marcadas como Global e são somente leitura para o administrador do tenant: não dá para editá-las nem excluí-las, e o botão de excluir fica desabilitado explicando o motivo.

Quem cria e mantém base global é o administrador da plataforma, no menu Catálogo global → Bases de Conhecimento Globais. A separação é proposital: cada papel configura apenas o escopo que ele responde por, e a tela do tenant não oferece a opção de marcar uma base como global.

Tudo que é global é visível a todos

Todos os tenants leem uma base global. Conteúdo que um cliente não pode ver não pertence ao escopo global — carregue-o na base do tenant.

Como escrever para a busca vetorial

A busca não lê o documento inteiro: ela recorta o texto em trechos e envia ao agente apenas os trechos mais parecidos com a instrução daquela etapa — 3 por padrão, de 1 a 20 conforme o agente ou a etapa (veja Busca híbrida, abaixo). Todo o resto do documento fica de fora. Escrever pensando nesse recorte é o que separa uma base que ajuda de uma que atrapalha.

Escreva trechos que se sustentam sozinhos. Uma regra dividida em cinco seções de um manual não chega inteira — chegam no máximo três pedaços dela, possivelmente sem o começo. Prefira um bloco curto que enuncie a regra completa, com o contexto necessário dentro dele, a uma exposição longa que só faz sentido lida do início.

Base pequena e focada vence base completa. Sem piso configurado, os trechos mais próximos são enviados sempre, mesmo quando nenhum deles é bom — o agente pode definir uma similaridade mínima, mas ela só corta, não melhora o que a base tem. Uma base que mistura assuntos não fica neutra — ela ocupa o espaço com material irrelevante e empurra para fora o que importava. Prefira várias bases enxutas, vinculadas cada uma ao processo em que fazem sentido, a uma base única com tudo.

Fale a língua da instrução do agente. Quem faz a busca é a instrução configurada na etapa, não uma pergunta do usuário. Se a instrução diz "prazo de entrega" e o documento diz "lead time", a proximidade cai e o trecho certo pode não entrar. Vale revisar os dois lados juntos e usar os mesmos termos.

Prefira o texto ao escaneado. O OCR recupera o texto de um PDF digitalizado, mas não a estrutura: títulos e tabelas viram texto corrido. Um arquivo com texto de verdade sempre se localiza melhor — e numa instalação sem OCR o digitalizado fica como Precisa de OCR (veja abaixo).

Na prática

O mesmo conteúdo, escrito das duas formas:

<!-- ❌ o trecho não se sustenta: depende do que veio antes -->
Conforme descrito na seção anterior, o limite mencionado se aplica
integralmente. Nos demais casos, observa-se o disposto no parágrafo
precedente, ressalvadas as exceções já apontadas.

Se esse pedaço for um dos escolhidos, o agente recebe "o limite mencionado" sem saber qual é o limite, qual seção, nem quais exceções.

<!-- ✅ o trecho responde sozinho -->
## Limite de aprovação — reembolso de viagem

Despesas de viagem até R$ 2.000 são aprovadas pelo gestor direto.
Acima de R$ 2.000 exigem aprovação do diretor da área.

Vale para todos os centros de custo, a partir de 01/2026.
Exceção: viagens internacionais sempre exigem aprovação do diretor,
independentemente do valor.

Título que nomeia o assunto, regra completa, faixa de valores explícita, vigência e exceção — tudo dentro do mesmo bloco. Se esse for o único trecho recuperado, ainda assim o agente decide certo.

O que NÃO deve ir para a Base de Conhecimento

Tabelas de códigos e identificadores — catálogo de produtos, centros de custo, códigos de município, tabela de cargos, tabela de preços. Elas parecem documentos, mas não funcionam por similaridade: códigos vizinhos têm descrições quase idênticas e milhares de linhas repetem termos genéricos como "Outros". Perguntar por um código específico devolve, com toda a confiança, uma linha sem relação.

Esse tipo de dado vai para o CMS, onde a consulta é exata. A regra prática é: identificador exato → CMS; texto que se interpreta → Base de Conhecimento.

Busca híbrida: palavra-chave + vetorial

A busca vetorial acha trechos de significado parecido, e erra justamente no que se digita quando a precisão importa: um código NCM (8471.30.12), art. 37-A, um SKU, um número de cláusula. Para isso existe o modo híbrido: além da busca por significado, a plataforma procura as palavras e códigos da pergunta literalmente e junta as duas listas (Reciprocal Rank Fusion — conta a posição de cada trecho em cada lista, não a nota).

• O modo é escolhido no agente (Busca na base de conhecimento: Vetorial ou Híbrida, trechos por busca e similaridade mínima) e pode ser sobreposto na etapa — veja Agentes.
• Um agente existente continua no modo que tinha (Vetorial, 3 trechos, sem piso, se ninguém mudou). Um agente criado a partir de agora nasce Híbrido, 3 trechos, sem piso. Para decidir o modo de um agente antigo, meça a base com Perguntas de referência (abaixo).
• A busca por palavra-chave não chama modelo nenhum: não gasta token. E cada busca agora embute a pergunta uma vez só para a base do tenant e a global juntas.
• A palavra-chave vale mais na ferramenta de busca do agente, onde o modelo digita o código como ele aparece no documento. Na busca automática, a pergunta é a instrução da etapa inteira.

Idioma da busca por palavra-chave

Na aba Busca da base você escolhe como as palavras são comparadas:

Idioma	O que faz
Simples — sem radical (padrão)	Códigos e números ficam intactos; plural e singular contam como palavras diferentes
Português, Inglês, Espanhol	Reduz as palavras ao radical daquele idioma (autorização ↔ autorizações); códigos continuam intactos

Trocar o idioma recalcula só o índice de palavras desta base, em segundo plano — nenhum documento é reprocessado e nenhum token é gasto. Enquanto recalcula a aba mostra o aviso e a busca continua funcionando. A aba também mostra Trechos recuperáveis e Trechos no índice de palavras: se o segundo estiver em zero com o primeiro cheio, a busca híbrida desta base está usando só o lado vetorial.

A comparação não ignora acentos: "licitacao" não acha "licitação" pela palavra-chave (a busca por significado continua achando).

Medindo a busca: perguntas de referência

A aba Perguntas de referência da base diz, com número, se a busca traz o documento certo — antes que um agente responda errado por nunca ter visto o trecho que precisava.

1. Escreva as perguntas como uma pessoa ou um agente faria, e diga onde está a resposta: de 1 a 5 documentos da base, escolhidos pela lista de documentos (com busca por nome). Página e um trecho que deve aparecer são opcionais e deixam o acerto mais estrito. Até 100 perguntas por base.
2. Avaliar busca abre a escolha das configurações — Atual (vetorial, 3), Híbrida 3, Vetorial 5, Híbrida 5 ou uma sua (modo, trechos, piso), até 6 de uma vez. Estimar mostra quantas perguntas rodam, os tokens aproximados e a cota que resta; só Confirmar e rodar começa. Mudou a escolha, estime de novo.
3. Cada pergunta é embutida uma vez e pontuada em todas as configurações, pela mesma busca que o agente usa. Nenhum modelo responde: só a busca é medida. 50 perguntas custam por volta de 1 a 2 mil tokens, contados na cota de IA como RETRIEVAL_EVALUATION.

Como ler o resultado — uma coluna por configuração:

Métrica	O que diz
hit@k	em que parte das perguntas pelo menos um documento esperado apareceu entre os k trechos
recall@k	quantos dos documentos esperados apareceram (difere do hit@k só em perguntas com mais de um alvo)
MRR	quão alto veio o primeiro acerto: 1 é sempre em primeiro, 0,5 em média em segundo, 0 nunca apareceu

Ao lado de cada número aparece a diferença para a rodada anterior com a mesma configuração — é assim que uma troca de idioma, um documento novo ou o modo híbrido aparece como melhor ou pior. A grade abaixo mostra, por pergunta, a posição do primeiro acerto em cada configuração; um clique abre a lista do que veio (arquivo, página, posição vetorial e por palavra) e o texto do trecho.

• Quem roda vê só o que alcança. A avaliação busca com o seu nível de acesso: um documento acima dele nunca entra no ranking, e uma pergunta cujos documentos esperados estão todos acima do seu nível fica Fora do seu nível — não é contada como erro da busca. Quem olha um resultado com nível menor vê a posição dos trechos restritos, não o nome.
• Resultado desatualizado. Quando os trechos da base ou o modelo de embedding mudam depois da última rodada, a aba avisa e oferece Rodar de novo. Nada roda sozinho.
• Uma avaliação por vez em cada base (iniciar outra enquanto uma está na fila ou rodando é recusado), uma rodando por vez em cada tenant, e uma pausa curta entre as perguntas: a avaliação não disputa o limite do provedor de embedding com a busca dos agentes. Uma falha aparece com a explicação traduzida; o detalhe técnico fica no log do servidor.
• A base guarda as 20 rodadas mais recentes. Base global: só o administrador da plataforma escreve perguntas e roda avaliações; o tenant vê os resultados.

Formatos aceitos e como cada um é cortado

O tipo do arquivo é reconhecido pelo conteúdo, não pela extensão nem pelo que o navegador declara: um executável renomeado para .docx é recusado, e a mensagem diz o tipo detectado. A área de upload mostra a lista que esta instalação aceita e o tamanho máximo (50 MB por padrão).

Família	Formatos	Como vira trecho	Como o trecho se localiza
PDF	.pdf	uma unidade por página	página
Texto de escritório	.docx, .doc, .odt, .rtf	uma unidade por seção, cortada nos títulos (Título 1 a 3)	caminho dos títulos
Planilha	.xlsx, .xls, .ods, .csv	blocos de linhas que repetem o cabeçalho, sem nunca partir uma linha	planilha e faixa de linhas
Apresentação	.pptx, .ppt, .odp	um slide por unidade, com título, corpo e as notas do apresentador	número e título do slide
Web e texto	.html, .md, .txt	HTML e Markdown por seção; TXT inteiro	seção, quando houver
Imagem	.png, .jpg, .tiff	só com OCR ligado	página (quadro do TIFF)

Todo trecho chega ao agente começando pelo nome do arquivo e pelo localizador — por exemplo Tabela de diárias.xlsx › Planilha: 2026 · linhas 2–41 — para que um pedaço cortado no meio ainda diga de onde veio.

Antes do texto, cada trecho ganha uma linha de referência com um rótulo — por exemplo [F2] Tabela de diárias.xlsx · v1 · planilha "2026", linhas 2–41 · base Normas — e o agente é instruído a citar o documento e o local (ou o rótulo) quando usa o trecho. A referência não carrega nenhum identificador interno. O que cada etapa recebeu fica registrado na instância e aparece em Fontes no histórico de atividades (veja Instâncias), com a versão do documento que respondeu. Nada disso faz chamada nova ao modelo.

O trecho guardado na instância (até 300 caracteres) e o nome do arquivo ficam enquanto o documento puder ser restaurado. Quando o documento apagado é expurgado — depois da janela de órfãos, junto com os vetores dele —, esse trecho, o nome e o local são apagados também: a fonte passa a aparecer como Fonte removida, só com o rótulo. Apagar o documento, por si só, não apaga o trecho guardado.

Word cita a seção, não a página

Um .docx não tem número de página: a paginação é um efeito da impressão, não do arquivo. Por isso um documento do Word se localiza pelo título da seção. Use títulos de verdade (estilos Título 1, 2 e 3), e não apenas texto em negrito: sem eles o documento inteiro vira uma seção só.

Fórmulas entram pelo valor calculado que estava salvo, linhas vazias são ignoradas e planilhas ocultas são lidas — a tela avisa que leu uma planilha oculta. Uma planilha com mais de 5.000 linhas recebe um aviso: ela provavelmente é uma tabela de códigos, e consulta exata pertence a uma coleção do CMS (veja o aviso abaixo).

PDF digitalizado e OCR

Uma página com menos de 20 caracteres de texto é tratada como página sem camada de texto. O que acontece depende de a instalação ter OCR:

• Com OCR — a página é renderizada e lida pelo Tesseract dentro da própria instalação: o documento não sai para nenhum serviço externo e não há consumo de tokens. Até 200 páginas por documento passam por OCR; o restante fica de fora e a versão aparece como Parcial.
• Sem OCR, nenhuma página com texto — a versão fica como Precisa de OCR, sem nenhum trecho e sem nenhum embedding cobrado.
• Sem OCR, parte das páginas com texto — as páginas com texto entram, a versão fica como Parcial e a tela lista as páginas puladas.

Depois que o OCR for ligado, o botão Reingerir processa de novo a versão que precisava dele. A área de upload diz se esta instalação tem OCR.

Limites

Arquivo acima de 50 MB, PDF ou apresentação com mais de 2.000 páginas/slides, planilhas somando mais de 200.000 linhas, mais de 5 milhões de caracteres extraídos ou extração que passa de 15 minutos são recusados antes de qualquer embedding — nada é cobrado de um documento que não cabe. Arquivo protegido por senha também é recusado, com o motivo na tela.

O status de cada documento

A lista mostra, para cada documento, o status da versão mais recente, o que a extração leu (por exemplo, 12 de 14 páginas lidas · 2 por OCR), as páginas puladas, o autor do envio e a versão atual. Enquanto houver documento em andamento, a lista se atualiza sozinha a cada poucos segundos.

Status	O que significa
Na fila, Extraindo, Indexando	a ingestão está em andamento
Pronto	todo o conteúdo está buscável
Parcial	buscável, mas algumas páginas ficaram de fora (listadas na tela)
Precisa de OCR	PDF digitalizado numa instalação sem OCR; nada foi indexado
Falhou	o motivo aparece na linha: protegido por senha, acima dos limites, sem texto legível, erro no modelo de embedding…
Sem alteração	o arquivo enviado tem o mesmo texto da versão atual
Substituída	uma versão antiga, guardada no histórico

Uma ingestão interrompida por reinício do servidor volta sozinha para a fila; depois de três tentativas sem terminar, a versão fica como Falhou com o motivo interrompida.

Versões: reenviar o mesmo documento

Enviar de novo um arquivo com o mesmo nome na mesma base não duplica nada:

• mesmo arquivo, byte a byte — a tela responde já está na base, sem alteração, e nada é guardado nem cobrado;
• arquivo diferente, mesmo texto (um DOCX salvo de novo, por exemplo) — a versão é registrada como Sem alteração e o arquivo é descartado;
• texto novo — vira a próxima versão (v2, v3…). Enquanto ela é processada, a versão anterior continua respondendo; a troca acontece de uma vez quando a nova fica pronta, e se ela falhar a anterior segue em uso. A busca nunca vê as duas ao mesmo tempo.

O mesmo conteúdo com outro nome na mesma base é recusado, com o nome do documento que já o tem: os dois disputariam os mesmos três lugares da busca. Em bases diferentes, pode.

O botão de versões de cada documento abre o histórico: status, números da extração, autor, tokens de embedding gastos e de qual versão cada uma foi restaurada.

Restaurando uma versão antiga

Restaurar cria uma nova versão com o conteúdo de uma versão substituída — o histórico só cresce. Dentro da janela de retenção de órfãos (30 dias por padrão), os vetores da versão antiga ainda estão guardados e a restauração é imediata e não consome tokens. Depois da janela, o arquivo é reprocessado e o embedding é cobrado de novo; a tela avisa antes de confirmar e mostra quantos tokens a versão gastou da última vez.

A restauração vira a versão mais recente: um envio anterior ainda em processamento, ao terminar, fica como Substituída em vez de tomar o lugar da versão restaurada.

Quem pode ler cada documento

Cada documento da base tem um nível: Público (o padrão), Secreto ou Ultrassecreto — os mesmos níveis das coleções do CMS. Uma busca só devolve trechos de documentos até o nível de quem busca:

Quem busca	Nível usado
Etapa de IA de um processo ou caso	o acesso à base de conhecimento do agente (padrão Público)
Copiloto de execução	o nível do usuário logado (Usuário e Modelador → Público, Gerente → Secreto, Administrador → Ultrassecreto)
Playground do agente	o menor entre o seu nível e o do agente
Qualquer outro caminho (MCP, por exemplo)	Público

O filtro roda dentro da própria consulta ao banco: um trecho negado nunca chega ao servidor da aplicação, e muito menos ao modelo. Reclassificar vale na próxima busca, sem reprocessar o documento nem gastar tokens.

Quando um trecho classificado acima do nível teria entrado entre os resultados, a ferramenta de busca diz ao agente que houve negação — quantos trechos e de que nível, nunca o nome do documento — para que ele informe falta de permissão em vez de concluir que a informação não existe.

Na tela da base:

• A coluna Nível mostra o nível de cada documento; o botão Classificação muda o nível, oferecendo só os níveis que você alcança.
• Nível padrão define o nível com que os próximos documentos nascem. Marque Aplicar também aos documentos que já estão na base para reclassificar tudo de uma vez. Uma nova versão de um documento mantém o nível do documento.
• Você só altera, reenvia, restaura, reingere, baixa ou apaga um documento até o seu próprio nível. Um Modelador cuida apenas de material público; um Gerente chega a Secreto; Ultrassecreto exige Administrador. Um documento acima do seu nível aparece na lista com o aviso Acima do seu nível de acesso, sem ações.
• O Administrador vê Acessos a material restrito: cada busca que devolveu ou negou um trecho classificado, com a origem (etapa, contexto automático, copiloto ou playground), o nível usado e a instância. Buscas só em material público não são registradas. O registro é mantido por 365 dias.

Documentos anexados diretamente a um processo (fora de uma base) continuam públicos. Apagar a base inteira exige alcançar o documento mais restrito dela, e os arquivos de uma base só saem pela tela da base — a API genérica de anexos não os serve.

O nível limita o que chega ao modelo, não o que o modelo escreve. Um agente com acesso Secreto pode resumir um documento Secreto numa variável que um Usuário verá na próxima tarefa. Conceder o nível ao agente significa aceitar isso.

Sincronizando com SharePoint e OneDrive

Em vez de enviar arquivos à mão, uma base pode ter fontes: uma pasta de uma biblioteca do SharePoint ou de um OneDrive for Business, mantida em dia sozinha. Cada arquivo da pasta passa pelo mesmo caminho de um envio manual — tipo detectado pelo conteúdo, limite de 50 MB, OCR ou "Precisa de OCR", versões — e o embedding é contado no consumo de IA como qualquer outro.

Antes de começar (administrador do tenant):

1. O operador da instalação liga a sincronização (app.knowledge.sources.providers=microsoft, veja Implantação). Sem isso, a aba Fontes avisa que o recurso está desligado.
2. No Entra ID do seu diretório, registre um app com permissão de aplicativo Sites.Selected e peça ao administrador do Microsoft 365 para liberar só os sites que o Flowi deve ler. Files.Read.All também funciona, mas lê todos os drives do diretório.
3. Guarde o segredo do app numa variável secreta em Variáveis e segredos (o valor, ou uma referência vault://). A tela de conexão não tem campo de segredo: ela só deixa escolher a variável.
4. Em Integrações e automação › Conexões de conhecimento, crie a conexão (diretório, client ID, nuvem, variável) e clique em Testar conexão. O teste diz qual host falhou: "esta instalação não alcança login.microsoftonline.com" é assunto de firewall ou proxy.

Adicionando a fonte (aba Fontes da base): escolha a conexão, navegue até a pasta — com Sites.Selected a lista de sites não aparece, então informe o endereço do site ou o e-mail do dono do OneDrive —, decida se as subpastas entram, o nível dos documentos e o intervalo (60 min por padrão, mínimo 15). Antes da primeira sincronização a tela mostra quantos arquivos e quantos MB há na pasta e um teto de tokens de embedding; uma biblioteca grande leva horas e é processada em rodadas de 500 arquivos.

O que acontece depois:

• Arquivo novo ou alterado entra como documento ou nova versão; arquivo idêntico não custa nada. Renomear ou mover dentro da pasta só muda o nome, sem novo embedding.
• Arquivo apagado ou movido para fora sai da base na hora. Se uma rodada fosse apagar mais de 30 % dos documentos da fonte (e pelo menos 20), ela pausa sem apagar nada e avisa quem cura a base: Confirmar exclusão apaga; Manter documentos guarda os documentos como documentos comuns da base, que deixam de ser sincronizados.
• Documento sincronizado tem o selo Sincronizado de … e não se apaga à mão (voltaria na próxima rodada): apague na origem ou remova a fonte. Remover a fonte pergunta se os documentos ficam.
• As permissões do SharePoint/OneDrive não são copiadas. Quem enxerga os documentos no Flowi é o nível escolhido na fonte. Você pode elevar um documento à mão, e a sincronização não o rebaixa.
• O cartão da fonte mostra o estado (Em dia, Parcial, Credencial recusada, Host inalcançável, Pausada…) com o motivo em texto, a última sincronização completa, a próxima e os arquivos com falha — tipo não aceito, acima do teto, PDF digitalizado sem texto, conteúdo repetido. Quando a fonte entra num estado de falha, ADMIN, MANAGER e MODELER com alcance ao nível dela recebem uma notificação, uma vez.
• Download que falhou é tentado de novo sozinho, com intervalo crescente (5 min, 10 min, 20 min… até um dia), sem precisar mudar o arquivo na origem. Depois de 10 tentativas a falha fica como As novas tentativas se esgotaram até o arquivo mudar ou alguém clicar em Tentar de novo em Detalhes. Arquivo apagado e recolocado com o mesmo conteúdo continua na base.
• Subir o nível padrão da base sobe junto o nível das fontes que estavam abaixo dele.
• A fonte só fica visível e editável para quem alcança o nível dela; criar ou editar uma fonte exige também alcançar o nível padrão da base.
• Credencial recusada ou acesso revogado ao site nunca apagam documentos: a fonte fica em falha até alguém corrigir.

Bases globais não têm fontes nesta versão. Google Drive virá depois.

Bases externas (Elasticsearch / OpenSearch)

Uma base pode ser um índice externo em vez de documentos enviados ao Flowi. Ela não guarda nada aqui: a cada busca da etapa a pergunta vai ao índice na origem — um Elasticsearch 8.x ou um OpenSearch 2.x que a empresa já mantém, muitas vezes dentro da própria rede — e os trechos que voltam são citados como os de um documento ([F2] Política de viagens · página 4 · base Normas).

Criando. Em Nova Base, o Administrador do tenant escolhe Tipo: Índice externo e preenche:

Campo	O que é
Backend, Endereço, Índice	https://host:porta do cluster e o nome do índice (sem curinga nem vírgula)
Modo de consulta	Palavras (BM25) funciona com qualquer índice. Vetor da plataforma só quando o índice foi gerado com o mesmo modelo de embedding desta instalação — Testar conexão confere o tamanho do vetor e recusa se for diferente
Mapeamento de campos	quais campos do índice são conteúdo (obrigatório), título, link, página e id. Sem título vale o nome da base; sem página a citação fica sem página
Filtro estático	um JSON fixo (por exemplo {"term": {"status": "publicado"}}) aplicado em toda consulta. Só são aceitas as cláusulas term, terms (com lista de valores), range, match, match_phrase, exists, prefix, ids, bool e nested, com campo e valor simples — nada de script, wrapper, query_string, regexp ou busca em outro índice. O agente nunca escreve no filtro: ele só fornece o texto da pergunta
Trechos, tempo limite, caracteres	quantos trechos pedir (1–20), quanto esperar (padrão 3 s) e onde cortar cada trecho
Quando a base não responder	Seguir (o agente é avisado de que a fonte não respondeu) ou Falhar a etapa — a etapa falha antes de chamar o modelo, o job tenta de novo e, esgotado, aparece no monitor
Autenticação	chave de API, usuário e senha ou nenhuma. A credencial é uma variável secreta do tenant (ou uma referência de cofre) escolhida pelo nome — nenhum campo aceita o valor

Gerente e Modelador veem a base, a vinculam a processos e usam Testar consulta; só o Administrador muda o destino e a credencial.

Destinos permitidos. Na mesma tela o Administrador mantém a lista de hosts que as bases externas do tenant podem consultar (*.empresa.com cobre um nível de subdomínio). Sem lista, vale a política da instalação — por padrão, nenhuma base externa é consultada até haver lista. Um endereço de rede interna (10.x, 192.168.x…) só é alcançado quando o operador da instalação lista o host — uma tela de tenant nunca abre a rede interna. É exigido https; redirecionamentos não são seguidos.

Testar consulta. A aba mostra os trechos exatamente como o agente os receberia, no seu nível de acesso, com o resultado e o tempo da consulta.

Acesso. A base externa tem um nível só, o da base (Classificação da base). Quem busca abaixo dele nem consulta o índice — a pergunta não sai da plataforma — e o agente recebe o aviso de que falta acesso. O controle de acesso do próprio índice por usuário não é usado.

Quando a fonte falha. Indisponível não é vazio: se o índice não responde, o tempo esgota, a credencial é recusada ou o destino não é permitido, o agente recebe uma linha dizendo qual fonte faltou, a etapa registra a fonte em Fontes no histórico da instância, e as outras fontes seguem respondendo. Depois de 5 falhas seguidas em 60 s a base fica 30 s sem ser chamada neste servidor.

O que chega ao modelo. Os trechos locais e os externos são misturados pela posição em que cada fonte os devolveu, não pela pontuação — a nota de um índice BM25 não se compara à similaridade vetorial. O total continua sendo o topK da etapa.

Custo. A consulta ao índice não gasta token: ela é contada, não precificada, em Governança de IA → Consultas a bases externas. No modo vetorial, o vetor da pergunta é o mesmo da busca local — nenhuma chamada de embedding a mais.

Nesta versão: Elasticsearch e OpenSearch. Azure AI Search, um contrato HTTP para um RAG interno, Bedrock e Vertex vêm depois.

Vinculando a Processos

Após popular a base de conhecimento com os documentos corporativos, você a vincula a uma definição de processo, não a um agente. O agente alcança a base porque roda dentro daquele processo — se a mesma base serve a mais de um processo, cada um precisa do seu próprio vínculo. Quando o agente for acionado, a IA pesquisa automaticamente nas bases vinculadas antes de responder, garantindo que as respostas sejam embasadas nas diretrizes da sua empresa e reduzindo o risco de alucinações.

O vínculo do processo define o conjunto ao alcance; dentro dele, cada etapa do fluxo pode reduzir as bases que consulta, ou declarar que não consulta nenhuma — veja Bases desta etapa.

Apagando uma base

Apagar uma base remove o cadastro imediatamente, mas os vetores gerados a partir dos documentos dela não somem no mesmo instante: ficam marcados como órfãos e são removidos por uma limpeza diária depois de uma janela de retenção — 30 dias por padrão, configurável em RAG_ORPHAN_VECTOR_RETENTION_DAYS.

Isso é proposital. Reconstruir um índice grande custa horas de processamento e o valor cobrado pelos embeddings, então a janela existe para dar tempo de recuperar uma base apagada por engano. Nesse intervalo os vetores não aparecem em nenhuma busca — a pesquisa só considera bases que estão vinculadas a algum processo, e uma base apagada não está vinculada a nada.

Apagar um documento segue a mesma regra: ele some da lista e da busca na hora, todas as suas versões saem junto, e os vetores ficam marcados como órfãos pela mesma janela antes da limpeza.

Uma base ainda vinculada a algum processo não é apagada: a plataforma recusa a exclusão e responde listando os processos que ainda a usam. Desvincule cada um deles e repita a exclusão.

Recarregando uma base inteira

Para trocar todo o conteúdo de uma base, crie uma base nova, carregue nela, vincule ao processo e só então desvincule a antiga. Reenviar um arquivo com o mesmo nome cria uma nova versão e tira a antiga da busca (veja Versões); um arquivo com nome novo, porém, é um documento a mais, e o antigo continua respondendo até ser apagado.