🌫️ Receta imprecisa
¿Eres nuevo aquí? Un workflow (la receta) es vago cuando no dice lo suficiente para que el agente decida sin adivinar — por ejemplo, «organiza los archivos» sin decir por qué organizarlos, con qué criterio ni dónde guardar el resultado. Una receta vaga es la causa más común de fallas en WAT: no es que el agente «no entendió», sino que la receta no dijo lo suficiente.
Un ejemplo cotidiano: pides «haz un resumen de las ventas del mes para que lo mande al grupo de WhatsApp de la tienda». Parece claro, pero está lleno de vacíos — ¿resumen de qué exactamente (total, por producto, por vendedor)? ¿De dónde salen los datos (la hoja de cálculo de ayer, la de hoy, un sistema)? ¿Cuántas filas puede tener el resumen? El agente no puede rechazar la tarea, así que completa cada espacio en blanco con la suposición más razonable que encuentres — y "razonable para él" rara vez coincide con "lo que tenías en mente". El resultado queda genérico: un párrafo correcto sobre números, pero sin el enfoque que querías.
🔍 Mira por dentro: lo que hace el agente cuando falta un detalle
Ante una instrucción incompleta, el agente sigue un camino predecible — y eso es lo que genera el resultado genérico:
- 1. Lee la solicitud e identifica qué falta para ejecutarla (formato, fuente, criterio, destino).
- 2. Elige la suposición más común — la interpretación más común en pedidos parecidos, no tu interpretación específica.
- 3. Ejecútalo con esta suposición y entrega algo técnicamente correcto, pero genérico.
- 4. No avisa que eligió, porque, desde su punto de vista, ya llenó el vacío y completó la tarea.
✗ Vago
"Organiza estos informes para mí."
✓ Claro
"Cambia el nombre de los archivos de la carpeta 'relatorios/' al formato AAAA-MM-relatorio.pdf, según la fecha que aparece en el nombre actual. Si algún nombre no tiene fecha, déjalo de lado y avísame al final."
✗ Vago
"Haz un resumen de las ventas del mes para el grupo."
✓ Claro
"Usa la hoja de cálculo 'vendas-agosto.xlsx', pestaña 'resumo'. Trae el total del mes, los 3 productos más vendidos y la comparación con julio. Máximo 5 líneas, lenguaje sencillo para el grupo de WhatsApp."
💡 Consejo práctico
Antes de escribir la receta, pregúntate: «si le diera este texto a una persona nueva en prácticas que nunca ha visto mi negocio, ¿sabría exactamente qué hacer?». Si la respuesta es «solo si lo adivina», la receta todavía es vaga.
🔑 Herramienta sin clave ni permiso
¿Eres nuevo aquí? Muchas herramientas exigen una clave de API (una contraseña específica que autoriza el uso de un servicio, como enviar correos o publicar en un sitio) para funcionar. Si la clave no está configurada o el agente no tiene permiso para usar esa herramienta (la Ruta 0 ya trató los permisos), el paso del workflow que depende de ella simplemente no se puede ejecutar, por más clara que esté el resto de la receta.
Este es un error que es fácil confundir con «el agente no sabe hacer esto»: en realidad, sabe exactamente qué hacer, solo que no tiene la llave de la puerta. La solución nunca es reescribir el workflow — es configurar la credencial que falta (tema que se profundiza en la Trilha 4, módulo de Secretos).
🔍 Por dentro
- Clave de API: una contraseña específica del servicio, distinta de tu contraseña personal; cada herramienta externa puede pedir una.
- Permiso: el límite que tú mismo defines para lo que el agente puede hacer por su cuenta.
Ejemplo real: pides "envía un correo al cliente para avisarle que el pedido fue enviado". Si la herramienta de correo electrónico (por ejemplo, un servidor MCP de Gmail —tema de la Trilha 2—) nunca recibió la clave de acceso a tu cuenta, el agente llega al paso de enviar y se detiene ahí: el mensaje ya está escrito, pero no se envía. Es distinto de un error de ejecución: el agente no "lo intentó y falló"; identificó que la puerta está cerrada y, si está bien construido, se detiene y te avisa en vez de inventar que lo envió.
⚠️ Modo de falla distinto: el agente «inventa» una ruta
Una variación peligrosa de la falta de acceso es la alucinación — cuando el agente, al no encontrar el archivo, la carpeta o el comando correcto, inventa una ruta parecida en vez de decir «no encontré». Ejemplo: pides que ejecute «el script de cierre de caja» y no existe ningún archivo con ese nombre exacto — en vez de detenerse y preguntar, un agente mal orientado puede asumir que fechamento.py es el archivo correcto (no lo es) y ejecutarlo de todos modos, generando un resultado que parece correcto, pero no es lo que pediste.
🧩 Agente sin suficiente contexto
A veces el workflow está claro y la herramienta tiene permiso, pero el agente sigue equivocándose porque falta contexto — información de contexto que necesitaría para tomar la decisión correcta. Ejemplo: pedir "escribe un resumen con el tono de la empresa" sin haberle mostrado nunca ejemplos de ese tono. El CLAUDE.md (visto en la Trilha 0) existe precisamente para mantener ese contexto de forma persistente, sin tener que repetirlo en cada pedido.
La falta de contexto también se manifiesta de una forma más costosa: cuando el agente entra en un loop — un ciclo que se repite sin llegar nunca al final, porque no tiene información suficiente para saber cuándo detenerse. Imagina un workflow que diga "revisa este texto hasta que quede bien", sin ningún criterio para definir qué significa "bien". En cada turno el agente lo revisa de nuevo, encuentra algo que ajustar (siempre encuentra algo) y vuelve a revisarlo; sin un criterio para detenerse, el ciclo puede continuar durante decenas de turnos. Cada turno consume tokens (la unidad que mide cuánto «lee» y «escribe» el modelo —y lo que determina el costo de cada ejecución), así que un loop mal diseñado no es solo una pérdida de tiempo: es un costo real que aumenta sin control, a veces por un workflow que parecía inofensivo.
💡 Consejo práctico
Todo workflow que incluya «repite hasta...» necesita un criterio de detención objetivo (un número de rondas, una condición verificable), no una meta subjetiva como «hasta que quede bien». Sin eso, podrías terminar pagando por un ciclo que nunca acabaría por sí solo.
❓ Workflow ambiguo
A diferencia de «vago» (al que le faltan detalles), un workflow ambiguo hay demasiados detalles que se contradicen o permiten más de una interpretación razonable. Ejemplo: «envía el informe al cliente antes del viernes, priorizando la calidad» y, tres líneas después, «no dediques más de 10 minutos a revisarlo» —las dos instrucciones compiten entre sí, y el agente puede elegir cualquiera.
La diferencia práctica entre algo vago y algo ambiguo importa porque la solución es opuesta. Una receta vaga se resuelve agregando detalle. Un workflow ambiguo se resuelve eliminando la contradicción — decidiendo cuál de las instrucciones en conflicto tiene más peso y dejándolo por escrito, no implícito.
✗ Workflow mal hecho
"Responde todos los correos del día prestando total atención a cada uno. Ah, y deja la bandeja de entrada vacía antes del mediodía."
Dos metas en competencia: máxima calidad vs. plazo ajustado. El agente decide por su cuenta cuál priorizar y puede cambiar de opinión en cada ejecución.
✓ Workflow bien redactado
"Antes del mediodía, responde tantos correos simples (1-2 líneas) como puedas. Deja marcados como pendientes los correos complejos para que yo los revise; no intentes resolverlos rápido."
La prioridad queda explícita: velocidad en las tareas sencillas, sin sacrificar la calidad en las complejas, porque estas quedan fuera de plazo.
Leyenda: los cuatro puntos de falla más comunes de WAT, junto con la solución específica para cada uno: ninguno se resuelve de la misma manera.
🚨 Cómo darte cuenta: las señales de alerta
Cada tipo de falla deja una pista diferente en el comportamiento del agente. Aprender a leer esas pistas evita «pelearte» con el agente sin entender por qué no acierta.
Si piensas en el ciclo de WAT (visto en el módulo 1.2: el agente lee el workflow, decide el siguiente paso, usa una tool, repite), la falla casi siempre aparece al principio de ese ciclo — al leer el workflow o al tomar la decisión — y tú solo la notas al final, como un resultado incorrecto, un costo alto o tiempo perdido. El diagrama de abajo muestra el recorrido:
Leyenda: la falla casi nunca empieza en la herramienta — aparece antes, en el workflow o en la decisión del agente, y solo se hace visible al final como un mal resultado, un costo alto o tiempo perdido.
Hace algo razonable, pero distinto de lo que querías
Señal de una receta vaga — completó el vacío con una suposición razonable, pero no era la tuya.
Se detiene y pide una contraseña o credencial
Señal de una tool sin clave — identificó correctamente el bloqueo y está pidiendo ayuda.
El resultado «se sale del patrón» de la casa
Señal de contexto insuficiente — no tenía ejemplos del patrón esperado.
Varía: lo hace de una manera en una sesión y de otra en la siguiente
Señal de ambigüedad — el workflow permite más de una interpretación válida.
✅ Lista de verificación de reparación
Ante un resultado que no salió como esperabas, recorre esta lista de verificación antes de culpar al agente: en la gran mayoría de los casos, la solución está en una de estas cuatro líneas.
✅ Lista de verificación rápida
- ☐ ¿La receta indica claramente qué hacer, con qué y dónde guardar el resultado?
- ☐ ¿Todas las herramientas que necesita el paso tienen la clave o los permisos configurados?
- ☐ ¿El agente tiene suficientes ejemplos o reglas (CLAUDE.md) sobre el estándar esperado?
- ☐ ¿Hay dos instrucciones del workflow que compiten entre sí?
💡 Consejo práctico
Guarda esta lista de verificación: vuelve completa en el módulo 1.5 (Build), cuando revises por qué la automatización del boletín no salió como esperabas en el primer intento.
Copia esta lista de verificación antes de ejecutar cualquier workflow nuevo; pégala en un bloc de notas y ve marcando cada punto:
[ ] O QUE fazer está escrito (não só "organize", "resuma", "revise")
[ ] COM QUE dados/arquivos trabalhar está nomeado (caminho ou fonte exata)
[ ] ONDE salvar ou entregar o resultado está definido
[ ] Toda ferramenta usada no workflow tem chave/permissão já testada
[ ] O CLAUDE.md tem exemplo do padrão esperado (se o resultado exige "tom" ou "estilo")
[ ] Não há duas instruções competindo (prazo vs. qualidade, rapidez vs. cuidado)
[ ] Se existe "repita até...", há um critério de parada objetivo (não subjetivo)Cómo verificar: ejecuta el workflow una vez con un caso pequeño y económico antes de confiar en él a escala. Si el resultado coincide con lo que esperabas sin necesidad de ajustes, probablemente los siete puntos anteriores están cubiertos. Si no coincide, vuelve a la lista de verificación y busca qué línea quedó sin marcar: ahí está el defecto, no en la «capacidad» del agente.
Verificación rápida (opcional): el agente se detiene y pide una contraseña específica de un servicio. ¿Cuál es la causa más probable?