Guia do cérebro

Por padrão, tudo que o agente sabe vem do prompt. Mas o prompt tem limite — você não consegue jogar um catálogo inteiro de produtos, uma lista com centenas de convênios ou um manual técnico lá dentro sem prejudicar a performance. O Cérebro resolve isso. Ele é um repositório de documentos que o agente consulta sob demanda, buscando só o que for relevante para a pergunta do cliente naquele momento.

Como funciona por baixo dos panos

Você não precisa entender a tecnologia para usar, mas entender o processo ajuda a montar documentos melhores. Veja como funciona na prática:

Quando você sobe um arquivo

Imagine que você tem um livro — pode ser um catálogo de produtos, uma lista de médicos, um FAQ. Ao subir esse arquivo na base, o sistema faz o seguinte:

1. Divide o documento em fichas — o texto é recortado em pedaços de aproximadamente 1000 caracteres cada. Cada pedaço vira uma ficha independente.

2. Grava o "significado" de cada ficha — cada ficha recebe uma impressão digital do seu conteúdo. Não é uma busca por palavras exatas: o sistema entende o significado do que está escrito.

3. Armazena tudo — as fichas e suas impressões digitais ficam guardadas. A base está pronta.

Quando o seu cliente faz uma pergunta

1. O agente recebe a pergunta e aciona a ferramenta knowledge_base_search

2. O sistema compara o significado da pergunta com o significado de todas as fichas

3. Retorna as fichas mais parecidas — não as que têm as mesmas palavras, mas as que têm o mesmo sentido

4. O agente lê essas fichas e formula a resposta

É por isso que funciona mesmo quando o cliente pergunta "vocês atendem Bradesco?" e o documento diz "convênios aceitos: Bradesco Saúde" — o sistema entende que é a mesma coisa.

Como criar uma base de conhecimento

Acesse Inteligência Artificial > Bases de conhecimento no menu lateral e clique em + Criar nova base de conhecimento.

Na tela de criação, preencha:

Nome — identifica a base internamente e é visível no Cérebro do agente.

Descrição — explica o que a base contém.

Situação — define se a base está ativa e disponível para os agentes usarem.

Como adicionar documentos

Existem duas formas de alimentar a base:

Upload de arquivo

Arraste ou selecione os arquivos diretamente na área de upload. Você pode enviar até 10 arquivos por vez.

Formatos suportados: PDF, MD, TXT, PPTX, DOCX e DOC.

Após salvar, os arquivos entram numa fila de processamento. O sistema divide cada um em fichas e grava o significado de cada trecho. Dependendo do tamanho, pode levar alguns minutos. Quando terminar, a base mostra o número de documentos e chunks processados.

Texto simples

Se você não tem um arquivo pronto, pode colar o conteúdo diretamente em texto. É útil para conteúdos curtos como horários de funcionamento, FAQs simples ou informações avulsas que não justificam um arquivo separado.

Formatos e o que funciona melhor

Nem todo formato é igual. Alguns geram fichas muito melhores que outros:

Markdown (.md) — o melhor formato. Hierarquia clara com títulos (#, ##, ###), listas e separadores ajudam o sistema a entender onde começa e termina cada assunto. Gera fichas muito precisas.

Texto simples (.txt) — funciona bem para conteúdo linear sem formatação complexa. Bom para FAQs e listas simples.

PDF com texto selecionável — funciona bem quando o texto é real (você consegue selecionar com o mouse). PDFs escaneados não funcionam — o sistema não enxerga imagem, só texto.

PPTX — funciona razoavelmente. O sistema extrai o texto dos slides, mas perde formatação visual.

DOCX / DOC — suportado, mas não é o formato mais preciso. Prefira converter para PDF ou MD quando possível.

Como estruturar bem seus documentos

Essa é a parte mais importante do guia. A estrutura do documento impacta diretamente na qualidade das respostas do agente.

Lembre que o sistema recorta o documento em fichas de ~1000 caracteres. Se o documento for um bloco de texto contínuo sem estrutura, as fichas saem misturadas — um pedaço começa falando de um médico e termina no convênio de outro. O agente fica confuso.

Quando o documento tem hierarquia clara, o sistema consegue montar fichas que fazem sentido sozinhas — cada ficha carrega o contexto necessário para a resposta.

Exemplos

Lista de médicos e convênios

Um documento de médicos bem estruturado separa cada profissional com um título próprio e organiza as informações em subtítulos consistentes:

# Dra. Lucia Silva
## Especialidade
Otorrinolaringologia

## Convênios atendidos
UNIMED, Particular

## Currículo
Especialista em Otorrinolaringologia e Medicina do Sono.

---

# Dr. Joao Silva
## Especialidade
Pneumologista

## Convênios atendidos
UNIMED, Amil, Bradesco, SulAmérica, Particular

## Currículo
Especialista em pediatria e atendimentos de urgência

Com essa estrutura, quando o cliente perguntar "a clínica tem otorrino que atende Bradesco?", o sistema vai encontrar as fichas corretas com nome, especialidade e convênios juntos na mesma ficha — e o agente responde com precisão.

Catálogo de produtos

A mesma lógica se aplica a catálogos. Cada produto com seu próprio bloco, atributos consistentes:

# Areia Grossa
## Aplicação
Reboco, assentamento de tijolos e blocos, contrapiso.

## Apresentação
Sacos de 20kg ou granel (m³)

## Observações
Indicada para obras em geral. Alta granulometria.

---

# Brita Nº 1
## Aplicação
Fundações, vigas, pilares e lajes.

## Apresentação
Granel (m³)

## Observações
Tamanho de grão entre 9,5mm e 19mm.

FAQ

Para perguntas frequentes, organize cada pergunta como um bloco separado:

# Qual o horário de funcionamento?
Segunda a sexta das 7h às 19h. Sábados das 8h às 13h. Não abrimos aos domingos.

---

# Como faço para remarcar uma consulta?
Entre em contato pelo WhatsApp (19) 99999-0000 com pelo menos 24 horas de antecedência.

---

# Vocês aceitam pacientes sem convênio?
Sim, atendemos particular. O pagamento pode ser feito em dinheiro, cartão de débito ou crédito.

Boas práticas gerais

Use títulos para separar assuntos. Cada bloco de informação deve ter um título claro. Se o documento falar de 50 produtos, cada produto tem seu #.

Seja consistente. Se você usa ## Convênios atendidos para um médico, use o mesmo subtítulo para todos. O sistema aprende os padrões.

Evite parágrafos longos e densos. Prefira listas curtas e frases diretas. Quanto mais limpo o texto, mais precisa a ficha.

Separe assuntos diferentes em arquivos diferentes. Um arquivo de médicos, um de convênios gerais, um de horários. Não misture tudo num documento único gigante.

Dê nomes descritivos aos arquivos. medicos-e-convenios.md é muito melhor que doc-final-v3.pdf. O nome do arquivo aparece nos metadados das fichas e ajuda o agente a entender o contexto.

Upload via API

Para casos mais avançados, é possível alimentar a base de conhecimento programaticamente via API — sem precisar fazer upload manual pelo painel. Isso é útil quando:

• Você tem um sistema próprio que precisa sincronizar seu conteúdo automaticamente com a base

• Quer atualizar documentos com frequência (tabelas de preços, disponibilidade de produtos, agendas)

• Precisa integrar a base com uma fonte de dados externa

A documentação completa do endpoint de upload está disponível em: https://developers.convert.app.br/docs/api/omnichannel-clients/bases-de-conhecimento#upload-de-arquivos-para-uma-base