# Notificaciones de agentes: cuándo interrumpir a la persona y cuándo esperar

> Un agente de IA debe interrumpir solo ante una decisión pendiente, un bloqueo o un resultado listo. Qué eventos avisar, cómo priorizarlos y cómo evitar ruido.

*Tags: ia, agentes, notificaciones, ux*

---


> [!info] Definición Rápida
> Las **notificaciones de un agente de IA** son los avisos que el sistema envía a la persona mientras trabaja. Deben interrumpir solo cuando hay una decisión pendiente, un bloqueo o un resultado listo para revisar. Todo lo demás pertenece a un registro que la persona consulta cuando quiera.


## ¿Por qué interrumpir es una decisión de diseño?

Un [[agentes-en-segundo-plano|agente que trabaja en segundo plano]] puede generar decenas de eventos por hora. Si cada uno produce una notificación, la persona aprende a ignorarlas todas, incluida la que importa: el permiso urgente se pierde entre cien avisos de "paso completado".

Nielsen Norman Group distingue las notificaciones, que informan de eventos del sistema que la persona no provocó directamente, de los indicadores, que son pasivos, y de las validaciones, que responden a lo que la persona acaba de escribir. Su artículo advierte que una notificación enviada sin relación con el objetivo de la persona probablemente se ignore y hasta moleste. También separa las que exigen una acción, urgentes e intrusivas, de las pasivas, menos intrusivas pero fáciles de pasar por alto.

La pregunta correcta no es "¿hay algo que avisar?", sino "¿la persona necesita hacer algo ahora, o en los próximos minutos?". Si no, el aviso no es una notificación: es un registro.

## ¿Qué eventos de un agente merecen un aviso?

Claude Code, una herramienta real de agente, sirve de ejemplo. Su evento de notificación, que se puede conectar a un hook, distingue tipos según la situación. Entre ellos:

| Tipo | Cuándo se dispara, según la documentación |
|---|---|
| `permission_prompt` | Claude necesita que apruebes el uso de una herramienta y el aviso lleva unos seis segundos esperando |
| `idle_prompt` | Claude terminó de responder hace unos 60 segundos y no has escrito desde entonces |
| `agent_needs_input` | Una sesión en segundo plano empieza a esperar tu respuesta (con la vista de agentes abierta en una terminal) |
| `agent_completed` | Una sesión en segundo plano termina o falla (solo con la vista de agentes abierta) |

Esa lista muestra una idea útil para tu propio producto: los avisos se agrupan según lo que la persona debe hacer. Tres clases cubren casi todo:

| Clase | Mensaje de ejemplo | Cuándo interrumpir |
|---|---|---|
| **Decisión pendiente** | "Necesito aprobación para enviar el correo" | Siempre, porque el trabajo está detenido |
| **Bloqueo** | "Falló la conexión con el sistema de pagos" | Siempre, con la causa y la siguiente acción |
| **Resultado listo** | "La migración terminó; 118 de 120 pruebas pasaron" | Según la urgencia; a veces basta un resumen al final |

Un avance normal, como "paso 3 de 7 completado", no entra en ninguna clase. Va al registro de [[progreso-de-tareas-largas|progreso de tareas largas]]. Las decisiones pendientes son la clase que más importa, y su pantalla se describe en [[aprobacion-de-acciones|aprobación de acciones]].

## ¿Cómo debe verse una buena notificación?

Una notificación útil responde tres preguntas en una línea: qué pasó, qué se necesita de la persona y cuánto puede esperar. Un mensaje de ejemplo: "Esperando tu aprobación para editar la configuración de precios. El trabajo está pausado desde hace 4 minutos."

Son tres partes que se pueden diseñar: el hecho, la acción pedida y el estado del trabajo. Una notificación que solo dice "El agente necesita tu atención" obliga a abrir la herramienta para entender qué pasa. En Claude Code, la notificación llega con un texto (`message`), un título opcional y el tipo, justo los datos para armar un aviso así.

Si pide una decisión, el control de respuesta debe estar en el aviso o a un clic. Obligar a navegar hasta un panel para aprobar algo sencillo es una forma de perder la decisión.

## ¿Cómo se prioriza y cuándo se avisa?

Un sistema necesita al menos dos niveles:

- **Urgente.** Bloquea el trabajo y necesita respuesta. Se muestra con sonido o aviso visible, en el momento.
- **Informativo.** Ocurre, pero el trabajo sigue. Se acumula en un resumen o en el panel, sin alerta. Como los avisos pasivos se pasan por alto con facilidad, nada que requiera acción debe vivir solo ahí.

Tres decisiones más afinan el sistema:

1. **Avisar según la presencia.** Claude Code dispara la notificación cuando parece que la persona se alejó de la terminal, y espera unos segundos antes de avisar de un permiso. Si la persona está mirando la pantalla, el aviso sobra.
2. **Elegir el canal por tipo.** Con un hook, un equipo puede filtrar por tipo (un patrón como `permission_prompt|idle_prompt`) y mandar solo los permisos a una alerta de escritorio. Claude Code usa por defecto una notificación de escritorio en algunas terminales y un pitido o nada en otras; los hooks se ejecutan junto al aviso integrado, sin reemplazarlo. La documentación aclara que los hooks de notificación sirven para efectos laterales y no controlan ninguna decisión.
3. **Reducir las causas de raíz.** Muchas interrupciones nacen de permisos que se piden por costumbre. Los modos de permiso de Claude Code muestran la alternativa: en modo manual pide permiso antes de la mayoría de las ediciones, comandos y accesos a la red; `acceptEdits` permite editar archivos sin preguntar, y el modo `auto` usa un clasificador que revisa las acciones antes de ejecutarlas y pausa si bloquea tres veces seguidas o veinte en total. Pregunta menos, pero define dónde sí debe parar.

## ¿Qué pasa cuando la persona no responde?

Una decisión pendiente que nadie contesta es un problema de diseño. Pasado un tiempo razonable, el sistema debe recordar, escalar o detener la tarea de forma explícita. Lo que no debe hacer es esperar en silencio durante horas mientras la persona cree que el trabajo avanza.

Un recordatorio que dice "Hace 30 minutos esperamos tu respuesta sobre el reembolso; el trabajo está detenido" es mejor que repetir el primer aviso. Un tiempo de espera visible permite decidir si responder ahora o más tarde. Si la persona no está disponible, el diseño también debe definir quién más puede decidir; ver [[human-in-the-loop|human-in-the-loop]].

## ¿Cuándo NO conviene notificar?

- Cuando la tarea dura segundos y la persona la espera en pantalla. Un aviso extra solo añade ruido.
- Cuando el aviso llega después de que la acción ya ocurrió. Eso es informar, no pedir una decisión.
- Cuando el texto contiene datos sensibles y puede verse en una pantalla bloqueada o compartida. Mejor un aviso neutro que lleve a un lugar seguro.

## Ejemplo

Ejemplo ilustrativo: un agente pasa la tarde migrando un módulo de facturación y emite 240 eventos. La primera versión manda una notificación de escritorio por cada uno, y el equipo las silencia al segundo día.

Tras el rediseño, solo tres tipos interrumpen: permiso pendiente, bloqueo y fin de la tarea, y solo si la persona lleva unos segundos sin mirar la pantalla. Los demás eventos van a un resumen al final. Esa tarde el agente pide permiso para cambiar un valor de impuestos; el aviso llega con la pregunta, el estado del trabajo y un botón de aprobar. La decisión toma un minuto y el resto de la tarde no interrumpe a nadie.

## Errores comunes

- Notificar cada paso, hasta que la persona silencia todo.
- Mandar un aviso genérico sin decir qué se necesita.
- Pedir una decisión en una notificación que no permite responder.
- Dejar una decisión pendiente en silencio durante horas.
- Tratar igual una decisión urgente y un resumen informativo.
- Avisar aunque la persona esté mirando la pantalla.

## Fuentes

- [Hooks reference: Notification (Claude Code, documentación)](https://code.claude.com/docs/en/hooks)
- [Configure your terminal: terminal bell or notification (Claude Code, documentación)](https://code.claude.com/docs/en/terminal-config)
- [Choose a permission mode (Claude Code, documentación)](https://code.claude.com/docs/en/permission-modes)
- [Indicators, Validations, and Notifications, Nielsen Norman Group](https://www.nngroup.com/articles/indicators-validations-notifications/)


---

Source: https://www.fernandoux.com/es/wiki/ia/notificaciones-de-agentes/