Referencia para agentes

A medida que crees agentes personalizados, consulta este artículo para obtener más información sobre configuraciones clave, como instrucciones y esquemas de salida. Para una configuración paso a paso, consulta Crear agentes personalizados. Para una introducción, consulta Agentes de Braze y Preguntas frecuentes.

Modelos

Cuando configuras un agente, puedes elegir el modelo que utiliza para generar respuestas. Tienes dos opciones: usar un modelo proporcionado por Braze o traer tu propia clave de API.

Importante

El modelo Auto proporcionado por Braze está optimizado para modelos cuyas capacidades de razonamiento son suficientes para realizar tareas como recuperar datos de catálogo a través de fuentes de conocimiento y comprobar la pertenencia a Segments. Cuando uses otros modelos, te recomendamos realizar pruebas para confirmar que tu modelo funciona bien para tu caso de uso. Es posible que necesites ajustar tus instrucciones para dar diferentes niveles de detalle o razonamiento paso a paso a modelos con diferentes velocidades y capacidades.

Opción 1: Usar un modelo proporcionado por Braze

Esta es la opción más sencilla, sin necesidad de configuración adicional. Braze proporciona acceso a modelos de lenguaje grande (LLM) directamente. Para usar esta opción, selecciona Auto, que utiliza modelos Gemini.

Importante

Si no ves Braze Auto como opción en el desplegable Model al crear un agente, contacta a tu administrador de éxito de cliente para saber cómo ser elegible para usar el modelo Braze Auto.

Opción 2: Traer tu propia clave de API

Con esta opción, puedes conectar tu cuenta de Braze con proveedores como OpenAI, Anthropic o Google Gemini. Si traes tu propia clave de API de un proveedor de LLM, los costes de tokens se facturan directamente a través de tu proveedor, no a través de Braze.

Te recomendamos probar de forma rutinaria los modelos más recientes, ya que los modelos heredados pueden ser descontinuados o quedar obsoletos después de unos meses. Asegúrate de tener suficientes créditos con tu proveedor para ejecutar tus agentes a escala. También puedes suscribirte a las notificaciones de Agent Console en Preferencias de notificación para recibir alertas cuando Braze detecte que un modelo ya no está disponible o encuentre problemas de facturación con tu proveedor de LLM.

Para configurar esto:

1. Ve a Partner Integrations > Technology Partners y busca tu proveedor.
2. Introduce tu clave de API del proveedor.
3. Selecciona Save.

Luego, puedes volver a tu agente y seleccionar tu modelo.

Cuando usas un LLM proporcionado por Braze, los proveedores de dicho modelo actúan como subprocesadores de Braze, sujetos a los términos del Acuerdo de Procesamiento de Datos (DPA) entre tú y Braze. Si decides traer tu propia clave de API, el proveedor de tu suscripción de LLM se considera un proveedor externo según el contrato entre tú y Braze.

Niveles de razonamiento

Algunos proveedores de LLM pueden permitirte ajustar el nivel de razonamiento de un modelo seleccionado. Los niveles de razonamiento definen el rango de reflexión que el modelo utiliza antes de responder, desde respuestas rápidas y directas hasta cadenas de razonamiento más largas. Esto afecta la calidad de la respuesta, la latencia y el uso de tokens.

Te recomendamos empezar con Mínimo y probar las respuestas de tu agente. Luego, puedes ajustar el nivel de razonamiento a Bajo o Medio si encuentras que el agente tiene dificultades para proporcionar respuestas precisas. En casos excepcionales, puede ser necesario un nivel de razonamiento Alto, aunque usar este nivel puede resultar en altos costes de tokens y tiempos de respuesta más largos o mayor riesgo de errores de tiempo de espera agotado. Si tu agente tiene dificultades para equilibrar el razonamiento de múltiples pasos con tiempos de respuesta razonables, considera dividir tu caso de uso en más de un agente que puedan trabajar juntos en un Canvas o catálogo.

Braze utiliza los mismos rangos de IP para las llamadas LLM salientes que para el contenido conectado. Los rangos están listados en la lista de IP permitidas de contenido conectado. Si tu proveedor admite listas de IP permitidas, puedes restringir la clave a esos rangos para que solo Braze pueda usarla.

Importante

Cuando usas un LLM proporcionado por Braze, los proveedores de dicho modelo actúan como subprocesadores de Braze, sujetos a los términos del Acuerdo de Procesamiento de Datos (DPA) entre tú y Braze. Si decides traer tu propia clave de API, el proveedor de tu suscripción de LLM se considera un proveedor externo según el contrato entre tú y Braze.

Determinar qué modelo usar

Cada proveedor de LLM tiene una combinación ligeramente diferente de capacidades de modelo, costes y niveles de razonamiento. Aquí tienes algunas directrices generales y mejores prácticas:

• Para optimizar costes, prioriza probar modelos con menor coste de tokens sobre modelos de mayor coste. Ajusta a modelos de mayor coste solo si los modelos de menor coste tienen dificultades con el caso de uso o generan resultados inconsistentes o imprecisos.
• Para optimizar velocidad y rendimiento, prioriza probar niveles de razonamiento de modelo más bajos sobre niveles más altos. Ajusta a niveles de razonamiento más altos solo si los niveles más bajos tienen dificultades con el caso de uso o generan resultados inconsistentes o imprecisos.
• Si los modelos de menor coste o los niveles de razonamiento más bajos tienen dificultades con el caso de uso o generan resultados inconsistentes o imprecisos, considera ajustar a modelos de mayor coste o niveles de razonamiento más altos.
• Durante las pruebas, asegúrate de equilibrar la fiabilidad y la precisión con el uso de tokens y la duración de la invocación.
• Cada caso de uso puede tener un modelo y nivel de razonamiento óptimo diferente. Te recomendamos realizar pruebas exhaustivas para comprobar la calidad consistente sin tiempos de espera agotados.

Controles de flujo de invocación

Los siguientes controles de flujo de invocación se aplican por espacio de trabajo:

• Modelo proporcionado por Braze: 5000 invocaciones por minuto
• Traer tu propia clave de API: 5000 invocaciones por minuto

Cuando muchos usuarios entran en un paso de agente al mismo tiempo, Braze pone en cola las invocaciones según estos límites, por lo que el procesamiento puede tardar más durante envíos de alto volumen.

Límites diarios de invocación y créditos

Cada agente tiene un límite diario de invocaciones (predeterminado 250 000; máximo 1 000 000 a menos que tu contrato permita más). Cada invocación (incluyendo las vistas previas de Agent Console y las ejecuciones de Canvas de prueba que usan Simulate response) cuenta para este límite.

En Agent Console, el Daily action credit cost limit estima los créditos máximos que un agente puede consumir por día. Braze multiplica la ratio de créditos por invocación de tu espacio de trabajo para el modelo seleccionado por el límite diario de invocaciones.

Cuándo se consumen los créditos

Braze cobra créditos solo por las invocaciones que completan el procesamiento. Los créditos no se consumen cuando una invocación falla debido a:

• Un error de límite de velocidad del proveedor de LLM (incluyendo los reintentos que finalmente fallan)
• El modelo seleccionado no está disponible
• El agente alcanza su límite diario de invocaciones

Los créditos se consumen cuando una invocación supera el tiempo de espera, aunque el agente no devuelva un resultado utilizable.

Monitorizar el uso de créditos

Ve a Settings > Billing > Credits Usage > Agent Console para ver el consumo de créditos, los recuentos de invocaciones y las ratios de créditos por agente.

Las ratios de créditos provienen de tu contrato y aparecen en el panel de Credits Usage (pestaña Credit Ratios y pestaña Agent Console). La estimación se actualiza cuando cambias el modelo o el límite de invocaciones.

Para gestionar el gasto, reduce el límite diario de invocaciones. Para los modelos de traer tu propia clave (BYO), también puedes elegir un modelo de menor coste o reducir el nivel de razonamiento para disminuir los costes de tokens del proveedor. Braze Auto no admite el ajuste del nivel de razonamiento.

Errores de límite de velocidad

Si el proveedor de LLM devuelve un error de límite de velocidad durante una invocación de un agente de paso en Canvas o agente de catálogo, Braze reintenta continuamente la solicitud usando retirada exponencial hasta que la llamada tenga éxito o Braze determine que no puede completarse.

Cuando los reintentos de Canvas o catálogo se agotan, el panel de detalles de Logs muestra Error y el mensaje del proveedor (como Rate limit exceeded) en Output. Los reintentos son visibles en los registros, incluyendo la primera invocación independientemente de su éxito o fallo final. Para un usuario determinado, si se necesitan cuatro reintentos para finalmente obtener un éxito, puedes buscar el ID de usuario y ver los cinco (el original más cuatro reintentos) en Logs, y el original más los tres primeros reintentos mostrarán Error con Rate limit exceeded.

Los errores de límite de velocidad no consumen créditos de Braze, incluyendo los reintentos fallidos que aparecen en Logs.

Instrucciones de escritura

Las instrucciones son las reglas o directrices que le proporcionas al agente (indicación del sistema). Definen cómo debe comportarse el agente cada vez que se ejecuta. Las instrucciones del sistema pueden tener hasta 25 KB.

Si creaste tu agente con BrazeAI Operator utilizando una plantilla de inicio, revisa las instrucciones prerrellenadas y edítalas según sea necesario.

Estas son algunas mejores prácticas generales para comenzar con las indicaciones:

1. Comienza con el fin en mente. Declara el objetivo primero.
2. Dale al modelo un rol o persona (“Eres un …”).
3. Establece un contexto y restricciones claros (audiencia, longitud, tono, formato).
4. Pide estructura (“Devuelve JSON/lista con viñetas/tabla…”).
5. Muestra, no cuentes. Incluye algunos ejemplos de alta calidad.
6. Divide las tareas complejas en pasos ordenados (“Paso 1… Paso 2…”).
7. Incentiva el razonamiento (“Piensa en los pasos internamente, luego proporciona una respuesta final concisa” o “explica brevemente tu decisión”).
8. Prueba, inspecciona e itera. Pequeños ajustes pueden producir grandes mejoras en la calidad.
9. Maneja los casos límite, añade barreras de protección e instrucciones de rechazo.
10. Mide y documenta lo que funciona internamente para reutilización y escalamiento.

Ejemplos

Para configuraciones iniciales en Agent Console, consulta Plantillas de agentes creadas con Operator.

Para ejemplos completos de instrucciones que puedes copiar o adaptar, consulta la biblioteca de casos de uso para Braze Agents.

Uso de Liquid

Incluir Liquid en las instrucciones de tu agente puede añadir una capa adicional de personalización en su respuesta. Puedes especificar la variable de Liquid exacta que recibe el agente e incluirla en el contexto de tu indicación. Por ejemplo, en lugar de escribir explícitamente “nombre”, puedes usar el fragmento de Liquid {{${first_name}}}:

1

Tell a one-paragraph short story about this user, integrating their {{${first_name}}}, {{${last_name}}}, and {{${city}}}. Also integrate any context you receive about how they are currently thinking, feeling, or doing. For example, you may receive {{context.${current_emotion}}}, which is the user's current emotion. You should work that into the story.

En la sección Logs de Agent Console, puedes revisar los detalles de la entrada y salida del agente para comprender qué valor se renderiza desde Liquid.

Qué datos reciben los agentes

El contexto del agente no es memoria conversacional abierta. A diferencia de un asistente de chat, un agente solo ve los datos que le pasas explícitamente en el momento de la invocación: no navega perfiles de usuario, no infiere campos faltantes ni te avisa cuando falta información requerida.

Diseña cada agente como un flujo deliberado de entrada a salida. Conecta cada punto de datos que el agente necesita utilizando uno o más de los siguientes métodos:

1. Liquid en las instrucciones: Usa plantillas de atributos de usuario ({{${first_name}}}) y variables de contexto de Canvas ({{context.${variable_name}}}) directamente en la indicación del agente.
2. + Agent context: Selecciona fuentes de conocimiento, pertenencia a Segments, directrices de marca, All Canvas Context o datos de interacción del usuario en Agent Console.
3. Pasos de contexto: Establece o actualiza variables context.* en una etapa anterior del Canvas antes de que se ejecute un paso del agente.
4. Contexto adicional en el paso del agente: Pasa cualquier valor adicional con plantillas de Liquid que no se haya especificado previamente a través de los otros métodos al agente en el momento del envío desde la configuración del paso.

Asegúrate de usar plantillas de Liquid para estas variables de contexto en las instrucciones del agente, adjuntar archivos de contexto que el agente deba consultar, o seleccionar Add All Canvas Context. Si un valor no se pasa a través de uno de estos canales, el agente no lo recibe. Enumera las entradas requeridas en tus instrucciones o en los prerrequisitos del caso de uso, y verifica las entradas en Agent Console > Logs después de las pruebas.

Para agentes de catálogo, usa Fields en la sección Output en lugar del esquema JSON; aún puedes escribir instrucciones que le pidan al modelo una salida de clave-valor que coincida con esos nombres de campo.

Para más detalles sobre mejores prácticas de indicaciones, consulta las guías de los siguientes proveedores de modelos:

• OpenAI
• Anthropic
• Gemini

Salidas

Si construiste tu agente con BrazeAI Operator usando una plantilla inicial, revisa el esquema de salida precargado y edítalo según sea necesario.

Esquemas básicos

Los esquemas básicos son una salida simple que un agente devuelve. Puede ser una cadena, un número, un booleano, una matriz de cadenas o una matriz de números.

Por ejemplo, si deseas recopilar puntuaciones de sentimiento de usuarios a partir de un cuestionario de opinión sencillo para determinar qué tan satisfechos están tus clientes después de recibir un producto, puedes seleccionar Number como esquema básico para estructurar el formato de salida.

Importante

Las matrices solo están disponibles para agentes de paso en Canvas, no para agentes de catálogo.

Esquemas avanzados

Las opciones de esquemas avanzados incluyen estructurar campos manualmente o usar JSON.

• Fields: Una forma sin código para aplicar una salida de agente que puedes usar de manera consistente.
• JSON: Un enfoque con código para crear un formato de salida preciso, donde puedes anidar variables y objetos dentro del esquema JSON. Solo disponible para agentes de paso en Canvas, no para agentes de catálogo.

Recomendamos usar esquemas avanzados cuando deseas que el agente devuelva una estructura de datos con múltiples valores definidos de forma estructurada, en lugar de una salida de valor único. Esto permite que la salida tenga un mejor formato como variable de contexto consistente.

Salida alternativa

Los valores alternativos están disponibles solo para agentes de paso en Canvas. En la sección Output de la consola de agente para un agente de paso en Canvas, puedes definir valores que Braze utiliza cuando una invocación falla.

Para esquemas JSON, Braze lee el esquema y genera un campo de entrada para cada propiedad, de modo que puedas establecer un valor alternativo por clave. Para esquemas Fields, introduces un valor alternativo para cada campo. Para esquemas básicos, introduces un único valor alternativo. Los agentes de paso en Canvas admiten Liquid en los valores alternativos.

Para los pasos de configuración, consulta Configurar valores alternativos. Para el comportamiento en tiempo de ejecución en Canvas, consulta Manejo de errores y comportamiento alternativo.

Por ejemplo, puedes usar un formato de salida dentro de un agente que está diseñado para crear un itinerario de viaje de ejemplo para un usuario basado en un formulario que envió. El formato de salida te permite definir que cada respuesta del agente debe regresar con valores para tripStartDate, tripEndDate y destination. Cada uno de estos valores puede extraerse de variables de contexto y colocarse en un paso de mensaje para personalización usando Liquid.

• fields
• json schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string"
    },
    "reasoning": {
      "type": "string"
    }
  },
  "required": [
    "sentiment",
    "reasoning"
  ]
}

Contexto de catálogo y campos

Para dar a un agente de paso en Canvas acceso a los datos de un catálogo, crea una fuente de conocimiento a partir del catálogo y añádela como + Agent context. El agente consulta la fuente de conocimiento para recuperar las filas coincidentes y envía solo los datos relevantes del catálogo al LLM, lo que minimiza el uso de tokens y mejora la precisión de la recuperación. No adjuntes el catálogo directamente como contexto del agente. Los agentes configurados con la opción heredada Add catalog fields antes de que las fuentes de conocimiento estuvieran disponibles pueden seguir utilizando ese contexto hasta que los migres.

Cuando despliegas un agente de catálogo en un campo de catálogo, habilita el control de entrada obligatoria y elige qué columnas seleccionadas son necesarias para ejecutarse antes de que el agente se invoque. El agente omite una fila solo cuando una de esas columnas obligatorias está vacía o no existe; por ejemplo, un campo gender que aún no se ha rellenado. Las columnas seleccionadas se marcan como obligatorias de forma predeterminada, pero puedes eliminar columnas que pueden estar vacías sin bloquear la ejecución. Esto evita el desperdicio de tokens en datos incompletos.

Los agentes de catálogo también respetan el orden de las columnas cuando los campos de entrada dependen unos de otros. Si la columna D debe generarse a partir de las columnas B y C, el agente no se ejecuta en la columna D hasta que B y C contengan valores para esa fila.

Para escenarios de despliegue y ejemplos, consulta Usar agentes de catálogo y Prácticas recomendadas para agentes de catálogo.

Contexto de pertenencia a Segment

Puedes seleccionar hasta cinco Segments para que el agente haga una referencia cruzada de la pertenencia de cada usuario a un Segment cuando el agente se utiliza en un Canvas. Supongamos que tu agente tiene la pertenencia a Segment seleccionada para un Segment “Loyalty Users” y el agente se utiliza en un Canvas. Cuando los usuarios entran en un paso de agente, el agente puede verificar si cada usuario es miembro de cada Segment que especificaste en la consola del agente, y utilizar la pertenencia (o no pertenencia) de cada usuario como contexto para el LLM.

Directrices de marca

Puedes seleccionar directrices de marca para que tu agente las siga en sus respuestas. Por ejemplo, si quieres que tu agente genere textos de SMS para animar a los usuarios a suscribirse a una membresía de gimnasio, puedes usar este campo para hacer referencia a tus directrices predefinidas de estilo atrevido y motivacional.

Archivos de contexto

Sube documentos de referencia para que un agente pueda consultar material estático en cada invocación; por ejemplo, una guía de tono, un documento de políticas o una especificación de producto. Los archivos de contexto están disponibles para agentes de paso en Canvas y agentes de catálogo.

Para adjuntar archivos:

1. En el paso Instructions, selecciona + Agent context > Upload files.
2. Añade uno o más archivos. Los tipos compatibles son PDF, TXT, MD y CSV.
3. Guarda el agente. Los archivos se suben cuando guardas. Permanecen preparados en el navegador y se incluyen cuando previsualizas el agente.

Puedes adjuntar hasta 10 archivos por agente. Todos los archivos adjuntos juntos pueden sumar hasta 15 MB. Cuando adjuntes archivos de contexto, indica al agente en tus instrucciones cómo utilizarlos. Por ejemplo, puedes incluir: “Sigue el tono y la terminología de la guía de estilo adjunta.” Una sección Files vacía cuenta para la advertencia de needs setup hasta que adjuntes al menos un archivo.

Braze envía los archivos adjuntos con cada invocación del agente, incluidas las vistas previas de la consola del agente. Dado que los archivos se incluyen en cada ejecución, los archivos adjuntos de mayor tamaño pueden aumentar el uso de tokens y la latencia.

Los archivos de contexto difieren de las directrices de marca: las directrices de marca son configuraciones de espacio de trabajo sintetizadas, mientras que los archivos de contexto son documentos que subes directamente a un solo agente. Para los pasos de configuración, consulta Añadir contexto.

Historial de interacción específico del usuario

Los datos de interacción de un usuario incluyen las Campaign y los mensajes de Canvas recibidos recientemente por canal, el contenido de cada mensaje y si el usuario interactuó con cada mensaje. Puedes incluir esto como contexto específico del usuario para que un agente lo consulte cuando se invoca para un usuario en Canvas. El historial de interacción específico del usuario puede ayudar a influir en un agente para que redacte textos que conecten con cada usuario cuando su tarea es escribir textos de mensajes personalizados.

Historial de versiones

La Consola de Agente registra una nueva versión cada vez que guardas cambios en el agente. La pestaña Historial de versiones enumera cada versión guardada y las ediciones entre guardados.

1. Abre el agente en la Consola de Agente.
2. Selecciona la pestaña Historial de versiones.
3. Selecciona una versión para revisar su configuración.

Para inspeccionar qué cambió en una versión, selecciona Ver. Braze muestra una diferencia en línea de estilo código que resalta las adiciones y eliminaciones. El contenido eliminado aparece con estilo de tachado en rojo. Cuando añades o eliminas archivos de contexto, la diferencia muestra los nombres de los archivos adjuntos.

Si necesitas restaurar instrucciones de una versión anterior, abre Ver para esa versión, copia el texto de las instrucciones y pégalo en tu campo Instrucciones actual.

Consejo

En la vista de diferencias en línea, presiona ⌘ + A (macOS) o Ctrl + A (Windows) para seleccionar todas las instrucciones sin el marcado de eliminación en rojo, de modo que puedas copiar y restaurar el texto limpio.

Duplicar agentes

Duplica un agente para probar mejoras o iteraciones en paralelo con el original. Usa el historial de versiones para revisar o restaurar configuraciones anteriores. Para duplicar un agente:

1. Pasa el cursor sobre la fila del agente y selecciona el menú .
2. Selecciona Duplicar.

Archivar agentes

A medida que crees más agentes personalizados, puedes organizar la página Agent Management archivando los agentes que no estén en uso activo. Para archivar un agente:

1. Pasa el cursor sobre la fila del agente y selecciona el menú .
2. Selecciona Archive.