itellicoAI Documentation

Visão Geral

O itellicoAI suporta três tipos de itens de conhecimento, cada um projetado para diferentes fontes de conteúdo e casos de uso. Entender como cada tipo funciona e como são processados ajudará você a escolher o formato certo para suas informações.

Visão Geral dos Tipos de Conteúdo

Itens de Texto

Entrada direta de conteúdo usando o editor integrado

Upload de Arquivos

Faça upload de PDF, DOC, DOCX, TXT e outros formatos de documentos até 10MB

Scraping de URL

Extraia conteúdo de páginas web

Itens de Texto

O que são Itens de Texto?

Itens de texto são conteúdo que você insere diretamente no editor da base de conhecimento do itellicoAI. Eles são o tipo de conteúdo mais direto e confiável.

Quando Usar Itens de Texto

Escrevendo FAQs

Crie pares de perguntas e respostas diretamente no sistema.Exemplo:

Título: Como redefinir minha senha?

Conteúdo:
Para redefinir sua senha:

1. Vá para a página de login
2. Clique em "Esqueci minha senha"
3. Digite seu endereço de e-mail
4. Verifique seu e-mail para um link de redefinição
5. Clique no link e crie uma nova senha

Requisitos de senha:
- Mínimo de 8 caracteres
- Pelo menos uma letra maiúscula
- Pelo menos um número
- Pelo menos um caractere especial

Se você não receber o e-mail em 5 minutos, verifique sua pasta
de spam ou entre em contato com suporte@empresa.com.

Criando resumos de políticas

Escreva declarações de política claras e concisas.Exemplo:

Título: Política de Devolução - Produtos Digitais

Conteúdo:
Produtos digitais podem ser reembolsados dentro de 30 dias da compra se:

Elegível para reembolso:
- Produto tem um defeito técnico que impede o uso
- Descrição do produto foi materialmente imprecisa
- Cliente não acessou ou baixou o produto

Não elegível para reembolso:
- Mudança de ideia após acessar o produto
- Problemas de compatibilidade divulgados na descrição do produto
- Erro do usuário ou mal-entendido dos recursos

Para solicitar um reembolso:
Envie e-mail para suporte@empresa.com com seu número de pedido e motivo
da solicitação de reembolso.

Tempo de processamento: 5-7 dias úteis
Método de reembolso: Método de pagamento original

Documentando procedimentos

Instruções passo a passo para processos.Exemplo:

Título: Processo de Modificação de Pedido

Conteúdo:
Clientes podem modificar pedidos dentro de 24 horas após a realização.

O que pode ser modificado:
- Endereço de entrega
- Velocidade de entrega
- Quantidades de itens (se houver estoque disponível)

O que não pode ser modificado:
- Método de pagamento (deve cancelar e fazer novo pedido)
- Itens após início do processamento
- Pedidos feitos há mais de 24 horas

Processo de modificação:
1. Cliente entra em contato com o suporte via telefone ou e-mail
2. Agente verifica se o pedido está dentro da janela de modificação
3. Agente verifica estoque para as alterações solicitadas
4. Agente atualiza pedido no sistema
5. Cliente recebe e-mail de confirmação

Se o pedido já foi enviado, o cliente deve usar o processo de devolução.

Informações de referência rápida

Informações breves e frequentemente referenciadas.Exemplo:

Título: Horário Comercial e Informações de Contato

Conteúdo:
Suporte ao Cliente:
- Telefone: 0800-555-0123
- E-mail: suporte@empresa.com
- Horário: Segunda a Sexta, 9h - 18h BRT
- Após expediente: emergencia@empresa.com (apenas problemas urgentes)

Vendas:
- Telefone: 0800-555-0124
- E-mail: vendas@empresa.com
- Horário: Segunda a Sexta, 8h - 20h BRT

Faturamento:
- Telefone: 0800-555-0125
- E-mail: faturamento@empresa.com
- Horário: Segunda a Sexta, 9h - 17h BRT

Criando Itens de Texto

Navegue até a pasta

Abra a pasta onde você deseja adicionar o item.

Clique em 'Adicionar Item de Conhecimento'

Clique no botão para criar um novo item.

Selecione categoria 'TEXT'

Escolha TEXT das opções de tipo de conteúdo.

Digite o título

Dê ao seu item um título claro e descritivo.

Escreva o conteúdo

Digite seu conteúdo no editor. Use formatação para clareza:

Títulos para seções
Marcadores para listas
Números para passos
Negrito para ênfase

Clique em 'Criar'

Salve seu item de texto. O status mostrará imediatamente como COMPLETED.

Exemplo JSON de Item de Texto

{
  "category": "TEXT",
  "title": "Informações de Preços do Produto",
  "content": "Nossos níveis de preço incluem Básico (R$ 29/mês), Pro (R$ 99/mês) e Empresarial (preço personalizado).",
  "status": "COMPLETED"
}

Vantagens dos Itens de Texto

Processamento Instantâneo

Itens de texto estão imediatamente disponíveis - sem atraso de processamento

Controle Total

Controle completo sobre formatação e estrutura de conteúdo

Atualizações Fáceis

Rápido para editar e atualizar quando as informações mudarem

Confiável

Sem erros de processamento ou problemas de extração

Itens de texto são o tipo de conteúdo mais confiável. Quando possível, insira o conteúdo como texto em vez de fazer upload de arquivos.

Itens de Upload de Arquivo

O que são Itens de Upload de Arquivo?

Itens de upload de arquivo permitem que você faça upload de documentos existentes em vários formatos. O sistema extrai o conteúdo de texto e o disponibiliza para seus agentes.

Quando Usar Upload de Arquivos

Documentação existente

Você já tem conteúdo em formato de documento.Exemplos:

Manuais do usuário
Especificações de produto
Documentos legais
Materiais de treinamento

Documentos formatados

Documentos com layouts específicos que são mais fáceis de manter como arquivos.Exemplos:

Diagramas técnicos
Tabelas e gráficos
Layouts de múltiplas colunas
Modelos de marca

Documentos de terceiros

Documentação que você recebe de fornecedores ou parceiros.Exemplos:

Catálogos de fornecedores
Documentos de conformidade
Materiais de certificação

Requisitos de Arquivo

Especificações de arquivo:

Formatos: PDF, DOC, DOCX, TXT e outros formatos de documentos
Limite de tamanho: Máximo de 10MB
Conteúdo: Documentos baseados em texto e imagens digitalizadas (análise avançada lida com a maioria das digitalizações)
Proteção: Sem proteção por senha

O sistema usa análise avançada de documentos para extrair texto de imagens digitalizadas e PDFs. A maioria dos documentos digitalizados será processada corretamente, embora digitalizações de qualidade muito baixa possam exigir entrada manual de texto.

Criando Itens de Arquivo

Navegue até a pasta

Abra a pasta onde você deseja adicionar o arquivo.

Clique em 'Adicionar Item de Conhecimento'

Clique no botão para criar um novo item.

Selecione categoria 'FILE'

Escolha FILE das opções de tipo de conteúdo.

Digite o título

Dê ao seu arquivo um título descritivo (isso é separado do nome do arquivo).

Faça upload do arquivo

Clique em Upload e selecione seu documento do seu computador.

Clique em 'Criar'

O sistema fará upload e começará a processar seu arquivo.Progressão do status:

PENDING → Arquivo carregado, na fila para processamento
PROCESSING → Extraindo conteúdo de texto
COMPLETED → Pronto para uso
FAILED → Ocorreu erro de processamento

Exemplo JSON de Item de Arquivo

{
  "category": "FILE",
  "title": "Manual do Usuário - Produto X",
  "file": "/uploads/knowledge/manual-usuario-produto-x.pdf",
  "status": "COMPLETED"
}

Tempo de Processamento

O tempo de processamento de arquivo varia com base em:

Tamanho do arquivo: Arquivos maiores demoram mais
Contagem de páginas: Mais páginas = processamento mais longo
Complexidade: Tabelas, imagens e layouts complexos retardam o processamento
Qualidade do texto: Texto limpo e simples extrai mais rápido

Tempos típicos de processamento:

Arquivos pequenos (< 1MB, 10 páginas): 10-30 segundos
Arquivos médios (1-5MB, 10-50 páginas): 30-90 segundos
Arquivos grandes (5-10MB, 50+ páginas): 2-5 minutos

Problemas Comuns com Arquivos

Processamento falhou

Causas:

Arquivo excede 10MB
Arquivo está protegido por senha
Arquivo está corrompido
Imagens digitalizadas de qualidade muito baixa

Soluções:

Comprima o arquivo ou divida em arquivos menores
Remova a proteção por senha
Reexporte o arquivo da fonte
Para digitalizações de qualidade muito baixa, copie o conteúdo em um item de texto

Conteúdo extraído incorretamente

Causas:

Layouts complexos (múltiplas colunas, tabelas)
Imagens digitalizadas de qualidade muito baixa
Fontes ou codificação especiais
Campos de formulário e elementos interativos

Soluções:

Verifique o conteúdo extraído no modo de edição
Recrie como item de texto com formatação adequada
Simplifique o layout do documento antes do upload
Exporte como documento de texto simples

Processamento demora muito

O que fazer:

Aguarde 5-10 minutos antes de assumir falha
Verifique tamanho do arquivo e contagem de páginas
Para arquivos grandes, considere dividir em vários arquivos
Converta para texto e faça upload como itens TEXT

Melhores Práticas de Upload de Arquivo

Otimize antes do upload

Comprima arquivos grandes
Remova imagens desnecessárias
Use documentos baseados em texto
Mantenha abaixo de 5MB quando possível

Teste a extração

Revise o conteúdo extraído após processamento
Verifique problemas de formatação
Verifique se informações críticas estão precisas
Faça novo upload se a extração for ruim

Itens de URL

O que são Itens de URL?

Itens de URL fazem scraping de conteúdo de páginas web e os armazenam na sua base de conhecimento. Isso é útil para referenciar documentação online, centrais de ajuda ou postagens de blog.

Quando Usar Itens de URL

Documentação pública

Referencie documentação externa que você não mantém.Exemplos:

Documentação de API (sua ou de terceiros)
Bases de conhecimento públicas
Artigos da central de ajuda
Páginas de produtos

Conteúdo frequentemente atualizado

Conteúdo que muda regularmente e você quer manter atualizado fazendo novo scraping.Exemplos:

Páginas de preços
Disponibilidade de produtos
Promoções atuais
Páginas de status

Postagens de blog ou artigos

Conteúdo educacional ou anúncios.Exemplos:

Guias de instruções
Artigos de melhores práticas
Anúncios de produtos
Tutoriais de recursos

Criando Itens de URL

Navegue até a pasta

Abra a pasta onde você deseja adicionar a URL.

Clique em 'Adicionar Item de Conhecimento'

Clique no botão para criar um novo item.

Selecione categoria 'URL'

Escolha URL das opções de tipo de conteúdo.

Digite o título

Dê ao conteúdo um título descritivo.

Digite a URL fonte

Cole a URL completa incluindo https://Exemplo:

https://docs.empresa.com/api/autenticacao

Clique em 'Criar'

O sistema buscará e processará a página web.Progressão do status:

PENDING → URL na fila para scraping
PROCESSING → Buscando e extraindo conteúdo
COMPLETED → Conteúdo disponível
FAILED → Ocorreu erro de scraping

Exemplo JSON de Item de URL

{
  "category": "URL",
  "title": "Documentação de Autenticação da API",
  "source_url": "https://docs.empresa.com/api/autenticacao",
  "status": "COMPLETED"
}

Requisitos de URL

URLs funcionais:

Publicamente acessível (sem login necessário)
Páginas de conteúdo HTML simples
Sites de documentação
Postagens de blog e artigos
Páginas de conteúdo estático

URLs problemáticas:

Páginas que exigem autenticação
Aplicações pesadas em JavaScript (SPAs)
Conteúdo com paywall
Conteúdo carregado dinamicamente
Aplicações interativas

O scraping de URL funciona melhor com páginas web simples baseadas em texto. Aplicações web complexas podem não fazer scraping com sucesso.

Problemas Comuns com URL

Scraping falhou

Causas:

Página requer login/autenticação
URL está incorreta ou quebrada
Conteúdo carrega via JavaScript
Site bloqueia scraping (robots.txt)
Página não existe (404)

Soluções:

Verifique se a URL está publicamente acessível
Teste a URL em janela anônima do navegador
Verifique se a URL está completa e correta
Copie o conteúdo manualmente em um item de texto
Use exportação em PDF da página

Conteúdo incompleto ou errado

Causas:

Conteúdo renderizado por JavaScript não capturado
Carregamento de conteúdo dinâmico
Múltiplas abas/seções na página
Comentários ou barra lateral em scraping em vez do conteúdo principal

Soluções:

Inspecione o conteúdo em scraping no modo de edição
Use URL direta para conteúdo específico
Copie o conteúdo desejado em um item de texto
Exporte a página como PDF e faça upload

Conteúdo fica desatualizado

Solução: O conteúdo da URL é extraído uma vez no momento da criação. Para atualizar:

Exclua e recrie o item de URL
Ou copie o conteúdo atual em um item de texto para atualizações manuais

Para conteúdo que muda com frequência, considere:

Itens de texto manuais que você atualiza regularmente
Exportações em PDF que você atualiza periodicamente

Melhores Práticas de URL

Teste acessibilidade

Abra a URL em janela anônima
Verifique se não há login necessário
Verifique se o conteúdo está visível
Garanta que a página carregue rapidamente

Revise conteúdo em scraping

Verifique o conteúdo após scraping
Verifique se o conteúdo correto foi capturado
Procure problemas de formatação
Confirme que não há conteúdo extra (anúncios, barras laterais)

Fluxo de Status de Processamento

Os itens de conhecimento passam por dois pipelines de processamento separados:

Processamento de Conteúdo - Extraindo texto de arquivos/URLs
Indexação Vetorial - Preparando conteúdo para RAG (busca semântica)

Status de Processamento de Conteúdo

Isso rastreia a extração de conteúdo de texto da sua fonte.

PENDING

Significado: Item criado, na fila para extração de conteúdoO que está acontecendo:

Item foi salvo no banco de dados
Aguardando worker de processamento
Geralmente muito breve (segundos)

Ação necessária: Nenhuma - aguarde o início do processamento

PROCESSING

Significado: O conteúdo do item está sendo extraído agoraO que está acontecendo:

Para ARQUIVOS: Extraindo texto de PDF, Word, etc.
Para URLs: Buscando e fazendo scraping da página web específica
Para TEXTO: N/A (pula diretamente para COMPLETED)

Ação necessária: Aguarde a conclusão do processamento

COMPLETED

Significado: Extração de conteúdo finalizada com sucessoO que está acontecendo:

Conteúdo foi extraído e armazenado
Indexação vetorial começará automaticamente
Item estará disponível quando a indexação for concluída

Ação necessária: Nenhuma - aguarde indexação vetorial

FAILED

Significado: Extração de conteúdo encontrou um erroO que está acontecendo:

Extração de arquivo falhou (PDF corrompido, formato não suportado)
Scraping de URL falhou (página não encontrada, bloqueada, requer autenticação)
Conteúdo não está disponível para agentes

Ação necessária: Verifique mensagem de erro e corrija o problema

Fluxo de Processamento de Conteúdo: CREATED → PENDING → PROCESSING → COMPLETED ou FAILED

Status de Indexação Vetorial

Depois que o conteúdo é extraído, ele deve ser indexado para RAG (busca semântica). Isso permite que os agentes encontrem conhecimento relevante com base no significado, não apenas em palavras-chave.

PENDING

Significado: Aguardando início da indexação vetorialO que está acontecendo:

Processamento de conteúdo concluído com sucesso
Na fila para geração de embeddings
Geralmente breve (segundos a minutos)

Ação necessária: Nenhuma

INDEXING

Significado: Criando embeddings vetoriais para RAGO que está acontecendo:

Conteúdo está sendo dividido em pedaços
Embeddings de IA sendo gerados para cada pedaço
Vetores sendo armazenados na base de conhecimento

Ação necessária: Aguarde - isso pode levar vários minutos para documentos grandes

INDEXED

Significado: Item está totalmente pronto para recuperação RAGO que está acontecendo:

Embeddings vetoriais armazenados com sucesso
Item pode ser recuperado via busca semântica
Agentes agora podem usar esse conhecimento

Ação necessária: Nenhuma - item está totalmente pronto

FAILED

Significado: Indexação vetorial falhouO que está acontecendo:

Geração de embedding encontrou um erro
Item não aparecerá nos resultados RAG
Pode estar disponível apenas para injeção de contexto

Ação necessária: Tente reindexar ou entre em contato com o suporte

REMOVED

Significado: Vetores foram excluídosO que está acontecendo:

Item foi excluído ou explicitamente removido do índice
Não está mais disponível para RAG

Ação necessária: Reindexe se necessário

Fluxo de Indexação Vetorial: PENDING → INDEXING → INDEXED ou FAILED

Ambos os status devem ter sucesso para funcionalidade completa:

Status de Conteúdo: COMPLETED
Status de Vetor: INDEXED

Só então o item pode ser usado tanto em injeção de contexto quanto em recuperação RAG.

Tratamento de Erros

Quando Itens Falham

Se um item de conhecimento mostrar status FAILED:

Verifique a mensagem de erro

Clique no item com falha para ver detalhes do erro.

Identifique a causa

Causas comuns:

Arquivos: Arquivo muito grande, corrompido, protegido por senha, imagem digitalizada
URL: Autenticação necessária, link quebrado, conteúdo não acessível

Tente soluções

Para Arquivos: Comprima, remova proteção, adicione camada de texto ou converta para texto
Para URLs: Verifique acessibilidade, tente URL diferente ou copie conteúdo para item de texto

Recrie ou converta

Exclua item com falha
Crie novo item com correções aplicadas
Ou converta para item de texto copiando conteúdo manualmente

Prevenindo Erros

Prevenção de Arquivo

Mantenha arquivos abaixo de 5MB
Use documentos baseados em texto ou digitalizações de qualidade
Remova senhas
Teste com arquivo pequeno primeiro

Prevenção de URL

Teste URL em modo anônimo
Use páginas HTML simples
Evite conteúdo autenticado
Verifique compatibilidade com robots.txt

Monitorando Processamento

Indicadores do Painel

No painel da sua base de conhecimento, você pode ver o status de processamento rapidamente para cada item em suas pastas: Indicadores de status:

Marca de seleção verde = COMPLETED
Ampulheta = PROCESSING
Símbolo de pausa = PENDING
X vermelho = FAILED

Exemplo de visualização de pasta:

Manual do Usuario.pdf - COMPLETED
Guia de Inicio Rapido.pdf - PROCESSING
Documentacao API - PENDING
Manual Legado.pdf - FAILED

Processamento em Lote

Ao fazer upload de vários itens:

Itens processam sequencialmente ou em paralelo (dependente do sistema)
Verifique depois de 5-10 minutos para lotes grandes
Revise o status de cada item
Corrija quaisquer falhas individualmente

Faça upload de um item de teste primeiro para verificar formato e processamento antes de fazer upload em lote.

Escolhendo o Tipo de Conteúdo Certo

Use esta árvore de decisão para selecionar o melhor tipo de conteúdo: Você tem conteúdo existente?

Não → Use TEXT (escreva diretamente)
Sim, é um documento →
- Menos de 10MB → Use FILE
- Mais de 10MB → Extraia texto, use TEXT
Sim, é uma página web →
- Publicamente acessível → Use URL (se scraping falhar, copie para TEXT)
- Não acessível → Copie conteúdo para TEXT

Recomendações Rápidas

Sua Situação	Melhor Tipo de Conteúdo
Escrevendo FAQs do zero	TEXT
Tem documentos Word/PDF existentes	Upload como FILE
Tem documentos abaixo de 10MB	FILE
Tem documentos acima de 10MB	Divida em arquivos menores ou extraia para TEXT
Documentação web pública	URL (com TEXT como backup)
Conteúdo privado/autenticado	Copie para TEXT
Precisa de disponibilidade imediata	TEXT (sem atraso de processamento)
Formatação complexa importa	FILE

Próximos Passos

Contexto vs RAG

Aprenda como agentes acessam seu conteúdo de conhecimento

Criar Bases de Conhecimento

Guia de criação passo a passo

Visão Geral da Arquitetura

Entenda a estrutura da base de conhecimento

Variáveis e Conteúdo Dinâmico

Referencie conhecimento nas instruções do agente

Get Started

Build

Test

Launch

Optimize

Accounts and Subaccounts

Partner Network

Legal

​Visão Geral

​Visão Geral dos Tipos de Conteúdo

Itens de Texto

Upload de Arquivos

Scraping de URL

​Itens de Texto

​O que são Itens de Texto?

​Quando Usar Itens de Texto

​Criando Itens de Texto

​Exemplo JSON de Item de Texto

​Vantagens dos Itens de Texto

Processamento Instantâneo

Controle Total

Atualizações Fáceis

Confiável

​Itens de Upload de Arquivo

​O que são Itens de Upload de Arquivo?

​Quando Usar Upload de Arquivos

​Requisitos de Arquivo

​Criando Itens de Arquivo

​Exemplo JSON de Item de Arquivo

​Tempo de Processamento

​Problemas Comuns com Arquivos

​Melhores Práticas de Upload de Arquivo

Otimize antes do upload

Teste a extração

​Itens de URL

​O que são Itens de URL?

​Quando Usar Itens de URL

​Criando Itens de URL

​Exemplo JSON de Item de URL

​Requisitos de URL

​Problemas Comuns com URL

​Melhores Práticas de URL

Teste acessibilidade

Revise conteúdo em scraping

​Fluxo de Status de Processamento

​Status de Processamento de Conteúdo

​Status de Indexação Vetorial

​Tratamento de Erros

​Quando Itens Falham

​Prevenindo Erros

Prevenção de Arquivo

Prevenção de URL

​Monitorando Processamento

​Indicadores do Painel

​Processamento em Lote

​Escolhendo o Tipo de Conteúdo Certo

​Recomendações Rápidas

​Próximos Passos

Contexto vs RAG

Criar Bases de Conhecimento

Visão Geral da Arquitetura

Variáveis e Conteúdo Dinâmico

Visão Geral

Visão Geral dos Tipos de Conteúdo

Itens de Texto

O que são Itens de Texto?

Quando Usar Itens de Texto

Criando Itens de Texto

Exemplo JSON de Item de Texto

Vantagens dos Itens de Texto

Itens de Upload de Arquivo

O que são Itens de Upload de Arquivo?

Quando Usar Upload de Arquivos

Requisitos de Arquivo

Criando Itens de Arquivo

Exemplo JSON de Item de Arquivo

Tempo de Processamento

Problemas Comuns com Arquivos

Melhores Práticas de Upload de Arquivo

Itens de URL

O que são Itens de URL?

Quando Usar Itens de URL

Criando Itens de URL

Exemplo JSON de Item de URL

Requisitos de URL

Problemas Comuns com URL

Melhores Práticas de URL

Fluxo de Status de Processamento

Status de Processamento de Conteúdo

Status de Indexação Vetorial

Tratamento de Erros

Quando Itens Falham

Prevenindo Erros

Monitorando Processamento

Indicadores do Painel

Processamento em Lote

Escolhendo o Tipo de Conteúdo Certo

Recomendações Rápidas

Próximos Passos