Implementar agentes personalizados
Después de crear un agente, utiliza esta página para saber dónde y cómo implementarlo en Braze. El tipo de agente que elijas en el momento de la creación —agente de Canvas o agente de catálogo— determina dónde puede ejecutarse el agente. Para obtener una introducción, consulta Agentes de Braze.
Tipos de agentes personalizados
Los agentes personalizados se implementan en distintas partes de Braze según su tipo. Usa la siguiente tabla para encontrar la ruta de implementación adecuada para tu agente.
| Tipo de agente | Se implementa en | Se ejecuta cuando | Sección |
|---|---|---|---|
| Agente de paso en Canvas | Paso de agente en Canvas | Un usuario entra en el paso | Usar agentes de paso en Canvas |
| Agente de catálogo | Campo de catálogo | Se crea o actualiza una fila del catálogo | Usar agentes de catálogo |
Seleccionas el tipo de agente en la Consola de agentes cuando creas el agente. Para ver los pasos de configuración, consulta Crear agentes personalizados.
Mejores prácticas
Céntrate en casos de uso de alto valor en los que los agentes puedan generar el mayor retorno de la inversión (ROI) y elige audiencias con probabilidad de responder. Una audiencia más pequeña y con muchas oportunidades suele dar mejores resultados que una audiencia grande con pocas oportunidades.
Con los agentes de paso en Canvas, empieza por usuarios con señales fuertes, como búsquedas recientes, alta participación o datos de perfil completos, antes de ampliar a Segments más amplios. Con los agentes de catálogo, da prioridad a las filas en las que ya estén rellenadas las columnas de entrada que necesitas, para que cada invocación tenga contexto suficiente y genere resultados útiles.
Para probar el ROI a pequeña escala antes de implementar un agente de forma generalizada, usa un paso de Recorridos de experimentos para que solo una parte de tu audiencia entre en la rama que contiene tu paso de agente.
Escalar tras una prueba satisfactoria
Cuando una prueba a pequeña escala (por ejemplo, una rama de Recorridos de experimentos) muestre una calidad y un ROI aceptables, planifica implementar el agente para todo tu público objetivo (no solo para el grupo de prueba), de modo que todos los usuarios elegibles se beneficien.
Antes de escalar, ten en cuenta lo siguiente:
- Aumenta el límite diario de invocaciones del agente en Agent Console para que pueda gestionar el volumen completo de tu audiencia. El valor predeterminado es 250 000; puedes aumentarlo hasta 1 000 000 (o más, con tu administrador de éxito de cliente). Consulta Límites diarios de invocaciones y créditos.
- Revisa la estimación del Límite diario de coste de créditos por acción y confirma que tu espacio de trabajo tiene créditos suficientes para envíos a escala completa.
- Elimina o vuelve a configurar el experimento para que todo el público objetivo entre en el paso de agente (o promueve la variante ganadora a la ruta principal).
Escalar a toda la audiencia aumenta el consumo de créditos de forma proporcional. Supervisa el uso en Configuración > Facturación > Uso de créditos > Agent Console después del lanzamiento.
Usar agentes de paso en Canvas
Después de crear un agente de paso en Canvas, añádelo a un Canvas como paso de agente para personalizar mensajes u orientar la toma de decisiones en tiempo real.
Cómo funciona
Cuando un usuario llega a un paso de agente en un Canvas, Braze envía a tu agente los datos de entrada que configuraste. El agente procesa la entrada con su modelo y sus instrucciones y, después, devuelve una salida que se almacena en la variable de salida que definiste en el paso. Puedes usar esa salida para la toma de decisiones, la personalización o el procesamiento posterior.
Los pasos de agente usan variables de contexto de Canvas para recibir el contexto relevante y generar una variable que se puede usar en el Canvas. Para conocer los requisitos previos y consultar la referencia completa, consulta Paso de agente.
Añadir un paso de agente
Para añadir un agente a tu Canvas:
- Arrastra y suelta el componente Agente desde la barra lateral, o selecciona el botón más en la parte inferior de un paso y selecciona Agente.
- Selecciona el agente que procesa los datos en este paso.
- Define el nombre de la variable de salida. El tipo de datos de salida se establece en la Consola de agentes.
- (Opcional) Añade valores de contexto adicionales para que el agente los consulte cuando se ejecute. Pueden incluir variables de Liquid adicionales o contexto de Canvas que aún no hayas vinculado en la configuración del agente; por ejemplo, valores que solo quieras pasar en el momento del envío desde este paso.
- Prueba el agente con la vista previa del paso o con Probar Canvas para recorrer la ruta completa del usuario.
Para ver los tipos de datos de salida, las plantillas de Liquid y capturas de pantalla, consulta Paso de agente.
Casos de uso
| Caso de uso | Descripción |
|---|---|
| Puntuación y cualificación de clientes potenciales | Usa un paso de agente para evaluar los clientes potenciales entrantes en una escala (por ejemplo, del 1 al 10). Dirige a los usuarios con una puntuación superior a un umbral hacia rutas de nutrición y descarta los clientes potenciales poco adecuados. |
| Personalización dinámica de mensajes | Haz que un agente genere líneas del asunto, recomendaciones de productos o textos de mensajes en función de los atributos o comportamientos recientes del usuario. La respuesta puede insertarse directamente en un paso de Mensaje. |
| Gestión de los comentarios de los clientes | Pasa los comentarios de los clientes a un agente para que analice el sentimiento y genere mensajes de seguimiento empáticos. Para los usuarios de alto valor, el agente puede escalar la respuesta o incluir ventajas. |
| Enrutamiento inteligente | Usa las salidas del agente (booleanas o numéricas) para dividir a los usuarios en distintas rutas de Canvas. Por ejemplo, clasifica a los usuarios como “en riesgo” o “saludables” y ajusta la cadencia de mensajería en consecuencia. |
| Interpretación de cuestionarios o respuestas | Deja que un agente analice las respuestas abiertas de cuestionarios o los campos de texto libre y devuelva valores estructurados (por ejemplo, categorizando la intención o la necesidad) que dirijan las rutas posteriores. |
| Razonamiento en varios pasos | Configura un agente para que combine campos de contexto y tome decisiones complejas, como recomendar la siguiente mejor acción (correo electrónico, SMS o contacto humano) en función de varios atributos del usuario. |
Usar la salida del agente
Después de que se ejecute el agente, usa la variable de salida en tu Canvas:
- Enrutamiento del recorrido: Dirige a los usuarios por distintas rutas de Canvas en función de la respuesta del agente. Usa rutas de audiencia o divisiones de decisiones con salidas numéricas, booleanas o estructuradas.
- Personalización: Inserta la respuesta del agente directamente en un paso de Mensaje con Liquid.
- Procesamiento de datos de usuario: Analiza y estandariza los datos de usuario y, después, guárdalos en el perfil de usuario (por ejemplo, con un paso de Actualización de usuario) o envíalos mediante un webhook.
Para ver ejemplos, consulta Cómo funciona en Paso de agente.
Gestión de errores y comportamiento alternativo
Lo siguiente se aplica a los agentes de paso en Canvas en un paso de agente.
- Si el modelo conectado devuelve un error de límite de velocidad del proveedor de LLM, Braze reintenta la solicitud continuamente con retirada exponencial hasta que la llamada se completa correctamente o Braze determina que no se puede completar; después, los usuarios pasan al siguiente paso en Canvas.
- En otros fallos (como un tiempo de espera agotado o una clave de API no válida), la variable de salida se establece en
null, a menos que el agente tenga valores alternativos configurados en la Consola de agentes. - Si un agente alcanza su límite diario de invocaciones, Braze también aplica los valores alternativos configurados cuando existen; de lo contrario, la variable de salida se establece en
null.
Cuando hay valores alternativos configurados, Braze los aplica en los errores que no se reintentan y en los fallos por límite diario. Braze renderiza el valor alternativo con Liquid para cada usuario y almacena el resultado en la variable de salida del paso de agente. Sin valores alternativos, esos fallos establecen la variable de salida en null. Si prefieres configurar valores predeterminados específicos del paso en los pasos de Mensaje en lugar de usar los valores alternativos de la Consola de agentes, puedes seguir usando valores predeterminados de Liquid en los pasos posteriores. Para ello, deja en blanco los valores alternativos en la sección Salida de la configuración del agente para que puedan aplicarse los valores predeterminados de Liquid cuando el agente devuelva null.
Los errores de límite de velocidad, la falta de disponibilidad del modelo y los fallos por límite diario de invocaciones no consumen créditos de Braze. Los tiempos de espera agotados sí consumen créditos. Consulta Cuándo se consumen créditos.
- Las respuestas se almacenan en caché para entradas idénticas y pueden reutilizarse en invocaciones idénticas repetidas en un plazo de pocos minutos. Las respuestas en caché siguen contando para las invocaciones totales y diarias.
- Los pasos de agente pueden tardar en procesar un lote grande de usuarios. Braze pone en cola las invocaciones según los controles de flujo de invocaciones, por lo que los usuarios pueden permanecer pendientes durante envíos de gran volumen.
Para conocer los detalles de configuración y ejecución del paso de agente, consulta Gestión de errores en Paso de agente. Para más información, consulta Gestión de errores en Braze Agents.
Usar agentes de catálogo
Después de crear un agente de catálogo, aplícalo a un campo del catálogo para generar o calcular valores automáticamente para cada fila. El agente también se ejecuta en las nuevas filas que se añadan al catálogo en el futuro.
Cómo funciona
Tras el lanzamiento, el agente se ejecuta y evalúa cada fila, tomando las columnas seleccionadas como contexto para producir un resultado. Los agentes se ejecutan en todas las filas nuevas que se añadan después de implementar el agente. Si seleccionaste Recalcular cuando se actualicen las filas del catálogo, todos los valores de este campo se actualizan si cambian los campos de origen existentes.
Cuando configures las columnas de entrada de un agente de catálogo, habilita el control del producto que indica qué columnas seleccionadas son obligatorias antes de que se invoque el agente (las etiquetas pueden variar ligeramente según el espacio de trabajo). Con ese control habilitado, elige el subconjunto de columnas que deben contener valores: las columnas seleccionadas son obligatorias de forma predeterminada, pero puedes quitar las columnas que pueden estar vacías sin bloquear al agente. El agente solo omite una fila cuando una columna que dejaste como obligatoria está en blanco o falta; por ejemplo, un campo gender que no se ha rellenado. Ejecutar el agente sin el contexto necesario desperdicia tokens y puede producir resultados de baja calidad.
Los agentes de catálogo también respetan las dependencias entre columnas. Si la columna D se genera a partir de las columnas B y C, el agente no se ejecuta en la columna D de una fila hasta que B y C contengan valores para esa fila.
Puedes actualizar y editar los campos de tu catálogo que usan agentes. Para quitar un agente de una columna, deselecciona Aplicar agente de IA. Esto convierte la columna en una columna no agéntica, y los campos conservan los últimos valores que aplicó el agente la última vez que se ejecutó en el catálogo.
Las referencias circulares en los catálogos no son compatibles, lo que significa que no puede darse el siguiente escenario:
- La columna agéntica 1 usa la columna agéntica 2 como entrada
- La columna agéntica 2 usa la columna agéntica 1 como entrada
Añadir un agente a un campo del catálogo
Para añadir un agente a tu campo del catálogo:
- En tu catálogo, añade un nuevo campo.
- Selecciona Aplicar agente de IA.
- Asigna un agente a este campo.
- Selecciona qué columnas deben pasarse como entrada. Si no seleccionas ninguna, el agente tiene acceso a todas las columnas del catálogo.
- (Opcional) Habilita Ejecutar solo cuando las columnas obligatorias tengan valores para omitir las filas en las que una o más columnas de entrada seleccionadas estén en blanco. Cuando esta opción está activada, selecciona cuáles de las columnas de entrada deben estar rellenas para que se ejecute el agente: todas las columnas seleccionadas son obligatorias de forma predeterminada, pero puedes quitar las que pueden estar vacías sin bloquear una ejecución.
- Decide si el agente debe recalcular los campos cuando se actualicen las filas del catálogo. Si no seleccionas esta opción, el agente se ejecuta solo una vez por fila.
- Selecciona Añadir campos para implementar el agente y revisar las estimaciones de costes. El modal Estimación de costes muestra cuántas veces se ejecutará el agente en este catálogo, aproximadamente igual al número total de filas. Para continuar, selecciona Confirmar.
Buenas prácticas para agentes de catálogo
Planifica qué columnas necesita el agente antes de aplicarlo a un campo del catálogo. Después de habilitar los controles de entrada obligatoria para el campo, selecciona las columnas que contienen los datos que debe leer tu agente y, a continuación, desmarca cualquier columna que pueda quedarse vacía sin bloquear una ejecución. El agente solo omite una fila cuando una columna que dejaste marcada como obligatoria está en blanco.
No dejes una columna marcada como obligatoria si esperas que quede vacía en algunas filas y aun así quieres que se ejecute el agente; en su lugar, quítala del conjunto de columnas obligatorias. Omitir las filas incompletas evita un uso incorrecto de tokens y mantiene una alta calidad de los resultados.
| Escenario | Qué ocurre |
|---|---|
| Filas precargadas con marcadores de posición | Si añades filas al catálogo solo con un ID y un nombre de fondo, y rellenas otras columnas más tarde, el agente omite esas filas hasta que las columnas de entrada obligatorias tengan valores. |
| Agente aplicado cuando ya existen filas | Cuando aplicas un agente a un campo de un catálogo que ya tiene filas, el agente evalúa todas las filas, pero solo se ejecuta donde las columnas de entrada obligatorias están rellenas. |
| Catálogo parcialmente completo | Por ejemplo, un catálogo con 100 filas en el que leader está rellenado para las entradas de 2026, pero otras filas solo contienen un ID y un nombre de fondo con campos en blanco en el resto. El agente se ejecuta en las filas con un valor de leader y omite las filas que no lo tienen cuando leader sigue siendo obligatorio. |
| Columnas dependientes | Si la columna 3 depende de las columnas 1 y 2, el agente no escribe en la columna 3 hasta que las columnas 1 y 2 tengan valores para esa fila. |
Casos de uso
| Caso de uso | Descripción |
|---|---|
| Generar descripciones de productos | Crea automáticamente textos de marketing breves para nuevas entradas del catálogo; por ejemplo, generando una descripción atractiva a partir de datos estructurados del producto, como el nombre, la categoría y las características. |
| Enriquecer atributos de productos | Rellena valores que faltan, como la familia de colores, el estilo o la temporada, a partir del nombre y los detalles de un producto. Por ejemplo, si el nombre de un producto es “Laguna Polarized Sunglasses”, el agente podría asignar el estilo “deportivo” y la familia de colores “azul”. |
| Calcular campos derivados | Usa campos existentes para generar nuevos datos, como una “puntuación de ajuste” basada en atributos o una “etiqueta de popularidad” a partir de las ventas y el número de reseñas. |
| Categorizar o etiquetar artículos | Asigna etiquetas para la lógica de recomendación, de modo que los modelos de personalización puedan segmentar los productos de forma más eficaz. Por ejemplo, etiqueta productos como “exterior”, “listo para festivales” o “premium”. |
| Localizar contenido | Traduce el texto del catálogo a otro idioma para Campaigns globales, o ajusta el tono y la longitud para canales específicos de cada región. Por ejemplo, traduce “Classic Clubmaster Sunglasses” al español como “Gafas de sol Classic Clubmaster”, o acorta las descripciones para Campaigns de SMS. |
| Resumir reseñas o comentarios | Resume la opinión o los comentarios en un nuevo campo, por ejemplo, asignando puntuaciones de opinión como Positiva, Neutral o Negativa, o creando un breve resumen de texto como “La mayoría de los clientes mencionan un ajuste excelente, pero señalan que el envío es lento”. |
Definir campos de respuesta
Si tu agente usa campos como formato de salida, puedes seleccionar el campo correspondiente del agente en Campo de respuesta para usarlo en el campo del catálogo.
Supongamos que tienes un agente que añade descripciones de productos a un catálogo con los siguientes campos para estructurar el formato de salida:
| Nombre del campo | Valor |
|---|---|
| description | Texto |
| confidence_score_out_of_ten | Número |
Puedes añadir un campo llamado product_description a un catálogo y seleccionar description como Campo de respuesta para rellenar la columna con las descripciones del agente.
También puedes sobrescribir manualmente la celda generada por el agente seleccionando Editar elemento y actualizando la descripción generada por el agente con tus cambios. Para volver a la descripción generada por el agente, selecciona el símbolo de actualizar en la celda.
Tratamiento de errores
- Si el proveedor de LLM devuelve un error de límite de velocidad, Braze reintenta continuamente la solicitud usando retirada exponencial hasta que la llamada se realiza correctamente o Braze determina que no se puede completar.
- Para otros fallos (como un tiempo de espera agotado o una clave de API no válida), el valor del campo del catálogo no se actualiza. Los agentes de catálogo no admiten la configuración de valores alternativos en la consola de agentes.
- Puedes revisar los registros del agente para ver los detalles de las ejecuciones fallidas.
- Los agentes de catálogo están limitados a procesar valores de entrada de hasta 25 KB por fila.
Supervisa tu agente
La supervisión funciona igual tanto si tu agente se ejecuta en Canvas como en catálogos.
En la sección Uso de tu agente, puedes consultar los catálogos y Canvas en los que se está utilizando activamente el agente y navegar hasta ellos.
En la sección Registros de tu agente, puedes supervisar las llamadas reales al agente que se producen en tus Canvas y catálogos. Puedes filtrar por información como el intervalo de fechas, el resultado (éxito o error) o la ubicación de la llamada. También puedes seleccionar Exportar CSV para exportar solo los registros que se muestran en la página actual.
También puedes supervisar los errores por límite diario de invocaciones en el Registro de actividad de mensajes.
Selecciona Ver en una llamada concreta al agente para ver la entrada, la salida y el ID de usuario.
En el caso de los agentes de pasos en Canvas, los registros incluyen una sección Salida alternativa que muestra cualquier salida alternativa que se haya utilizado cuando la invocación generó un error.
Usar Currents
También puedes utilizar estos eventos de Currents para acceder a los esquemas de registros de Kafka:
- Eventos de agente ejecutado
- Eventos de invocación de herramientas
Consulta el glosario de eventos de interacción con mensajes para obtener más información.