En esta página
RabbitMQ para agentes en un párrafo
RabbitMQ para agentes en un párrafo
Ponga cada trabajo de LLM o de herramienta en una cola de quórum como mensaje persistente con un ID único, publicado con confirms. Ejecute consumidores en competencia con un prefetch de 1 y confirmaciones (ack) manuales, dimensionados según el límite de tasa del proveedor y no según la demanda. Configure un límite de entregas y un dead letter exchange para que un poison message falle unas cuantas veces y se detenga. Enrute por intención o habilidad mediante un topic exchange, use reply-to e IDs de correlación para las tool calls y mantenga un stream para replay. Haga que los handlers sean idempotentes, limite la longitud de las colas, pase referencias en lugar de payloads grandes y dimensione el consumer timeout según la llamada legítima más lenta.
Por qué los agentes necesitan un broker
Un bucle de agente consiste sobre todo en esperar. Una llamada al modelo tarda segundos o minutos, una herramienta agota su timeout y el proveedor le limita cuando el tráfico se dispara. Las llamadas en línea atan a cada llamante a la dependencia más lenta. Un broker rompe ese acoplamiento: el llamante publica una tarea y sigue adelante, y los workers la recogen cuando tienen capacidad.
Ese único cambio aporta todo lo demás. Las llamadas fallidas se reintentan mediante reentrega, no con bucles escritos a mano. La contrapresión (backpressure) es una cola que crece, no un pool de hilos que se viene abajo. El fan-out a varias herramientas es una sola publicación. Una tarea sobrevive a la caída de un worker porque nunca se confirmó. Y un paso de aprobación humana es una cola de la que consume la herramienta de un revisor, de modo que el plan espera sin mantener un proceso abierto.
Ejecute los trabajos de LLM como una cola de trabajo
La forma básica es la cola de trabajo de los tutoriales de RabbitMQ: una cola, muchos consumidores en competencia y cada mensaje entregado a uno de ellos. Dos ajustes la hacen segura para llamadas al modelo. Use confirmaciones (ack) manuales, porque en modo automático RabbitMQ considera entregado un mensaje en cuanto lo envía, y un worker que se cae a mitad de llamada lo pierde. Y fije el prefetch en 1. La documentación califica un prefetch de 1 como el valor más conservador y advierte de que penaliza el throughput, que es la contrapartida adecuada cuando cada mensaje es una llamada larga y facturada, no una escritura rápida en base de datos.
El número de consumidores pasa a ser su límite de concurrencia. Si el proveedor permite 50 peticiones simultáneas, ejecute 50 consumidores con un prefetch de 1 y deje que la cola absorba el resto. El throughput se convierte en una decisión de capacidad tomada a propósito y no en un efecto secundario de un pico de tráfico, lo que lo convierte en uno de los controles de coste más sencillos que existen.
Tareas de agente duraderas con colas de quórum (quorum queues)
Una petición de cliente, un plan de varios pasos o una aprobación pendiente deben sobrevivir a un fallo de nodo. Declare esas colas como colas de quórum (x-queue-type con valor quorum), publique los mensajes como persistentes y active publisher confirms para que el productor sepa que el broker tiene la tarea antes de darla por encolada. Las colas de quórum son siempre duraderas y replicadas, y ofrecen las dos funciones en las que más se apoya el trabajo de agentes: un límite de entregas, que por defecto es 20 desde RabbitMQ 4.0, y un modo de dead-lettering at-least-once. No admiten QoS global, así que configure el prefetch por consumidor.
Frene los prompts problemáticos con un límite de entregas y una cola dead-letter (DLQ)
Algunas entradas nunca saldrán bien: un prompt que el modelo rechaza, un documento que el parser no puede leer, una tool call cuyos argumentos no superan la validación. Si se reencolan sin fin, entran en bucle y queman tokens. Una cola de quórum cuenta las entregas fallidas en la cabecera x-delivery-count y, cuando se supera el límite de entregas, descarta el mensaje, o lo envía a dead-letter si hay un dead letter exchange configurado. Para llamadas al modelo facturadas, el valor por defecto de 20 es generoso; un límite de 3 a 5 mantiene acotado el coste de una entrada defectuosa.
Asocie la cola a un dead letter exchange y vincule detrás una cola que lea una persona o un agente de triaje. RabbitMQ añade una cabecera x-death que registra la cola de origen, el motivo y el recuento, de modo que la cola dead-letter explica por qué ha llegado allí cada tarea. Cuando un worker ya sabe que un reintento no tiene sentido, debe rechazar el mensaje con requeue en false y enviarlo directamente allí.
Un worker de partida
El worker siguiente usa aio-pika, el cliente asyncio para Python, de modo que la conexión sigue atendiéndose mientras se espera una llamada al modelo; la propia documentación de pika advierte de que un callback de larga duración puede tumbar la conexión por timeout del heartbeat. Consume una cola de quórum con un límite de entregas de 5, toma un mensaje cada vez, omite duplicados por ID de mensaje, espera antes de devolver un trabajo limitado por tasa y rechaza directamente al dead letter exchange todo lo que no puede salir bien. run_agent_step, already_done y save_result representan su propio código.
import asyncio
import json
import aio_pika
class Transient(Exception):
"""Rate limit, timeout or 5xx from the model or a tool: worth retrying."""
async def handle(msg):
key = msg.message_id # stable per task, set by the publisher
if await already_done(key): # duplicate delivery: do not repeat the work
await msg.ack()
return
try:
job = json.loads(msg.body)
result = await run_agent_step(job) # the slow model or tool call
await save_result(key, result) # record the outcome before acknowledging
await msg.ack()
except Transient:
attempt = int((msg.headers or {}).get("x-delivery-count", 0))
await asyncio.sleep(min(2 ** attempt, 60)) # back off before handing it back
await msg.nack(requeue=True) # counts toward the delivery limit
except Exception:
await msg.reject(requeue=False) # cannot succeed: straight to the DLX
async def main():
conn = await aio_pika.connect_robust("amqps://agent-worker:PASSWORD@broker.example.com/agents")
ch = await conn.channel()
await ch.set_qos(prefetch_count=1) # one job in flight per worker
dlx = await ch.declare_exchange("agents.dlx", aio_pika.ExchangeType.FANOUT, durable=True)
dead = await ch.declare_queue("llm-jobs.dead", durable=True,
arguments={"x-queue-type": "quorum"})
await dead.bind(dlx)
jobs = await ch.declare_queue("llm-jobs", durable=True, arguments={
"x-queue-type": "quorum",
"x-delivery-limit": 5,
"x-dead-letter-exchange": "agents.dlx",
})
async with jobs.iterator() as messages:
async for msg in messages:
await handle(msg)
asyncio.run(main())El publicador fija el ID de mensaje del que depende la comprobación de idempotencia, marca el mensaje como persistente y le asigna una caducidad (aio-pika convierte un timedelta a los milisegundos que usa el protocolo, y sus canales tienen publisher confirms activados por defecto).
from datetime import timedelta
await ch.default_exchange.publish(
aio_pika.Message(
json.dumps(job).encode(),
message_id=job["task_id"], # idempotency key
delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
expiration=timedelta(minutes=2), # stale after two minutes
),
routing_key="llm-jobs",
)Los argumentos de la cola van en línea para que el ejemplo funcione por sí solo. En producción, configure delivery-limit y dead-letter-exchange mediante policy: la documentación recomienda las policies porque pueden cambiarse sin volver a desplegar las aplicaciones.
Tool calls y enrutamiento: reply-to y topic exchanges
Cuando un agente llama a una herramienta a través del broker y necesita la respuesta, use el patrón petición-respuesta del tutorial RPC de RabbitMQ: fije reply_to a una cola de callback y correlation_id a un valor único por petición, y haga que la herramienta publique su resultado en esa cola con el mismo ID. Descarte las respuestas con un ID de correlación que no reconozca. Direct reply-to (amq.rabbitmq.reply-to) evita declarar una cola para llamadas interactivas cortas, pero sus respuestas no se almacenan y se descartan si el solicitante se desconecta, así que todo lo que no pueda permitirse perder necesita una cola de respuesta duradera.
Para llegar al agente o la herramienta adecuados, publique en un topic exchange con una routing key construida a partir de la intención y la habilidad, como agent.billing.refund o tool.search.web. En un binding, * coincide con exactamente una palabra y # con cero o más, de modo que los especialistas usan claves específicas mientras que un consumidor de auditoría se vincula a agent.#. Un mensaje llega a todas las colas cuyo binding coincide, y así una sola publicación hace fan-out a varias herramientas. Las routing keys están limitadas a 255 bytes.
Prioridades, peticiones caducadas y llamadas largas al modelo
En RabbitMQ 4.3, las colas de quórum admiten prioridades estrictas con 32 niveles (de 0 a 31) sin necesidad de activarlas; las colas clásicas usan x-max-priority, idealmente con pocos niveles (menos de diez). Publique las peticiones de cara al usuario por encima de los resúmenes nocturnos y los workers las atenderán primero.
Una petición que nadie espera es gasto desperdiciado. Asígnele un TTL por mensaje con la propiedad expiration para que un turno de chat que no haya empezado en, por ejemplo, dos minutos caduque en lugar de ejecutarse. Los mensajes caducados solo se eliminan, o se envían a dead-letter, cuando llegan a la cabeza de la cola, de modo que un backlog profundo los sigue reteniendo hasta que los consumidores llegan a ellos.
Después está el consumer timeout. RabbitMQ cierra un canal con un error PRECONDITION_FAILED cuando una entrega no se confirma en 30 minutos por defecto, y reencola todas las entregas de ese canal. Una ejecución larga de un agente puede alcanzar ese límite. Desde RabbitMQ 3.12 el timeout puede configurarse por cola, con la clave de policy consumer-timeout o el argumento x-consumer-timeout en milisegundos, así que súbalo solo en las colas que transportan trabajos largos, con margen sobre la ejecución legítima más lenta.
Streams para replay y memoria de agentes
Una cola olvida un mensaje en cuanto se confirma. Los agentes suelen necesitar lo contrario: un registro de cada evento que ha producido un flujo de trabajo, que un agente nuevo puede leer desde el principio o un depurador puede reproducir (replay) desde un momento dado. Eso es un stream de RabbitMQ: un log replicado, de solo anexado (append-only), que se lee sin eliminar mensajes. Vincule un stream al exchange en el que ya publican sus agentes, configure la retención con max-age o max-length-bytes y deje que cada lector elija su punto de partida con x-stream-offset: first, last, next, un offset, un timestamp o un intervalo. Los streams no admiten dead-lettering ni TTL, así que mantenga el trabajo en colas de quórum y el histórico en el stream.
Frameworks y MCP
Para equipos de Python, Celery es la vía directa: RabbitMQ es su broker por defecto, y fijar task_default_queue_type en quorum traslada la cola por defecto a colas de quórum. Celery confirma una tarea justo antes de ejecutarla por defecto; acks_late la confirma después, de modo que una caída a mitad de tarea hace que se ejecute de nuevo, y por eso la documentación de Celery pide tareas idempotentes.
LangGraph, CrewAI y AutoGen orquestan el propio agente, y el broker se sitúa a su alrededor: un worker toma una tarea de una cola e invoca el grafo o el crew. LangGraph guarda el estado del grafo en un checkpointer indexado por un thread_id (su documentación enumera savers en memoria, SQLite y Postgres), así que incluya el thread ID en el mensaje y una tarea reentregada podrá reanudarse desde el último checkpoint. Los crews de CrewAI se inician con kickoff() o sus variantes asíncronas. El runtime distribuido de AutoGen usa gRPC y está marcado como experimental. En todos los casos, RabbitMQ transporta el trabajo entre servicios; no sustituye al runtime del framework.
MCP, el Model Context Protocol, es un estándar abierto para conectar aplicaciones de IA con herramientas y datos externos, con stdio y Streamable HTTP como transportes estándar. Existen servidores MCP para RabbitMQ creados por la comunidad, que normalmente encapsulan la API de gestión y AMQP para que un asistente pueda inspeccionar colas o publicar. Asigne a cualquiera de ellos su propio usuario de RabbitMQ con los permisos mínimos que funcionen, porque actúa con todo el acceso que tenga.
Errores que aparecen en producción
- Colas sin límite cuando la API del modelo limita la tasa. En cuanto el proveedor devuelve errores de límite de tasa, los consumidores se ralentizan y la cola crece hasta que una alarma de memoria o una alarma de disco bloquea todas las conexiones que publican en el nodo. Limite las colas que reciben tráfico de usuarios con
max-lengthy el overflowreject-publish, para que un publicador que use confirms reciba unbasic.nacky pueda pedir al usuario que lo reintente. El overflow por defecto,drop-head, descarta el mensaje más antiguo, o lo envía a dead-letter si hay un dead letter exchange configurado. - Ejecuciones largas que alcanzan el consumer timeout. Dimensione
consumer-timeoutpor cola, mantenga el prefetch en 1 para el trabajo lento y confirme en todas las rutas de código, incluidos los errores. - Payloads grandes. El tamaño máximo de mensaje por defecto es de 16 MiB (
max_message_size, configurable hasta 512 MiB); los mensajes más grandes se rechazan. Guarde documentos, imágenes y lotes de embeddings en almacenamiento de objetos o en una base de datos vectorial y ponga una referencia en el mensaje. - Suposiciones sobre el orden. Una cola mantiene el orden de publicación, pero con varios consumidores y reencolados cada consumidor puede ver los mensajes desordenados. Para un orden estricto por conversación, use una cola con un único consumidor activo o incluya un número de secuencia.
- Reintentos que repiten efectos secundarios. La entrega es at-least-once: un worker puede terminar el trabajo y caerse antes de confirmar, y el mensaje vuelve con el flag
redeliveredactivado. Asocie cada efecto secundario (un correo enviado, un ticket abierto, un reembolso emitido) al ID de mensaje de la tarea y compruébelo primero, como hace el worker anterior.
Preguntas frecuentes
¿Se puede usar RabbitMQ para agentes de IA?
Sí. Los workers consumen trabajos de LLM y de herramientas con confirmaciones (ack) manuales, las colas de quórum mantienen las tareas duraderas, los límites de entregas y los dead letter exchanges frenan los prompts problemáticos, los topic exchanges enrutan por habilidad y los streams conservan un histórico reproducible.
¿Qué cola de mensajes conviene usar para agentes de IA?
Depende de la carga de trabajo. El reparto de tareas con reintentos, prioridades y confirmación por tarea encaja con un broker de colas como RabbitMQ; los streams de eventos de gran volumen que muchos consumidores reproducen encajan con un log, como Kafka o los streams de RabbitMQ.
¿Cómo evito que las llamadas largas a un LLM alcancen el consumer timeout de RabbitMQ?
El timeout por defecto es de 30 minutos. En RabbitMQ 3.12 y posteriores, configure consumer-timeout mediante policy, o x-consumer-timeout como argumento de cola, en las colas que transportan trabajos largos, mantenga el prefetch en 1 y confirme en todas las rutas de código.
¿LangChain o LangGraph funcionan con RabbitMQ?
Se usan juntos, con RabbitMQ como capa de tareas alrededor del grafo. Un worker consume una tarea e invoca el grafo, mientras que el checkpointer de LangGraph, que su documentación describe como en memoria, SQLite o Postgres, guarda el estado del grafo bajo un thread_id incluido en el mensaje.
¿Cómo debe gestionar un agente de IA los mensajes duplicados de RabbitMQ?
Dé por hecho que la entrega es at-least-once. Asigne a cada tarea un ID de mensaje estable, registre los IDs completados junto al resultado y omita cualquier entrega cuyo ID ya esté registrado antes de repetir un efecto secundario.