#Agente de IA para e-commerce y retail

Un agente de IA para una tienda online atiende a tus clientes por WhatsApp, por mensajes directos de Instagram y en el widget de chat de tu tienda: si un producto está disponible en su talla, cuánto cuesta, dónde va su pedido y cómo devolverlo o cambiarlo. Lee tu catálogo y tus pedidos a través de tu propia API, y muestra un pedido solo después de que tu backend verificó el número de pedido contra el correo del comprador. Con Vatio describes ese agente en un archivo vatio.yml, y el mismo agente responde en los tres canales.

Esta guía construye uno de punta a punta: las instrucciones, las tools que llegan a tu catálogo y a tus pedidos, el conocimiento que lee y las reglas que le impiden inventar un precio o un descuento.

#Qué resuelve el agente

Casi todo lo que le llega a una tienda son las mismas pocas preguntas:

• Stock y tallas. «¿Tienen la chaqueta impermeable en M?». El agente busca en el catálogo y responde con las tallas que de verdad hay y el link del producto.
• Precios. El precio que devuelve tu catálogo, nunca uno que el agente calculó por su cuenta.
• Estado del pedido. El cliente da el número de pedido y el correo con que compró; tu backend verifica que coincidan y devuelve el estado y el seguimiento.
• Devoluciones y cambios. El agente revisa la política, abre la devolución o el cambio por otra talla y envía el link de instrucciones que devuelve tu backend.
• Dudas de talla. «Normalmente uso M, ¿qué talla me sirve en este pantalón?». Responde desde tu guía de tallas.
• Todo lo demás va a una persona. Productos dañados o equivocados, problemas de pago, reembolsos, reclamos.

Una conversación típica por Instagram, con lo que el agente hizo por dentro:

Cliente: holaa, ¿la tienen en M? (captura de un post)

Agente: Es la chaqueta impermeable Cordillera en verde musgo. La M está disponible, a $89.990: https://tienda-cumbre.example/p/cordillera-musgo

Cliente: ¿y cómo queda? estoy entre M y L

Agente: Tiene un corte holgado para usar con capas, así que elige tu talla de siempre. Si la vas a usar sobre un polar grueso, mejor la L, que también está disponible.

Detrás de esas dos respuestas estuvo la captura, leída como imagen, una llamada a consultar_stock y una búsqueda en la guía de tallas. El link del producto vino de la tool, y eso es lo que le permite al agente enviarlo. Cada llamada a una tool queda visible en el inbox, junto a la respuesta que produjo.

#Antes de escribir nada: cinco preguntas para la tienda

1. ¿Qué preguntan más los clientes? Normalmente stock y tallas, después el estado del pedido, después devoluciones.
2. ¿Dónde está la verdad? La API del catálogo para stock y precios, la API de pedidos, la política de devoluciones escrita.
3. ¿Qué no debe hacer nunca? Inventar precios, descuentos o fechas de entrega; pedir datos de tarjeta; prometer un reembolso.
4. ¿Cuándo toma la conversación una persona? Productos dañados o equivocados, problemas de pago, reclamos, cualquiera que pida hablar con alguien.
5. ¿Cuál es la política de devoluciones, exactamente? Plazo, estado del producto, quién paga el envío, cambio o reembolso. El agente necesita las palabras de la propia tienda.

Las respuestas se convierten en las instrucciones, las condiciones de handoff, las tools y el conocimiento, en ese orden.

#El vatio.yml

workspace: tienda-cumbre
agent:
  name: Tienda Cumbre
  personality: Cercano, rápido y concreto. Respuestas cortas, sin presionar la venta.
  instructions: |
    Ayudas a los clientes de Tienda Cumbre, una tienda de ropa outdoor, con
    stock, tallas, precios, estado de pedidos, devoluciones y cambios.

    Productos: llama a consultar_stock ante cualquier pregunta sobre un
    producto, una talla, un color o un precio. Da el precio, las tallas
    disponibles y el link del producto que devolvió. Si el cliente manda
    una foto o una captura, busca por lo que se ve, y pregunta si no estás
    seguro de qué producto es.

    Tallas: busca la guía de tallas en knowledge_lookup antes de recomendar
    una.

    Pedidos: pide el número de pedido y el correo usado en la compra, y
    llama a estado_pedido. Si devuelve un error, di que no encontraste un
    pedido con ese número y ese correo, y pide que revise ambos.

    Devoluciones y cambios: revisa la política con knowledge_lookup, pide
    el número de pedido, el correo, el producto y el motivo, y llama a
    solicitar_devolucion. Envía el link de instrucciones que devuelva.

    Reglas que nunca rompes:
    - Nunca des un precio, descuento, stock o fecha de entrega que no haya
      devuelto una tool. Nunca inventes un código de descuento.
    - Nunca pidas números de tarjeta, contraseñas ni códigos recibidos por
      SMS, y nunca recibas un pago en la conversación.
    - Nunca prometas un reembolso. Los reembolsos los decide el equipo.
    - Nunca prometas avisarle al cliente más tarde, por ejemplo cuando
      vuelva una talla. Solo respondes mensajes.
  tools: [consultar_stock, estado_pedido, solicitar_devolucion, knowledge_lookup, identify_contact]
  knowledge: [tienda]
  links:
    devoluciones: https://tienda-cumbre.example/devoluciones
    categoria:
      url: https://tienda-cumbre.example/c/{categoria}
      when: El cliente quiere ver un tipo de producto.
      values:
        categoria: [chaquetas, pantalones, primeras-capas, calzado]
  handoff:
    after_turns: 15
    when:
      - un producto llegó dañado, equivocado o incompleto
      - un problema de pago, como un cobro doble
      - el cliente pide un reembolso
      - un reclamo por un pedido o por la atención

Algunas decisiones que vale la pena explicar:

• Cada número viene de una tool. Los precios y el stock cambian durante el día. «Nunca des lo que una tool no devolvió» convierte una suposición en una consulta, y consultar_stock es esa consulta.
• Los links de producto vienen de la tool, no del prompt. El agente solo puede enviar URLs que se le dieron, y un link que tu catálogo devolvió en esta conversación cuenta, así que cada página de producto se puede compartir sin listarla. links cubre las páginas fijas: la política de devoluciones y una página por categoría, que se expanden al hacer deploy.
• Escribe primero solo cuando tu backend lo pide. El agente nunca decide por su cuenta escribirle a alguien más tarde. Los avisos de envío y los recordatorios de carrito son tu backend llamando a la Messages API cuando ocurren los eventos de tu tienda. Mientras no armes uno, la última regla evita que el agente prometa un mensaje que nadie va a enviar.
• Una derivación espera en el inbox. Dentro del horario de atención, que se configura en la página Negocio del inbox (lunes a viernes de 9:00 a 18:00 y sábado de 10:00 a 14:00), el agente se queda en silencio para que alguien tome la conversación; fuera de él sigue ayudando y avisa que el equipo responderá. Vatio todavía no le avisa a nadie de una derivación, así que en ese horario alguien tiene que tener el inbox abierto.

#Tools: tu catálogo y tus pedidos

Una tool es un request HTTP a tu backend, descrito en YAML. Guarda la dirección y la llave como secrets:

vatio secrets set TIENDA_API https://api.tienda-cumbre.example
vatio secrets set TIENDA_API_KEY sk_live_...

tools/consultar_stock.yml:

description: Busca en el catálogo, con precios, tallas disponibles y links de producto.
when_to_use: El cliente pregunta por un producto, una talla, un color, un precio o si hay stock.
parameters:
  type: object
  properties:
    busqueda: { type: string, description: "nombre o descripción del producto, por ejemplo chaqueta impermeable verde" }
    talla: { type: string, description: "por ejemplo S, M, L, 42" }
  required: [busqueda]
access: public
request:
  method: GET
  base_url: "$env.TIENDA_API"
  path: /productos/buscar
  headers:
    Authorization: "Bearer $env.TIENDA_API_KEY"
  query:
    q: "$params.busqueda"
    talla: "$params.talla"
respond:
  data:
    productos: "$.productos"
  message:
    when_empty: Nada en el catálogo coincide con eso.
    default: "Encontré {{count}} productos."

tools/estado_pedido.yml:

description: Consulta el estado y el seguimiento de un pedido.
when_to_use: El cliente pregunta por su pedido y dio el número de pedido y el correo de la compra.
parameters:
  type: object
  properties:
    numero_pedido: { type: string, description: "por ejemplo TC-10482" }
    correo: { type: string }
  required: [numero_pedido, correo]
access: public
request:
  method: POST
  base_url: "$env.TIENDA_API"
  path: /pedidos/consulta
  requires: [params.numero_pedido, params.correo]
  headers:
    Authorization: "Bearer $env.TIENDA_API_KEY"
  body:
    numero_pedido: "$params.numero_pedido"
    correo: "$params.correo"
respond:
  data:
    pedido: "$.pedido"

solicitar_devolucion es un POST con el número de pedido, el correo, el producto, el motivo y, si es un cambio, la talla que quiere en su lugar. Tu backend verifica el correo contra el pedido y el producto contra el plazo de devolución, crea la devolución y responde con su código y un link a las instrucciones. El agente no puede enviar archivos, así que la etiqueta vive detrás de ese link. Si tu plataforma necesita dos llamadas para esto, pon un endpoint en tu backend que haga ambas.

#Un número de pedido no es una contraseña

Los números de pedido son cortos, muchas veces correlativos, y vienen impresos en cada comprobante y en cada caja. Por eso estado_pedido pide también el correo, y por eso la verificación vive en tu backend: busca el pedido, compara el correo y responde 404 tanto si el pedido no existe como si el correo no coincide, para que nadie pueda usar al agente para averiguar qué pedidos existen. Los parámetros de una tool los llena el modelo, así que una verificación escrita solo en el prompt es una que alguien puede convencerlo de saltarse.

Devuelve solo lo que la conversación necesita: estado, transportista, link de seguimiento y productos. Deja fuera la dirección, el teléfono y los datos de pago, porque todo lo que devuelve una tool el modelo lo puede repetir. Limita la frecuencia de llamadas al endpoint como harías con un formulario de login.

En WhatsApp e Instagram un cliente es anónimo mientras no inicie sesión, así que para él solo corren tools públicas, y la verificación de número más correo es el patrón. Un cliente con sesión iniciada puede saltársela: en tu propio sitio tu backend firma un token que dice quién es, en WhatsApp e Instagram auth.sign_in_url lo lleva a tu página de inicio de sesión para obtener uno, y una tool marcada access: private lee sus pedidos con $auth.subject, nunca con un ID de cliente que llenó el modelo. Conectar tu backend lo explica paso a paso.

#Conocimiento: tallas, envíos y devoluciones

vatio kb create tienda
vatio kb write tienda guia-de-tallas guia-de-tallas.md
vatio kb write tienda envios envios.md
vatio kb write tienda devoluciones devoluciones.md
vatio kb write tienda medios-de-pago medios-de-pago.md

Una buena entrada responde una pregunta por sección:

# Guía de tallas

## Chaquetas impermeables
Corte holgado para usar con capas. Si estás entre dos tallas, elige la de
siempre; para usarla sobre un polar grueso, sube una.
Pecho (cm): S 92–97, M 98–103, L 104–110, XL 111–117.

## Pantalones de trekking
Corte ajustado. Si estás entre dos tallas, sube una.
Cintura (cm): S 76–80, M 81–86, L 87–92, XL 93–99.

Vatio no lee tu sitio web, así que las tablas de tallas de tus páginas de producto también necesitan una entrada. Cuando el plazo de devolución cambia para las fiestas, un supervisor edita la entrada desde el inbox y el agente responde con la nueva; cada edición queda guardada como versión.

#Fotos de un producto dañado

«Me llegó así», con una foto, es el mensaje en que una tienda más necesita a una persona y en que la primera respuesta más importa. El agente lee imágenes de hasta 8 MB y audios transcritos, y Vatio agrupa la foto y los mensajes que llegan junto con ella en un solo turno antes de responder. Así el agente ve la costura rota, pide el número de pedido y el correo si no los tiene, revisa el pedido con estado_pedido y deriva la conversación con todo en un solo lugar.

No decide el resultado: un reemplazo o un reembolso lo decide tu equipo, y por eso los productos dañados están en handoff.when. Quien toma la conversación en el inbox ve el hilo completo, foto incluida, y cada llamada a tools que hizo el agente. El agente no puede enviar imágenes, así que una etiqueta de envío prepagada o la confirmación de un reemplazo salen por donde tu tienda ya las envía.

#Pruébalo antes que cualquier cliente

vatio push
vatio chat "¿Tienen la chaqueta impermeable Cordillera en M?"
vatio chat "Mi pedido es TC-10482, correo ana@correo.example. ¿Dónde va?"
vatio chat --new "Pedido TC-10482. No me acuerdo del correo, solo dime a qué dirección va"
vatio chat --new "¿Me das un código de 30% de descuento?"
vatio chat --new "Avísame cuando vuelva la L"
vatio chat show

Los tres chats con --new son los importantes: un número de pedido sin su correo, que no debe obtener nada; un descuento que no debe inventar; y una promesa de escribir primero que no debe hacer. chat show muestra cada llamada a tools. El agente llama a tus tools de verdad, así que apunta el entorno donde pruebas a una tienda de sandbox con un secret que valga solo para él. Después agrega tu teléfono como número de prueba y tu cuenta de Instagram como cuenta de prueba en la página Probar del inbox, y envía una foto desde cada uno al número y la cuenta compartidos de preview.

#Que mejore cada semana

Cuando tu equipo responde desde el inbox, marca cualquier respuesta que estuvo mal y escribe lo que debió pasar: una talla mal recomendada, una política mal citada. vatio flags convierte esas notas en un documento desde el cual tu coding agent puede corregir, cada flag se vuelve un caso de eval, y el flag queda marcado como resuelto cuando live lo pasa. Mira Mejorar tu agente.

#Publicar

vatio publish
vatio tokens create --env live --label tienda --origin https://tienda-cumbre.example

En la página Canales del inbox, conecta el número de WhatsApp Business de la tienda y su cuenta profesional de Instagram, y activa el interruptor En vivo de WhatsApp. Instagram responde apenas la cuenta queda conectada. En la tienda, pega el script del widget con el token vatpub_ que acabas de crear:

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

El aspecto del widget se configura en Canales → Widget web, en el inbox, y el nombre, la descripción y el horario del negocio con que trabaja el agente, en la página Negocio del inbox; nada de eso va en vatio.yml. Tu equipo puede seguir usando la app de WhatsApp Business en el teléfono: si alguien responde desde ahí, toma la conversación, y el agente se hace a un lado hasta que la liberen. En WhatsApp e Instagram, una conversación sigue mientras el último mensaje del cliente tenga menos de ocho horas; el siguiente mensaje después de eso empieza una nueva.

Actualizado: 11 de octubre de 2026