API de Customer Agent (versión beta)
Qué aprenderás
Qué son las API de Customer Agent, qué hace cada grupo de punto de conexión y cómo empezar a llamarlas. Las API te permiten configurar tu Customer Agent, leer lo que está haciendo en producción y ejecutarlo mediante programación, directamente a través de HTTP, junto con el resto de la API pública de Klaviyo.
Nota: Las API de Customer Agent están en fase beta. Los punto de conexión y los esquemas pueden cambiar antes de la disponibilidad general. Las API beta no están diseñadas para su uso en producción (consulta la política de versionado y retirada de versiones de Klaviyo para obtener más información).
Qué te permiten hacer las API
Las API de Customer Agent cubren 4 tareas:
- Configura el agente: lee o actualiza el agente en sí, además de sus habilidades, herramientas, fuentes de conocimiento y secretos.
- Lee conversaciones de producción: enumera e inspecciona las conversaciones de los Customer Agent.
- Informa sobre el rendimiento: volumen de extracción, tasa de resolución y métricas por habilidad.
- Ejecuta el agente durante un turno: envía un turno de conversación y recupera la respuesta del agente. Esta es la primitiva sin cabeza, útil para incrustar el agente en tu propia superficie.
Como estos cuatro trabajos están detrás de una sola API, puedes conectarlos en un bucle de entrenamiento continuo: extraer lo que ocurrió, diagnosticar lo que funcionó y lo que no, y después aplicar los cambios de configuración. Con una integración de API o una conexión MCP configurada de forma segura, un asistente de IA como Claude o ChatGPT puede ayudar a leer conversaciones, encontrar patrones en los fallos y proponer cambios en tus habilidades, herramientas, conocimientos y orientación.
Autenticación y acceso
Usa una clave de API privada de Klaviyo con el ámbito agents para llamar a estos punto de conexión. Customer Agent ya debe estar habilitado para tu cuenta.
Cuando creas la clave, eliges el nivel de acceso para el ámbito agents:
Nivel de acceso | Subvenciones |
Acceso de lectura | agents:read (puntos de conexión GET para configuración y conversaciones, además de puntos de conexión POST para informes). No se devuelven los valores secretos. |
Acceso completo | agents:read y agents:write: todo lo anterior, además de cambios de configuración compatibles, creación y actualizaciones de conversaciones, y ejecución del agente para un turno. |
Elige la opción de solo lectura si solo necesitas observar al agente (por ejemplo, un panel de informes). Elige lectura/escritura si necesita configurar el agente o ejecutar turnos de conversación.
- Ve a Configuración > claves de API y haz clic en Crear clave de API privada.
- Introduce un nombre de clave de API privada y selecciona Clave personalizada.
- En la fila Agentes, selecciona Acceso de lectura o Acceso completo para la integración, usando la tabla anterior.
- Haz clic en Crear y, a continuación, haz clic en el icono de copiar y guarda la clave de forma segura. No puedes volver a ver la clave después de salir de la página de confirmación.
Para obtener más información, consulta cómo crear o clonar una clave de API privada.
Envía solicitudes de API desde el servidor a https://a.klaviyo.com e incluye este encabezado de autorización. Mantén la clave privada fuera del código del navegador y de las aplicaciones orientadas a compradores:
Authorization: Klaviyo-API-Key your-private-api-key
Cada solicitud también debe incluir el encabezado de la revisión beta:
revision: 2026-10-15.pre
Sin el encabezado de la revisión beta, la solicitud se rechazará.
Límites de la tasa
Los límites de tasa dependen del grupo de puntos de conexión:
- Agente, habilidades, herramientas, conocimientos, secretos y respuestas: límite de ráfaga de 10 solicitudes por segundo y límite sostenido de 150 solicitudes por minuto.
- Conversaciones, mensajes de conversación e informes: límite de ráfaga de 3 solicitudes por segundo y límite constante de 60 solicitudes por minuto.
Formato de la solicitud
Utiliza las convenciones de solicitud JSON:API de Klaviyo, con un formato independiente para las cargas de archivos:
- Tipo de contenido:
application/vnd.api+jsonpara solicitudes JSON. Usamultipart/form-dataparaPOST /api/agent-knowledge-files. - Las colecciones paginadas usan
page[cursor]ypage[size](por defecto 50, máximo 100, solo hacia adelante). Sigue links.next hasta que esté vacío para recuperar las páginas restantes. - El filtrado utiliza los campos y los operadores compatibles que se enumeran en la referencia de cada punto de conexión. El orden de clasificación es específico del punto de conexión: las conversaciones van de la más reciente a la más antigua, los mensajes van del más antiguo al más reciente, y las habilidades y las herramientas se clasifican por ID.
Grupos de punto de conexión
Agente
Hay como máximo 1 Customer Agent por empresa. Llama a GET /API/Customer Agent para encontrar su ID y, a continuación, usa ese ID en la URL de GET o PATCH. La lista está vacía si Customer Agent no está habilitado para la cuenta.
Método | Ruta | Qué hace |
| Encuentra el agente y su ID | |
| Recupera el nombre del agente, el tono de voz, las reglas de escalado y los estilos de comunicación | |
| Actualiza los campos de nivel superior del agente. |
Habilidades de los agentes
Puedes leer las habilidades que quedan en la cuenta, incluidas las habilidades personalizadas y los valores predeterminados personalizados anteriormente. Se han eliminado las habilidades predeterminadas sin modificar y la biblioteca de plantillas de habilidades predeterminadas. Solo las habilidades personalizadas se pueden actualizar o eliminar a través de estos puntos de conexión. Establece el status de una habilidad personalizada en draft para ponerla en fase de preparación o pausarla, o en live para activarla.
Método | Ruta | Qué hace |
| Enumera todas las habilidades | |
| Crear una habilidad | |
| Consigue una habilidad | |
| Actualizar una habilidad | |
| Eliminar una habilidad |
Herramientas del agente
Solo las herramientas personalizadas se pueden actualizar o eliminar. Para usar una herramienta dentro de una habilidad personalizada, vincúlala mediante la relación agent-tools de la habilidad. El uso directo se controla mediante los permisos de la herramienta en Customer Agent > Conectores; una herramienta no necesita una habilidad cuando se configura en Permitir siempre. Una herramienta configurada en Solo en habilidades debe incluirse en una habilidad, y Bloqueado evita el uso por cualquiera de las dos vías.
Método | Ruta | Qué hace |
| Herramientas de lista visibles para la empresa | |
| Crear una herramienta HTTP externa | |
| Consigue una herramienta | |
| Actualizar una herramienta | |
| Eliminar una herramienta |
Conocimientos del agente
Crea fragmentos de texto, páginas web, pares de preguntas y respuestas o carpetas configurando source.source_type como snippet, webpage, qa o folder. Para añadir un file, usa el punto de conexión de carga de archivos independiente.
Método | Ruta | Qué hace |
| Enumera los elementos de conocimiento de nivel superior, del más reciente al más antiguo; filtra por folder_id para enumerar el contenido de una carpeta | |
| Crear un fragmento, una página web, un par de Q&A o una carpeta | |
| Subir un archivo como fuente de conocimiento (varias partes) | |
| Obtén una fuente de conocimientos | |
| Actualiza el título o el contenido de un fragmento, o la pregunta o la respuesta de un par de preguntas y respuestas | |
| Eliminar una fuente de conocimientos |
Secretos del agente
Secretos cifrados que usan las herramientas personalizadas. El punto de conexión de la lista solo devuelve metadatos seguros; el valor secreto en sí nunca se devuelve.
Método | Ruta | Qué hace |
| Lista secreta (solo metadatos) | |
| Crear un secreto | |
| Actualizar un secreto | |
| Eliminar un secreto |
Conversaciones
Lee las conversaciones que el agente ha tenido con los compradores o crea una conversación para ejecutarla a través de la API. Una conversación puede abarcar muchos mensajes durante un periodo largo. La lista puede incluir conversaciones en directo y de vista previa; usa filter=equals(mode,"live") para limitarla a conversaciones en directo.
Método | Ruta | Qué hace |
| Enumerar conversaciones | |
| Obtener una conversación por ID, incluidas las referencias a sus mensajes | |
|
| Leer el contenido del mensaje, de más antiguo a más reciente, con paginación |
| Crea una conversación vacía antes de ejecutar el agente. |
Informes
Métricas agregadas, limitadas a la empresa solicitante. Ambos informes que aparecen a continuación son puntos de conexión POST: pasa los parámetros del informe en el cuerpo. Requieren agents:read, así que una clave de solo lectura puede ejecutarlos.
Método | Ruta | Qué hace |
| Métricas de nivel de conversación: volumen y tasa de resolución | |
| Informe de volumen por habilidad |
Ejecuta el agente
Método | Ruta | Qué hace |
| Ejecuta el Customer Agent durante un turno de conversación: pasa la entrada del comprador y recupera la respuesta del agente. |
Este es el método primitivo para integrar el Customer Agent en tu propia superficie (tu aplicación, tu centro de ayuda, un panel de asistencia diseñado por socios).
Crea una conversación abierta con POST /api/customer-agent-conversations antes de ejecutar un turno. El punto de conexión de respuesta solo acepta conversaciones creadas mediante la API. Una conversación cerrada, o una que ya se ha asignado a tu equipo, no puede aceptar más respuestas.
Qué sigue requiriendo la interfaz de usuario de Klaviyo
Algunos pasos de configuración aún no están activos en el API:
- Configuración de canales (chat web, correo electrónico, SMS, WhatsApp): la configuración de canales se lleva a cabo en la configuración de la Plataforma Klaviyo.
- Activación en cada canal: el interruptor de encendido/apagado por canal permanece en la interfaz de usuario.
- Selección de Helpdesk (en Customer Agent, abre un canal en Channels y configura la sección Transferencia). Consulta Gestionar la configuración de Customer Agent para obtener más información.
Flujos de trabajo típicos
Configura una vez y luego mantén
- Crea una clave de API privada con el alcance
agentsy acceso de lectura y escritura en Klaviyo. - Extrae el estado actual (GET /api/customer-agents para encontrar el ID del agente) y, a continuación, recupera el agente y las listas de habilidades, herramientas y conocimientos. Sigue los enlaces de paginación para leer todas las páginas.
- Realiza cambios (crea o actualiza habilidades, herramientas, conocimientos y secretos personalizados según sea necesario). Revisa los permisos de la herramienta en Conectores. Vincula las herramientas a cualquier habilidad personalizada que las use y establece esas habilidades en estado: activo cuando estés listo para activarlas.
- Comprueba la producción: enumera las conversaciones recientes y extrae un informe de valores para ver cómo está funcionando el agente.
- Iterar
Entrena a tus agentes en un bucle
Las APIs están diseñadas para cerrar el bucle entre lo que tu agente hizo en producción y cómo está configurado. Un bucle típico:
- Extrae conversaciones recientes (OBTÉN conversaciones filtradas por created_at y status, añadiendo equals(mode,"live") al filtro para conversaciones de producción). Obtén los Customer Agent-messages de cada conversación y sigue links.next para leer todas las páginas.
- Diagnosticar: clasifica cada conversación como un éxito o un fracaso. Buscar patrones: ¿las escalas se agrupan en torno a un tema? ¿Se están desviando ciertas habilidades cuando no deberían? ¿El agente no tiene los conocimientos que necesita?
- Métricas extraídas: informes de valores para el volumen y la tasa de resolución, además de informes de valores de habilidades para desgloses por habilidad. Confirma que los patrones se mantengan en conjunto.
- Propón cambios: en función de los patrones de fallos, decide qué cambiar: edita las instrucciones de una habilidad, añade un fragmento de conocimiento, crea una nueva herramienta personalizada, ajusta una regla de tono, añade un activador de escalada.
- Aplicar cambios: PARCHAR las habilidades afectadas, PUBLICAR nuevas fuentes de conocimiento, etc.
- Loop Se repite en la siguiente ventana de conversaciones.
Puedes usar un asistente de IA como Claude, ChatGPT o Cursor para extraer conversaciones, detectar carencias, proponer ediciones específicas y aplicar cambios con tu aprobación. Conéctalo a través del servidor MCP de Klaviyo o de tu propia integración de API y mantén la clave de API privada en una configuración segura en lugar de incluirla en prompts. El servidor MCP admite muchas de estas tareas, pero crear o actualizar secretos y subir archivos de conocimiento requieren llamadas directas a la API.
Inserta el agente en tu propia superficie
Usa mode: preview para hacer pruebas sin facturación ni métricas de producción. mode: live es para interacciones reales de compradores y cuenta para la facturación y las métricas de producción. La advertencia anterior sobre el uso beta sigue aplicándose.
- Crea una clave con el alcance de los agentes (lectura/escritura).
- Crea una conversación (desde tu servidor, envía una solicitud POST a
/api/customer-agent-conversationscon elmodeseleccionado). Guarda el ID de conversación devuelto. - Abre una conversación en tu interfaz de usuario: recopila la entrada del comprador.
- Ejecuta un turno (desde el servidor, envía una solicitud POST a /api/customer-agent-responses con mode, messages y el ID guardado en data.relationships.conversation.data.id). Usa el tipo de relación customer-agent-conversation. Incluye el historial de la conversación en messages y termina con el mensaje más reciente del comprador con role: user.
- Renderiza la respuesta (procesa los eventos devueltos en orden y muestra los mensajes del agente y cualquier dato estructurado compatible en tu interfaz). Gestiona los eventos de transferencia en tus integraciones. La API devuelve eventos juntos sin streaming; no los entrega a través de un canal.
- Repite en cada turno con el mismo ID de conversación y modo mientras la conversación esté abierta. Después de una transferencia difícil o silenciosa, deja de solicitar respuestas del agente y redirige al comprador al equipo de soporte.
PREGUNTAS FRECUENTES
¿Hay algún servidor MCP?
Sí. El servidor MCP de Klaviyo alojado de forma remota incluye herramientas de Customer Agent para habilidades, herramientas, conocimientos, metadatos secretos, conversaciones, informes y la ejecución del agente. Crear una conversación, crear o actualizar secretos y cargar archivos de conocimiento requiere llamadas directas a la API. Consulta Servidor MCP de Klaviyo.
¿Es esto lo suficientemente estable como para seguir avanzando?
La versión beta significa que el esquema puede cambiar. Los puntos de conexión son perfectamente definibles, pero aún no nos comprometemos a lograr una estabilidad a largo plazo. No envíes integraciones críticas para la producción en comparación con la revisión beta.
¿Dónde encuentro el esquema completo?
La referencia completa está disponible en el portal de desarrolladores de Klaviyo en https://developers.klaviyo.com/en/reference/. Los puntos de conexión de Customer Agent aparecen en las API beta en la revisión 2026-10-15.pre.
Artículos relacionados
Learn more about Klaviyo APIs, authentication, and beta features.