Procesamiento asíncrono de agentes
Qué significa asíncrono aquí
De manera predeterminada, REDA AI ejecuta el bucle agéntico de forma síncrona. Llega el mensaje del usuario, la plataforma llama al modelo, el agente usa herramientas, el modelo produce una respuesta final y se actualiza el registro de conversación, todo dentro de la transacción que hace la llamada. El usuario (o un flujo, o un sistema externo) obtiene la respuesta del agente en el retorno de la llamada.
Algunas solicitudes no caben en una sola transacción. El motivo más común es una carga de archivo lo bastante grande como para superar los límites de procesamiento síncrono de Salesforce. Cuando la plataforma detecta esa condición, cambia al procesamiento asíncrono en lugar de fallar.
Qué ve el llamador
Las solicitudes enrutadas de forma asíncrona regresan de inmediato con dos campos reveladores en la respuesta:
| Campo | Significado |
|---|---|
isAsync | true cuando la solicitud se enrutó al procesamiento en segundo plano. |
asyncRequestId | El Id del registro Solicitud asíncrona que hace seguimiento del trabajo. |
conversationId | La conversación a la que pertenece la solicitud. La respuesta final del agente aparece como un nuevo Mensaje en esta conversación. |
El campo síncrono response está vacío cuando isAsync es true: la respuesta real aún no se ha generado. Los llamadores deben ramificar según isAsync y, o bien sondear hasta que se complete, o bien esperar a que la conversación reciba el nuevo Mensaje.
Ciclo de vida de la solicitud asíncrona
Cada solicitud enrutada de forma asíncrona crea un registro Solicitud asíncrona que la plataforma actualiza a medida que avanza el trabajo:
| Estado | Significado |
|---|---|
| En cola (Queued) | El Queueable se ha puesto en cola; el procesamiento aún no ha comenzado. |
| En proceso (Processing) | El procesador en segundo plano ha tomado la solicitud y está llamando al modelo. |
| Complete (Complete) | El trabajo terminó correctamente; la respuesta está disponible en la conversación. |
| Error (Error) | El trabajo falló incluso tras el reintento. El campo Mensaje de error (Error Message) del registro contiene el motivo. |
Otros campos del registro te dan el contexto completo: la conversación y el mensaje del usuario relacionados, la definición de agente que gestionó la solicitud, el contexto de registro al que estaba vinculada la solicitud, los Id de los archivos que se procesan, los contadores de reintentos y una marca de tiempo de cuándo terminó el trabajo.
Gestión de fallos
Una solicitud asíncrona fallida no se reintenta. Cuando el procesador en segundo plano encuentra un error, escribe Error en el Status de la Solicitud asíncrona y el motivo en Error Message, y ahí se detiene. Nada la vuelve a encolar: ni un error transitorio del modelo, ni una llamada externa interrumpida.
Implementa tu propio reintento si el trabajo importa. Un Flow que llama a un agente de
forma asíncrona y da la entrega por garantizada perderá el turno ante cualquier fallo transitorio.
Comprueba el Status de la Solicitud asíncrona y vuelve a invocarlo cuando sea Error.
El registro incluye los campos Retry Count y Max Retries. Retry Count se incrementa una vez al recoger la solicitud, pero ningún código lo compara con Max Retries, así que hoy ninguno de los dos campos cambia lo que ocurre.
Los errores siguen siendo visibles: salvo que quien llama haya desactivado el registro de incidentes, el fallo queda capturado en los Registros de incidentes de IA con su clase, método y traza, que es donde hay que mirar primero.
Cómo manejan los canales el procesamiento asíncrono
Interfaz interna de Salesforce (widget de chat en una página de registro)
El widget de chat detecta isAsync y muestra un estado de espera amable. Cuando la conversación recibe el nuevo mensaje del agente, el widget se actualiza en el sitio. Los usuarios ven un breve retraso; por lo demás, la conversación no cambia.
Widget externo
El widget externo de un sitio web público detecta isAsync y muestra un estado de espera similar. Como el widget sondea en lugar de recibir la respuesta en streaming, el usuario ve llegar la respuesta pocos segundos después de que se complete.
Llamadores de Flow / API
Para los llamadores impulsados por Flow y los de API directa, el procesamiento asíncrono requiere un manejo explícito. El patrón más simple es un flujo activado por registro sobre el objeto Solicitud asíncrona: cuando el registro llega a Complete, ejecuta el seguimiento que la integración necesite: publicar la respuesta de vuelta en un sistema de mensajería, actualizar un registro, enviar un correo. Consulta Integración del canal de mensajería para el patrón más amplio.
Canal de correo — Entrante
Los correos entrantes de recepción de documentos siempre se ejecutan de forma asíncrona por diseño. El gestor del Servicio de correo electrónico almacena los adjuntos y pone en cola un Queueable; el agente se ejecuta en segundo plano. Consulta Canal de correo — Entrante.
Observabilidad
- El registro de solicitud asíncrona es la fuente de verdad principal: estado, número de reintentos, mensaje de error, marca de tiempo de finalización.
- La conversación muestra el mensaje del usuario de inmediato y la respuesta del agente cuando se completa el trabajo asíncrono, sin mensajes “en progreso”.
- El Depurador de conversaciones muestra el prompt ensamblado, las llamadas a herramientas y los créditos usados para la ejecución final del agente, igual que en una ejecución síncrona.
- El Registro de incidentes de IA captura cualquier fallo que agote el presupuesto de reintentos. Consulta Registros de incidentes de IA.
Diseñar agentes para el procesamiento asíncrono
La mayoría de los agentes no necesitan ningún diseño especial para el procesamiento asíncrono: el enrutamiento es automático y la conversación se comporta igual. Hay dos consideraciones de diseño que vale la pena tener en cuenta:
Presupuesto de tokens. La ruta asíncrona se ejecuta en un Queueable, que tiene sus propios límites reguladores. Los bucles agénticos muy largos o los prompts de tamaño excesivo aún pueden alcanzar los límites en modo asíncrono. Mantén realista el presupuesto de tokens del agente y divide el trabajo de muy larga ejecución en varios turnos siempre que sea posible.
Tarjetas de confirmación. Las confirmaciones de acciones requieren una interfaz que pueda mostrar una tarjeta. En los canales exclusivamente asíncronos (recepción de correo, ejecuciones impulsadas por Flow, integraciones de mensajería), activa la ejecución automática de acciones (Auto Execute Actions) en el agente o restringe el conjunto de herramientas a herramientas que no requieran confirmación. Consulta Confirmaciones de acciones.
Prácticas recomendadas
Ramifica según isAsync en los llamadores personalizados. Tratar la respuesta como síncrona cuando isAsync es true dejará a los llamadores esperando una contestación que nunca llega en esa respuesta.
Usa un flujo activado por registro sobre el objeto Solicitud asíncrona para los seguimientos. Es la forma más limpia de reaccionar cuando se completa una ejecución asíncrona: disparar una devolución de llamada, publicar una respuesta a través de otro canal o actualizar un campo de estado.
No esperes que los reintentos solucionen todos los fallos. La mayoría de los fallos asíncronos no son transitorios. Si una solicitud queda en Error, la entrada del Registro de incidentes de IA es el lugar correcto para empezar a investigar: las cadenas largas de reintentos rara vez convierten un fallo real en un éxito.
Vigila la profundidad de la cola. Una acumulación de registros en En cola significa que el trabajo asíncrono llega más rápido de lo que puede procesarse. Ajusta el diseño del agente (conjuntos de herramientas más reducidos, presupuestos de tokens más pequeños) antes de aumentar la concurrencia.
Automatización y fiabilidad
Las invocaciones masivas desde Flow pueden devolver identificadores de solicitudes diferidas en lugar de respuestas inmediatas. Revise los elementos posteriores que esperan respuesta, créditos o resultados en la misma transacción. Las acciones automáticas conservan el canal y modo configurados, y sus resultados reales quedan en contexto; esto no garantiza un turno narrativo adicional. Se conservan desplazamientos horarios explícitos en eventos, programación, escritura de campos y CSV compatibles. Sin desplazamiento se conserva la interpretación del usuario ejecutor. El modo Sistema no genera advertencias por el mero hecho de usarlo; continúan los registros y notificaciones de nivel ERROR. La extracción respeta el límite de salida, los colores funcionan en los temas Salesforce admitidos y las pruebas empaquetadas evitan referencias estáticas que bloqueaban la instalación sin tipos de registro de Cuenta.
Preguntas frecuentes
El desencadenante más común es una carga de archivo demasiado grande para caber dentro de los límites de procesamiento síncrono de Salesforce. La plataforma detecta esa condición antes de llamar al modelo y, en su lugar, enruta la solicitud a un trabajo en segundo plano.
El enrutamiento asíncrono lo decide la plataforma según la forma de la solicitud; no lo activa el llamador. Para estructurar el trabajo como asíncrono por diseño — por ejemplo, una ejecución en segundo plano impulsada por un flujo, sin ningún usuario esperando la respuesta — enrútalo a través de la acción invocable de Flow y deja que la plataforma decida si lo ejecuta en línea o lo delega.
La llamada al modelo en sí cuesta lo mismo; lo asíncrono solo cambia dónde se ejecuta el trabajo. La única diferencia en créditos proviene de los reintentos ante un fallo: cada reintento que vuelve a llamar al modelo consume créditos de la forma habitual.
El widget de chat muestra un estado de espera mientras la solicitud asíncrona está en curso. Para los canales no interactivos, diseña la integración de modo que exponga el estado: para las integraciones de mensajería, un indicador de escritura; para el correo, una respuesta de espera; para los llamadores de Flow, un campo de estado en el registro principal.
La solicitud asíncrona queda en estado Error con el mensaje de error registrado. También se crea un registro en el Registro de incidentes de IA. La conversación contiene el mensaje del usuario, pero ninguna respuesta del agente; las integraciones deben detectar el estado Error y, o bien reintentar con el usuario, o bien exponer el fallo de forma clara.
Sí. La ruta asíncrona ejecuta el mismo bucle agéntico que la ruta síncrona; las herramientas se ejecutan de la misma manera. Ten en cuenta que las tarjetas de confirmación necesitan una interfaz para mostrarse; en los canales exclusivamente asíncronos, configura el agente con la ejecución automática de acciones (Auto Execute Actions) o restringe el conjunto de herramientas a herramientas de lectura y acciones que no requieran confirmación.
En el Depurador de conversaciones de esa conversación. El Depurador muestra el ensamblaje del prompt, cada llamada a una herramienta, las respuestas del modelo y los créditos consumidos, igual que al inspeccionar una ejecución síncrona.
Próximos pasos
Lee Integración del canal de mensajería para conocer un patrón completo que usa el procesamiento asíncrono, o Invocar REDA AI desde Flujos para ver el lado del contrato que corresponde al llamador de Flow.