Como criar uma ferramenta

O que você vai aprender

Como conectar o Customer Agent a um ponto de extremidade HTTP usando uma ferramenta totalmente personalizada, escrever uma descrição da ferramenta que o Customer Agent realmente use e testar sua ferramenta antes de anexá-la a uma habilidade.

Antes de começar

Você precisará de:

• Customer Agent habilitado
• Um ponto de extremidade HTTP acessível por meio de um nome de host público. Endereços de rede privada, localhost e URLs que usam um endereço IP em vez de um nome de host não são compatíveis. Se o ponto de extremidade exigir uma chave de API ou token, você vai armazená-lo como um secret (veja as etapas 1 e 6).
• Uma habilidade com instruções editáveis para anexar a ferramenta a

Você pode criar e testar a ferramenta antes de anexá-la a uma habilidade. Para usá-la em conversas, adicione-a às instruções da habilidade. Se você precisar de uma nova habilidade, consulte Como criar uma habilidade.

O que é uma ferramenta totalmente personalizada

Uma ferramenta totalmente personalizada é uma solicitação HTTP que o Customer Agent pode fazer durante uma conversa. Use uma quando as ferramentas incluídas com o Customer Agent não cobrirem o que você precisa — por exemplo, consultar um pedido no seu próprio sistema de gerenciamento de pedidos em vez do Shopify, verificar o estoque em um sistema de depósito personalizado ou criar um tíquete em um helpdesk com o qual o Klaviyo não se integra nativamente.

Para entender o conceito subjacente, consulte Como entender as ferramentas.

Quando criar uma ferramenta totalmente personalizada

Alcance uma ferramenta totalmente personalizada quando:

• Você precisa de dados em tempo real de um sistema com o qual a Klaviyo ainda não se integrou
• Você quer que o Customer Agent execute uma ação em um sistema externo (cancele uma assinatura em seu sistema proprietário, crie um tíquete, atualize um registro)
• Uma ferramenta existente não se encaixa — por exemplo, você usa um OMS personalizado em vez da Shopify para pedidos

Se as informações não mudarem com frequência e forem iguais para cada cliente, adicione-as como conteúdo. As ferramentas são para ações e dados dinâmicos por cliente.

Configure

1. Abra a página Ferramentas personalizadas

1. Acesse Customer Agent > Conectores e abra o card Personalizado.
2. Se o seu ponto de extremidade precisar de uma credencial, vá até Segredos e clique em Adicionar segredo. Insira um Nome e um Valor do segredo e, em seguida, clique em Adicionar segredo. Pule esta etapa se o segredo já estiver salvo ou se o ponto de extremidade não precisar de um.
3. Clique em Criar ferramenta.

2. Nomeie e descreva a ferramenta

• Nome da ferramenta — Um identificador curto, como “Obter estoque” ou “Criar tíquete de devolução”.
• Descrição — Linguagem natural explicando o que a ferramenta faz e quando usá-la. O Customer Agent lê essa descrição para decidir se deve usar a ferramenta para uma determinada solicitação. Seja específico.

Um bom exemplo de descrição:

Obtém a contagem de estoque em tempo real de um determinado SKU de produto do sistema de warehouse. Use quando um comprador perguntar se um produto específico está em estoque.

Um exemplo de descrição vaga (evitar):

Obtém informações sobre o produto.

3. Configure a solicitação HTTP

• Método HTTP — GET, POST, PUT, DELETE ou PATCH.
• Modelo de URL — O URL completo do ponto de extremidade. Você pode incluir placeholders para valores dinâmicos (consulte a Etapa 5).
• Cabeçalhos — Quaisquer cabeçalhos que seu ponto de extremidade exija, incluindo Content-Type e cabeçalhos de autenticação.
• Parâmetro de consulta — Se o seu ponto de extremidade espera valores na string de consulta, insira aqui os nomes e os valores deles. Você pode usar placeholders para os valores (consulte a etapa 5).

4. Configure o corpo da solicitação (para POST, PUT, PATCH)

Em Modelo de corpo, forneça um objeto JSON. Use marcadores de posição para os valores que o Customer Agent deve preencher no tempo de execução.

Exemplo de corpo:

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

5. Defina variáveis para valores dinâmicos

Cada placeholder precisa ter uma variável correspondente em Variáveis. Para o exemplo de corpo acima:

1. Clique em Adicionar variáveis e insira profile_id como o Nome da variável. Defina Origem como Perfil da Klaviyo e Propriedade da Klaviyo como ID da Klaviyo. Isso fornece o ID do perfil da Klaviyo do cliente autenticado.
2. Adicione outra variável chamada product_sku. Defina Fonte como Variável dinâmica, escolha String como o Tipo e descreva o SKU que o Customer Agent deve fornecer em Descrição. Selecione Obrigatório se o ponto de extremidade exigir isso.

Repita para outros valores de que seu ponto de extremidade precisa, como order_id. Os nomes das variáveis precisam corresponder exatamente aos respectivos placeholders. Uma variável chamada conversation_id não é preenchida automaticamente com o ID da conversa atual.

Use as variáveis como marcadores de posição, como {{profile_id}} e {{product_sku}}, no URL, nos cabeçalhos, nos parâmetros de consulta ou no corpo. Ferramentas que usam variáveis de perfil Klaviyo exigem um comprador autenticado; a falta de um valor de perfil obrigatório impede a execução da solicitação.

6. Autenticação

Se o ponto de extremidade exigir uma chave de API, token bearer ou outra credencial, armazene-a como um secret. Secrets são criptografados, seus valores nunca são mostrados ao Customer Agent e não podem ser vistos novamente depois que você os salva.

1. Na sua ferramenta, em Variáveis, clique em Adicionar variáveis. Dê um nome à variável (por exemplo, api_key), defina Origem como Segredo e escolha o segredo que você salvou.
2. Faça referência à variável onde quer que seu ponto de extremidade espere a credencial: um cabeçalho, o URL, um parâmetro de consulta ou o corpo. Por exemplo, adicione um cabeçalho chamado Authorization com o valor Bearer {{api_key}}.

Para alternar uma chave, abra o menu da linha do secret, clique em Atualizar, insira o valor de substituição e, em seguida, clique em Atualizar. Toda ferramenta que usa o secret recebe o novo valor. A coluna Usado por mostra quais ferramentas fazem referência a cada secret; portanto, verifique-a antes de excluir um.

7. Salve e teste a ferramenta

Antes de salvar, revise Tempo limite (segundos) e Número máximo de tentativas em Configurações. Você pode definir um limite de tempo geral de 1–10 segundos e 0–3 tentativas de novo para falhas temporárias. Se a ferramenta alterar dados, verifique se o seu ponto de extremidade consegue lidar com segurança com uma solicitação repetida.

Clique em Salvar para criar a ferramenta. A ferramenta salva é aberta com uma seção de Teste.

Os testes enviam solicitações reais para seu ponto de extremidade e podem alterar dados. Use um perfil de teste e registros de teste. Salvar e executar teste também salva quaisquer edições na ferramenta, inclusive em uma ferramenta já usada por habilidades ao vivo.

Em Teste, insira valores de exemplo para as variáveis dinâmicas. Selecione um perfil de teste em Perfil se a ferramenta usar variáveis de perfil do Klaviyo. Clique em Salvar e executar teste.

Revise Resposta e verifique se:

• A resposta volta com sucesso
• A resposta contém os dados de que sua habilidade precisa
• Casos de erro esperados retornam códigos de status e mensagens úteis

8. Anexe a ferramenta a uma habilidade

1. Acesse Customer Agent > Skills e abra a habilidade em que você quer usar a ferramenta. Se as instruções estiverem como somente leitura, crie uma habilidade totalmente personalizada.
2. Em Como responder, digite / onde a ferramenta deve ser usada e selecione a ferramenta no menu. Explique quando chamá-la, quais valores fornecer e o que fazer com o resultado ou com um erro.
3. Quando as instruções estiverem prontas, clique em Publicar para uma skill de rascunho ou em Atualizar para uma skill ativa.

Escrevendo uma boa descrição da ferramenta

Uma descrição clara ajuda o Customer Agent a decidir quando usar a ferramenta. As instruções da habilidade também orientam qual ferramenta ela chama e como ela usa o resultado. Boas descrições:

• Diga o que a ferramenta faz em uma frase
• Diga quando usá-lo em uma frase
• São específicos sobre os dados retornados ou a ação realizada

As descrições ruins são vagas (“Obtém informações do cliente”), muito amplas (“Trata de qualquer coisa relacionada a pedidos”) ou informam ao Customer Agent como se comportar em vez do que a ferramenta faz.

Considerações de segurança

• Armazene credenciais como segredos. Nunca cole uma chave de API ou token diretamente em um cabeçalho, URL ou corpo. Adicione-a como um segredo e faça referência a ela com uma variável Secret (consulte a Etapa 6).
• Use a lista de permissões de IP sempre que possível. Seu ponto de extremidade ainda precisa ser acessível por meio de um nome de host público; endereços de rede privada e localhost são bloqueados. Use a lista de permissões como uma camada extra de proteção junto com a autenticação.
• Fique atento aos dados que você envia. A configuração da sua solicitação e as origens das variáveis determinam quais valores são enviados ao ponto de extremidade. As instruções de skill orientam os valores que o Customer Agent fornece para variáveis dinâmicas. Revise quais campos seu ponto de extremidade recebe.
• Limites de taxa. Se seu ponto de extremidade tiver limites de taxa, verifique se eles são altos o suficiente para lidar com o volume esperado de conversas.

Solução de problemas

Sintoma: Customer Agent nunca usa a ferramenta.
Causa provável: A descrição é vaga demais ou a ferramenta não está incluída nas instruções publicadas da habilidade.
Correção: Reescreva a descrição para explicar especificamente quando ela deve ser usada. Em Como responder, insira a ferramenta usando / e explique quando chamá-la. Clique em Publicar ou Atualizar para aplicar as instruções.

Sintoma: a ferramenta retorna um erro durante o teste.
Causa provável: URL incorreta, corpo malformado, dados obrigatórios do perfil ausentes ou um payload que seu ponto de extremidade não aceita.
Correção: em Teste, revise Visualização da solicitação e Resposta. Verifique a URL, os headers e o corpo em relação à entrada esperada do seu ponto de extremidade. Se a ferramenta usa variáveis de perfil do Klaviyo, selecione um perfil de teste com os valores obrigatórios.

Sintoma: o Customer Agent usa a ferramenta, mas passa parâmetros incorretos.
Causa provável: uma variável tem a origem errada ou a Propriedade do perfil errada, ou as instruções de skill não deixam claro o que passar.
Correção: verifique os nomes das variáveis, as origens e as Propriedades do perfil selecionadas em Variáveis. Atualize as descrições das variáveis e as instruções de skill para deixar explícito o que deve ser fornecido.

Sintoma: A ferramenta é lenta, causando atrasos nas respostas.
Causa provável: latência do ponto de extremidade.
Corrigir: Otimize seu ponto de extremidade. Verifique se você pode armazenar os resultados em cache do seu lado.

Perguntas frequentes

Uma ferramenta pode ser usada por várias skills?
Sim. Depois de criada, uma ferramenta pode ser usada por várias skills. Insira-a nas instruções editáveis de cada skill e publique ou atualize cada skill.

Quais métodos de autenticação são compatíveis?
Qualquer método que envie uma credencial estática com a solicitação, como um token de portador ou um cabeçalho de chave de API. Armazene a credencial como um segredo e faça referência a ela com uma variável Secret (consulte a etapa 6). Fluxos que precisam buscar ou atualizar um token no momento da solicitação, como OAuth, não são compatíveis em ferramentas totalmente personalizadas.

O que acontece se meu ponto de extremidade estiver fora do ar ou retornar um erro?
A Klaviyo relata falhas de ferramentas ao Customer Agent. Falhas temporárias podem ser repetidas dentro dos limites de tempo limite e de novas tentativas da ferramenta. Nas instruções da habilidade, explique como responder se a ferramenta não conseguir concluir a solicitação, por exemplo, oferecendo transferir para uma pessoa. Use pontos de extremidade confiáveis e monitore o comportamento das ferramentas de perto.

Posso editar uma ferramenta depois de criá-la?
Sim. Abra a ferramenta em Customer Agent > Conectores > Personalizado, edite o nome, a descrição ou a configuração de solicitação e, em seguida, clique em Salvar. Adicione ou remova a ferramenta nas instruções de cada habilidade.

Posso controlar versões de uma ferramenta?
O controle de versões ainda não é compatível. As alterações salvas se aplicam à ferramenta compartilhada usada por todas as habilidades que fazem referência a ela. Salvar e executar teste também salva as alterações. Portanto, verifique quais habilidades ativas usam a ferramenta antes de editá-la.

Recursos adicionais