Resumen
Esta guía explica cómo funcionan los atributos de acción de la API REST en Astra y cómo se utilizan dentro de los agentes de Astra. Los atributos actúan como marcadores de posición que almacenan y pasan datos entre instrucciones y acciones.
Aprenderá los diferentes tipos de atributos, cómo se comportan y cómo utilizarlos correctamente al configurar acciones de la API REST (Representational State Transfer).
Instrucciones
¿Qué es un atributo?
En Astra, un atributo es un marcador de posición que almacena un valor. Permite que su agente utilice datos dinámicamente durante la ejecución.
Por ejemplo, atributos como nombre o apellido pueden almacenar detalles del cliente y reutilizarse en respuestas o acciones.
Puntos clave
Los atributos actúan como variables dentro de su agente
Se pueden utilizar en instrucciones y acciones
En las instrucciones, los atributos se utilizan principalmente para dar claridad o estructurar entradas y salidas
Atributos de entrada y salida
Los atributos en Astra se categorizan según su uso:
Atributos de entrada
Proporcionan datos a una acción o paso
Ejemplo: pasar el nombre de un cliente a una solicitud de API
Atributos de salida
Almacenan los resultados devueltos de una acción
Ejemplo: guardar el ID de una respuesta de una API
Ambos tipos se pueden referenciar en todo el flujo de trabajo de su agente.
A. Atributos de contacto
Los atributos de contacto son un tipo específico de atributo vinculado a los datos del cliente.
Atributos de contacto predefinidos
Ejemplos comunes incluyen:
nombreapellido
Atributos de contacto personalizados
Puede crear atributos personalizados basados en su caso de uso dentro del agente.
Importante
Los atributos de contacto solo reciben valores cuando los datos se capturan realmente.
Se completan cuando:
Se envía un Formulario personalizado durante la conversación
Se activa una acción de API REST después de la conversación
Otros puntos importantes a tener en cuenta
Los atributos de contacto no son lo mismo que los campos de contacto
Los campos de contacto incluyen:
emailteléfono
También pueden provenir de:
Formularios personalizados
Criterios de calificación de clientes potenciales
Los atributos de contacto solo se enlazan a estos campos cuando los datos se capturan a través de estos flujos.
B. Atributos de acción
Los atributos de acción están vinculados a las acciones configuradas en su agente.
Tipos de atributos de acción
Atributos de acción de API REST
Atributos de acción predefinidos
1. Atributos de acción predefinidos
Estos se vuelven disponibles cuando agrega acciones específicas a su agente.
Ejemplos:
Wati enviar resumen de ventas →
sales_summary_content(entrada)Slack enviar mensaje →
message_content(entrada)Google Sheets añadir fila →
inserted_data_id(salida)Google Sheets actualizar fila →
target_data_id(entrada)
2. Atributos de acción de API REST
Los atributos de entrada se crean cuando configura la acción
Los atributos de salida se generan después de que la acción se ejecuta (durante las pruebas o la ejecución en vivo)
Importante
Debe agregar la acción correspondiente a su agente antes de usar sus atributos.
Cómo configurar la carga útil de la acción de API REST
Las acciones de API REST en Astra utilizan marcadores de posición para pasar datos dinámicos.
¿Qué son los marcadores de posición?
Los marcadores de posición se escriben usando: ##{{nombre_marcador_de_posicion}}
Puede usarlos en:
Parámetros de consulta
Encabezados
Cuerpo de la solicitud
Método recomendado: usar entrada de datos
Este es el enfoque más flexible y recomendado.
A. Usando entrada de datos
Paso 1: agregar un campo de entrada de datos
Cree una entrada de datos en la configuración de su acción.
Paso 2: configurar el campo
Defina:
Tipo de dato
Nombre
Descripción
Obligatorio u opcional
Atributo de referencia (opcional)
Valor predeterminado (opcional)
Paso 3: elegir cómo se obtiene el valor
Tiene 3 opciones:
Sin referencia
El agente genera el valor a partir del contexto
Agregue una descripción clara para que el agente sepa qué pasar
Referenciar un atributo de contacto
Use solo si el valor ya está capturado
Evite usar esto a menos que:
Se haya enviado un formulario personalizado, o
Ocurrió un evento de API posterior a la conversación
Referenciar un atributo de salida de acción
Use la salida de una acción anterior
La acción referenciada debe ejecutarse antes que la actual
Paso 4: usar el marcador de posición
Refiérase a él en su carga útil: ##{{nombre_entrada_de_datos}}
Asegúrese de que el nombre coincida exactamente.
B. Usando atributo de contacto directo
Puede referenciar directamente un atributo de contacto: ##{{contacto.nombre_atributo}}
No es necesario definir una entrada de datos
Se puede insertar directamente desde la UI
C. Usando atributo de acción directo
Puede referenciar la salida de una acción: ##{{accion.<id_accion>#salida#<nombre_atributo>}}
Se vincula a la salida de una acción anterior
Se puede insertar desde la UI
No es necesario escribir manualmente el formato completo
Mejores prácticas
Use la entrada de datos para la mayoría de los casos de uso
Evite depender de atributos de contacto a menos que esté seguro de que están poblados
Asegure el orden de ejecución de la acción correcto cuando use salidas
Pruebe todas las acciones de API antes de implementar
Al comprender los atributos de Astra, puede crear agentes más estructurados, confiables y dinámicos dentro de Wati.