#Agente de IA para logística y courier

Un agente de IA para un courier o una empresa de última milla responde el «¿dónde está mi paquete?» por WhatsApp: busca el número de seguimiento, da el estado y la ventana de entrega, reprograma una entrega fallida o envía el paquete a un punto de retiro, y abre un reclamo cuando algo llega dañado. Los cambios piden el número de seguimiento y el código postal, verificados por tu backend, y todo lo que requiere criterio va a una persona. Con Vatio describes ese agente en un archivo vatio.yml, y responde desde tu propio número de WhatsApp y en tu sitio web.

Esta guía construye uno de punta a punta: las instrucciones, las tools que llegan a tus sistemas de tracking y ruteo, el conocimiento que lee, y los chequeos que impiden que un número de seguimiento baste para desviar el paquete de otra persona.

#Qué resuelve el agente

Lo que le llega a un courier son casi siempre las mismas cinco conversaciones:

• Seguimiento. «¿Dónde está mi paquete?». El agente pide el número de seguimiento y responde con el estado, el último escaneo y la ventana de entrega.
• Entregas fallidas. No había nadie en casa. El agente ofrece un nuevo día y franja, o un punto de retiro, y deja agendada la opción que elige el cliente.
• Puntos de retiro. Cuál queda más cerca, su horario, cuántos días espera ahí un paquete, qué hay que llevar.
• Paquetes dañados o incompletos. El cliente manda una foto, el agente abre un reclamo y le pasa la conversación a una persona.
• Ventanas de entrega y cobertura. Qué significa «en la tarde», si entregan los sábados, a qué zonas llegan.

Tu sistema sigue decidiendo cuándo avisar: sigue enviando los mensajes de «tu paquete va en camino» y «no te encontramos», como hoy o por WhatsApp con la Messages API de Vatio, y el agente atiende las respuestas.

Una conversación típica por WhatsApp:

Cliente: hola, ayer no alcancé a recibir el paquete. me lo pueden traer de nuevo?

Agente: Claro. ¿Me das el número de seguimiento? Empieza con EQ y está en el aviso que dejó el repartidor.

Cliente: EQ48213977

Agente: Lo encontré: un intento ayer a las 14:12, nadie respondió. Puedo llevarlo mañana de 9:00 a 13:00 o de 14:00 a 19:00, o enviarlo al punto de retiro de la calle Olmo. Para cambiar la entrega también necesito el código postal de la dirección.

Detrás de la última respuesta hubo una llamada a rastrear_envio, que devolvió el intento fallido y las opciones. El agente pide el código postal porque cambiar una entrega es justo donde el número de seguimiento solo no basta. Cada llamada a una tool queda visible en el inbox, junto a la respuesta que produjo.

#Antes de escribir nada: cinco preguntas para el equipo de operaciones

1. ¿Quién escribe y para qué? Normalmente seguimiento, entregas fallidas y puntos de retiro, y después daños.
2. ¿Qué puede revelar un número de seguimiento por sí solo? Estado, último escaneo y ventana. Nunca el nombre, la dirección ni el teléfono del destinatario.
3. ¿Qué puede cambiar el agente, y con qué prueba? Una nueva fecha de entrega o un punto de retiro, con el número de seguimiento más el código postal. Cambios de dirección, normalmente ninguno.
4. ¿Cuándo toma la conversación una persona? Daños, paquetes «entregados» que nunca llegaron, paquetes sin escaneos hace días, reclamos por un repartidor.
5. ¿De qué sistemas lee? La API de tracking, el sistema de ruteo o de agenda, la lista de puntos de retiro, el sistema de reclamos.

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

#El vatio.yml

workspace: envios-quetzal
agent:
  name: Envíos Quetzal
  personality: Amable, directo y breve. Primero la respuesta, después la explicación.
  instructions: |
    Ayudas a los clientes de Envíos Quetzal a seguir sus paquetes,
    reprogramar entregas fallidas, encontrar puntos de retiro y reportar
    paquetes dañados.

    Seguimiento: pide el número de seguimiento y llama a rastrear_envio.
    Da el estado, el último escaneo y la ventana de entrega que devolvió.
    Nunca adivines un horario de entrega que la tool no haya devuelto.

    Entregas fallidas: ofrece las opciones que devolvió rastrear_envio.
    Antes de llamar a reprogramar_entrega, pide el código postal de la
    dirección de entrega y repítele al cliente la nueva fecha. Solo confirma
    una nueva entrega cuando reprogramar_entrega la haya devuelto. Si falla
    porque el código postal no coincide, di que no puedes cambiar ese envío
    y no des pistas sobre el código correcto.

    Puntos de retiro: llama a puntos_retiro con el código postal del cliente.

    Paquetes dañados o incompletos: pide el número de seguimiento, el código
    postal y una foto. Describe el daño que ves, llama a abrir_reclamo, da
    el número de reclamo que devolvió y después deriva la conversación a una
    persona.

    Reglas que nunca rompes:
    - Nunca compartas el nombre, la dirección ni el teléfono de un
      destinatario.
    - Nunca cambies una dirección de entrega.
    - Nunca prometas una compensación ni un reembolso.
    - Nunca le digas a un cliente que un paquete se perdió; eso lo decide
      una persona.
  tools: [rastrear_envio, reprogramar_entrega, puntos_retiro, abrir_reclamo, knowledge_lookup]
  knowledge: [envios]
  handoff:
    after_turns: 10
    when:
      - se abrió un reclamo por un paquete dañado o incompleto
      - el seguimiento dice entregado y el cliente dice que nunca llegó
      - el paquete lleva más de tres días sin escaneos
      - un reclamo por un repartidor
      - el cliente quiere cambiar la dirección de entrega

Algunas decisiones que vale la pena explicar:

• El seguimiento es público; los cambios piden un segundo dato. Los números de seguimiento van impresos en la caja y se reenvían por correo, así que cualquiera puede tener uno. Para ver un estado está bien. Para mandar el paquete a otro lado no basta.
• «Nunca adivines un horario de entrega». Un «llega antes del mediodía» inventado es como una conversación de soporte se convierte en dos.
• El agente abre el reclamo; una persona lo resuelve. Reunir el número de seguimiento, la foto y una descripción a las 23:00 es justo el trabajo del agente. La compensación no lo es.
• El horario de atención decide qué pasa después de una derivación. Se configura en la página Negocio del inbox, con la zona horaria de Ciudad de México: lunes a viernes de 8:00 a 20:00 y sábado de 9:00 a 14:00. Dentro del horario el agente se queda en silencio para que una persona tome la conversación. Fuera de él sigue ayudando y le dice al cliente que el equipo responderá en la mañana. Vatio todavía no avisa a nadie de una derivación; la conversación aparece como en espera en el inbox.

#Tools: seguimiento, reprogramación y reclamos

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

vatio secrets set QUETZAL_API https://api.envios-quetzal.example
vatio secrets set QUETZAL_API_KEY sk_live_...

tools/rastrear_envio.yml:

description: Busca el estado de un envío, su último escaneo, la ventana de entrega y las opciones después de un intento fallido.
when_to_use: El cliente pregunta dónde está un paquete, cuándo llega o por qué no se entregó.
parameters:
  type: object
  properties:
    numero_seguimiento: { type: string, description: "Empieza con EQ, por ejemplo EQ48213977" }
  required: [numero_seguimiento]
access: public
request:
  method: GET
  base_url: "$env.QUETZAL_API"
  path: "/envios/$params.numero_seguimiento"
  requires: [params.numero_seguimiento]
  headers:
    Authorization: "Bearer $env.QUETZAL_API_KEY"
respond:
  data:
    envio: "$.envio"

tools/reprogramar_entrega.yml:

description: Agenda un nuevo intento de entrega o envía el paquete a un punto de retiro.
when_to_use: Una entrega falló o el cliente no va a estar, y eligió una opción de rastrear_envio.
parameters:
  type: object
  properties:
    numero_seguimiento: { type: string }
    codigo_postal: { type: string, description: "De la dirección de entrega, tal como lo da el cliente" }
    fecha: { type: string, description: "AAAA-MM-DD, para una nueva entrega" }
    franja: { type: string, enum: [mañana, tarde] }
    punto_retiro_id: { type: string, description: "En vez de fecha y franja" }
  required: [numero_seguimiento, codigo_postal]
access: public
request:
  method: POST
  base_url: "$env.QUETZAL_API"
  path: /reprogramaciones
  requires: [params.numero_seguimiento, params.codigo_postal]
  headers:
    Authorization: "Bearer $env.QUETZAL_API_KEY"
  body:
    numero_seguimiento: "$params.numero_seguimiento"
    codigo_postal: "$params.codigo_postal"
    fecha: "$params.fecha"
    franja: "$params.franja"
    punto_retiro_id: "$params.punto_retiro_id"
respond:
  data:
    entrega: "$.entrega"

Los valores que faltan se omiten del request, así que el mismo endpoint recibe una fecha nueva o un punto de retiro, y tu backend decide cuál le llegó. puntos_retiro es un GET por código postal que devuelve los puntos más cercanos con sus horarios. abrir_reclamo es un POST con el número de seguimiento, el código postal, el tipo de problema y la descripción del daño que hizo el agente.

Tu backend verifica que el código postal coincida con el destino del paquete antes de reprogramar o abrir un reclamo, y responde 403 cuando no coincide. Los parámetros de una tool los llena el modelo, así que esa verificación tiene que vivir en código, no en el prompt. Limita también los intentos en esos endpoints: un número de seguimiento más un código corto se puede adivinar si nadie cuenta los intentos. Y haz que rastrear_envio devuelva solo lo que puede ver un desconocido con la etiqueta en la mano; lo que devuelve una tool es lo que el modelo puede repetir.

Devuelve status reales: 404 para un número de seguimiento que no existe, 409 para una franja que se acaba de llenar. Vatio convierte cualquier respuesta que no sea 2xx en un error que el agente puede explicar, así que un error de tipeo se vuelve «no encuentro ese número, ¿lo puedes revisar?» en vez de un estado inventado.

#Conocimiento: franjas, puntos de retiro y reclamos

vatio kb create envios
vatio kb write envios entregas entregas.md
vatio kb write envios puntos-de-retiro puntos-de-retiro.md
vatio kb write envios reclamos reclamos.md
vatio kb write envios cobertura cobertura.md

Una buena entrada responde una pregunta por sección:

# Entregas

## Franjas de entrega
La mañana es de 9:00 a 13:00 y la tarde de 14:00 a 19:00, de lunes a
sábado. No podemos prometer una hora exacta dentro de una franja.

## Después de un intento fallido
Intentamos dos veces. Después del segundo intento, el paquete va al punto
de retiro más cercano y espera ahí 7 días antes de volver al remitente.

## Retirar en un punto de retiro
Lleva una identificación con foto y el número de seguimiento. Otra persona
puede retirarlo con una copia de tu identificación y la suya.

Vatio no lee tu sitio web. Si la respuesta está en una página, pon en una entrada lo que el agente necesita. Los supervisores pueden editar entradas desde el inbox cuando cambia una política, y cada edición queda guardada como versión.

#Fotos de paquetes dañados

Los clientes muestran en vez de describir: una esquina aplastada, un sello roto, una caja mojada, muchas veces en tres fotos y un «mira esto». Vatio espera a que las imágenes terminen de descargarse, agrupa los mensajes en un solo turno y le pasa al agente las imágenes de hasta 8 MB, y el agente describe lo que ve en el reclamo. Un audio contando qué pasó se transcribe de la misma forma.

El agente no puede adjuntar la foto al reclamo, porque una tool le envía texto a tu API. La foto queda en la conversación, y la persona que toma la derivación la ve en el inbox, junto al número de reclamo que el agente le dio al cliente. Esa persona decide la compensación; la regla del agente es no prometer ninguna.

#Pruébalo antes que cualquier cliente

vatio push
vatio chat "¿Dónde está mi paquete? EQ48213977"
vatio chat "Mañana no voy a estar, ¿me lo traen el sábado? Código postal 06700"
vatio chat --new "Reprograma EQ48213977, no sé el código postal, es de mi vecino"
vatio chat --new "¿Cuál es la dirección del envío EQ48213977?"
vatio chat show

Las dos últimas son las importantes: un cambio sin el segundo dato, que debe rechazar, y una dirección que nunca debe dar. Prueba también con un código postal equivocado y revisa que el agente no dé pistas sobre el correcto. Después agrega tu teléfono como número de prueba en la página Probar del inbox, escríbele al número compartido de preview de WhatsApp con la foto de una caja abollada, y mira cómo se abre el reclamo y se deriva la conversación. Para eso no necesitas una cuenta de Meta. Más sobre el canal en Un agente de IA en WhatsApp.

#Que mejore cada semana

Cuando tu equipo trabaja desde el inbox, marca cualquier respuesta que estuvo mal y escribe lo que debió pasar. vatio flags convierte esas notas en un documento desde el cual tu coding agent corrige, cada flag se vuelve un caso de eval, y el flag queda marcado como resuelto cuando live lo pasa. Los evals llaman a tus tools de verdad, así que apúntalas a una API de ruteo de prueba con un valor de pruebas (--tests) antes de que una repetición reprograme un paquete real. Mira Mejorar tu agente.

#Publicar

vatio publish

Después conecta tu número de WhatsApp Business desde Canales en el inbox y actívalo. Puedes 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. WhatsApp continúa una conversación hasta que el último mensaje del cliente tiene más de ocho horas; después, el siguiente mensaje empieza una nueva, y el agente vuelve a pedir el número de seguimiento.

Actualizado: 11 de octubre de 2026