AI Tools permite definir conexões de API externas que o seu assistente de IA (prompts Specialist) pode chamar durante as conversas. Em vez de codificar as chamadas de API diretamente no seu fluxo, a IA decide quando e como usar cada ferramenta com base no contexto da conversa.

Acesse Integrate > AI Tools para usar o recurso.

📘 Recurso em beta O AI Tools está atualmente em beta. Está disponível para bots com o AI Specialist habilitado.

Visão geral

A página AI Tools lista todas as suas definições de ferramentas. As ferramentas são organizadas em duas abas:

• Tools: ferramentas do tipo API que chamam endpoints externos

• Auth Tokens: tokens de autenticação HTTP usados pelas suas ferramentas de API

Você pode buscar ferramentas por nome e ordená-las por nome, tipo, descrição, data da última atualização ou autor.

Cada ferramenta exibe seu método HTTP como uma tag (GET, POST, PUT, DELETE).

Criar uma ferramenta

Clique em Add a New Tool para abrir o assistente de criação. O assistente guia você por quatro etapas.

Etapa 1 — About

Forneça os dados básicos que ajudam a IA a entender quando e por que usar esta ferramenta.

• Tool Name: use uma frase verbo-substantivo (por exemplo, "Check Flight Status", "Get Order Details")

• Description: descreva o problema específico que esta ferramenta resolve

📘 Como a IA usa essa informação Diferente do software tradicional, o Name e a Description não são apenas rótulos — são instruções. A IA os lê para decidir se e quando usar esta ferramenta durante uma conversa.

Etapa 2 — API Connection

Configure como a ferramenta chama sua API externa.

Collect data inputs

Defina os parâmetros que sua ferramenta espera da conversa. Para cada parâmetro, especifique:

• Name: o nome da variável (por exemplo, order_id, flight_number)

• Format: Text, Number, Integer, Boolean, Enum, Array ou Object

• Required or Optional: os parâmetros obrigatórios usam a sintaxe ${variable}, os opcionais usam ?{variable}

• Description: ajuda a IA a entender quais dados coletar do usuário

HTTP Method

Selecione o método para a sua requisição de API: GET, POST, PUT ou DELETE.

URL

Insira a URL do endpoint. Você pode inserir seus data inputs e as variáveis do seu bot usando o seletor de variáveis (ícone de colchetes). As variáveis aparecem como badges no campo URL.

Example: https://api.example.com/orders/${order_id}

Headers

Adicione headers à sua requisição. Dois tipos estão disponíveis:

• Key-value pair: header padrão (por exemplo, Content-Type: application/json)

• HTTP Authentication token: referencia um token de autenticação pré-configurado (veja Auth Tokens abaixo)

Body

Para requisições POST/PUT, forneça o body da requisição em JSON. Você também pode inserir variáveis no body. Você pode digitar o body ou colá-lo: o conteúdo colado entra do jeito que está e as variáveis que ele contém aparecem como badges.

Platform variables

Além dos data inputs que a IA coleta, uma ferramenta pode enviar as próprias variáveis do seu bot para a sua API. Abra o seletor de variáveis (ícone de colchetes) na URL, em um header ou no body. A lista tem dois grupos:

• Data inputs: os valores que a IA coleta da conversa. Usam a sintaxe ${variable} ou ?{variable}.

• Platform variables: as variáveis custom, de user channel e de system do seu bot. Usam a sintaxe #{variable}.

Quando a ferramenta é executada, cada platform variable é substituída pelo seu valor na conversa atual. A IA não escolhe nem altera esses valores. Use-as para dados que precisam chegar à sua API exatamente como estão, por exemplo:

• um customer ID enviado pelo seu site quando o visitante está logado (variável de user channel)

• o idioma da conversa (variável de system)

• um customer tier definido antes no fluxo por uma etapa Data Manipulation (variável custom)

Cada variável aparece como um badge, com uma cor por categoria. As variáveis não podem ser digitadas manualmente: selecione-as na lista, ou cole um body que as contenha: elas também aparecem como badges. Uma variável que não existe mais é sinalizada no campo, e a ferramenta recebe um valor vazio em seu lugar.

As platform variables também estão disponíveis na URL, nos headers e no body dos seus Auth Tokens.

📘 Veja os valores no Trace No Trace de uma conversa, cada chamada de ferramenta lista os valores que recebeu: os data inputs preenchidos pela IA e as platform variables resolvidas pela plataforma. Veja Trace no Flow Builder.

Etapa 3 — Test Response

Antes de publicá-la, teste sua ferramenta com o endpoint real da API.

1. Insira um valor de teste para cada data input e cada platform variable que a ferramenta usa

2. Clique em Test request para executar a chamada

3. Revise a resposta JSON bruta para verificar se está correta

Se o teste for bem-sucedido, você verá um banner verde "Successful response received (200 OK)" com o body completo da resposta.

Você pode pular esta etapa, mas o teste é altamente recomendado para:

• Verificar se a conexão funciona corretamente

• Filtrar dados sensíveis da resposta

• Mapear os resultados da API para variáveis do ViaSay para uso no seu fluxo

⚠️ Pular o teste Pular esta etapa pode limitar sua capacidade de verificar a conexão, filtrar dados sensíveis da resposta e mapear os resultados da API para variáveis do ViaSay.

Etapa 4 — Data Access

Controle a quais campos da resposta da API a IA pode acessar.

• Full data access: a IA vê a resposta JSON completa

• Manually restrict access: selecione campos específicos para excluir da resposta que a IA vê

Isso é útil para evitar que a IA acesse dados sensíveis (por exemplo, IDs internos, tokens ou informações privadas de clientes).

Auth Tokens

Para APIs que exigem autenticação, você pode configurar tokens de autenticação HTTP.

Acesse a aba Auth Tokens na página AI Tools, ou adicione um diretamente a partir da etapa API Connection em Add a header > HTTP Authentication token.

Configure o seguinte:

• Token title: um nome para identificar este token (por exemplo, "Booking API Auth")

• Description: descrição opcional

• HTTP Method / URL / Headers / Body: o endpoint de autenticação a ser chamado

• Token configuration:

  • Access Token Field: o campo da resposta que contém o token (por exemplo, access_token)

  • Header Token Key: a chave de header em que o token é enviado (por exemplo, Authorization)

  • Token Type: o prefixo do valor do token (por exemplo, Bearer)

Clique em Test request para verificar se o endpoint do token funciona, depois em Save token.

Depois de salvo, o token pode ser referenciado na seção Headers de qualquer ferramenta. A plataforma chama automaticamente o endpoint do token e injeta o token nas suas requisições de API.

Conectar ferramentas a uma Gen AI Step

Depois que suas ferramentas forem criadas, você pode anexá-las a qualquer Gen AI Step no Flow Builder.

1. Abra uma etapa Gen AI no Flow Builder

2. Abra Create or Edit a prompt

3. Abra Advanced Settings

4. Ative Tools

5. Selecione ferramentas no dropdown — as ferramentas do tipo Token são excluídas automaticamente

Clique em uma ferramenta anexada para abrir seu detail panel, onde você pode:

• Ver a descrição e os parâmetros da ferramenta

• Ir para a página de definição da ferramenta em Edit tool

• Abrir o modal Test tool para testar com valores de exemplo

• Configurar os mapeamentos de Save output para extrair dados da resposta da ferramenta para variáveis da conversa

Output mapping

Na seção Save output, mapeie campos da resposta JSON da ferramenta para variáveis da conversa:

1. Clique em + Add para criar um novo mapeamento

2. Selecione ou crie uma variável de conversa

3. Insira uma consulta JMESPath para extrair o campo desejado da resposta

Exemplo: para extrair o status do voo de {"status": "On Time", "gate": "B42"}, use a consulta JMESPath status.

Editar e excluir ferramentas

Editar uma ferramenta

Na lista de AI Tools, clique no menu de ações (⋮) de qualquer ferramenta e selecione Edit. Isso abre o assistente com a configuração existente da ferramenta pré-preenchida.

Você também pode acessar a página de edição diretamente a partir do detail panel do Flow Builder pelo link Edit tool.

⚠️ Editar uma ferramenta afeta todos os prompts Ao editar uma ferramenta existente, as alterações se aplicam a todos os prompts em que essa ferramenta está anexada.

Excluir uma ferramenta

No menu de ações, selecione Delete. Uma caixa de diálogo de confirmação aparecerá. Essa ação não pode ser desfeita.