Custom Tools

Casos de Uso

Configuração

Campos

• Nome — um identificador para a função (letras, números, sublinhados), por exemplo, get_order_status. A IA vê este nome.
• Descrição — o campo mais importante. Diz à IA quando chamar a ferramenta. Seja explícito: “Chame isto sempre que o cliente mencionar um número de pedido. Não peça verificação.”
• URL do endpoint — a URL HTTPS pública que a Asyntai irá chamar.
• Método HTTP — GET (somente leitura, recomendado) ou POST (pode alterar dados — veja Segurança abaixo).
• Parâmetros — as entradas que a IA extrai da conversa e envia. Cada uma tem um nome, tipo, descrição e indicador de obrigatoriedade. Para GET são enviados como parâmetros de query string; para POST como um corpo JSON.
• Cabeçalho de autenticação (opcional) — um nome de cabeçalho + valor enviado em cada chamada, por exemplo, X-API-Key. Use isto se o seu endpoint exigir uma chave.

Exemplo prático: consulta de estado do pedido

Suponha que a sua loja exponha este endpoint:

GET https://yourstore.com/api/order-status?order_number=10294

…que retorna JSON como:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

Você configuraria uma ferramenta assim:

• Nome: get_order_status
• Descrição: “Consulte o estado de um pedido de um cliente. Chame isto imediatamente sempre que o cliente fornecer um número de pedido — não peça verificação adicional. Use o customer_message retornado na sua resposta.”
• URL do endpoint: https://yourstore.com/api/order-status
• Método: GET
• Parâmetro: order_number (string, obrigatório) — “O número do pedido do cliente, normalmente com mais de 8 dígitos.”

Quando um cliente escreve “Como está o meu pedido #10294?”, a IA chama get_order_status(order_number=10294), a Asyntai solicita a sua URL com ?order_number=10294 e a IA responde usando a resposta.

O que o seu endpoint recebe e deve retornar

• Solicitação: um GET com os seus parâmetros na query string, ou um POST com um corpo JSON. Qualquer cabeçalho de autenticação que você configurou é incluído.
• Resposta: retorne JSON (preferido) ou texto simples. A Asyntai devolve o corpo à IA. Um campo que a IA pode citar diretamente — como customer_message — funciona bem.
• Não encontrado / erros: retorne um payload claro (por exemplo, um objeto JSON com found: false e um customer_message) para que a IA possa responder com veracidade em vez de adivinhar.

Testar a sua ferramenta

Cada ferramenta tem um painel integrado Testar esta ferramenta na página de configuração, para que você possa verificar se funciona antes de qualquer cliente a usar — e sem enviar uma mensagem através do bot.

1. Insira valores de exemplo para os parâmetros da ferramenta (por exemplo, um número de pedido real).
2. Clique em Executar teste. A Asyntai chama o seu endpoint exatamente como a IA faria — mesma query string ou corpo JSON, mesmo cabeçalho de autenticação, mesmo timeout de 5 segundos e mesmas verificações de segurança.
3. Você verá o resultado instantaneamente: um selo de sucesso/falha, o estado HTTP, o tempo de resposta, a URL exata que chamamos e a resposta bruta do seu endpoint (formatada de forma legível se for JSON).

Isto também funciona em edições não salvas, para que você possa ajustar a URL, os parâmetros ou o cabeçalho de autenticação e testar novamente até que retorne o que você espera.

Segurança — leia isto

• Prefira GET / somente leitura. As consultas (estado do pedido, estoque, rastreamento) são seguras para expor. GET é o padrão por este motivo.
• POST requer confirmação. Como o POST pode alterar dados, uma ferramenta POST só pode ser salva depois de você marcar uma caixa de seleção confirmando que é o único responsável por proteger e autorizar as solicitações no seu próprio endpoint. Nunca conecte reembolsos, cancelamentos, alterações de senha ou movimentação de dinheiro a menos que o seu endpoint verifique a solicitação de forma independente.
• Proteja-se contra a enumeração. Se uma chave de consulta for adivinhável (como números de pedido sequenciais), exija um segundo fator — por exemplo, o número do pedido e o e-mail associado ao pedido, e verifique se correspondem — para que um visitante não possa ler os dados de outros clientes tentando números.
• Nunca confie nos argumentos da IA. Valide e autorize cada solicitação no lado do servidor como se viesse de um atacante anónimo — porque, na prática, pode vir.

Verificar chamadas ao vivo

Assim que a sua ferramenta estiver ativa, cada invocação real de uma conversa é registrada. Para cada chamada, registramos o nome da ferramenta, os argumentos que a IA enviou, a URL exata que solicitamos, o estado HTTP, a resposta e a duração. Isto permite que você confirme que uma ferramenta foi acionada num chat real e veja o que o seu endpoint retornou, sem vasculhar os logs do seu próprio servidor. (O painel Testar esta ferramenta acima serve para você mesmo verificar a configuração; este registro captura o que acontece durante as conversas reais com os clientes.)

Limites & salvaguardas

• Até 10 ferramentas por site.
• Timeout de 5 segundos por chamada; as respostas são limitadas a 10 KB.
• Os endpoints devem ser URLs http(s) públicos. Endereços privados, de loopback e de rede interna são bloqueados.
• Disponível nos planos Standard e Pro.
• Faturação: cada chamada de ferramenta conta como uma mensagem adicional do seu plano. Uma resposta normal usa 1 mensagem; uma resposta em que a IA chama uma ferramenta usa 2 (a resposta mais a chamada de ferramenta), porque uma chamada de ferramenta requer um pedido de IA adicional.
• Se uma chamada de ferramenta falhar (timeout, erro, bloqueio), a IA é informada e responde de forma elegante — não fará a conversa travar.