#Cómo mejorar tu agente de IA con reportes

Para mejorar un agente de IA que atiende clientes reales, parte por las respuestas que salieron mal. Con Vatio, un supervisor reporta una respuesta equivocada en el inbox y escribe lo que debió decir, y ese reporte ya es una prueba. Cada mañana tus developers reciben un correo con los reportes abiertos y un prompt, /vatio:vatio-improve. En Claude Code, esa skill toma todos los reportes, corrige la causa, actualiza preview y repite cada reporte contra la versión nueva con vatio eval. vatio publish la lleva a live solo si no rompe lo que funcionaba. Claude corrige, Vatio comprueba. El agente es un vatio.yml que responde en WhatsApp, Instagram y la web, así que un solo ciclo cubre todos los canales.

#Por qué corregir desde los reportes

Quienes leen las conversaciones de tu agente saben cuándo una respuesta está mal. Tú conoces el código. Lo normal es que se encuentren en un mensaje del tipo «ayer el bot le dijo algo raro a un cliente», sin la conversación y sin forma de saber si la causa fueron las instrucciones, el conocimiento o el backend.

Un reporte cierra esa brecha. Trae la conversación, cada llamada a una tool que hizo el agente en ese turno con lo que respondió tu backend, y lo que alguien que conoce el negocio dice que debió pasar. Eso le basta a un coding agent para encontrar la causa, y basta para convertir el error en una prueba, así que no puede volver en silencio con el próximo cambio.

#Cómo funciona el ciclo

1. Reporte. Un supervisor reporta una respuesta mala en el inbox y escribe lo que debió pasar. Desde ese momento es un caso de eval, sea en live o en preview.
2. Correo diario. Cada mañana con reportes nuevos, el dueño y los developers del workspace reciben cuántos hay abiertos y el prompt /vatio:vatio-improve.
3. Arreglo. En Claude Code, /vatio:vatio-improve toma todos los reportes abiertos en una sola sesión: lee vatio flags, corrige cada causa donde vive y hace vatio push, que actualiza preview sin correr pruebas.
4. Eval. vatio eval repite cada reporte contra preview. Lo que pasa queda Arreglado · falta publicar.
5. Publicación. vatio publish lleva preview a live, salvo que rompa un reporte que live pasa. Los resultados de preview pasan a live con la versión, y cada reporte que pasó queda Resuelto, con el sha de la versión que lo arregló.

Nadie tiene que avisar que un reporte está listo. Que el agente que hablan tus clientes lo pase es la evidencia.

#Paso 1: los supervisores reportan en el inbox

Invita a los supervisores desde Equipo en el inbox. Entran con un código que les llega al correo, ven cada conversación y las llamadas a tools del agente, pueden responder para tomar una conversación (hasta 8 horas después del último mensaje de la persona) y pueden editar las entradas de conocimiento. No pueden desplegar nada.

En cualquier respuesta del agente, Reportar esta respuesta pide lo que debió pasar. Pídeles a los supervisores que escriban qué debió hacer el agente, una respuesta corregida o una acción, no un veredicto:

• Débil: «mal».
• Útil: «Debió decir que el pedido sale el jueves y enviar el link de seguimiento».
• También útil: «Debió buscar el pedido con la tool de pedidos antes de responder». El juez ve las llamadas a tools, así que una nota así también se puede probar.

Un reporte sin nota no llega al digest y no es una prueba: «esto estuvo mal» sin decir qué debió pasar no sirve para corregir un agente. Un dato desactualizado, como un precio antiguo, el supervisor también lo puede corregir en el momento en la entrada de conocimiento; cada edición queda guardada como versión.

El estado de cada reporte aparece en la misma respuesta reportada, dentro de la conversación: Abierto, Arreglado · falta publicar o Resuelto con la versión que lo arregló. Si un reporte resuelto sigue sin convencer, el supervisor reescribe la nota y vuelve a quedar abierto. Mejora continua, en el inbox, lista todos los reportes con su estado y su última prueba, dice qué sigue (arreglos por hacer, arreglos que esperan publicarse o uno que rompió algo) con el prompt /vatio:vatio-improve, listo para pegar en Claude Code dentro del repositorio del agente, y desde ahí también se quita un reporte.

#Paso 2: /vatio:vatio-improve en Claude Code

Instala las skills de Vatio una vez en el proyecto:

/plugin marketplace add vatio-ai/skills
/plugin install vatio@vatio

Después, /vatio:vatio-improve en el repositorio del agente toma todos los reportes abiertos a la vez, y Claude Code también la usa sola cuando le pides mejorar el agente. Para cualquier otro coding agent, npx @vatio-ai/skills en la raíz de tu proyecto copia la misma skill a .agents/skills/, donde la buscan Codex, Cursor y la mayoría de los demás. vatio init además escribe una sección breve de Vatio en el AGENTS.md del workspace que apunta a vatio flags. Claude Code no actualiza solo los plugins de marketplaces de terceros: actívalo una vez en /plugin → Marketplaces → vatio → Enable auto-update. vatio flags te avisa cuando tus skills están desactualizadas.

La skill empieza por el digest:

vatio flags --save        # escribe vatio-flags.md

Para cada reporte, el digest trae el canal y la versión desplegada, los 10 mensajes anteriores a la respuesta reportada, cada llamada a una tool en ese turno con sus argumentos y la respuesta que devolvió tu backend, las búsquedas en el conocimiento y la nota del supervisor. Sus primeras líneas le explican a un coding agent cómo trabajarlo.

vatio-flags.md contiene conversaciones de visitantes reales. Agrégalo a .gitignore y en los commits nombra los reportes por su número.

#Paso 3: corrige la causa donde vive

Varios reportes suelen compartir una causa, y muchas veces la causa no es el prompt:

Los reportes solo atrapan lo que un supervisor notó. Una tool que falla casi nunca se reporta, porque el agente se disculpa y sigue, así que pide a tu coding agent que también corra vatio tools --env live: la página Herramientas del inbox en Markdown, con la tasa de error, los timeouts y la latencia p50/p95 de cada tool, y las llamadas que fallaron con lo que respondió tu backend. Después de publicar un arreglo, vatio tools --env live --period 1h muestra si los errores pararon.

Tu coding agent tiene enfrente tu repositorio y tu backend, y Vatio no; por eso el arreglo le toca a él. Cuando termina, sube el arreglo a preview:

vatio push                # actualiza preview; no corre pruebas

Hay solo dos entornos: preview, la próxima versión, y live, con la que hablan tus clientes. Si el agente ya está publicado y preview tiene un push sin publicar hecho desde otra rama de git, vatio push se rechaza para no pisarlo: publícalo primero, o usa --force para reemplazarlo.

#Paso 4: compruébalo con vatio eval

vatio eval                # todos los reportes, contra preview
vatio eval --show RUN_ID  # la razón del juez para cada caso

Cada caso corre en un chat nuevo: los turnos del visitante (hasta los últimos 8) se envían uno por uno, y un juez lee la conversación, incluida cada tool que llamó el agente, y la nota, y responde pasa o falla en una frase. Una nota que pide una tool pasa cuando el agente la llama. El juez es un modelo de otra familia que el de tu agente, para que nunca califique respuestas de su mismo tipo. Todo corre en los servidores de Vatio, cinco casos a la vez, y puede tardar unos minutos: en Claude Code, córrelo en segundo plano. El comando sale con 1 cuando algún caso falla.

Lee primero las regresiones. Un reporte que pasa en live y falla en preview aparece arriba: el arreglo rompió algo que ayer funcionaba, y así no se puede publicar. Cada caso es un turno real del agente, así que puede pasar una vez y fallar la siguiente sin que nada cambie; por eso un caso que falla se repite solo, hasta 3 veces.

Sin terminal, Correr pruebas en la página Probar del inbox vuelve a correr los mismos reportes contra preview, y la tarjeta de preview dice cuántos pasaron.

Los evals llaman a tus tools. Apúntalas a un backend de staging con un valor de pruebas, que usan todas las repeticiones y preview. Una escritura (reservas, pedidos, tickets) cuya URL no tiene valor de pruebas se simula en vez de enviarse:

vatio secrets set TIENDA_API https://staging.api.tostaduria-cumbre.example --tests

Los chats de los evals no aparecen en el inbox ni cuentan como conversaciones.

#Paso 5: publica y deja que live resuelva el reporte

vatio publish

Mientras el agente nunca se ha publicado, preview es el agente: un reporte queda resuelto cuando preview lo pasa, y la primera publicación no tiene control. Una vez publicado, vatio publish se rechaza cuando:

• la versión actual de preview no tiene una corrida de vatio eval (corre vatio eval y después publica);
• sus pruebas siguen corriendo (vatio eval espera a que terminen);
• un reporte que pasa en live falla en preview. La respuesta nombra cada uno; vatio publish --force publica igual, y sus resultados fallidos pasan a live con él.

Los reportes que todavía fallan no frenan nada: un arreglo parcial puede salir. Al publicar, los resultados de preview pasan a live sin volver a correr nada, y cada reporte que pasó queda Resuelto con el sha de 7 caracteres de la versión que lo arregló. El botón Publicar a live de la página Probar del inbox pasa por el mismo control, y no aparece mientras preview es la misma versión que live: no hay nada que publicar.

#El correo diario

Cada mañana a las 8:00 (America/Santiago), cada workspace con reportes nuevos le envía a su dueño y sus developers un correo con cuántos llegaron y cuántos siguen abiertos, y el prompt /vatio:vatio-improve para pegar en Claude Code. No cita lo que alguien escribió: las conversaciones, las respuestas de las tools y las notas solo se leen con un token de Vatio.

#Un ejemplo completo

Tostaduría Cumbre vende café en grano por internet y atiende por WhatsApp. El correo del lunes trae tres reportes:

• Reportes 31 y 35. Ante «¿cuándo llega mi pedido?», el agente respondió «va en camino». Las dos notas: «Debió dar la fecha de entrega y el link de seguimiento». El digest muestra que estado_pedido devolvió el estado y nada más.
• Reporte 34. Ante «¿me lo pueden moler para cafetera italiana?», el agente dijo que solo venden en grano. La nota: «Molemos al momento para cualquier método. Preguntar cuál». Ninguna búsqueda en el conocimiento encontró nada.

La developer pega /vatio:vatio-improve en Claude Code, que encuentra dos causas. En 31 y 35 el prompt nunca fue el problema: el endpoint no devolvía ninguna fecha. Agrega entrega_estimada y url_seguimiento a la respuesta del backend, lo sube a staging y mapea ambos campos en la tool:

# tools/estado_pedido.yml
description: Consulta el estado de un pedido.
when_to_use: El visitante pregunta dónde está su pedido o cuándo llega.
parameters:
  type: object
  properties:
    numero_pedido: { type: string }
    email: { type: string, description: "el correo con el que se hizo el pedido" }
  required: [numero_pedido, email]
access: public
request:
  method: GET
  base_url: "$env.TIENDA_API"
  path: /pedidos/consulta
  requires: [params.numero_pedido, params.email]
  headers:
    Authorization: "Bearer $env.TIENDA_API_KEY"
  query:
    numero: "$params.numero_pedido"
    email: "$params.email"
respond:
  data:
    estado: "$.pedido.estado"
    entrega_estimada: "$.pedido.entrega_estimada"
    url_seguimiento: "$.pedido.url_seguimiento"
  message: Pedido encontrado.

Un link que devuelve una tool es uno que el agente puede enviar durante el resto de la conversación, así que la URL de seguimiento no hay que declararla. Para el 34 escribe una entrada molienda con vatio kb write tienda molienda molienda.md. Después hace vatio push y corre vatio eval en segundo plano; TIENDA_API ya tiene un valor de pruebas que apunta a staging.

La primera corrida muestra una regresión: un reporte anterior, «nunca prometer fecha para una preventa», pasa en live y falla en preview, porque ahora las preventas también vuelven con fecha. vatio publish no la dejaría salir. Ese arreglo también vive en el backend, que deja entrega_estimada vacío en las preventas. La segunda corrida pasa todos los casos, vatio publish lleva preview a live, y los reportes 31, 34 y 35 quedan resueltos con el sha de esa versión.

#Errores comunes

• Corregir todos los reportes en el prompt. Las reglas nuevas esconden la causa y engordan el prompt. Lee primero las respuestas de las tools en el digest.
• Notas que juzgan en vez de responder. «Mal tono» no se puede convertir en prueba; «debió disculparse y dar la nueva fecha», sí.
• Una nota que pide algo que el agente no debe hacer, como un descuento que no puede dar. Díselo al supervisor en vez de saltártela; puede editar o quitar el reporte.
• Publicar con --force por costumbre. Una regresión es un cliente que mañana recibe la respuesta mala que ya habías arreglado.
• Evals que escriben en producción. Define un valor de pruebas con --tests.
• Conversaciones en el repositorio. Deja vatio-flags.md fuera de tus commits.

#Qué sigue

Para los hábitos que mantienen los reportes al mínimo, lee Buenas prácticas. Todos los comandos están en la documentación.

Actualizado: 11 de octubre de 2026