Como criar uma ferramenta (Beta)

Recurso beta. A criação de ferramentas totalmente personalizadas do zero está em versão beta aberta e disponível para todas as contas do Customer Agent — não é necessário se inscrever. Você encontrará a página Ferramentas no Customer Agent. O recurso ainda está sendo expandido e pode mudar.

O que você vai aprender

Como conectar o Customer Agent a qualquer ponto de extremidade HTTP usando uma ferramenta totalmente personalizada, escreva uma descrição da ferramenta que o Customer Agent realmente usará e teste sua ferramenta antes de anexá-la a uma habilidade.

Antes de começar

Você precisará de:

• Customer Agent habilitado
• Um ponto de extremidade HTTP que você deseja que o Customer Agent chame — um que não exija credenciais secretas (chaves de API, tokens de portador etc.) para acessar hoje (pontos de extremidade autenticados em breve, consulte o aviso abaixo)
• Uma habilidade para anexar a ferramenta — uma habilidade que o Customer Agent traz consigo ou uma habilidade totalmente personalizada que você criou

Se você ainda não configurou uma habilidade, crie uma primeiro. As ferramentas não fazem nada por conta própria — elas precisam ser apegadas a uma habilidade.

Alerta: armazenamento seguro para chaves de API e outros segredos estará disponível em breve. Até que ele seja enviado, não coloque chaves de API, tokens ao portador ou outras credenciais confidenciais em ferramentas totalmente personalizadas. A configuração da ferramenta ainda não é um local seguro para armazená-las. Por enquanto, use apenas ferramentas com pontos de extremidade seguros para chamadas sem autenticação secreta (por exemplo, pontos de extremidade internos atrás da lista de permissões de IP ou pontos de extremidade que aceitam identificadores não confidenciais). O suporte para pontos de extremidade autenticados está a caminho.

O que é uma ferramenta totalmente personalizada

Uma ferramenta totalmente personalizada é uma solicitação HTTP que o Customer Agent pode fazer durante uma conversa. A criação de ferramentas totalmente personalizadas está em versão beta aberta e disponível para todas as contas do Customer Agent. Use uma quando as ferramentas que o Customer Agent usa não cobrirem o que você precisa, por exemplo, pesquisar um pedido no seu próprio sistema de gerenciamento de pedidos em vez da Shopify, verificar o estoque em um sistema de warehouse personalizado ou criar um tíquete em um helpdesk com o qual a Klaviyo não faz integração nativa.

Para entender o conceito subjacente, consulte o artigo Como funcionam as ferramentas do Customer Agent.

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

Navegue até Customer Agent > Tools e clique em Create tool.

2. Nomeie e descreva a ferramenta

• Nome — Um identificador curto como "Obter inventário" 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 — GET, POST, PUT, DELETE ou PATCH.
• URL — URL completo do ponto de extremidade. Você pode incluir espaços reservados 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.

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

Forneça um corpo JSON. Use espaços reservados para valores que o Customer Agent deve preencher em tempo de execução.

Exemplo de corpo:

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

5. Use espaços reservados para valores dinâmicos

O Customer Agent pode preencher valores em tempo de execução usando espaços reservados. Espaços reservados comuns:

• {{profile_id}} — O ID do perfil do Klaviyo do cliente na conversa
• {{conversation_id}} — O ID da conversa atual
• Qualquer parâmetro que você definir no seu esquema de entrada (por exemplo, {{product_sku}}, {{order_id}})

Os espaços reservados funcionam no URL, cabeçalhos e corpo.

6. Autenticação

O suporte para pontos de extremidade autenticados está chegando. Até lá, não coloque chaves de API, tokens ao portador ou outros segredos em uma ferramenta totalmente personalizada. Use apenas pontos de extremidade seguros para chamadas sem credenciais secretas, por exemplo, pontos de extremidade internos protegidos por lista de permissões de IP ou pontos de extremidade públicos que aceitam identificadores não confidenciais.

O armazenamento secreto seguro está a caminho e desbloqueará os pontos de extremidade autenticados.

7. Teste a ferramenta

Clique em Ferramenta de teste. Forneça valores de amostra para qualquer parâmetro de entrada. Verifique se:

• A resposta volta com sucesso
• O formato de resposta é o que o Customer Agent espera
• Todos os casos de erro são tratados

8. Salve e anexe a uma habilidade

Clique em Save. Para que o Customer Agent realmente use a ferramenta, abra a habilidade que deseja usar e adicione a ferramenta.

Escrevendo uma boa descrição da ferramenta

A descrição é o campo mais importante. O Customer Agent escolhe qual ferramenta usar com base inteiramente na descrição, não no nome. 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

• Não use ferramentas totalmente personalizadas para pontos de extremidade que ainda exigem credenciais secretas. O suporte para pontos de extremidade autenticados está chegando. Até o envio, use apenas pontos de extremidade seguros para chamadas sem autenticação secreta.
• Use a lista de permissões de IP sempre que possível. Se seu ponto de extremidade for interno, restrinja o acesso aos intervalos de IP da Klaviyo em vez de depender de segredos.
• Esteja ciente de quais dados você envia. O Customer Agent transmite dados do cliente para a ferramenta com base no que as instruções de habilidade dizem a ele. Revise os campos que 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: o Customer Agent nunca usa a ferramenta.
Causa provável: a descrição é muito vaga ou a ferramenta não está ligada à habilidade que a usaria.
Correção: Reescreva a descrição para descrever especificamente quando ela deve ser usada. Confirme se a ferramenta aparece na lista de ferramentas da habilidade.

Sintoma: a ferramenta retorna um erro durante o teste.
Causa provável: URL incorreta, corpo com formato incorreto ou payload que seu ponto de extremidade não aceita.
Corrigir: Use o recurso da ferramenta Teste para verificar a solicitação e a resposta brutas. Verifique o URL e o formato do corpo em relação à entrada esperada do ponto de extremidade.

Sintoma: o Customer Agent usa a ferramenta, mas passa por parâmetros errados.
Causa provável: os nomes dos placeholders não correspondem ao esquema, ou as instruções de habilidade não são claras sobre o que passar.
Correção: verifique se os nomes dos espaços reservados correspondem exatamente. Atualize as instruções de habilidade para ser explícito sobre quando usar a ferramenta e quais parâmetros fornecer.

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 habilidades?
Sim. Uma vez criada, uma ferramenta pode ser anexada a qualquer número de habilidades.

Quais métodos de autenticação são compatíveis?
O suporte para pontos de extremidade autenticados está chegando. Por enquanto, use pontos de extremidade que não exigem credenciais secretas (pontos de extremidade internos com lista de permissões de IP ou pontos de extremidade públicos com identificadores não confidenciais).

O que acontece se meu ponto de extremidade estiver inativo ou retornar um erro?
O tratamento de erros para ferramentas totalmente personalizadas ainda não foi criado. Se seu ponto de extremidade falhar, o Customer Agent poderá produzir uma resposta degradada ou confusa. Até que o erro seja enviado, use apenas os pontos de extremidade nos quais você tem confiança e monitore o comportamento da ferramenta de perto.

Posso editar uma ferramenta depois de criá-la?
Sim. Você pode editar o nome, a descrição, a configuração e as habilidades anexadas a qualquer momento.

Posso fazer a versão de uma ferramenta?
O controle de versão ainda não é compatível. As edições em uma ferramenta entram em vigor imediatamente em todas as habilidades que a usam.

Additional resources