#Construir un agente en Vatio: el manual para coding agents

Esta página está escrita para el coding agent, Claude Code, Codex, Cursor o cualquier otro, al que un developer le pidió construir en Vatio un agente de IA que atienda a clientes. Es el orden que funciona: qué mirar, qué preguntarle al dueño, qué escribir, cómo probarlo y qué entregar, con un ejemplo completo. Las personas también pueden leerla; la versión para developers es más corta.

El contrato, cada campo del vatio.yml y cada comando, está en la documentación, y la documentación manda donde no coincida con esta página. Léela antes de escribir nada:

npx @vatio-ai/cli docs

Lo mismo está en un solo archivo Markdown en vatio.ai/docs/docs.md, y cada página de la documentación también está en su propia dirección más .md. Esta página está en vatio.ai/es/guias/manual-para-coding-agents.md.

#Qué estás construyendo

• Un workspace, un agente. Un workspace tiene un slug y corre exactamente un agente, descrito en un vatio.yml cuyas únicas claves raíz son workspace, agent y auth.
• Instrucciones, tools y conocimiento. Las instrucciones dicen qué hace el agente y las reglas que nunca rompe. Una tool es un request HTTP a la API del negocio, descrito en YAML bajo tools/. El conocimiento son entradas en Markdown que el agente busca, guardadas en Vatio y versionadas.
• Entornos. Hay dos: vatio push actualiza preview y vatio publish lo lleva a live. Nada llega a los clientes hasta que se publica, y una vez publicado el agente, vatio publish exige que vatio eval haya probado la versión de preview.
• Ningún modelo que elegir. Vatio corre el modelo y las conversaciones. No hay llave de modelo ni configuración de modelo.
• Canales. El mismo agente responde en un widget web, WhatsApp, mensajes directos de Instagram y los SDK de navegador, iOS y Android. Los supervisores leen cada conversación en el inbox, toman una respondiendo y marcan las respuestas que estuvieron mal.

Lo que no hace, para que nunca se lo prometas al dueño:

• Responde con texto. Lee imágenes, audios y PDF, pero no envía archivos.
• No lee sitios web. Lo que deba saber lo escribes como conocimiento.
• Escribe primero solo cuando el backend del negocio llama a la Messages API, en WhatsApp. Nunca decide por su cuenta escribirle a alguien.
• Vatio todavía no le avisa a nadie de una derivación: la conversación aparece como pendiente en el inbox.

#El orden que funciona

1. Instala las skills.
2. Mira antes de crear.
3. Cuenta lo que encontraste y recomienda.
4. Pregúntale al dueño solo lo que el código no responde.
5. Escribe el agente: vatio.yml, tools y conocimiento.
6. Revisa, haz push y pruébalo.
7. Entrega el link.
8. Publica solo cuando te lo pidan.
9. Antes de terminar, cuenta lo que te estorbó.

#1. Instala las skills

A menos que .agents/skills/vatio-init ya esté en el proyecto, corre esto desde su raíz:

npx @vatio-ai/skills

Copia las skills de Vatio a .agents/skills/ y .claude/skills/, así este procedimiento y el de mejorar el agente quedan en el repositorio para la próxima sesión, sea cual sea el coding agent que la corra. Más abajo, vatio es npx @vatio-ai/cli cuando la CLI no está instalada globalmente. Necesita Node.js 20 o más reciente.

#2. Mira antes de crear

Puede que el proyecto ya tenga un agente.

• Busca un vatio.yml en el directorio actual o por encima, y en cualquier parte del repositorio: git ls-files '*vatio.yml'. Su línea workspace: nombra el workspace. Si hay uno, el agente existe: nunca corras vatio init ahí, porque escribe un agente inicial y hacer push de ese reemplaza al real. Sigue Joining an existing workspace.
• Un slug de workspace pero ningún vatio.yml: pide el repositorio donde vive. Vatio guarda lo que se desplegó, no los archivos de donde salió.
• Lee la app. Qué hace y para quién; la API que un agente podría llamar (rutas, controladores, un archivo OpenAPI); cómo inician sesión sus usuarios; y la documentación, las preguntas frecuentes y las políticas que un agente podría leer.
• Revisa la máquina. vatio doctor dice si la CLI tiene sesión iniciada y a qué workspace corresponde este directorio.

#3. Cuenta lo que encontraste y recomienda

Antes de cambiar nada, dile a la persona para la que trabajas, en pocas líneas, qué hay y qué recomiendas, y pídele que lo confirme. Haz una propuesta concreta, a partir de su código:

Esto es el backend de una tienda de bicicletas con una API de productos
(GET /productos) y una política de devoluciones en docs/devoluciones.md.
Todavía no hay un agente de Vatio.

Recomiendo un agente para WhatsApp y la web que:
- responda stock y precios llamando a GET /productos (tool consultar_stock)
- responda reparaciones, horarios y devoluciones desde conocimiento escrito a partir de docs/
- derive a una persona los reclamos y las devoluciones de dinero

Antes de escribirlo, necesito que me respondas cuatro cosas.

#4. Pregúntale al dueño solo lo que el código no responde

Cuatro preguntas, breves, todas juntas:

1. ¿A qué se dedica el negocio y quién escribe?
2. ¿Qué no debe decir ni prometer nunca el agente?
3. ¿Cuándo tiene que tomar la conversación una persona?
4. ¿De cuáles de tus sistemas debe leer: una API, un calendario, un catálogo?

No inventes datos del negocio que no te dieron: precios, horarios, políticas, plazos de entrega. Si el dueño todavía no lo sabe, escribe la instrucción para que el agente diga que no lo sabe y ofrezca a una persona. Cada respuesta tiene su lugar:

#5. Escribe el agente

#vatio.yml

Crea el workspace en el repositorio al que pertenece el agente, normalmente el del backend al que va a llamar. init escribe vatio.yml en el directorio actual y una sección de Vatio en AGENTS.md, y no necesita una cuenta:

vatio init ciclo-norte

Después reemplaza el vatio.yml inicial. El ejemplo es una tienda de bicicletas con taller:

workspace: ciclo-norte
agent:
  name: Ciclo Norte
  personality: Cercano, directo y breve.
  instructions: |
    Ayudas a los clientes de Ciclo Norte, una tienda de bicicletas con
    taller. Respondes sobre bicicletas y repuestos en stock, precios de
    reparación, horarios y devoluciones.

    Stock y precios: llama a consultar_stock. Solo di que algo está en
    stock, o di su precio, cuando consultar_stock lo haya devuelto.

    Reparaciones, horarios y devoluciones: busca primero en
    knowledge_lookup. Si no encuentras la respuesta, dilo y ofrece pasarle
    la pregunta al equipo.

    Reglas que nunca rompes:
    - Nunca inventes un producto, un precio ni una fecha de entrega.
    - Nunca prometas un descuento ni un plazo de reparación.
  tools: [consultar_stock, knowledge_lookup]
  knowledge: [tienda]
  handoff:
    after_turns: 10
    when:
      - un reclamo por una compra o una reparación
      - el cliente pide una devolución de dinero

Cómo escribirlo:

• agent.instructions es el único campo obligatorio. Escríbelo como qué hace el agente, después qué tool o qué conocimiento responde cada tipo de pregunta, y después las reglas. Vatio agrega el contexto del negocio, el contacto, las descripciones de las tools y sus propias instrucciones de plataforma, así que no las repitas.
• Reglas escritas como reglas. «Nunca prometas un descuento» en su propia viñeta se sostiene mucho mejor que una frase sobre el tono.
• handoff es lo que le da al agente la tool para pasarle la conversación a una persona, con las condiciones de when, en las palabras del dueño. after_turns es el piso: pasados esos mensajes del cliente, deriva igual. Un cliente que pide hablar con una persona siempre la obtiene.
• Idioma. El agente responde en el idioma del visitante. Dilo en instructions solo si el negocio necesita un idioma fijo.
• Una clave raíz desconocida hace fallar el push. Un bloque business: o hours: se ignora con una advertencia.

#Tools

Una tool es un request HTTP a la API del negocio. El nombre del archivo es la clave de la tool, y la tool solo existe para el agente cuando su clave está en agent.tools. Las direcciones y las llaves van en secrets, nunca en el repositorio:

vatio secrets set TIENDA_API https://api.ciclo-norte.example
vatio secrets set TIENDA_API_KEY sk_live_...

tools/consultar_stock.yml:

description: Revisa el stock y el precio de una bicicleta, un repuesto o un accesorio.
when_to_use: El cliente pregunta si hay algo disponible o cuánto cuesta.
parameters:
  type: object
  properties:
    producto: { type: string, description: "Nombre, modelo o talla, por ejemplo casco trail M" }
  required: [producto]
access: public
request:
  method: GET
  base_url: "$env.TIENDA_API"
  path: /productos
  requires: [params.producto]
  headers:
    Authorization: "Bearer $env.TIENDA_API_KEY"
  query:
    q: "$params.producto"
respond:
  data:
    productos: "$.productos"
  message:
    when_empty: No hay productos con ese nombre.
    default: "Encontré {{count}} productos."

Lo que más rompe las tools:

• Un endpoint por tarea. Todo lo que necesite ramificaciones, una segunda llamada o una respuesta derivada es código, y va en el backend. Si el endpoint que el agente necesita no existe, propón agregarlo ahí y dilo antes de escribirlo.
• Status reales. Una respuesta que no es 2xx se convierte en un error que el agente puede explicar; un error dentro de un 200 parece un éxito. El mensaje de un error debe decir qué cambiar, para que el agente pueda corregirse en su siguiente llamada.
• Nada de localhost. Las tools corren en los servidores de Vatio. La API tiene que ser accesible desde internet; un deploy de staging sirve.
• Las pruebas llegan al backend. Una conversación en preview llama a la API real. Para las escrituras, dale al secret un valor de staging con --tests, que usan preview y todas las repeticiones de los evals.
• Límites. Una llamada se corta a los 8 segundos, y una respuesta hace como máximo 12 llamadas a tools.
• Clientes con sesión iniciada. Una tool que lee los datos propios de un cliente es access: private, con un bloque auth:: su backend firma un token que dice quién es el cliente, y Vatio solo lo verifica. Si la app inicia sesión con Supabase, corre primero vatio auth --supabase. Conectar tu backend lo explica.

#Conocimiento

El conocimiento es Markdown que escribes tú, una entrada por tema, con títulos que puedan responder una pregunta por sí solos. Una base de conocimiento listada en agent.knowledge tiene que existir antes del push:

vatio kb create tienda
vatio kb write tienda reparaciones reparaciones.md
vatio kb write tienda horarios-y-devoluciones horarios-y-devoluciones.md
vatio kb show tienda

Escribe las entradas a partir de la documentación y las políticas del repositorio, y de lo que te dijo el dueño. Nada de un sitio web le llega al agente si no lo pones en una entrada.

#6. Revisa, haz push y pruébalo

vatio diff
vatio push

diff valida los archivos y muestra lo que cambiaría el push. El primer push inicia la sesión del developer: abre su navegador, o imprime un link para mostrárselo si no puede. El developer inicia sesión con correo, Google o GitHub y revisa que el código de la página coincida con el de la terminal. Si el comando se cansa de esperar, córrelo de nuevo después de que haya iniciado sesión; retoma la misma página.

push, diff y secrets trabajan en preview. Si el agente ya está publicado y preview tiene un push sin publicar hecho desde otra rama de git, push se rechaza para no pisarlo: publícalo primero, o reemplázalo con --force solo si el developer está de acuerdo.

Después prueba las conversaciones que te dicen si funciona:

vatio chat "¿Tienen un casco trail talla M?"
vatio chat "El casco que compré la semana pasada se rompió. Quiero que me devuelvan el dinero"
vatio chat --new "¿Me haces un descuento si pago en efectivo?"
vatio chat show

vatio chat show imprime cada llamada a tools con lo que respondió la API. Cuando una respuesta está mal, busca la causa, que muchas veces está en la respuesta de la tool y no en las instrucciones, corrígela, haz push de nuevo y repite la misma conversación.

#7. Entrega el link

vatio push imprime un link después de Try it:. Abre la página Probar del inbox, donde el developer y el dueño prueban el agente:

• Chat web, en la página.
• WhatsApp: un código QR conecta su teléfono al número compartido de preview de Vatio, sin cuenta de Meta. Hasta cinco teléfonos de prueba.
• Instagram: una cuenta compartida de preview, hasta cinco cuentas de prueba.

Entrégales el link con lo que probaste y cómo respondió, y lo que solo el dueño puede decidir:

El agente está en preview: <el link de Try it>

Probé cinco conversaciones:
- stock de un casco trail: llamó a consultar_stock y respondió que hay 2 a $45
- casco roto, quiere su dinero de vuelta: derivó a una persona
- descuento por pagar en efectivo: se negó, como dicen las reglas
- una pregunta por marcas de neumáticos: no está en el conocimiento, ofreció a una persona
- un visitante nuevo que saluda: se presentó y preguntó qué necesitaba

Pendiente para ti: los precios de reparación de reparaciones.md salen de
la carpeta docs; revisa que estén al día.

#8. Publica solo cuando te lo pidan

vatio publish

Córrelo cuando el developer o el dueño te lo pidan, y no antes. La primera publicación no tiene control; las siguientes se rechazan si la versión de preview no se probó con vatio eval o si rompe un reporte que live pasa. Después, los canales:

• Sitio web. Un token para su dominio, y un script tag:

vatio tokens create --env live --label website --origin https://ciclo-norte.example

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="ciclo-norte"
        data-token="vatpub_REPLACE_ME"></script>

• WhatsApp e Instagram. El dueño los conecta en el inbox, en Canales, en live: su número de empresa con el registro de Meta y después el interruptor En vivo; una cuenta profesional de Instagram. vatio whatsapp imprime el link.

vatio rollback restaura el deploy anterior de live, configuración y conocimiento juntos.

#9. Antes de terminar

1. Si un error o la documentación te dejó adivinando, dilo: vatio feedback "qué estabas haciendo y qué faltaba". Lo leen las personas que escriben ambos.
2. En Claude Code, corre vatio share-session --should-ask al final. Si imprime yes, muéstrale a la persona para la que trabajas lo que se enviaría (vatio share-session --save ARCHIVO) y pregúntale una vez si se lo envías al equipo de Vatio: enviarla, ahora no, o no volver a preguntar (vatio share-session --never). Si un control de permisos no te deja enviarla, dale vatio share-session --id ID --yes para que la corra en su terminal y después revisa con vatio share-session --list, que marca las sesiones enviadas. Si imprime no, no digas nada.

#Errores que cuestan una sesión

#Cuando el agente ya existe

Si el proyecto ya tiene un vatio.yml, el trabajo es distinto: inicia sesión con la dirección con la que invitaron al developer, compara la carpeta con live (vatio diff --env live), explica el agente a partir del vatio.yml y recomienda a partir de lo que encuentres. vatio flags lista lo que reportaron los supervisores, que la skill vatio-improve trabaja, y vatio tools lista las llamadas a tools que están fallando, que se corrigen en el backend al que llaman. El ciclo es vatio push a preview, vatio eval en segundo plano y vatio publish cuando te lo pidan. Mira Mejorar tu agente.

Actualizado: 11 de octubre de 2026