Como criar habilidades personalizadas para o agente de IA

Habilidades HTTP permitem que o agente faça chamadas a APIs externas durante uma conversa. Por exemplo: consultar estoque, verificar status de pedido ou registrar dados em um sistema interno.

---

O que são habilidades

São ações que você configura para o agente executar quando precisar de informação externa. Quando identifica a necessidade, o agente dispara a chamada HTTP configurada e usa os dados retornados para responder ao lead.

Criar uma habilidade

1. Acesse Configurações > Base de conhecimento > Habilidades

2. Clique em + Criar habilidade

3. Preencha o Título da habilidade (nome descritivo que será exibido)

4. Selecione HTTP no campo Tipo

5. Configure as abas abaixo

Aba Configuração HTTP

Método HTTP: selecione o método da requisição (GET, POST, PUT, PATCH, DELETE)

URL da API: insira a URL completa do endpoint. Use :variavel para path params dinâmicos (ex: https://api.exemplo.com/v1/users/:userId/orders)

Timeout (ms): tempo máximo de espera pela resposta da API (entre 1.000 e 120.000ms). O padrão é 30.000ms

Headers HTTP: adicione os headers necessários clicando em + Adicionar Header (ex: Authorization, Content-Type)

Query Parameters: adicione parâmetros de URL clicando em + Adicionar Parâmetro. Para cada parâmetro, defina o Nome e a Fonte do valor:

• Valor fixo — texto literal, igual para toda chamada (ex: v2 em api_version)

• Campo inteligente — valor vem de um campo do contexto da conversa (contato, empresa, conversa), escolhido no seletor de campos

• Gerado pela IA — a IA extrai o valor da conversa em tempo real a partir de um prompt que você escreve (ex: “Extraia o CPF informado pelo lead”); há um switch para marcar o campo como obrigatório

Aba Auth & Retry

Autenticação: configure como a habilidade se autenticará na API. Os tipos disponíveis são:

• Bearer Token: insira o token de autenticação

• API Key: insira a chave de API

• HMAC (assinatura): a Nuvia assina cada requisição com um segredo compartilhado (ver abaixo)

Autenticação HMAC (assinatura por requisição)

Algumas APIs não aceitam um token fixo: elas exigem que cada requisição seja assinada com um segredo, para provar que a chamada é legítima e não foi reaproveitada. É o padrão usado por gateways de pagamento, bancos e várias APIs brasileiras feitas em Laravel.

Escolha HMAC (assinatura) no tipo de autenticação e preencha os campos conforme a documentação da API que você vai chamar.

Montando o template da string assinada. Use os marcadores abaixo, separando as linhas com \n:

{method} · {path} · {path_with_query} · {path_relative} · {query} · {url} · {host} · {body} · {body_sha256_hex} · {timestamp} · {api_key}

O botão Usar formato comum preenche o template com {method}\n{path_with_query}\n{timestamp}\n{body} e ajusta o formato do timestamp para ISO 8601 microssegundos — o arranjo mais frequente. Se a API que você usa pede outra ordem, edite à mão.

Onde a assinatura é enviada. Por padrão a Nuvia envia três cabeçalhos separados, cujos nomes você pode trocar:

Header único (opcional). Algumas APIs pedem tudo empacotado em um cabeçalho só. Preencha Nome do header único (ex.: X-Auth) e Template do valor do header (ex.: hmac {api_key}:{timestamp}:{signature}), usando os marcadores {api_key}, {timestamp} e {signature}.

Quando você preenche o template do header único, os campos de nome do header de API Key e de assinatura somem da tela, eles deixam de ser usados. O cabeçalho de timestamp continua sendo enviado à parte.

Retry (Tentativas): define o comportamento em caso de falha na chamada:

• Max Tentativas: número máximo de tentativas (1 a 10)

• Delay (ms): intervalo inicial entre tentativas

• Multiplicador: fator de backoff exponencial entre as tentativas

Aba Parâmetros

Define os parâmetros que o agente extrai da conversa para usar na chamada. Configure usando o Parameters Schema (JSON Schema):

• Nome do campo: identificador do parâmetro

• Tipo: tipo do dado (Texto, Número, etc.)

• Descrição: instrução para o agente sobre como extrair esse valor da conversa

Clique em + Adicionar propriedade para incluir novos parâmetros. Para configurações avançadas, alterne para a aba Avançado e edite o JSON Schema diretamente.

Quando o valor estiver vazio

Para cada parâmetro você define o que a Nuvia envia ao webhook quando o agente não consegue preencher aquele campo na conversa:

• Não enviar o campo (padrão) — a chave é omitida do corpo da requisição (mesmo comportamento de antes)

• Enviar vazio (“”) — envia o campo com texto vazio

• Enviar null — envia o campo com o valor null

Essa opção fica disponível para campos de primeiro nível. Use-a quando a API do outro lado espera receber a chave sempre presente (mesmo sem valor) em vez de simplesmente ausente.

Aba Resposta

Configure como a resposta da API será interpretada pelo agente através do Response Mapping (opcional). Quando habilitado, permite mapear campos específicos do retorno da API para uso na conversa.

Aba Testar Requisição

Use a aba Testar Requisição para disparar a chamada HTTP isoladamente e ver a resposta sem precisar rodar uma conversa inteira com o agente. Serve para validar endpoint, autenticação e payload antes de colocar a habilidade em produção. A aba aparece tanto na criação quanto na edição de habilidades HTTP.

Como testar:

1. Abra a aba Testar Requisição

2. No campo Parâmetros (JSON), ajuste os valores de teste. O campo já vem pré-preenchido com os parâmetros declarados na aba Parâmetros — o valor de cada um traz a descrição do parâmetro como exemplo, para você substituir por um valor real

3. Clique em Testar Requisição

O que o resultado mostra:

• Status da resposta (verde para sucesso, vermelho para erro) e Tempo de resposta em milissegundos

• URL chamada, Headers enviados e Body enviado — exatamente o que foi disparado. Por segurança, o token de autenticação é ocultado no retorno

• Response Body (cru): o que a API devolveu

• Response Body (mapeado): o resultado depois do Response Mapping configurado na aba Resposta

• Histórico dos últimos testes: guarda as últimas execuções (até 10) para você comparar resultados; clique em qualquer uma para revê-la

Avisos que ajudam a configurar:

• Se você digitar um campo que não está declarado na aba Parâmetros, a Nuvia avisa que ele será ignorado no teste — o mesmo filtro que o agente real aplica (só envia o que está no schema)

• Se nenhum parâmetro estiver declarado na aba Parâmetros, o teste envia o body vazio e exibe um aviso pedindo que você declare os parâmetros lá

Casos de uso

• Consultar estoque de produto

• Verificar status de pedido

• Agendar visita técnica

• Calcular frete

• Registrar lead no CRM externo