> Construye un agente de IA que rastrea envíos, reprograma entregas fallidas, busca puntos de retiro y abre reclamos por WhatsApp, con chequeos en tu backend. # 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](https://vatio.ai/docs/api/messages) 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` ```yaml 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: ```bash vatio secrets set QUETZAL_API https://api.envios-quetzal.example vatio secrets set QUETZAL_API_KEY sk_live_... ``` `tools/rastrear_envio.yml`: ```yaml 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`: ```yaml 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 ```bash 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: ```markdown # 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 ```bash 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](/es/guias/agente-ia-para-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](/es/guias/mejorar-tu-agente-de-ia). ## Publicar ```bash 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. ## Preguntas frecuentes ### ¿Un agente de IA puede hacer el seguimiento de paquetes por WhatsApp? Sí. El cliente envía el número de seguimiento y el agente llama a tu API de tracking con una tool que describes en YAML. Responde con el estado, el último escaneo y la ventana de entrega que devolvió tu sistema, y nunca adivina un horario que no le dieron. ### ¿Cómo sabe el agente que quien reprograma una entrega es el destinatario? Le pide dos cosas: el número de seguimiento y el código postal de la dirección de entrega. Tu backend verifica que coincidan antes de cambiar nada. El número de seguimiento solo nunca muestra más que el estado. ### ¿Los clientes pueden mandar fotos de un paquete dañado? Sí. El agente lee imágenes de hasta 8 MB, describe el daño que ve, abre un reclamo con tu API y deriva la conversación a una persona. La foto queda en la conversación, donde quien la toma la ve en el inbox, y una persona decide la compensación. ### ¿El agente envía las notificaciones de entrega? Sí, cuando tu sistema los pide. Cuando un paquete sale a ruta o una entrega falla, tu sistema llama a la Messages API de Vatio y la conversación se abre por WhatsApp: tu propio texto, un brief a partir del cual escribe el agente, o una plantilla aprobada si pasaron más de 24 horas desde el último mensaje del cliente. El agente atiende la respuesta sabiendo de qué paquete escribió. ### ¿El agente puede cambiar la dirección de entrega? Solo si le das una tool para eso, y esta guía no lo hace. Un cambio de dirección es donde un número de seguimiento robado hace más daño, así que está en handoff y lo resuelve una persona.