Message Batches: qué trabajos van en lote

Un equipo procesa 20.000 documentos por noche y además corre una revisión antes de cada merge. Los dos usan el mismo modelo y el mismo prompt. Uno puede ir en lote y el otro no, y la diferencia no es el volumen: es si alguien está esperando la respuesta.

Qué ofrece

La Message Batches API procesa muchos pedidos de forma asíncrona:

• cuesta 50% menos que las llamadas normales;
• cada lote se procesa en hasta 24 horas (muchas veces mucho antes), sin garantía de latencia;
• cada pedido lleva un custom_id propio, y los resultados pueden volver en cualquier orden: el custom_id es lo único que te permite emparejar respuesta y documento.

Qué va en lote y qué no

Trabajo	API
Informe nocturno, auditoría semanal, generación de tests de madrugada, reprocesar un archivo histórico	Lotes
Chequeo antes del merge que bloquea el PR	Síncrona
Respuesta a un cliente en el chat de soporte	Síncrona
Agente que llama herramientas y sigue según el resultado	Síncrona

La regla: el lote sirve para cargas tolerantes a demoras (latency-tolerant) que no bloquean a nadie. Un flujo bloqueante (blocking workflow), como un pre-merge, no puede esperar hasta 24 horas.

Ojo con el último caso: dentro de un pedido del lote no hay tool calling de varios turnos. El modelo puede pedir una herramienta, pero nadie la ejecuta y le devuelve el resultado en el mismo pedido. Un flujo agéntico que necesita ir y volver con herramientas no entra en un lote.

Cada cuánto enviar

Si el negocio promete un SLA de 30 horas desde que llega el documento hasta el resultado, y el lote puede tardar 24, el peor caso es: el documento llega justo después de un envío, espera la próxima ventana y después tarda 24 horas. Entonces:

ventana de envío + 24 h ≤ SLA

Con 30 horas de SLA, la ventana no puede pasar de 6 horas. La guía usa ventanas de 4 horas: el peor caso queda en 28 horas y deja margen.

Cuando algo falla

Un lote de 10.000 pedidos vuelve con 3 errores. Los otros 9.997 ya están bien:

• reenviá solo los fallidos, identificados por su custom_id;
• corregí antes la causa: si un documento excedió el contexto, partilo en partes; si falló la validación, mandalo con su error concreto;
• poné un tope de reenvíos y lo que siga fallando pasa a revisión.

Probar antes de lanzar

Antes de mandar 200.000 documentos, refiná el prompt sobre una muestra. Cada error que se escapa en el prompt se multiplica por el volumen y obliga a reenviar. Medir primero en una muestra etiquetada sube el porcentaje de aciertos a la primera y baja el costo de las correcciones. Lo mismo para cambios de costo: si querés mandar los documentos simples a un modelo más chico, medí la precisión de cada ruta sobre datos etiquetados antes de cambiar.

Las trampas típicas

• Usar el lote para el pre-merge “porque es más barato”.
• Pensar que el lote sirve para un agente con herramientas.
• Reenviar el lote entero porque fallaron unos pocos.
• Emparejar resultados por posición en lugar de por custom_id.
• Lanzar el volumen completo sin probar el prompt.

En el examen

Fijate si el escenario tiene a alguien esperando (un PR bloqueado, un cliente). Si sí, síncrona. Si no, lote. Si piden la frecuencia de envío, restá 24 horas al SLA. Si fallaron algunos pedidos, la respuesta menciona custom_id y reenviar solo esos.