#Uma base de conhecimento para o seu agente de IA

Uma base de conhecimento é de onde um agente de IA responde quando uma pergunta precisa de dados: políticas de troca, regiões de entrega, como um serviço funciona. Na Vatio, ela é um conjunto de entradas em Markdown que você escreve, pelo CLI ou pelo inbox, e que o agente busca com a tool embutida knowledge_lookup; a Vatio não lê sites. Você conecta a base ao agente no seu vatio.yml, testa cada mudança no preview e publica junto com o agente, que responde a partir dela no WhatsApp, no Instagram e na web.

#O que é e por que importa

Sem uma base de conhecimento, um agente que recebe uma pergunta sobre a sua política de trocas só pode dizer que não sabe, ou chutar. Colar todas as políticas nas instruções também não escala: o prompt cresce, as regras ficam enterradas e só um developer consegue corrigir um dado desatualizado.

Uma base de conhecimento tira os dados longos do prompt. O agente busca nela quando uma pergunta pede e lê só as seções que batem, e os supervisores conseguem corrigir uma entrada assim que um dado muda.

Ela é um de três lugares de onde uma resposta pode vir, e escolher o certo evita toda uma classe de respostas erradas:

O teste: se a resposta pode estar errada ainda hoje à tarde, ela vem de uma tool que chama a sua API. Conhecimento não é cache do seu catálogo.

#Como funciona

1. Uma base guarda entradas. Crie uma base para cada conjunto de entradas que você quer manter separado, e liste no agente as bases que ele lê.
2. Uma entrada é Markdown que você escreve. O título vem do próprio # heading, e cada ## começa uma seção que é buscada sozinha.
3. O agente busca com knowledge_lookup, uma tool embutida que você ativa em agent.tools. Quando nada bate, a tool diz isso, e as suas instruções decidem o que o agente faz em seguida.
4. A indexação é assíncrona. Uma entrada pode ser buscada quando as seções dela já foram indexadas; o vatio kb show mostra quais entradas estão prontas.
5. O live responde com as entradas publicadas. O preview guarda as próprias mudanças por cima do live e lê todo o resto dele.

#Passo a passo

#1. Crie a base e escreva as entradas

vatio kb create loja
vatio kb write loja entregas entregas.md
vatio kb write loja trocas-e-devolucoes trocas-e-devolucoes.md
vatio kb write loja preparo preparo.md
vatio kb show loja

vatio kb write BASE ENTRADA ARQUIVO cria a entrada, ou substitui o que existe. Sem arquivo ele lê o stdin, então editar no lugar é uma linha só: vatio kb cat loja entregas | edit | vatio kb write loja entregas. O vatio kb cat imprime exatamente o que a Vatio guarda.

#2. Conecte a base ao agente

agent:
  instructions: |
    Entregas, trocas e preparo: busque primeiro em knowledge_lookup. Se os
    resultados não responderem à pergunta, diga isso e ofereça passar a
    pergunta para a equipe.
  tools: [knowledge_lookup]
  knowledge: [loja]

Uma base referenciada precisa existir antes: um nome digitado errado faz o push falhar em vez de virar, em silêncio, uma base vazia. Tirar a referência depois não apaga o conteúdo da base.

#3. Faça push e teste a busca

vatio push
vatio chat "Quanto tempo leva a entrega para Curitiba?"
vatio chat show

O chat show mostra a busca no conhecimento que o agente fez e o que voltou. Se a resposta não aparecer, confira o vatio kb show loja: uma entrada que ainda está sendo indexada não pode ser encontrada.

#Escreva entradas que respondem sozinhas

O agente recebe as seções que batem com uma pergunta, não a entrada inteira em ordem. Uma seção que depende de outra responde mal. Esta entrada se lê bem de cima a baixo e falha como resultado de busca:

# Entregas

Entregamos para todo o Brasil. Detalhes abaixo.

## Mais informações
Igual ao de cima, mas demora mais para o Norte e o Nordeste.
Grátis acima do valor que comentamos.

Esta responde a partir de qualquer seção:

# Entregas

## Prazos de entrega
Enviamos de São Paulo. Capital e Grande São Paulo: 1 a 2 dias úteis.
Sul e Sudeste: 3 a 5 dias úteis. Centro-Oeste, Norte e Nordeste: 5 a 9 dias úteis.

## Valor do frete
Grátis em compras acima de R$ 150. Abaixo disso, R$ 14,90 para o Sul e o
Sudeste e R$ 24,90 para as demais regiões.

## Horário de corte
Pedidos pagos até as 13h de um dia útil, por Pix ou cartão, saem no mesmo dia.

• Uma entrada por assunto, e cada ## uma pergunta que um cliente realmente faz, com a resposta completa embaixo.
• Nada de “ver acima”, “como dissemos” ou “detalhes abaixo”.
• Números, condições e exceções, por escrito.
• As palavras do cliente. “Prazos de entrega”, não “SLA de fulfillment”.
• Nunca uma credencial. Chaves e senhas não vão no conhecimento.

#Os supervisores editam no inbox

Os supervisores, convidados em Equipe no inbox, abrem o conhecimento no inbox, editam entradas e preenchem uma a partir de um arquivo. Ao salvar ali, a mudança vai para o live na hora, sem deploy. Cada mudança, pelo inbox ou pelo CLI, vira uma versão numerada da entrada, com quem fez e de onde.

É isso que mantém a base em dia: quem fica sabendo que o horário de retirada mudou corrige a entrada em um minuto. Quando uma resposta errada tem uma causa mais funda, o supervisor reporta a resposta, e a correção passa pelo preview e pelos seus evals; veja Melhorar seu agente.

#Teste as mudanças no preview

Com o agente já no live, mude o conhecimento do mesmo jeito que você muda o prompt. kb write, cat, rm-entry, show e status trabalham no preview, então só o preview responde com o que você escreveu:

vatio kb write loja entregas entregas.md
vatio chat "Quanto fica o frete para Manaus?"
vatio kb status loja        # o que o live ainda não tem
vatio publish               # o agente e estas entradas, juntos

O vatio kb publish loja leva para o live só as mudanças de uma base, sem o agente, e --env live lê e escreve direto no live.

#Conflitos

Se o live muda uma entrada depois que o preview também mudou, porque um supervisor corrigiu no inbox, por exemplo, publicar sobrescreveria uma mudança que ninguém trabalhando no preview leu. Por isso é recusado, e o vatio kb status mostra a entrada. Há duas saídas:

• Pelo terminal: leia a entrada do live, escreva a sua mudança por cima, e o conflito some.

  vatio kb cat loja entregas --env live > entregas.md
  $EDITOR entregas.md
  vatio kb write loja entregas entregas.md

• No inbox: a página de mudanças de conhecimento em Testar tem o diff de cada entrada que o preview mudou (o vatio env imprime o link). Em um conflito, ela mostra os dois lados e oferece três opções: manter a versão do preview por cima do live, ficar com a do live, ou combinar as duas à mão.

#Histórico e como voltar atrás

vatio kb history loja                                     # cada versão que chegou ao live
vatio kb cat loja entregas --version 3 > entregas.md
vatio kb write loja entregas entregas.md --env live       # a versão 3 vira a mais recente

Voltar atrás é escrever de novo uma versão antiga. No inbox é um botão, Restaurar esta versão, no histórico da entrada.

O vatio rollback vai além. Um deployment live é um snapshot da configuração e da versão de cada entrada com que ele respondia, então um rollback restaura a configuração e o conhecimento anteriores do live, juntos. Uma edição no inbox também deixa um snapshot, o que significa que o primeiro rollback depois da correção de um supervisor desfaz essa correção. Leia o vatio kb history antes de fazer rollback.

#Um exemplo completo

A Casa Ipê Chás vende chá a granel pela internet e atende no WhatsApp e no site:

workspace: casa-ipe-chas
agent:
  name: Casa Ipê Chás
  personality: Acolhedor e breve. Palavras simples.
  instructions: |
    Você ajuda os clientes da Casa Ipê Chás a escolher chás e responde
    dúvidas sobre entregas, trocas, preparo e armazenamento.

    Entregas, trocas, preparo e armazenamento: busque primeiro em
    knowledge_lookup. Se não encontrar a resposta, diga isso e ofereça
    passar a pergunta para a equipe. Nunca informe um valor ou prazo de
    frete que não esteja no conhecimento.

    Estoque e preços: chame consultar_estoque. Nunca informe um estoque
    ou um preço que consultar_estoque não tenha devolvido.
  tools: [consultar_estoque, knowledge_lookup]
  knowledge: [loja]

A base loja tem quatro entradas: entregas, trocas-e-devolucoes, preparo e armazenamento. Preços e estoque não estão nela, porque mudam todo dia; a consultar_estoque lê esses dados da API da loja.

Em dezembro, a transportadora anuncia uma tabela nova para janeiro. Uma developer reescreve a seção de valores de entregas e testa em um chat do preview. Enquanto isso, um supervisor corrige o horário de corte na mesma entrada pelo inbox, e o live passa a responder com essa correção na hora. Quando a developer roda vatio kb status loja, entregas aparece como conflito. Ela lê a entrada do live, aplica a tabela nova por cima da correção do supervisor, escreve de novo e publica. O live fica com a tabela nova e com o horário de corte corrigido.

#Erros comuns

• Dados ao vivo no conhecimento. Estoque ou preços que mudam a cada hora ficam velhos assim que você escreve. Use uma tool.
• “Veja o nosso site”. O agente não consegue seguir um link para ler uma página. Escreva a resposta em uma entrada.
• Uma base que o agente não alcança. Ele precisa de knowledge: [loja] e também de knowledge_lookup em agent.tools.
• Testar cedo demais. A indexação é assíncrona; confira o vatio kb show antes de concluir que a busca está quebrada.
• Nenhuma instrução para “não encontrei”. Sem “se não encontrar a resposta, diga isso”, o modelo tende a preencher a lacuna.
• Rollback às cegas. Uma edição no inbox também deixa um snapshot, então confira o histórico antes.

#Próximos passos

Quando uma resposta errada vem de uma entrada, o supervisor a reporta e a correção passa pelos evals: veja Melhorar seu agente. Todos os comandos estão na documentação de conhecimento.

Atualizado: 11 de outubro de 2026