Cómo crear una herramienta (beta)

Función beta. La creación de herramientas totalmente personalizadas desde cero está en fase beta abierta y está disponible para todas las cuentas de Agente de Clientes; no es necesario registrarse. Encontrarás la página Herramientas en Agente de Clientes. La función aún se está ampliando y puede cambiar.

Objetivos del artículo

Cómo conectar Agente de Clientes a cualquier punto de conexión HTTP utilizando una herramienta totalmente personalizada, escribir la descripción de la herramienta que Agente de Clientes utilizará realmente y probar tu herramienta antes de añadirla a una habilidad.

Antes de empezar

Necesitarás lo siguiente:

• Agente de Clientes habilitado
• Un punto de conexión HTTP al que deseas llamar al Agente de Clientes, uno que no requiera credenciales secretas (claves de API, tokens de portador, etc.) para acceder hoy mismo (los puntos de conexión autenticados estarán disponibles pronto, consulta la advertencia a continuación)
• Una habilidad a la que adjuntar la herramienta, ya sea una habilidad con la que viene Agente de Clientes o una habilidad totalmente personalizada que has creado

Si aún no has configurado una habilidad, crea una primero. Las herramientas no hacen nada por sí solas, tienen que estar unidas a una habilidad.

Advertencia: Pronto habrá almacenamiento seguro para las claves de API y otros secretos. Hasta que se envíe, no pongas claves de API, tokens de portador u otras credenciales delicadas en herramientas totalmente personalizadas; la configuración de la herramienta aún no es un lugar seguro para almacenarlas. Por ahora, solo usa herramientas con puntos de conexión seguros para llamar sin autorización secreta (por ejemplo, puntos de conexión internos detrás de listas de IP permitidas o puntos de conexión que acepten identificadores no confidenciales). Ya está en marcha la compatibilidad con puntos de conexión autenticados.

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. La creación de herramientas totalmente personalizadas está en fase beta abierta y está disponible para todas las cuentas de Agente de Clientes. Utiliza una cuando las herramientas con las que viene 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, comprobar el inventario en un sistema de almacén personalizado o crear un ticket en un helpdesk con el que Klaviyo no se integra de forma nativa.

Para conocer el concepto subyacente, consulta el artículo Cómo funcionan las herramientas del Agente de Clientes.

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

Ve a Agente de Clientes > Herramientas y haz clic en Crear herramienta.

2. Nombra y describe la herramienta

• Nombre: Un identificador corto 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: GET, POST, PUT, DELETE o PATCH.
• 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.

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

Dales un cuerpo JSON. Utiliza marcadores de posición para los valores que el Agente de Clientes debe rellenar en tiempo de ejecución.

Cuerpo del ejemplo:

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

5. Utiliza marcadores de posición para los valores dinámicos

Agente de Clientes puede rellenar valores en tiempo de ejecución utilizando marcadores de posición. Marcadores de posición comunes:

• {{profile_id}} — El ID de perfil de Klaviyo del cliente en la conversación
• {{conversation_id}} — El ID de conversación actual
• Cualquier parámetro que definas en el esquema de entrada (p. ej., {{product_sku}}, {{order_id}})

Los marcadores de posición funcionan en la URL, los encabezados y el cuerpo.

6. Autentificación

Pronto habrá compatibilidad con puntos de conexión autenticados. Hasta entonces, no pongas claves de API, tokens de portador u otros secretos en una herramienta totalmente personalizada. Utiliza solo puntos de conexión seguros para llamar sin credenciales secretas; por ejemplo, puntos de conexión internos protegidos por listas de IP permitidas o puntos de conexión públicos que acepten identificadores no confidenciales.

El almacenamiento secreto seguro está en camino y desbloqueará los puntos de conexión autenticados.

7. Prueba la herramienta

Haz clic en Herramienta de prueba. Proporciona valores de muestra para todos los parámetros de entrada. Comprueba que:

• La respuesta se recuperó correctamente
• El formato de respuesta es el que espera Agente de Clientes
• Se gestionan los casos de error

8. Guarda y adjúntalo a una habilidad

Haz clic en Guardar. Para que Agente de Clientes realmente use la herramienta, abre la habilidad que deseas usar y añade la herramienta allí.

Escribir una buena descripción de la herramienta

La descripción es el campo más importante. Agente de Clientes elige qué herramienta utilizar en función de la descripción, no del nombre. 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

• Aún no utilices herramientas totalmente personalizadas para puntos de conexión que requieran credenciales secretas. Pronto habrá compatibilidad con puntos de conexión autenticados. Hasta que se envíe, solo usa puntos de conexión seguros para llamar sin autorización secreta.
• Utiliza la IP para permitir la inclusión en la lista cuando sea posible. Si tu punto de conexión es interno, restringe el acceso a los intervalos de IP de Klaviyo en lugar de depender de secretos.
• Ten en cuenta los datos que envías. Agente de Clientes transmite los datos de los clientes a la herramienta en función de lo que le indican las instrucciones de habilidad. Revisa qué campos recibe tu 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: Agente de Clientes nunca utiliza la herramienta.
Causa probable: la descripción es demasiado vaga o la herramienta no está vinculada a la habilidad que la usaría.
Solución: Vuelve a escribir la descripción para describir específicamente cuándo debe utilizarse. Confirma que la herramienta aparece en la lista de herramientas de la habilidad.

Síntoma: La herramienta devuelve un error durante la prueba.
Causa probable: URL incorrecta, cuerpo mal formado o una carga útil que tu punto de conexión no acepta.
Solución: Utiliza la función de la herramienta de prueba para comprobar la solicitud sin procesar y la respuesta. Verifica el formato de la URL y del cuerpo con la entrada esperada de tu punto de conexión.

Síntoma: Agente de Clientes utiliza la herramienta, pero pasa parámetros incorrectos.
Causa probable: los nombres de los marcadores de posición no coinciden con el esquema o las instrucciones de habilidad no son claras sobre qué aprobar.
Solución: Comprueba que los nombres de los marcadores de posición coincidan exactamente. Actualiza las instrucciones de las habilidades para que sean explícitas sobre cuándo utilizar la herramienta y qué parámetros 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

¿Pueden utilizar una herramienta varias habilidades?
Sí. Una vez creada, una herramienta puede adjuntarse a cualquier cantidad de habilidades.

¿Qué métodos de autenticación son compatibles?
Pronto habrá compatibilidad con puntos de conexión autenticados. Por ahora, usa puntos de conexión que no requieran credenciales secretas (puntos de conexión internos con una lista de IP permitida o puntos de conexión públicos con identificadores no confidenciales).

¿Qué ocurre si mi punto de conexión está inactivo o devuelve un error?
El manejo de errores para herramientas totalmente personalizadas aún no está diseñado. Si falla tu punto de conexión, Agente de Clientes puede producir una respuesta degradada o confusa. Hasta que se produzcan errores en el manejo de los barcos, solo usa los puntos de conexión en los que confíes y monitorea de cerca el comportamiento de las herramientas.

¿Puedo editar una herramienta después de crearla?
Sí. Puedes editar el nombre, la descripción, la configuración y las habilidades asociadas en cualquier momento.

¿Puedo cambiar la versión de una herramienta?
Aún no se admite el control de versiones. Las ediciones de una herramienta surten efecto inmediatamente en todas las habilidades que la utilicen.

Additional resources