API de Agente de Clientes (Beta)

Objetivos del artículo

Qué son las API de Agente de Clientes, qué hace cada grupo de puntos de conexión y cómo empezar a llamarlas. Las API te permiten configurar tu Agente de Clientes, 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 interfaz de programación de aplicaciones (API) del Agente de Clientes están en beta. Los puntos de conexión y los esquemas pueden cambiar antes de la disponibilidad general. Las interfaz de programación de aplicaciones (API) beta no están pensadas para usarse en producción. Consulta la política de control de versiones y descontinuación de Klaviyo para obtener más detalles.

Lo que las API te permiten hacer

Las interfaz de programación de aplicaciones (API) del Agente de Clientes cubren 4 funciones:

1. Configura el agente: lee o actualiza el agente en sí, además de sus habilidades, herramientas, fuentes de conocimiento y secretos.
2. Lee las conversaciones de producción: enumera e inspecciona las conversaciones del Agente de Clientes.
3. Informe sobre el rendimiento: volumen de extracción, tasa de resolución y métricas por habilidad.
4. Ejecuta el agente por un turno: envía un turno de conversación y obtén la respuesta del agente. Esta es la primitiva headless, útil para incrustar el agente en vuestra propia superficie.

Como estos cuatro trabajos viven detrás de una sola interfaz de programación de aplicaciones (API), puedes conectarlos a un bucle de entrenamiento continuo: extraer lo que pasó, diagnosticar qué funcionó y qué no, y luego enviar cambios de configuración de vuelta. Con una integración de interfaz de programación de aplicaciones (API) configurada de forma segura o una conexión MCP, 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, conocimiento y orientación.

Autenticación y acceso

Usa una clave de API privada de Klaviyo con el alcance agents para llamar a estos puntos de conexión. El Agente de Clientes ya debe estar habilitado para la cuenta.

Cuando creas la clave, eliges el nivel de acceso para el alcance agents:

Elige la opción de solo lectura si tu integración solo necesita observar al agente (por ejemplo, un panel de informes). Elige lectura/escritura si necesitas configurar el agente o ejecutar turnos de conversación.

1. Ve a Configuración > Claves de API y haz clic en Crear clave de API privada.
2. Ingresa un nombre de clave de API privada y selecciona Clave personalizada.
3. En la fila Agentes, selecciona Acceso de lectura o Acceso completo para la integración, usando la tabla anterior.
4. Haz clic en Crear, luego haz clic en el ícono 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 detalles, consulta cómo crear o clonar una clave de API privada.

Envía solicitudes a la interfaz de programación de aplicaciones (API) desde tu 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 apps orientadas a los compradores:

Authorization: Klaviyo-API-Key your-private-api-key

Cada solicitud debe incluir también el encabezado de la revisión beta:

revision: 2026-10-15.pre

Sin el encabezado de la revisión beta, la solicitud será rechazada.

Límites de tasas

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 estable de 150 solicitudes por minuto.
• Conversaciones, mensajes de conversaciones e informes: límite de ráfaga de 3 solicitudes por segundo y límite constante de 60 solicitudes por minuto.

Formato de solicitud

Usa las convenciones de solicitud JSON:interfaz de programación de aplicaciones (API) de Klaviyo, con un formato separado para las cargas de archivos:

• Tipo de contenido: application/vnd.api+json para solicitudes JSON. Usa multipart/form-data para POST /api/agent-knowledge-files.
• Las colecciones paginadas usan page[cursor] y page[size] (predeterminado 50, máximo 100, solo hacia adelante). Sigue links.next hasta que esté vacío para recuperar las páginas restantes.
• El filtrado usa los campos y operadores compatibles que se enumeran en la referencia de cada punto de conexión. El orden de clasificación es específico de cada punto de conexión: las conversaciones muestran primero las más recientes, los mensajes muestran primero los más antiguos y las habilidades y herramientas se ordenan por ID.

Grupos de puntos de conexión

Agente

Hay como máximo 1 Agente de Clientes por empresa. Llama a GET /interfaz de programación de aplicaciones (API)/Agentes de Clientes para encontrar su ID y luego usa ese ID en la URL de GET o PATCH. La lista está vacía si Agente de Clientes no está habilitado para la cuenta.

Habilidades del agente

Puedes leer habilidades predefinidas y personalizadas. Solo las habilidades personalizadas se pueden actualizar o eliminar. Configura el status de una habilidad personalizada en draft para prepararla o pausarla, o en live para activarla.

Herramientas del agente

Solo las herramientas personalizadas se pueden actualizar o eliminar. Después de crear una herramienta HTTP externa, asígnala a una habilidad personalizada mediante la relación agent-tools de la habilidad. Una herramienta no está disponible para esa habilidad hasta que se asigne.

Conocimiento del agente

Crea fragmentos de texto, páginas web, pares de preguntas y respuestas (Q&A) o carpetas al configurar source.source_type en snippet, webpage, qa o folder. Para agregar un file, usa el punto de conexión independiente de carga de archivos.

Secretos del agente

Secretos encriptados utilizados por herramientas personalizadas. El punto de conexión de lista solo devuelve metadatos seguros; el valor secreto en sí nunca se devuelve.

Conversaciones

Lee las conversaciones que el agente ha tenido con compradores o crea una conversación para ejecutarla a través de la interfaz de programación de aplicaciones (API). Una conversación puede abarcar muchos mensajes durante un periodo largo. La lista puede incluir conversaciones en vivo y de vista previa; usa filter=equals(mode,"live") para limitarla a conversaciones en vivo.

Informes

Métricas agregadas, limitadas a la empresa solicitante. Los dos informes 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.

Ejecuta el agente

Esta es la forma primitiva de incrustar Agente de Clientes en tu propia superficie (tu aplicación, tu centro de ayuda, un panel de asistencia creado por tus 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 a través de la interfaz de programación de aplicaciones (API). Una conversación cerrada, o una que ya se enrutó 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 disponibles en la API:

• Configuración del canal (chat web, correo electrónico, SMS, WhatsApp): la configuración del canal vive en la configuración de la plataforma Klaviyo.
• Activando cada canal: el interruptor de encendido/apagado por canal permanece en la interfaz de usuario.
• Selección de Helpdesk — en Agente de Clientes, abre un canal en Canales y configura la sección Handoff. Consulta Administrar la configuración de Agente de Clientes para ver los detalles.

Flujos de trabajo típicos

Configura una vez y luego mantén

1. Crea una clave de API privada con el alcance agents y acceso de lectura/escritura en Klaviyo.
2. Extraer el estado actual — GET /api/customer-agents para encontrar el ID del Agente de Clientes, y luego recuperar el agente y las listas de habilidades, herramientas y conocimientos. Sigue los enlaces de paginación para leer todas las páginas.
3. Realiza cambios — crea o actualiza habilidades, herramientas, conocimiento y secretos personalizados según sea necesario. Vincula herramientas nuevas a las habilidades que las usan y establece las habilidades personalizadas con el estado: activo cuando estés listo para activarlas.
4. Revisa la producción: enumera las conversaciones recientes y extrae un informe de valores para ver cómo se está desempeñando el agente.
5. Iterar.

Entrena a tu agente en un bucle

Las API 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:

1. Extraer conversaciones recientes — OBTÉN conversaciones filtradas por created_at y status, agregando equals(mode,"live") al filtro para conversaciones de producción. Obtén los mensajes de Agente de Clientes de cada conversación y sigue links.next para leer cada página.
2. Diagnosticar: para cada conversación, clasifícala como un éxito o un fracaso. Busca patrones: ¿las derivaciones se agrupan en torno a un tema? ¿Se están desviando ciertas habilidades cuando no deberían? ¿Al agente le faltan los conocimientos que necesita?
3. Métricas de extracción: informe de valores para el volumen y la tasa de resolución, más informe de valores de habilidad para desgloses por habilidad. Confirma que los patrones se mantengan en el agregado.
4. Proponte cambios: en función de los patrones de falla, 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 y añade un activador de derivación.
5. Aplicar cambios: PARCHAR las habilidades afectadas, PUBLICAR nuevas fuentes de conocimiento, etc.
6. Bucle. Repite en la siguiente ventana de conversaciones.

Puedes usar un asistente de IA como Claude, ChatGPT o Cursor para extraer conversaciones, identificar brechas, proponer ediciones específicas y aplicar cambios con tu aprobación. Conéctalo a través del servidor MCP de Klaviyo o tu propia integración de interfaz de programación de aplicaciones (API), y mantén las claves de API privadas en una configuración segura en lugar de en los prompts. El servidor MCP admite muchas de estas tareas, pero para crear o actualizar secretos y cargar archivos de conocimiento se requieren llamadas directas a la interfaz de programación de aplicaciones (API).

Incrusta 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 con compradores y cuenta para la facturación y las métricas de producción. La advertencia anterior sobre el uso de la beta sigue aplicando.

1. Crea una clave con el alcance de los agentes (lectura/escritura).
2. Crea una conversación — desde el servidor, envía una solicitud POST a /api/customer-agent-conversations con el mode elegido. Guarda el ID de la conversación devuelta.
3. Abre una conversación en tu interfaz de usuario: obtén la opinión del comprador.
4. Ejecuta un turno — desde el servidor, realiza un 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.
5. Renderiza la respuesta — procesa los eventos devueltos en orden y muestra los mensajes del agente y cualquier dato estructurado compatible en la interfaz. Maneja los eventos de transferencia en la integración. La interfaz de programación de aplicaciones (API) devuelve los eventos juntos, sin streaming; no los entrega a través de un canal.
6. Repite en cada turno usando el mismo ID de conversación y el mismo modo mientras la conversación esté abierta. Después de una transferencia directa o silenciosa, deja de solicitar respuestas de agentes y dirige al comprador a tu equipo de soporte.

Preguntas frecuentes

¿Hay un servidor MCP?

Sí. El servidor MCP de Klaviyo alojado de forma remota incluye herramientas de Agente de Clientes para habilidades, herramientas, conocimiento, metadatos de secretos, conversaciones, reportes y para ejecutar el agente. Crear una conversación, crear o actualizar secretos y subir archivos de conocimiento requieren llamadas directas a la interfaz de programación de aplicaciones (API). Consulta el servidor MCP de Klaviyo.

¿Es esto lo suficientemente estable como para aprovechar?

La versión beta significa que el esquema puede cambiar. Los puntos de conexión son totalmente accesibles, pero aún no nos comprometemos con la estabilidad a largo plazo. No envíes integraciones críticas para la producción contra la revisión beta.

¿Dónde encuentro el esquema completo?

La referencia completa está en el portal para desarrolladores de Klaviyo en https://developers.klaviyo.com/en/reference/. Los punto de conexión del Agente de Clientes aparecen en interfaz de programación de aplicaciones (API) beta en la revisión 2026-10-15.pre.

Artículos relacionados