Referencia para agentes

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

Modelos

Cuando configuras un agente, puedes elegir el modelo que utiliza para generar respuestas. Tienes dos opciones: usar un modelo con tecnología de Braze o usar tu propia clave de API.

Importante

El modelo Auto con tecnología de Braze está ajustado para tareas como buscar en fuentes de conocimiento y comprobar la pertenencia a un Segment. Si usas tu propio modelo, prueba estas tareas específicamente. Los modelos de menor coste con niveles de razonamiento bajos pueden omitir llamadas a herramientas o responder antes de recuperar los datos. Es posible que tengas que ajustar tus instrucciones para dar distintos niveles de detalle o pedir un razonamiento paso a paso a modelos con distintas velocidades y capacidades.

Opción 1: Usar un modelo con tecnología de Braze

Esta es la opción más sencilla y no requiere ninguna configuración adicional. Braze proporciona acceso directo a grandes modelos de lenguaje (LLM). Para usar esta opción, selecciona Auto, que utiliza modelos Gemini.

Opción 2: Usar tu propia clave de API

Con esta opción, puedes conectar tu cuenta de Braze con proveedores como OpenAI, Anthropic o Google Gemini. Para ver la lista completa de proveedores compatibles, consulta Proveedores de modelos de IA. Si usas 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 periódicamente los modelos más recientes, ya que los modelos antiguos pueden retirarse o quedar obsoletos al cabo de unos meses. Asegúrate de tener créditos suficientes 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 un aviso cuando Braze detecte que un modelo ya no está disponible o encuentre problemas de facturación con tu proveedor de LLM.

Para configurarlo:

1. Ve a Integraciones de socios > Socios tecnológicos y busca tu proveedor.
2. Introduce la clave de API de tu proveedor.
3. Selecciona Guardar.

Después, puedes volver a tu agente y seleccionar tu modelo.

Cuando usas un LLM proporcionado por Braze, los proveedores de dicho modelo actuarán como subencargados del tratamiento de Braze, sujetos a los términos del Anexo de Tratamiento de Datos (DPA) entre tú y Braze. Si decides usar 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 te permiten ajustar el nivel de razonamiento del modelo seleccionado. Los niveles de razonamiento definen cuánto razona el modelo antes de responder: desde respuestas rápidas y directas hasta cadenas de razonamiento más largas. Esto afecta a la calidad de la respuesta, la latencia y el uso de tokens.

Los niveles disponibles varían según el modelo. Algunos modelos ofrecen Ninguno en lugar de Mínimo, y no todos los modelos ofrecen Alto.

Te recomendamos empezar con Mínimo (o Ninguno) y probar las respuestas de tu agente. Si tu agente usa fuentes de conocimiento, empieza con Bajo. En el nivel más bajo, algunos modelos responden sin ejecutar la búsqueda. Si al agente le cuesta dar respuestas precisas, sube de nivel de uno en uno. En casos excepcionales, puede ser necesario un nivel de razonamiento Alto, aunque usar este nivel puede generar costes de tokens elevados, tiempos de respuesta más largos o un mayor riesgo de errores de tiempo de espera. Si a tu agente le cuesta equilibrar el razonamiento de varios pasos con tiempos de respuesta razonables, plantéate dividir tu caso de uso en más de un agente que puedan trabajar juntos en un Canvas o un catálogo.

Braze usa los mismos rangos de IP para las llamadas salientes a LLM que para el contenido conectado. Los rangos aparecen en la lista de IP permitidas para 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 actuarán como subencargados del tratamiento de Braze, sujetos a los términos del Anexo de Tratamiento de Datos (DPA) entre tú y Braze. Si decides usar 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 ofrece una combinación ligeramente distinta de capacidades, costes y niveles de razonamiento. Estas son algunas pautas generales y buenas prácticas:

• Para optimizar costes, prioriza probar modelos con menor coste por token antes que modelos más caros. Pasa a modelos más caros solo si los de menor coste tienen dificultades con el caso de uso o generan resultados incoherentes o imprecisos.
• Para optimizar la velocidad y el rendimiento, prioriza probar niveles de razonamiento más bajos antes que niveles más altos. Pasa a niveles de razonamiento más altos solo si los más bajos tienen dificultades con el caso de uso o generan resultados incoherentes 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 incoherentes o imprecisos, plantéate pasar a modelos más caros o a 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 las invocaciones.
• Cada caso de uso puede tener un modelo y un nivel de razonamiento óptimos distintos. Te recomendamos hacer pruebas exhaustivas para comprobar que la calidad es constante y no se producen tiempos de espera agotados.

Controles del flujo de invocaciones

Los siguientes controles del flujo de invocaciones se aplican por espacio de trabajo:

• Modelo con tecnología de Braze: 5000 invocaciones por minuto
• Usar tu propia clave de API: 5000 invocaciones por minuto

Cuando muchos usuarios entran a la vez en un paso Agente, Braze pone en cola las invocaciones según estos límites, por lo que el procesamiento puede tardar más durante los envíos de gran volumen.

Límites diarios de invocaciones y créditos

Cada agente tiene un límite diario de invocaciones (250 000 de forma predeterminada; máximo de 1 000 000, salvo que tu contrato permita más). Cada invocación (incluidas las vistas previas de Agent Console y las ejecuciones de prueba de Canvas que usan Simular respuesta) cuenta para este límite.

En Agent Console, el Límite diario de coste en créditos de acción estima el máximo de créditos que un agente puede consumir al 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. No se consumen créditos cuando una invocación falla por:

• Un error de límite de velocidad del proveedor de LLM (incluidos los reintentos que acaban fallando)
• Que el modelo seleccionado no esté disponible
• Que el agente alcance su límite diario de invocaciones

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

Supervisar el uso de créditos

Ve a Configuración > Facturación > Uso de créditos > Agent Console para ver el consumo de créditos, el número de invocaciones y las ratios de créditos por agente.

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

Para controlar el gasto, reduce el límite diario de invocaciones. En el caso de los modelos con tu propia clave (BYO), también puedes elegir un modelo de menor coste o reducir el nivel de razonamiento para bajar los costes de tokens del proveedor. Braze Auto no permite ajustar el nivel de razonamiento.

Errores de límite de velocidad

Si el proveedor de LLM devuelve un error de límite de velocidad durante la invocación de un agente de paso en Canvas o de un agente de catálogo, Braze reintenta la solicitud de forma continua usando retirada exponencial hasta que la llamada tiene éxito o Braze determina que no se puede completar.

Cuando se agotan los reintentos de Canvas o del catálogo, el panel de detalles de Registros muestra Error y el mensaje del proveedor (como Rate limit exceeded) en Salida. Los reintentos son visibles en los registros, incluida la primera invocación, independientemente de que acabe teniendo éxito o no. Para un usuario determinado, si se necesitan cuatro reintentos para conseguir finalmente un resultado correcto, puedes buscar el ID de usuario y ver las cinco invocaciones (la original más los cuatro reintentos) en Registros; la original y los tres primeros reintentos mostrarán Error con Rate limit exceeded.

Los errores de límite de velocidad no consumen créditos de Braze, incluidos los reintentos fallidos que se muestran en Registros.

Instrucciones de escritura

Las instrucciones son las reglas o pautas que le das al agente (prompt del sistema). Definen cómo debe comportarse el agente cada vez que se ejecuta. Las instrucciones del sistema pueden ocupar hasta 25 KB.

Si creaste tu agente con BrazeAI Operator a partir de una plantilla inicial, revisa las instrucciones predeterminadas y edítalas según sea necesario.

Estas son algunas prácticas recomendadas generales para empezar a escribir prompts:

1. Empieza pensando en el resultado final. Indica primero el objetivo.
2. Dale al modelo un rol o personaje (“Eres un…”).
3. Establece un contexto y unas restricciones claros (audiencia, longitud, tono, formato).
4. Pide una 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. Fomenta el razonamiento (“Piensa los pasos internamente y luego da una respuesta final concisa” o “explica brevemente tu decisión”).
8. Prueba, revisa e itera. Pequeños ajustes pueden suponer grandes mejoras de calidad.
9. Gestiona los casos límite con reglas positivas y explícitas, y añade instrucciones de rechazo cuando sea necesario.
10. Mide y documenta internamente lo que funciona para reutilizarlo y escalarlo.

Siempre que puedas, escribe instrucciones positivas y explícitas. Dile al agente qué debe hacer y expresa las restricciones en términos concretos. Si un agente ignora tus reglas, consulta ¿Por qué mi agente no siguió mis instrucciones o reglas?.

Dar formato a las instrucciones con Markdown

Las instrucciones admiten formato Markdown, incluidos encabezados, listas con viñetas y numeradas, texto en negrita, enlaces y tablas. Usa encabezados como # Role, ## Goal y ## Rules para dividir las instrucciones largas en secciones más fáciles de revisar para ti y tu equipo. El formato solo cambia cómo se muestran las instrucciones en Braze. El agente siempre recibe el texto original que escribes.

• En el paso Instrucciones, selecciona Vista previa para ver tus instrucciones como texto con formato, y Editar para volver al editor.
• En la página de vista del agente, las instrucciones se muestran con su formato Markdown.
• Los enlaces de las instrucciones con formato se abren en una pestaña nueva.
• Las etiquetas HTML sin procesar o de estilo XML (como <role>) se muestran como texto sin formato en la vista previa. El agente las sigue recibiendo tal como están escritas.

Ejemplos

Para ver configuraciones iniciales en la Consola de agentes, consulta Plantillas de agentes creadas con Operator.

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

Uso de Liquid

Incluir Liquid en las instrucciones de tu agente puede añadir una capa extra de personalización a su respuesta. Puedes especificar la variable de Liquid exacta que recibe el agente e incluirla en el contexto de tu prompt. Por ejemplo, en lugar de escribir explícitamente “nombre”, puedes usar el fragmento de código 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 Registros de la Consola de agentes, puedes revisar los detalles de la entrada y la salida del agente para entender qué valor se procesa a partir de Liquid.

Qué datos reciben los agentes

El contexto del agente no es una 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 explora perfiles de usuario, no deduce campos que faltan ni te avisa cuando falta información necesaria.

Diseña cada agente como una canalización deliberada de entrada a salida. Conecta cada punto de datos que necesite el agente mediante uno o varios de los siguientes métodos:

1. Liquid en las instrucciones: Inserta atributos de usuario ({{${first_name}}}) y variables de contexto de Canvas ({{context.${variable_name}}}) directamente en el prompt del agente.
2. + Contexto del agente: Selecciona fuentes de conocimiento, pertenencia a Segment, directrices de marca, Todo el contexto del Canvas o datos de interacción del usuario en la Consola de agentes.
3. Pasos de contexto: Establece o actualiza variables context.* en etapas anteriores del Canvas antes de que se ejecute un paso de agente.
4. Contexto adicional en el paso de agente: Pasa al agente en el momento del envío, desde la configuración del paso, cualquier valor adicional con plantilla de Liquid que no hayas especificado con los otros métodos.

Asegúrate de insertar con Liquid estas variables de contexto en las instrucciones del agente, adjuntar los archivos de contexto que el agente debe consultar o seleccionar Añadir todo el contexto del Canvas. Si un valor no se pasa por uno de estos canales, el agente no lo recibe. Enumera las entradas necesarias en tus instrucciones o en los requisitos previos del caso de uso, y verifica las entradas en Consola de agentes > Registros después de hacer pruebas.

Para los agentes de catálogo, usa Campos en la sección Salida en lugar de un esquema JSON; aun así, puedes escribir instrucciones que pidan al modelo una salida de pares clave-valor que coincida con esos nombres de campo.

Para obtener más información sobre las prácticas recomendadas para escribir prompts, consulta las guías de los siguientes proveedores de modelos:

• OpenAI
• Anthropic
• Gemini

Salidas

Si creaste tu agente con BrazeAI Operator a partir de una plantilla inicial, revisa el esquema de salida rellenado previamente y edítalo según sea necesario.

Esquemas básicos

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

Por ejemplo, si quieres recopilar puntuaciones de opinión de los usuarios a partir de un cuestionario de opinión sencillo para saber lo satisfechos que están tus clientes después de recibir un producto, puedes seleccionar Número como esquema básico para estructurar el formato de salida.

Importante

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

Esquemas avanzados

Las opciones de esquema avanzado incluyen estructurar campos manualmente o utilizar JSON.

• Campos: Una forma sin código de imponer una salida del agente que puedes utilizar de forma coherente.
• JSON: Un enfoque con código para crear un formato de salida preciso, en el que puedes anidar variables y objetos dentro del esquema JSON. Solo está disponible para los agentes de paso en Canvas, no para los agentes de catálogo.

Te recomendamos utilizar esquemas avanzados cuando quieras que el agente devuelva una estructura de datos con varios valores definidos de forma estructurada, en lugar de una salida de un solo valor. Así, la salida tendrá un formato más adecuado como variable de contexto coherente.

Salida alternativa

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

Para los 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 los esquemas de Campos, introduces un valor alternativo para cada campo. Para los esquemas básicos, introduces un único valor alternativo. Los agentes de paso en Canvas admiten Liquid en los valores alternativos.

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

Por ejemplo, puedes utilizar un formato de salida dentro de un agente destinado a crear un itinerario de viaje de ejemplo para un usuario en función de un formulario que haya enviado. El formato de salida te permite definir que cada respuesta del agente debe devolver valores para tripStartDate, tripEndDate y destination. Cada uno de estos valores puede extraerse de las variables de contexto y colocarse en un paso de Mensaje para personalizarlo con Liquid.

• campos
• esquema json

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 puedes adjuntar el catálogo directamente como contexto del agente. Los agentes configurados con la opción heredada Add catalog fields antes de que existieran las fuentes de conocimiento pueden seguir usando 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 deben tener valor antes de que se invoque el agente. 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 son obligatorias de forma predeterminada, pero puedes quitar las columnas que puedan estar vacías para que no bloqueen la ejecución. Así evitas desperdiciar 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 tengan valores para esa fila.

Para ver 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 compruebe la pertenencia de cada usuario a ellos cuando se utilice en un Canvas. Supongamos que tu agente tiene seleccionada la pertenencia al Segment «Loyalty Users» y que se utiliza en un Canvas. Cuando los usuarios entran en un paso de agente, el agente puede comprobar si cada usuario pertenece a cada Segment que especificaste en la consola de agentes y utilizar esa pertenencia (o no pertenencia) como contexto para el LLM.

Directrices de marca

Puedes seleccionar directrices de marca que tu agente deberá seguir en sus respuestas. Por ejemplo, si quieres que tu agente genere el texto de un SMS para animar a los usuarios a suscribirse a un gimnasio, puedes usar este campo para hacer referencia a tu directriz predefinida, audaz y motivadora.

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 por encima de la fila del agente y selecciona el menú .
2. Selecciona Duplicar.

Archivar agentes

A medida que creas más agentes personalizados, puedes organizar la página Administración de agentes archivando los agentes que no se estén utilizando activamente. Para archivar un agente:

1. Pasa el cursor por encima de la fila del agente y selecciona el menú .
2. Selecciona Archivar.