Cómo crear una herramienta

Objetivos del artículo

Cómo conectar el Agente de Clientes a un punto de conexión HTTP usando una herramienta totalmente personalizada, escribir una descripción de la herramienta que el Agente de Clientes realmente use y probar la herramienta antes de adjuntarla a una habilidad.

Antes de empezar

Necesitarás lo siguiente:

• Agente de Clientes habilitado
• Un punto de conexión HTTP accesible a través de un nombre de host público. No se admiten direcciones de red privada, localhost ni URL que usan 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 habilidad con instrucciones editables para adjuntar la herramienta a

Puedes crear y probar la herramienta antes de adjuntarla a una habilidad. Para usarla en conversaciones, agrégala a las instrucciones de la habilidad. Si necesitas una nueva habilidad, consulta Cómo crear una habilidad.

Qué es una herramienta totalmente personalizada

Una herramienta totalmente personalizada es una solicitud HTTP que el Agente de Clientes puede realizar durante una conversación. Usa una cuando las herramientas incluidas con el Agente de Clientes no cubran lo que necesitas; por ejemplo, buscar un pedido en tu propio sistema de gestión de pedidos en lugar de Shopify, revisar el inventario en un sistema de almacén personalizado o crear un ticket en una mesa de ayuda con la que Klaviyo no se integra de forma nativa.

Para conocer el concepto subyacente, consulta Comprender las herramientas.

Cuándo crear una herramienta totalmente personalizada

Puedes obtener una herramienta totalmente personalizada cuando:

• Necesitas datos en tiempo real de un sistema con el que Klaviyo no se integra
• Quieres que Agente de Clientes 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 es adecuada; por ejemplo, si utilizas un formulario OMS personalizado en lugar de Shopify para los pedidos

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

Configuralo

1. Abre la página Herramientas personalizadas

1. Ve a Agente de Clientes > Conectores y luego abre la tarjeta Personalizado.
2. Si el punto de conexión necesita una credencial, ve a Secretos y haz clic en Agregar secreto. Ingresa un Nombre y un Valor del secreto y luego haz clic en Agregar 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. Nombra y describe la herramienta

• Nombre de la herramienta — Un identificador breve como “Obtener inventario” o “Crear ticket de devolución”.
• Descripción — Lenguaje natural que explica qué hace la herramienta y cuándo utilizarla. Agente de Clientes lee esta descripción para decidir si utilizar 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 utiliza 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 el punto de conexión, incluidos Content-Type y los encabezados de autenticación.
• Parámetros de consulta — Si el punto de conexión espera valores en la cadena de consulta, ingresa 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 el Agente de Clientes debe completar en tiempo de ejecución.

Cuerpo del ejemplo:

{ suyo
  "customer_id": "{{profile_id}}",
  "sku": "{{product_sku}}"
} suyo

5. Define variables para valores dinámicos

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

1. Haz clic en Agregar variables e ingresa profile_id como Nombre de la variable. Configura Fuente como Perfil de Klaviyo y Propiedad de Klaviyo como ID de Klaviyo. Esto proporciona el ID del perfil de Klaviyo del comprador autenticado.
2. Agrega otra variable llamada product_sku. Configura Fuente como Variable dinámica, elige Cadena como su Tipo y describe el SKU que el Agente de Clientes debe proporcionar en Descripción. Selecciona Obligatorio si el punto de conexión lo requiere.

Repite este 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 llamada conversation_id no se rellena 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; la falta de un valor de perfil obligatorio impide que la solicitud se ejecute.

6. Autentificación

Si tu punto de conexión requiere una clave de API, token de portador u otra credencial, guárdala como secreto. Los secretos están cifrados, sus valores nunca se muestran al Agente de Clientes y no se pueden volver a ver después de guardarlos.

1. En la herramienta, en Variables, haz clic en Agregar variables. Asigna un nombre a la variable (por ejemplo, api_key), configura Source como Secret y elige el secreto que guardaste.
2. Haz referencia a la variable dondequiera que tu punto de conexión espere la credencial: un encabezado, la URL, un parámetro de consulta o el cuerpo. Por ejemplo, agrega 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, ingresa el valor de reemplazo y luego haz clic en Actualizar. Cada herramienta que usa el secreto adopta el nuevo valor. La columna Usado por muestra qué herramientas hacen referencia a cada secreto, así que revísala antes de eliminar uno.

7. Guarda y prueba la herramienta

Antes de guardar, revisa Tiempo de espera (segundos) y N.º máx. de reintentos en Configuración. Puedes establecer un límite de tiempo general de 1–10 segundos y 0–3 reintentos para fallas temporales. Si la herramienta cambia datos, asegúrate de que tu punto de conexión pueda procesar 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 al punto de conexión y pueden cambiar 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 activas.

En Prueba, ingresa 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 prueba.

Revisa Respuesta y verifica que:

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

8. Adjunta la herramienta a una habilidad

1. Ve a Agente de Clientes > Habilidades y abre la habilidad en la que quieras usar la herramienta. Si sus instrucciones son de solo lectura, crea una habilidad totalmente personalizada.
2. En Cómo responder, escribe / donde se debe usar la herramienta y selecciona la herramienta en el menú. Explica cuándo 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 al Agente de Clientes a decidir cuándo usar la herramienta. Las instrucciones de la habilidad también orientan qué herramienta llama y cómo usa el resultado. Buenas descripciones:

• Dime lo que la herramienta hace en una oración
• Dime cuándo usarlo en una sola oración
• Son específicos sobre los datos devueltos o la acción realizada

Las descripciones incorrectas son vagas ("Obtiene información del cliente"), demasiado amplias ("Administra cualquier cosa relacionada con los pedidos") o indican al Agente de Clientes cómo comportarse en lugar de lo que hace la herramienta.

Consideraciones de seguridad

• Almacena las credenciales como secretos. Nunca pegues una clave de API o un token directamente en un encabezado, URL o cuerpo. Agrégala como un secreto y haz referencia a ella con una variable de secreto (consulta el paso 6).
• Usa lista de permitidos de IP cuando sea posible. El punto de conexión debe seguir siendo accesible mediante un nombre de host público; las direcciones de red privada y localhost están bloqueados. Usa la lista 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 guían los valores que el Agente de Clientes proporciona para las variables dinámicas. Revisa qué campos recibe el punto de conexión.
• Límites de tasas. Si tu punto de conexión tiene límites de tasa, asegúrate de que sea lo suficientemente alto como para manejar el volumen esperado de conversaciones.

Guía de solución de problemas

Síntoma: El Agente de Clientes 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 la prueba.
Causa probable: URL incorrecta, cuerpo mal formado, datos obligatorios del perfil faltantes o una carga útil que el punto de conexión no acepta.
Solución: En Probar, revisa Vista previa de la solicitud y Respuesta. Verifica la URL, los encabezados y el cuerpo con respecto a la entrada esperada de tu punto de conexión. Si la herramienta usa variables de perfil de Klaviyo, selecciona un perfil de prueba con los valores obligatorios.

Síntoma: El Agente de Clientes usa la herramienta, pero envía parámetros incorrectos.
Causa probable: Una variable tiene la fuente o las propiedades del perfil incorrectas, o las instrucciones de la habilidad no son claras sobre qué enviar.
Solución: Revisa los nombres y las fuentes de las variables, y las propiedades del perfil seleccionadas en Variables. Actualiza las descripciones de las variables y las instrucciones de la habilidad para que sea explícito qué se debe proporcionar.

Síntoma: La herramienta es lenta, lo que provoca retrasos en las respuestas.
Causa probable: Latencia del 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 habilidades?
Sí. Una vez creada, una herramienta puede ser usada por varias habilidades. Insértala en las instrucciones editables de cada habilidad y publica o actualiza cada habilidad.

¿Qué métodos de autenticación son compatibles?
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. Guarda la credencial como un secreto y haz referencia a ella con una variable de Secreto (consulta el paso 6). Los flujo que necesitan obtener o actualizar un token en el momento de la solicitud, como OAuth, no son compatibles en las herramientas totalmente personalizadas.

¿Qué pasa si mi punto de conexión no está disponible o devuelve un error?
Klaviyo informa sobre las fallas de la herramienta al Agente de Clientes. 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 habilidad, explica cómo responder si la herramienta no puede completar la solicitud, por ejemplo, ofreciendo transferir la conversación. Usa puntos de conexión confiables y monitorea de cerca el comportamiento de la herramienta.

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

¿Puedo crear versiones de una herramienta?
Todavía no se admite el control de versiones. Los cambios guardados se aplican a la herramienta compartida que usa cada habilidad que la referencia. Guardar y ejecutar prueba también guarda los cambios, así que revisa qué habilidades en vivo usan la herramienta antes de editarla.

Recursos adicionales