Cómo crear una herramienta

Qué aprenderás

Cómo conectar Customer Agent a un punto de conexión HTTP usando una herramienta totalmente personalizada, redactar una descripción de herramienta que Customer Agent realmente use y probar la herramienta antes de adjuntarla a una skill.

Antes de empezar

Necesitarás:

• Customer Agent habilitado
• Un punto de conexión HTTP accesible a través de un nombre de host público. No se admiten direcciones de redes privadas, localhost ni URL que usen una dirección IP en lugar de un nombre de host. Si el punto de conexión requiere una clave de API o un token, lo almacenarás como un secreto (consulta los pasos 1 y 6).
• Una skill con instrucciones editables para asociar la herramienta a

Puedes crear y probar la herramienta antes de vincularla a una skill. Para usarla en conversaciones, añádela a las instrucciones de la skill. Si necesitas una skill nueva, consulta Cómo crear una skill.

Qué es una herramienta totalmente personalizada

Una herramienta totalmente personalizada es una solicitud HTTP que Customer Agent puede realizar durante una conversación. Úsala cuando las herramientas incluidas con Customer Agent no cubran lo que necesitas; por ejemplo, buscar un pedido en tu propio sistema de gestión de pedidos en lugar de Shopify, comprobar el inventario en un sistema de almacén personalizado o crear un ticket en un servicio de asistencia con el que Klaviyo no se integra de forma nativa.

Para consultar el concepto subyacente, consulta Información sobre Tools.

Cuándo crear una herramienta totalmente personalizada

Te recomendamos que uses una herramienta totalmente personalizada cuando:

• Necesitas datos en tiempo real de un sistema con el que Klaviyo aún no se haya integrado
• Quieres que el Customer Agent realice una acción en un sistema externo (cancelar una suscripción en tu sistema propietario, crear un ticket, actualizar un registro)
• Una herramienta existente no encaja — por ejemplo, usas un OMS personalizado en lugar de Shopify para los pedidos

Si la información no cambia a menudo y es la misma para todos los clientes, añádela como contenido. Las herramientas sirven para generar datos y acciones dinámicas por cliente.

Configuración

1. Abre la página Herramientas personalizadas

1. Ve a Customer Agent > Conectores y, a continuación, abre la tarjeta Personalizado.
2. Si el punto de conexión necesita una credencial, ve a Secretos y haz clic en Añadir secreto. Introduce un nombre y un valor secreto y, a continuación, haz clic en Añadir secreto. Omite este paso si el secreto ya está guardado o si el punto de conexión no necesita uno.
3. Haz clic en Crear herramienta.

2. Asigna un nombre a la herramienta y descríbelo

• Nombre de la herramienta: un identificador breve, como «Get Inventory» o «Create Return Ticket».
• Descripción: lenguaje natural que explica qué hace la herramienta y cuándo utilizarla. El Customer Agent lee esta descripción para decidir si se utiliza la herramienta para una solicitud determinada. Sé específico.

Un buen ejemplo de descripción:

Obtiene el recuento de inventario en tiempo real de un SKU de producto determinado del sistema de almacén. Se usa cuando un comprador pregunta si hay un producto específico en stock.

Un ejemplo de descripción vaga (evitar):

Obtén información sobre el producto.

3. Configura la solicitud HTTP

• Método HTTP, GET, POST, PUT, DELETE o PATCH.
• Plantilla de URL: la URL completa del punto de conexión. Puedes incluir marcadores de posición para valores dinámicos (consulta el paso 5).
• Encabezados: cualquier encabezado que requiera tu punto de conexión, incluidos Content-Type y encabezados de autenticación.
• Parámetros de consulta (Si el punto de conexión espera valores en la cadena de consulta, introduce aquí sus nombres y valores). Puedes usar marcadores de posición para los valores (consulta el paso 5).

4. Configura el cuerpo de la solicitud (para POST, PUT, PATCH)

En Plantilla del cuerpo, proporciona un objeto JSON. Usa marcadores de posición para los valores que Customer Agent debe completar en el momento de la ejecución.

Cuerpo de ejemplo:

{
  «customer_id»: «{{profile_id}}»,
  «sku»: «{{product_sku}}»
}

5. Definir variables para valores dinámicos

Cada marcador de posición debe tener una variable correspondiente en Variables. Para el cuerpo de ejemplo anterior:

1. Haz clic en Añadir variables e introduce profile_id como Nombre de variable. Configura Origen como perfil de Klaviyo y Propiedad de Klaviyo como ID de Klaviyo. Esto proporciona el ID del perfil de Klaviyo del comprador autenticado.
2. Añade otra variable llamada product_sku. Configura Source en Dynamic Variable, selecciona String como Type y describe el SKU que Customer Agent debe proporcionar en Description. Selecciona Required si el punto de conexión lo requiere.

Repite el proceso con otros valores que necesite tu punto de conexión, como order_id. Los nombres de las variables deben coincidir exactamente con sus marcadores de posición. Una variable denominada conversation_id no se completa automáticamente con el ID de la conversación actual.

Usa las variables como marcadores de posición, como {{profile_id}} y {{product_sku}}, en la URL, los encabezados, los parámetros de consulta o el cuerpo. Las herramientas que usan variables de perfil de Klaviyo requieren un comprador autenticado; si falta un valor de perfil obligatorio, la solicitud no se ejecutará.

6. Autentificación

Si el punto de conexión requiere una clave de API, un token de portador u otra credencial, guárdalo como un secreto. Los secretos están cifrados, sus valores nunca se muestran en Customer Agent y no se pueden volver a ver después de guardarlos.

1. En la herramienta, en Variables, haz clic en Add variables. Asigna un nombre a la variable (por ejemplo, api_key), establece Source en Secret y selecciona el secreto que guardaste.
2. Haz referencia a la variable dondequiera que el punto de conexión espere la credencial: un encabezado, la URL, un parámetro de consulta o el cuerpo. Por ejemplo, añade un encabezado llamado Authorization con el valor Bearer {{api_key}}.

Para rotar una clave, abre el menú de la fila del secreto, haz clic en Actualizar, introduce el valor de reemplazo y, a continuación, haz clic en Actualizar. Todas las herramientas que usen el secreto adoptarán el nuevo valor. La columna Usado por muestra qué herramientas hacen referencia a cada secreto, así que compruébala antes de eliminar uno.

7. Guarda y prueba la herramienta

Antes de guardar, revisa Timeout (seconds) y Max retries en Settings. Puedes establecer un límite de tiempo general de 1–10 segundos y 0–3 reintentos para fallos temporales. Si la herramienta cambia datos, asegúrate de que el punto de conexión pueda gestionar de forma segura una solicitud repetida.

Haz clic en Guardar para crear la herramienta. La herramienta guardada se abre con una sección de Prueba.

Las pruebas envían solicitudes reales a tu punto de conexión y pueden cambiar los datos. Usa un perfil de prueba y registros de prueba. Guardar y ejecutar prueba también guarda cualquier cambio en la herramienta, incluida una herramienta ya utilizada por habilidades en vivo.

En Prueba, introduce valores de ejemplo para las variables dinámicas. Selecciona un perfil de prueba en perfil si la herramienta usa variables de perfil de Klaviyo. Haz clic en Guardar y ejecutar la prueba.

Revisa Respuesta y comprueba que:

• La respuesta se ha recuperado correctamente.
• La respuesta contiene los datos que necesita tu habilidad
• Los casos de error esperados devuelven códigos de estado y mensajes útiles

8. Adjunta la herramienta a una habilidad

1. Ve a Customer Agent > Habilidades y abre la habilidad con la que quieres usar la herramienta. Si sus instrucciones son de solo lectura, crea una habilidad totalmente personalizada.
2. En Cómo responder, escribe / donde deba usarse la herramienta y selecciona la herramienta en el menú. Explica cuándo debes llamarla, qué valores proporcionar y qué hacer con el resultado o con un error.
3. Cuando las instrucciones estén listas, haz clic en Publicar para una habilidad en borrador o en Actualizar para una habilidad activa.

Escribir una buena descripción de la herramienta

Una descripción clara ayuda a Customer Agent a decidir cuándo usar la herramienta. Las instrucciones de la habilidad también orientan qué herramienta invoca y cómo usa el resultado. Buenas descripciones:

• Decir lo que hace la herramienta en una sola oración
• Decir cuándo usarlo en una sola oración
• Son específicos sobre los datos devueltos o las acciones realizadas

Las descripciones erróneas son vagas («Obtiene información del cliente»), demasiado amplias («Gestiona cualquier cosa relacionada con los pedidos») o indican al Customer Agent cómo comportarse en lugar de lo que hace la herramienta.

Consideraciones de seguridad

• Guarda las credenciales como secretos. No pegues nunca una clave de API o un token directamente en un encabezado, una URL o un cuerpo. Añádelo como secreto y haz referencia a él con una variable de secreto (consulta el paso 6).
• Usa listas de permitidos de IP cuando sea posible. El punto de conexión debe poder seguir siendo accesible a través de un nombre de host público; las direcciones de red privada y localhost están bloqueadas. Usa listas de permitidos como una capa adicional de protección junto con la autenticación.
• Ten en cuenta qué datos envías. La configuración de la solicitud y las fuentes de variables determinan qué valores se envían al punto de conexión. Las instrucciones de la habilidad orientan los valores que Customer Agent proporciona para las variables dinámicas. Revisa qué campos recibe el punto de conexión.
• Límites de la tasa. Si tus puntos de conexión tienen límites de tasa, asegúrate de que sean lo suficientemente altos como para manejar el volumen de conversaciones esperado.

Solución de problemas

Síntoma: Customer Agent nunca usa la herramienta.
Causa probable: la descripción es demasiado vaga o la herramienta no está incluida en las instrucciones publicadas de la habilidad.
Solución: reescribe la descripción para describir específicamente cuándo se debe usar. En Cómo responder, inserta la herramienta con / y explica cuándo llamarla. Haz clic en Publicar o Actualizar para aplicar las instrucciones.

Síntoma: La herramienta devuelve un error durante las pruebas.
Causa probable: URL incorrecta, cuerpo mal formado, falta de datos obligatorios del perfil o una carga útil que el punto de conexión no acepta.
Solución: En Prueba, revisa Vista previa de la solicitud y Respuesta. Verifica la URL, los encabezados y el cuerpo con respecto a la entrada esperada del punto de conexión. Si la herramienta usa variables de perfil de Klaviyo, selecciona un perfil de prueba con los valores obligatorios.

Síntoma: Customer Agent usa la herramienta, pero pasa parámetros incorrectos.
Causa probable: Una variable tiene la fuente o las propiedades de perfil incorrectas, o las instrucciones de la skill no dejan claro qué se debe pasar.
Solución: Comprueba los nombres y las fuentes de las variables, así como las propiedades de perfil seleccionadas, en Variables. Actualiza las descripciones de las variables y las instrucciones de la skill para indicar de forma explícita qué se debe proporcionar.

Síntoma: La herramienta es lenta, lo que provoca retrasos en las respuestas.
Causa probable: latencia de Punto de conexión.
Solución: Optimiza tus puntos de conexión. Comprueba si puedes almacenar en caché los resultados de tu lado.

PREGUNTAS FRECUENTES

¿Se puede usar una herramienta en varias skills?
Sí. Una vez creada, una herramienta puede ser utilizada por varias habilidades. Insértalo en las instrucciones editables de cada habilidad y publica o actualiza cada habilidad.

¿Qué métodos de autenticación se admiten?
Cualquier método que envíe una credencial estática con la solicitud, como un token de portador o un encabezado de clave de API. Almacena la credencial como un secreto y haz referencia a ella con una variable de secreto (consulta el paso 6). Los flujos que necesitan obtener o actualizar un token en el momento de la solicitud, como OAuth, no se admiten en herramientas totalmente personalizadas.

¿Qué sucede si mi punto de conexión no funciona o devuelve un error?
Klaviyo informa de los fallos de la herramienta a Customer Agent. Los fallos temporales se pueden reintentar dentro de los límites de tiempo de espera y de reintentos de la herramienta. En las instrucciones de la skill, explica cómo responder si la herramienta no puede completar la solicitud, por ejemplo, ofreciendo transferirla. Utiliza puntos de conexión fiables y supervisa de cerca el comportamiento de la herramienta.

¿Puedo editar una herramienta después de crearla?
Sí. Abre la herramienta desde Customer Agent > Conectores > Personalizado, edita el nombre, la descripción o la configuración de la solicitud y, luego, haz clic en Guardar. Añade o elimina la herramienta en las instrucciones de cada skill.

¿Puedo crear versiones de una herramienta?
La creación de versiones todavía no es compatible. Los cambios guardados se aplican a la herramienta compartida que usa cualquier skill que haga referencia a ella. Guardar y ejecutar prueba también guarda los cambios, así que revisa qué skills activas usan la herramienta antes de editarla.

Recursos adicionales