#Una base de conocimiento para tu agente de IA

Una base de conocimiento es de donde responde un agente de IA cuando una pregunta necesita datos: políticas de cambio, zonas de despacho, cómo funciona un servicio. En Vatio es un conjunto de entradas en Markdown que escribes tú, desde la CLI o el inbox, y que el agente busca con la tool incluida knowledge_lookup; Vatio no lee sitios web. La conectas al agente en tu vatio.yml, pruebas cada cambio en preview y la publicas junto con el agente, que responde desde ella en WhatsApp, Instagram y la web.

#Qué es y por qué importa

Sin una base de conocimiento, un agente al que le preguntan por tu política de cambios solo puede decir que no sabe, o adivinar. Pegar todas las políticas en las instrucciones tampoco escala: el prompt crece, las reglas quedan enterradas y solo un developer puede corregir un dato desactualizado.

Una base de conocimiento saca los datos largos del prompt. El agente la busca cuando una pregunta lo requiere y lee solo las secciones que coinciden, y los supervisores pueden corregir una entrada en cuanto un dato cambia.

Es uno de tres lugares de donde puede salir una respuesta, y elegir el correcto evita toda una clase de respuestas malas:

La prueba: si la respuesta podría estar mala esta misma tarde, sale de una tool que llama a tu API. El conocimiento no es un caché de tu catálogo.

#Cómo funciona

1. Una base guarda entradas. Crea una base por cada conjunto de entradas que quieras mantener separado, y lista en el agente las bases que lee.
2. Una entrada es Markdown que escribes tú. Su título sale de su propio # heading, y cada ## empieza una sección que se busca por sí sola.
3. El agente busca con knowledge_lookup, una tool incluida que activas en agent.tools. Cuando nada coincide, la tool lo dice, y tus instrucciones deciden qué hace el agente después.
4. La indexación es asíncrona. Una entrada se puede buscar cuando sus secciones ya se embebieron; vatio kb show dice qué entradas están listas.
5. Live responde con las entradas publicadas. Preview guarda sus propios cambios encima de live y lee todo lo demás de live.

#Paso a paso

#1. Crea la base y escribe las entradas

vatio kb create tienda
vatio kb write tienda despachos despachos.md
vatio kb write tienda cambios-y-devoluciones cambios-y-devoluciones.md
vatio kb write tienda preparacion preparacion.md
vatio kb show tienda

vatio kb write BASE ENTRADA ARCHIVO crea la entrada, o reemplaza lo que haya. Sin archivo lee stdin, así que editar en el lugar es una línea: vatio kb cat tienda despachos | edit | vatio kb write tienda despachos. vatio kb cat imprime exactamente lo que guarda Vatio.

#2. Conéctala al agente

agent:
  instructions: |
    Despachos, cambios y preparación: busca primero en knowledge_lookup.
    Si los resultados no responden la pregunta, dilo y ofrece pasársela
    al equipo.
  tools: [knowledge_lookup]
  knowledge: [tienda]

Una base referenciada ya debe existir: un nombre mal escrito hace fallar el push en vez de convertirse en silencio en una base vacía. Quitar la referencia después no borra el contenido de la base.

#3. Haz push y prueba la búsqueda

vatio push
vatio chat "¿Cuánto se demora un despacho a Temuco?"
vatio chat show

chat show muestra la búsqueda en el conocimiento que hizo el agente y lo que volvió. Si falta la respuesta, revisa vatio kb show tienda: una entrada que todavía se está indexando aún no se puede encontrar.

#Escribe entradas que respondan solas

El agente recibe las secciones que coinciden con una pregunta, no la entrada completa en orden. Una sección que depende de otra responde mal. Esta entrada se lee bien de arriba abajo y falla como resultado de búsqueda:

# Despachos

Despachamos a todo Chile. Detalles más abajo.

## Más información
Igual que arriba, pero demora más a Aysén y Magallanes.
Gratis sobre el monto que mencionamos.

Esta responde desde cualquier sección:

# Despachos

## Plazos de entrega
Despachamos desde Santiago. Región Metropolitana: 1 a 2 días hábiles.
Otras regiones: 3 a 5 días hábiles. Aysén y Magallanes: 5 a 8 días hábiles.

## Costo del despacho
Gratis en compras sobre $40.000. Bajo ese monto, $3.990 a la Región
Metropolitana y $5.990 a otras regiones.

## Hora de corte
Los pedidos pagados antes de las 13:00 de un día hábil salen el mismo día.

• Una entrada por tema, y cada ## una pregunta que un cliente de verdad hace, con la respuesta completa debajo.
• Nada de «ver arriba», «como mencionamos» ni «detalles más abajo».
• Números, condiciones y excepciones, escritos.
• Las palabras del cliente. «Plazos de entrega», no «SLA de fulfillment».
• Nunca una credencial. Las llaves y contraseñas no van en el conocimiento.

#Los supervisores editan en el inbox

Los supervisores, invitados desde Equipo en el inbox, abren el conocimiento en el inbox, editan entradas y llenan una desde un archivo. Al guardar ahí, el cambio llega a live de inmediato, sin deploy. Cada cambio, desde el inbox o la CLI, se vuelve una versión numerada de su entrada, con quién la hizo y desde dónde.

Eso es lo que mantiene la base al día: la persona que se entera de que cambió el horario de retiro puede corregir la entrada en un minuto. Cuando una respuesta mala tiene una causa más profunda, la reportan, y la corrección pasa por preview y tus evals; mira Mejorar tu agente.

#Prueba los cambios en preview

Cuando el agente ya está en live, cambia el conocimiento igual que cambias el prompt. kb write, cat, rm-entry, show y status trabajan en preview, así que solo preview responde con lo que escribiste:

vatio kb write tienda despachos despachos.md
vatio chat "¿Cuánto cuesta el despacho a Punta Arenas?"
vatio kb status tienda      # lo que live todavía no tiene
vatio eval                  # cada reporte, contra preview
vatio publish               # el agente y estas entradas, juntos

vatio kb publish tienda lleva a live solo los cambios de una base, sin el agente, y --env live lee y escribe live directamente.

#Conflictos

Si live cambia una entrada después de que preview también la cambió, porque un supervisor la corrigió en el inbox, publicar sobrescribiría un cambio que nadie ha leído. Así que se rechaza, y vatio kb status nombra la entrada. Hay dos salidas:

• Desde la terminal: lee la entrada desde live, escribe tu cambio encima, y el conflicto desaparece.

  vatio kb cat tienda despachos --env live > despachos.md
  $EDITOR despachos.md
  vatio kb write tienda despachos despachos.md

• En el inbox: la página de cambios de conocimiento en Probar tiene el diff de cada entrada que cambió preview (vatio env imprime el link). En un conflicto muestra los dos lados y ofrece tres opciones: conservar la versión de preview encima de live, usar la de live, o combinar las dos a mano.

#Historial y volver atrás

vatio kb history tienda                                     # cada versión que llegó a live
vatio kb cat tienda despachos --version 3 > despachos.md
vatio kb write tienda despachos despachos.md --env live     # la versión 3 pasa a ser la más reciente

Volver atrás es escribir de nuevo una versión antigua. En el inbox es un botón, Restaurar esta versión, en el historial de la entrada.

vatio rollback va más allá. Un deployment live es un snapshot de la configuración y de la versión de cada entrada con la que respondía, así que un rollback restaura la configuración y el conocimiento anteriores de live, juntos. Una edición en el inbox también deja un snapshot, lo que significa que el primer rollback después de la corrección de un supervisor deshace esa corrección. Lee vatio kb history antes de hacer rollback.

#Un ejemplo completo

Té Copihue vende té en hojas por internet y atiende por WhatsApp y en su sitio:

workspace: te-copihue
agent:
  name: Té Copihue
  personality: Cálido y breve. Palabras simples.
  instructions: |
    Ayudas a los clientes de Té Copihue a elegir tés y respondes dudas
    sobre despachos, cambios, preparación y conservación.

    Despachos, cambios, preparación y conservación: busca primero en
    knowledge_lookup. Si no encuentras la respuesta, dilo y ofrece pasarle
    la pregunta al equipo. Nunca digas un costo ni un plazo de despacho
    que no esté en el conocimiento.

    Stock y precios: llama a consultar_stock. Nunca digas un stock ni un
    precio que consultar_stock no haya devuelto.
  tools: [consultar_stock, knowledge_lookup]
  knowledge: [tienda]

La base tienda tiene cuatro entradas: despachos, cambios-y-devoluciones, preparacion y conservacion. Los precios y el stock no están ahí, porque cambian todos los días; consultar_stock los lee desde la API de la tienda.

En diciembre, el courier anuncia tarifas nuevas para enero. Una developer reescribe la sección de costos de despachos y la prueba en un chat de preview. Mientras tanto, un supervisor corrige la hora de corte en la misma entrada desde el inbox, y live responde con esa corrección de inmediato. Cuando la developer corre vatio kb status tienda, despachos aparece como conflicto. La lee desde live, aplica las tarifas nuevas encima de la corrección del supervisor, la escribe de nuevo y publica. Live queda con las tarifas nuevas y con la hora de corte corregida.

#Errores comunes

• Datos en vivo en el conocimiento. El stock o los precios que cambian cada hora quedan viejos apenas los escribes. Usa una tool.
• «Revisa nuestro sitio web». El agente no puede seguir un link para leer una página. Escribe la respuesta en una entrada.
• Una base que el agente no alcanza. Necesita knowledge: [tienda] y también knowledge_lookup en agent.tools.
• Probar demasiado pronto. La indexación es asíncrona; revisa vatio kb show antes de concluir que la búsqueda falla.
• Sin instrucción para «no encontré nada». Sin «si no encuentras la respuesta, dilo», el modelo tiende a llenar el vacío.
• Hacer rollback a ciegas. Una edición en el inbox también deja un snapshot, así que revisa el historial primero.

#Qué sigue

Cuando una respuesta mala viene del conocimiento, el ciclo de reportes la convierte en una prueba: mira Mejorar tu agente. Todos los comandos están en la documentación de conocimiento.

Actualizado: 11 de octubre de 2026