Cómo crear una herramienta (beta)

Función beta. La creación de herramientas totalmente personalizadas desde cero está en versión beta abierta y disponible para todas las cuentas de Customer Agent, sin tener que registrarse. Encontrarás la página de herramientas en Customer Agent. La función aún se está ampliando y puede cambiar.

Qué aprenderás

Cómo conectar un Customer Agent a cualquier punto de conexión HTTP usando una herramienta totalmente personalizada, escribe una descripción de la herramienta que el Customer Agent realmente usará y prueba tu herramienta antes de conectarla a una habilidad.

Antes de empezar

Necesitarás:

• Customer Agent habilitado
• Un punto de conexión HTTP al que quieras que llame un Customer Agent,uno que no requiera credenciales secretas (Claves de API, tokens de portador, etc.) para acceder hoy (puntos de conexión autenticados disponibles próximamente, consulta la advertencia a continuación).
• Una habilidad a la que puedes adjuntar la herramienta, ya sea con un Customer Agent o con una habilidad totalmente personalizada que hayas creado.

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

Advertencia: Pronto se almacenarán de forma segura las Claves de API y otros secretos. Hasta que se envíe, no pongas Claves de API, tokens de portador u otras credenciales confidenciales en herramientas totalmente personalizadas: la configuración de herramientas aún no es un lugar seguro para almacenarlas. Por ahora, solo usa herramientas con puntos de conexión a los que se pueda llamar sin autenticación secreta (por ejemplo, puntos de conexión internos detrás de la lista de permitidos de IP o puntos de conexión que acepten identificadores no confidenciales). La compatibilidad con puntos de conexión autenticados está en camino.

Qué es una herramienta totalmente personalizada

Una herramienta totalmente personalizada es una solicitud HTTP que el Customer Agent puede realizar durante una conversación. La creación de herramientas totalmente personalizadas está en versión beta abierta y disponible para todas las cuentas de Customer Agent. Usa una cuando las herramientas que incluye el 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 conocer el concepto subyacente, consulta el artículo sobre herramientas de Customer Agent.

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 de herramientas

Ve a Customer Agent > Herramientas y haz clic en Crear herramienta.

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

• 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. 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: GET, POST, PUT, DELETE o PATCH.
• URL: la URL de punto de conexión completa. 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.

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

Proporciona un cuerpo JSON. Usa marcadores de posición para los valores que el Customer Agent debe rellenar en tiempo de ejecución.

Cuerpo de ejemplo:

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

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

El Customer Agent 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 tu esquema de entrada (por ejemplo, {{product_sku}}, {{order_id}})

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

6. Autentificación

Próximamente se admitirán los puntos de conexión autenticados. Hasta entonces, no pongas Claves de API, tokens de portador u otros secretos en una herramienta totalmente personalizada. Usa solo puntos de conexión a los que se pueda llamar sin credenciales secretas; por ejemplo, puntos de conexión internos protegidos por listas de permisos de IP 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 Probar herramienta. Proporciona valores de muestra para cualquier parámetro de entrada. Comprueba que:

• La respuesta se ha recuperado correctamente.
• El formato de respuesta es el que Customer Agent espera
• Se gestionan los casos de error

8. Guarda y adáptate a una habilidad

Pulsa Guardar. Para hacer que Customer Agent realmente use la herramienta, abre la habilidad que quieras usarla y añade la herramienta allí.

Escribir una buena descripción de la herramienta

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

• No uses herramientas totalmente personalizadas para puntos de conexión que aún requieran credenciales secretas. Próximamente se admitirán los puntos de conexión autenticados. Hasta que se envíe, usa solo puntos de conexión a los que se pueda llamar sin autenticación secreta.
• Usa la IP para permitir la inclusión en la lista siempre que sea posible. Si tienes un punto de conexión interno, restringe el acceso a los rangos de IP de Klaviyo en lugar de depender de secretos.
• Ten en cuenta qué datos envías. El Customer Agent transfiere los datos de los clientes a la herramienta en función de lo que se le indique en las instrucciones técnicas. Revisa qué campos recibe tu 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: El Customer Agent nunca usa la herramienta.
Causa probable: la descripción es demasiado vaga o la herramienta no está vinculada a la habilidad que la utilizaría.
Solución: Reescribe la descripción para describir específicamente cuándo debes usarla. Confirma que la herramienta aparezca 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.
Corrección: Utiliza la función de la herramienta de prueba para comprobar la solicitud y la respuesta en bruto. Verifica el formato de la URL y el cuerpo del mensaje con la entrada esperada de tu punto de conexión.

Síntoma: el Customer Agent usa 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 tienen claro qué se debe pasar.
Solución: Comprueba que los nombres de los marcadores de posición coincidan exactamente. Actualiza las instrucciones de habilidades para que sean explícitas sobre cuándo usar la herramienta y qué parámetros 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 con varias habilidades?
Sí. Una vez creada, una herramienta se puede adjuntar a cualquier número de habilidades.

¿Qué métodos de autenticación se admiten?
Próximamente se admitirán los 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 permitidos de direcciones IP o puntos de conexión públicos con identificadores no confidenciales).

¿Qué ocurre si mi punto de conexión está caído o devuelve un error?
La gestión de errores de herramientas totalmente personalizadas aún no está diseñada. Si tu punto de conexión falla, el Customer Agent puede producir una respuesta degradada o confusa. Hasta que no se produzcan errores en los envíos, usa solo los puntos de conexión en los que confíes y monitoriza 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 adjuntas en cualquier momento.

¿Puedo editar una herramienta?
Aún no se admite el control de versiones. Las modificaciones de una herramienta se aplicarán inmediatamente a todas las habilidades que la utilicen.

Additional resources