APIs do Customer Agent (Beta)
O que você vai aprender
O que são as APIs do Customer Agent, o que cada grupo de pontos de extremidade faz e como começar a chamá-los. As APIs permitem que você configure seu Customer Agent, leia o que ele está fazendo na produção e execute-o de forma programática diretamente por HTTP, juntamente com o restante da API pública da Klaviyo.
Observação: As APIs do Customer Agent estão em beta. Pontos de extremidade e esquemas podem mudar antes da disponibilidade geral. As APIs em beta não se destinam ao uso em produção — consulte a política de controle de versão e descontinuação da Klaviyo para mais detalhes.
O que as APIs permitem que você faça
As APIs do Customer Agent abrangem 4 tarefas:
- Configure o agente — leia ou atualize o próprio agente, além de suas habilidades, ferramentas, fontes de conhecimento e segredos.
- Leia as conversas de produção — liste e inspecione as conversas do Customer Agent.
- Relatório sobre desempenho — volume de extração, taxa de resolução e métricas por habilidade.
- Execute o agente por um turno — envie uma conversa e receba a resposta do agente de volta. Este é o primitivo sem cabeça — útil para incorporar o agente em sua própria superfície.
Como esses quatro trabalhos ficam por trás de uma única API, você pode conectá-los em um ciclo de treinamento contínuo: puxar o que aconteceu, diagnosticar o que funcionou e o que não funcionou e, em seguida, enviar alterações de configuração de volta. Com uma integração de API ou conexão MCP configurada com segurança, um assistente de IA como Claude ou ChatGPT pode ajudar a ler conversas, encontrar padrões em falhas e propor mudanças nas suas habilidades, ferramentas, conhecimentos e orientações.
Autenticação e acesso
Use uma chave de API privada da Klaviyo com o escopo agents para chamar esses pontos de extremidade. O Customer Agent já deve estar ativado para a sua conta.
Ao criar a chave, você escolhe o nível de acesso para o escopo agents:
Nível de acesso | Concessões |
Acesso para leitura | agents:read — pontos de extremidade GET para configuração e conversas, além de pontos de extremidade POST para relatórios. Valores secretos não são retornados. |
Acesso total | agents:read e agents:write — tudo o que está acima, além de alterações de configuração compatíveis, criação e atualizações de conversas e execução do agente por um turno. |
Escolha somente leitura se sua integração só precisar observar o agente (por exemplo, um painel de relatórios). Escolha ler/escrever se precisar configurar o agente ou executar turnos de conversa.
- Acesse Configurações > Chaves de API e clique em Criar chave de API privada.
- Insira um nome de chave de API privada e selecione Chave personalizada.
- Na linha Agentes, selecione Acesso de leitura ou Acesso total para sua integração, usando a tabela acima.
- Clique em Criar, depois clique no ícone de copiar e armazene a chave com segurança. Você não pode ver a chave novamente depois de sair da página de confirmação.
Para mais detalhes, consulte como criar ou clonar uma chave de API privada.
Envie solicitações de API do seu servidor para https://a.klaviyo.com e inclua este cabeçalho de autorização. Mantenha a chave privada fora do código do navegador e de apps voltados para compradores:
Authorization: Klaviyo-API-Key your-private-api-key
Cada solicitação também deve incluir o cabeçalho da revisão beta:
revision: 2026-10-15.pre
Sem o cabeçalho de revisão beta, a solicitação será rejeitada.
Limites de taxa
Os limites de taxa dependem do grupo de ponto de extremidade:
- Agente, habilidades, ferramentas, conhecimento, segredos e respostas: limite de pico de 10 solicitações por segundo e limite contínuo de 150 solicitações por minuto.
- Conversas, mensagens de conversa e relatórios: limite de pico de 3 solicitações por segundo e limite constante de 60 solicitações por minuto.
Formato da solicitação
Use as convenções de solicitação JSON:API do Klaviyo, com um formato separado para uploads de arquivos:
- Tipo de conteúdo:
application/vnd.api+jsonpara solicitações JSON. Usemultipart/form-dataparaPOST /api/agent-knowledge-files. - Coleções paginadas usam
page[cursor]epage[size](padrão: 50, máximo: 100, apenas para frente). Siga links.next até ele ficar vazio para recuperar as páginas restantes. - A filtragem usa os campos e operadores compatíveis listados na referência de cada ponto de extremidade. A ordem de classificação é específica de cada ponto de extremidade: as conversas ficam com as mais recentes primeiro, as mensagens com as mais antigas primeiro, e as habilidades e ferramentas são classificadas por ID.
Grupos de pontos de extremidade
Agente
Há no máximo 1 Customer Agent por empresa. Chame GET /api/Customer Agent para encontrar o ID e, em seguida, use esse ID na URL de GET ou PATCH. A lista fica vazia se o Customer Agent não estiver ativado para a conta.
Método | Caminho | O que ele faz |
| Encontre o agente e o ID dele | |
| Recupere o nome do agente, o tom de voz, as regras de escalonamento e os estilos de comunicação | |
| Atualizar os campos de nível superior do agente |
Habilidades do agente
Você pode ler as habilidades que permanecem na sua conta, incluindo habilidades personalizadas e padrões personalizados anteriormente. As habilidades padrão não modificadas e a biblioteca de modelos de habilidades padrão foram removidas. Somente habilidades personalizadas podem ser atualizadas ou excluídas por meio destes pontos de extremidade. Defina o(a) status de uma habilidade personalizada como draft para prepará-la ou pausá-la, ou como live para ativá-la.
Método | Caminho | O que ele faz |
| Listar todas as habilidades | |
| Criar uma habilidade | |
| Obtenha uma habilidade | |
| Atualizar uma habilidade | |
| Excluir uma habilidade |
Ferramentas do agente
Apenas ferramentas personalizadas podem ser atualizadas ou excluídas. Para usar uma ferramenta em uma habilidade personalizada, vincule-a pela relação agent-tools da habilidade. O uso direto é controlado pelas permissões da ferramenta em Customer Agent > Connectors; uma ferramenta não precisa de uma habilidade quando está definida como Always allow. Uma ferramenta definida como Only in skills precisa ser incluída em uma habilidade, e Blocked impede o uso por qualquer uma das duas formas.
Para entender o comportamento das permissões de ferramentas, consulte Understanding Tools.
Método | Caminho | O que ele faz |
| Listar ferramentas visíveis para a empresa | |
| Criar uma ferramenta HTTP externa | |
| Obter uma ferramenta | |
| Atualizar uma ferramenta | |
| Excluir uma ferramenta |
Conhecimento do agente
Crie trechos de texto, páginas da web, pares de Q&A ou pastas definindo source.source_type como snippet, webpage, qa ou folder. Para adicionar um(a) file, use o ponto de extremidade de upload de arquivo separado.
Método | Caminho | O que ele faz |
| Liste itens de conhecimento de nível superior, do mais recente para o mais antigo; filtre por folder_id para listar o conteúdo de uma pasta | |
| Crie um snippet, uma página da web, um par de Q&A ou uma pasta | |
| Fazer upload de um arquivo como uma fonte de conhecimento (multipart) | |
| Obtenha uma fonte de conhecimento | |
| Atualize o título ou o conteúdo de um snippet ou a pergunta ou a resposta de um par de P&R | |
| Excluir uma fonte de conhecimento |
Segredos do agent
Segredos criptografados usados por ferramentas personalizadas. O ponto de extremidade da lista retorna apenas metadados seguros — o próprio valor secreto nunca é retornado.
Método | Caminho | O que ele faz |
| Listar segredos (somente metadados) | |
| Criar um segredo | |
| Atualizar um segredo | |
| Excluir um segredo |
Conversas
Leia conversas que o agente teve com compradores ou crie uma conversa para executar pela API. Uma conversa pode abranger muitas mensagens ao longo de um longo período. A lista pode incluir conversas ao vivo e de prévia; use filter=equals(mode,"live") para limitá-la às conversas ao vivo.
Método | Caminho | O que ele faz |
| Listar conversas | |
| Obtenha uma conversa pelo ID, incluindo referências às mensagens dela | |
|
| Leia o conteúdo das mensagens, da mais antiga para a mais recente, com paginação |
| Crie uma conversa vazia antes de executar o agente |
Relatórios
Métricas agregadas, com escopo limitado à empresa solicitante. Ambos os relatórios abaixo são pontos de extremidade POST: passe os parâmetros do relatório no corpo. Elas exigem agents:read, então uma chave somente leitura pode executá-las.
Método | Caminho | O que ele faz |
| Métricas em nível de conversa: volume e taxa de resolução | |
| Relatório de volume por habilidade |
Executar o agente
Método | Caminho | O que ele faz |
| Execute o Customer Agent para uma conversa, transfira a entrada do comprador e receba a resposta do agente de volta |
Este é o método primitivo para incorporar o Customer Agent em sua própria superfície (seu aplicativo, sua central de ajuda, um painel de suporte criado por um parceiro).
Crie uma conversa aberta com POST /api/customer-agent-conversations antes de executar uma etapa. O ponto de extremidade de resposta aceita apenas conversas criadas pela API. Uma conversa fechada, ou uma que já foi encaminhada para sua equipe, não pode aceitar mais respostas.
O que ainda requer a Klaviyo UI
Algumas etapas de configuração ainda não estão ativas na API:
- Configuração do canal (chat web, e-mail, SMS, WhatsApp) — a configuração do canal permanece nas configurações da plataforma Klaviyo.
- Entrando em operação em cada canal — o interruptor liga/desliga por canal permanece na IU.
- Seleção do Helpdesk — no Customer Agent, abra um canal em Canais e configure a seção Transferência. Para mais detalhes, consulte Como gerenciar as configurações do Customer Agent.
Fluxos de trabalho típicos
Configure uma vez e, em seguida, mantenha
- Crie uma chave de API privada com o escopo
agentse acesso de leitura/gravação no Klaviyo. - Extrair o estado atual — GET /api/customer-agents para encontrar o ID do agente e, em seguida, recuperar o agente e as listas de habilidades, ferramentas e conhecimentos. Siga os links de paginação para ler todas as páginas.
- Faça alterações — crie ou atualize habilidades personalizadas, ferramentas, conhecimento e segredos conforme necessário. Revise as permissões da ferramenta em Conectores. Vincule ferramentas a quaisquer habilidades personalizadas que as utilizem e defina essas habilidades com o status: ativo quando estiver pronto para ativá-las.
- Verificar produção — liste conversas recentes e extraia um relatório de valores para ver o desempenho do agente.
- Iterar.
Treine seu agente em um loop
As APIs são projetadas para fechar o ciclo entre o que seu agente fez na produção e como ele está configurado. Um loop típico:
- Buscar conversas recentes — GET conversas filtradas por created_at e status, adicionando equals(mode,"live") ao filtro para conversas de produção. Busque as Customer Agent-messages de cada conversa e siga links.next para ler todas as páginas.
- Diagnosticar — para cada conversa, classifique-a como um sucesso ou um fracasso. Procure padrões: os encaminhamentos são agrupados em torno de um tópico? Certas habilidades estão sendo encaminhadas quando não deveriam? O agente não tem o conhecimento de que precisa?
- Métricas de baixa automática — relatório de valores para volume e taxa de resolução, mais relatório de valores de habilidade para detalhamentos por habilidade. Confirme a retenção de padrões em conjunto.
- Propor mudanças — com base nos padrões de falha, decidir o que mudar: editar as instruções de uma habilidade, adicionar um snippet de conhecimento, criar uma nova ferramenta personalizada, apertar uma regra de tom e adicionar um disparador de escalonamento.
- Aplicar alterações — CORRIGIR as habilidades afetadas, PUBLICAR novas fontes de conhecimento etc.
- Loop. Repetir na próxima janela de conversas.
Você pode usar um assistente de IA, como Claude, ChatGPT ou Cursor, para extrair conversas, encontrar lacunas, propor edições específicas e aplicar alterações com a sua aprovação. Conecte-o pelo servidor MCP da Klaviyo ou pelas suas próprias integrações de API e mantenha a chave de API privada em uma configuração segura, em vez de em prompts. O servidor MCP oferece suporte a muitas dessas tarefas, mas criar ou atualizar segredos e fazer upload de arquivos de conhecimento exige chamadas diretas de API.
Incorpore o agente em sua própria superfície
Use mode: preview para testar sem cobrança ou métricas de produção. mode: live é para interações reais de compradores e conta para cobrança e métricas de produção. O aviso acima sobre o uso beta ainda se aplica.
- Crie uma chave com o escopo de agentes (leitura/gravação).
- Criar uma conversa — do seu servidor, faça um POST em
/api/customer-agent-conversationscom o(a)modeescolhido(a). Salve o ID da conversa retornado. - Abra uma conversa na sua UI — colete a opinião do comprador.
- Execute um turno — do seu servidor, faça um POST para /api/customer-agent-responses com mode, messages e o ID salvo em data.relationships.conversation.data.id. Use o tipo de relacionamento customer-agent-conversation. Inclua o histórico da conversa em messages, terminando com a mensagem mais recente do shopper com role: user.
- Renderizar a resposta — processe os eventos retornados em ordem e exiba as mensagens do agente e quaisquer dados estruturados compatíveis na sua interface. Lide com eventos de transferência na sua integração. A API retorna eventos juntos, sem streaming; ela não os entrega por um canal.
- Repita para cada interação usando o mesmo ID da conversa e o mesmo modo enquanto a conversa estiver aberta. Após um handoff rígido ou silencioso, pare de solicitar respostas do agente e encaminhe o cliente para a sua equipe de suporte.
Perguntas frequentes
Existe um servidor MCP?
Sim. O servidor MCP remoto hospedado do Klaviyo inclui ferramentas do Customer Agent para habilidades, ferramentas, conhecimento, metadados secretos, conversas, relatórios e execução do agente. Criar uma conversa, criar ou atualizar segredos e fazer upload de arquivos de conhecimento exige chamadas diretas à API. Consulte servidor MCP da Klaviyo.
Isso é estável o suficiente para continuar?
Beta significa que o esquema pode mudar. Os pontos de extremidade são totalmente chamáveis, mas ainda não nos comprometemos com a estabilidade a longo prazo. Não envie integrações críticas para a produção em relação à revisão beta.
Onde encontrar o esquema completo?
A referência completa está no portal do desenvolvedor da Klaviyo em https://developers.klaviyo.com/en/reference/. Os ponto de extremidade do Customer Agent aparecem em APIs beta na revisão 2026-10-15.pre.
Artigos relacionados
Learn more about Klaviyo APIs, authentication, and beta features.