1. [Ajuda](https://nuvia.ai/docs) 2. [Pipeline e Funis Inteligentes (Agentes de IA)](https://nuvia.ai/docs/colecoes/19377999-pipeline-e-funis-inteligentes-agentes-de-ia) 3. [Funis Inteligentes](https://nuvia.ai/docs/colecoes/19431085-funis-inteligentes) # Como criar habilidades personalizadas para o agente de IA Como criar e configurar ferramentas HTTP (Custom HTTP) que permitem ao agente de IA chamar APIs externas durante conversas. Disponível em todos os planos. Quem pode fazer administradores Atualizado em 9 de setembro de 2026 [Funis Inteligentes](https://nuvia.ai/docs/colecoes/19431085-funis-inteligentes) 1. [Como configurar um Funil Inteligente na Nuvia](https://nuvia.ai/docs/artigos/14570332-como-configurar-um-funil-inteligente-na-nuvia) 2. [Como criar habilidades personalizadas para o agente de IA](https://nuvia.ai/docs/artigos/14590394-como-criar-habilidades-personalizadas-para-o-agente-de-ia) 3. [Como escrever o objetivo, o conhecimento e os pilares de comunicação do agente](https://nuvia.ai/docs/artigos/16515436-como-escrever-o-objetivo-o-conhecimento-e-os-pilares-de-comunicacao-do-agente) 4. [Como escrever as instruções de uma etapa](https://nuvia.ai/docs/artigos/16515466-como-escrever-as-instrucoes-de-uma-etapa) 5. [Etapas padrão de um funil de vendas: como desenhar o fluxo do agente](https://nuvia.ai/docs/artigos/16515486-etapas-padrao-de-um-funil-de-vendas-como-desenhar-o-fluxo-do-agente) 6. [Como arquivar um Funil Inteligente transferindo as conversas](https://nuvia.ai/docs/artigos/16624949-como-arquivar-um-funil-inteligente-transferindo-as-conversas) 7. [Como funciona a reabertura de conversa recente no Funil Inteligente](https://nuvia.ai/docs/artigos/16644378-como-funciona-a-reabertura-de-conversa-recente-no-funil-inteligente) 8. [Como alimentar a Central de Conhecimento](https://nuvia.ai/docs/artigos/14579639-como-alimentar-a-central-de-conhecimento) 9. [Como configurar e usar Follow-ups Inteligentes na Nuvia](https://nuvia.ai/docs/artigos/14580483-como-configurar-e-usar-follow-ups-inteligentes-na-nuvia) Nesta página 1. O que são habilidades 2. Criar uma habilidade 3. Aba Configuração HTTP 4. Aba Auth & Retry 5. Aba Parâmetros 6. Aba Resposta 7. Aba Testar Requisição 8. Casos de uso **Nesta página8 seções** 1. O que são habilidades 2. Criar uma habilidade 3. Aba Configuração HTTP 4. Aba Auth & Retry 5. Aba Parâmetros 6. Aba Resposta 7. Aba Testar Requisição 8. Casos de uso 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. Campo Para que serve **API Key** Identificador público, enviado junto da assinatura. Obrigatório **Secret** O segredo usado para assinar. Obrigatório. O campo é mascarado na tela, como um campo de senha **Template da string assinada** Define exatamente qual texto é assinado. Obrigatório — cada API monta o seu de um jeito **Prefixo removido do path assinado** Opcional. Usado pelo {path_relative}. A barra final decide se sobra barra: /api/ gera customers, /api gera /customers. Em branco = path completo **Formato do timestamp** ISO 8601 microssegundos (Laravel/Carbon) · ISO 8601 milissegundos · Unix (segundos) · Unix (milissegundos). Padrão: ISO 8601 microssegundos **Algoritmo** HMAC-SHA256 (padrão) ou HMAC-SHA512 **Codificação da assinatura** Hexadecimal (padrão) ou Base64 **Prefixo da assinatura** Opcional. Texto colado antes da assinatura, ex.: sha256= **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. ⚠️ Marcador digitado errado não passa. Se você escrever algo como {pathwithquery}, a Nuvia recusa o salvamento e diz qual marcador é inválido, junto da lista dos aceitos. Isso é proposital: um marcador errado que passasse viraria um erro 401 sem explicação no meio de uma conversa real. Onde a assinatura é enviada. Por padrão a Nuvia envia três cabeçalhos separados, cujos nomes você pode trocar: Cabeçalho Nome padrão API Key X-API-Key Timestamp X-Timestamp Assinatura X-Signature **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. 💡 Deu 401 mesmo com tudo aparentemente certo? O suspeito número um é o formato do timestamp, ele precisa bater exatamente com o que a API do outro lado espera. Confira também se o Prefixo removido do path assinado corresponde ao que a documentação da API descreve. Use a aba Testar Requisição para validar antes de colocar a habilidade em produção. **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** 💡 Bom saber: ao testar, as alterações da habilidade são salvas automaticamente (criando ou atualizando) e a requisição roda no backend, simulando o cenário real. Você não precisa salvar manualmente antes. **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 ## Perguntas frequentes **Preciso rodar uma conversa para testar a habilidade?** Não. A aba **Testar Requisição** dispara a chamada isoladamente e mostra a resposta na hora, sem iniciar uma conversa com o agente. **O teste usa a versão que está na tela ou a salva?** Ao clicar em testar, a Nuvia salva a habilidade automaticamente (criando ou atualizando) e roda a requisição contra essa versão salva, então o teste sempre reflete o que você acabou de configurar. **O token de autenticação aparece no resultado do teste?** Não. Os headers de autenticação são ocultados no retorno do teste. **Consigo ver o Secret do HMAC depois de salvar?** O campo é mascarado na tela, como um campo de senha. A ocultação no resultado do **Testar Requisição** vale para os cabeçalhos de autenticação daquele teste, ela não impede que alguém com acesso à tela de habilidades recupere o segredo configurado. Trate o Secret como uma credencial da empresa e limite quem tem acesso à área de Habilidades. **O teste repete a chamada em caso de falha, como o Retry?** Não. O teste executa uma única chamada (sem retry), para você ver exatamente o que acontece em uma tentativa. O Retry continua valendo na execução real pelo agente. **O agente decide sozinho quando usar a habilidade?** Sim, com base na descrição e no contexto da conversa. **O que acontece se o agente não preencher um parâmetro?** Depende da opção **Quando o valor estiver vazio** daquele parâmetro: por padrão a Nuvia **omite** a chave; você pode escolher enviar vazio (“”) ou **null**, conforme o que a API externa espera. A configuração vale para campos de primeiro nível. **O que acontece se a API retornar erro?** O agente adapta a resposta e informa ao contato. No teste, o erro aparece com o status e a mensagem retornados pela API (ou “Erro de rede” quando a chamada nem chega a completar). [AnteriorComo configurar um Funil Inteligente na Nuvia](https://nuvia.ai/docs/artigos/14570332-como-configurar-um-funil-inteligente-na-nuvia) [PróximoComo escrever o objetivo, o conhecimento e os pilares de comunicação do agente](https://nuvia.ai/docs/artigos/16515436-como-escrever-o-objetivo-o-conhecimento-e-os-pilares-de-comunicacao-do-agente) Este artigo ajudou? ## Artigos relacionados - [Como gerenciar API Keys na Nuvia](https://nuvia.ai/docs/artigos/15230128-como-gerenciar-api-keys-na-nuvia) - [Como criar e editar Funis Inteligentes pelo MCP (Agent Builder)](https://nuvia.ai/docs/artigos/16074655-como-criar-e-editar-funis-inteligentes-pelo-mcp-agent-builder) [Funis Inteligentes](https://nuvia.ai/docs/colecoes/19431085-funis-inteligentes) 1. [Como configurar um Funil Inteligente na Nuvia](https://nuvia.ai/docs/artigos/14570332-como-configurar-um-funil-inteligente-na-nuvia) 2. [Como criar habilidades personalizadas para o agente de IA](https://nuvia.ai/docs/artigos/14590394-como-criar-habilidades-personalizadas-para-o-agente-de-ia) 3. [Como escrever o objetivo, o conhecimento e os pilares de comunicação do agente](https://nuvia.ai/docs/artigos/16515436-como-escrever-o-objetivo-o-conhecimento-e-os-pilares-de-comunicacao-do-agente) 4. [Como escrever as instruções de uma etapa](https://nuvia.ai/docs/artigos/16515466-como-escrever-as-instrucoes-de-uma-etapa) 5. [Etapas padrão de um funil de vendas: como desenhar o fluxo do agente](https://nuvia.ai/docs/artigos/16515486-etapas-padrao-de-um-funil-de-vendas-como-desenhar-o-fluxo-do-agente) 6. [Como arquivar um Funil Inteligente transferindo as conversas](https://nuvia.ai/docs/artigos/16624949-como-arquivar-um-funil-inteligente-transferindo-as-conversas) 7. [Como funciona a reabertura de conversa recente no Funil Inteligente](https://nuvia.ai/docs/artigos/16644378-como-funciona-a-reabertura-de-conversa-recente-no-funil-inteligente) 8. [Como alimentar a Central de Conhecimento](https://nuvia.ai/docs/artigos/14579639-como-alimentar-a-central-de-conhecimento) 9. [Como configurar e usar Follow-ups Inteligentes na Nuvia](https://nuvia.ai/docs/artigos/14580483-como-configurar-e-usar-follow-ups-inteligentes-na-nuvia) ## Ainda precisa de ajuda? Clientes falam com o suporte pelo chat dentro da plataforma. Ainda não é cliente? Fale com o nosso time. [Falar com o suporte na plataforma](https://app.nuvia.ai) [Ainda não sou cliente](https://nuvia.ai/contact) --- Source: https://nuvia.ai/docs/artigos/14590394-como-criar-habilidades-personalizadas-para-o-agente-de-ia