> Dê ao seu agente de IA uma base de conhecimento em Markdown escrita por você, teste cada mudança no preview e publique junto com o agente. # 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: | Vai em | Quando | Exemplo | |---|---|---| | `instructions` | Regras, a ordem dos passos, o que nunca dizer, qual tool faz cada trabalho | "Nunca informe um valor de frete que não esteja no conhecimento" | | Conhecimento | Dados que mudam devagar e levam parágrafos para explicar | Política de trocas, regiões de entrega, guias de preparo | | Uma tool | Dados que podem mudar de uma hora para outra, ou que são de uma pessoa | Estoque, o preço do dia, horários livres, o status de um pedido | 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 ```bash 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 ```yaml 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 ```bash 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: ```markdown # 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: ```markdown # 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](/pt/guias/melhorar-seu-agente-de-ia). ## 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: ```bash 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. ```bash 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 ```bash 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: ```yaml 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](/pt/guias/melhorar-seu-agente-de-ia). Todos os comandos estão na [documentação de conhecimento](https://vatio.ai/docs/knowledge). ## Perguntas frequentes ### Como dou uma base de conhecimento a um agente de IA? Crie uma base com vatio kb create, escreva cada assunto como uma entrada em Markdown com vatio kb write, coloque a base em agent.knowledge e adicione knowledge_lookup em agent.tools. Faça push, pergunte ao agente algo que as entradas respondem e confira a busca com vatio chat show. ### O agente consegue aprender com o meu site? Não. A Vatio não lê sites. Se a resposta está em uma página, escreva em uma entrada o que o agente precisa. Isso também quer dizer que nada muda pelas suas costas quando alguém edita o site. ### O que vai na base de conhecimento e o que vai em uma tool? O conhecimento é para dados que mudam devagar: políticas, regiões de entrega, como um serviço funciona. Tudo o que pode mudar de uma hora para outra, como estoque, o preço do dia ou horários livres, vem de uma tool que chama a sua API. As regras e a ordem dos passos vão nas instruções. ### Quem não é developer consegue editar a base de conhecimento? Sim. Os supervisores editam entradas no inbox, e ao salvar ali a mudança vai para o live na hora. Cada mudança fica como uma versão numerada, com quem fez e de onde, e qualquer versão é restaurada com um botão no histórico da entrada. ### O que acontece se um supervisor edita uma entrada que eu também mudei no preview? Publicar o preview é recusado, para não sobrescrever a correção dele sem ninguém ter lido. O vatio kb status mostra a entrada. Leia a entrada do live e escreva sua mudança por cima, ou resolva na página de mudanças de conhecimento em Testar, no inbox, onde você mantém a versão do preview, fica com a do live ou combina as duas à mão. ### O vatio rollback desfaz mudanças no conhecimento? Sim. Um deployment live é um snapshot da configuração e da versão de cada entrada com que ele respondia, e o vatio rollback restaura o anterior, com as duas coisas juntas. Ele não restaura os valores dos secrets nem desfaz o que uma tool já fez.