Cómo gestionar colisiones de agentes con Command Queue

Seguramente te ha pasado: envías varios mensajes seguidos a un bot y el sistema intenta procesar todo al mismo tiempo. Las llamadas a LLM son caras y, si no controlas el flujo, terminas con procesos compitiendo por archivos de sesión, logs bloqueados o alcanzando los rate limits de la API antes de lo esperado.

Para solucionar esto, serializamos las ejecuciones de auto-reply mediante una pequeña cola FIFO (First-In, First-Out) interna. Esto evita que las ejecuciones colisionen mientras permite mantener el paralelismo entre diferentes sesiones de usuario.

Requisitos previos

• Canales que utilicen el Gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, etc.)
• Acceso a la configuración de messages.queue

Inicio rápido

La mejor forma de empezar es usar el modo collect. Este modo agrupa todos los mensajes en cola en una sola respuesta de seguimiento, lo que ahorra tokens y mantiene la coherencia.

1. Abre tu archivo de configuración.
2. Define los límites globales en agents.defaults.maxConcurrent.
3. Configura el comportamiento de la cola en el objeto messages:

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

Con esta configuración, el sistema esperará 1 segundo de silencio antes de procesar los mensajes acumulados.

Cómo funciona la cola

El sistema utiliza “lanes” (carriles) para organizar el trabajo. Cada sesión tiene su propio carril (session:<key>), garantizando que solo una instancia del agente toque una sesión específica a la vez. Estos carriles luego se integran en un carril global (main) donde el paralelismo total se limita mediante maxConcurrent.

Modos disponibles

Puedes cambiar cómo reacciona la cola ante nuevos mensajes:

• collect: Agrupa los mensajes en cola en una única ejecución (recomendado).
• steer: Inyecta el mensaje inmediatamente en la ejecución actual.
• followup: Encola el mensaje para la siguiente ejecución tras terminar la actual.
• steer-backlog: Realiza un steer ahora y además preserva el mensaje para un followup.

Si usas superficies de streaming, ten cuidado con steer-backlog, ya que puede generar respuestas que parezcan duplicadas.

Opciones de control

Para ajustar el comportamiento en los modos followup o collect, dispones de estos parámetros:

• debounceMs: Tiempo de espera tras el último mensaje para evitar el “escribiendo, escribiendo”.
• cap: Límite máximo de mensajes en cola por sesión.
• drop: Qué hacer cuando se supera el cap (old, new o summarize).
• summarize: Esta política crea una lista de puntos con los mensajes descartados y los inyecta como un prompt sintético.

Comandos por sesión

No necesitas cambiar la configuración global para probar un modo. Puedes enviar comandos directamente en el chat de la sesión:

• /queue collect: Cambia el modo para la sesión actual.
• /queue collect debounce:2s cap:25 drop:summarize: Combina varias opciones en un comando.
• /queue reset: Limpia cualquier configuración personalizada de la sesión.

Solución de problemas

• Comandos atascados: Activa los logs verbosos. Busca líneas que digan “queued for …ms” para confirmar que la cola se está vaciando correctamente.
• Profundidad de la cola: Si quieres ver cuántos mensajes hay esperando, revisa las líneas de tiempo de la cola en los logs verbosos.

AI Setup Assistant

Próximos pasos

• Configuración de agents.defaults
• Guía de Gateway reply pipeline