> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Visão geral de ferramentas > Crie, teste e monitore as ações que seus agentes de IA, campanhas e WhatsApp Flows podem executar. Uma **ferramenta** é uma ação reutilizável que a Connectly pode executar para você, como consultar um pedido, verificar o estoque, criar um ticket ou salvar um registro. Você a cria uma vez na página **Ferramentas** e depois a usa nos seus agentes de IA, campanhas e [WhatsApp Flows dinâmicos](/campaigns/whatsapp-flow-builder). Busque um cliente, pedido ou reserva no seu próprio sistema. Crie um ticket, atualize um registro de CRM ou envie dados para um webhook. Limpe ou combine dados com algumas linhas de JavaScript. Armazene pequenas informações entre execuções no datastore integrado. ## A página Ferramentas Abra **Ferramentas** na barra lateral. A página tem quatro abas: | Aba | O que ela mostra | | - | - | | **Ferramentas** | Todas as ferramentas da sua empresa, com status, taxa de sucesso e as campanhas que as utilizam. | | **Execuções** | Um registro em tempo real de cada execução de ferramenta, com resultado e duração. | | **Ferramentas compartilhadas** | Ferramentas que outra empresa compartilhou com você (somente leitura). | | **Integrações** | Suas integrações conectadas. | A aba **Ferramentas** mostra estas colunas: | Coluna | Significado | | - | - | | **Ferramenta** | Nome e descrição. | | **Status** | `Rascunho` ou `Publicada`. | | **Atividade** | Taxa de sucesso recente, por exemplo `98% de sucesso`. Mostra `Ainda sem execuções` para uma ferramenta nova ou `Dados limitados` quando há poucas execuções. | | **Campanhas** | Quantas campanhas usam a ferramenta. Passe o cursor para ver os nomes. | | **Criada por / Atualizada** | Quem criou a ferramenta e quando ela foi alterada pela última vez. | Use a caixa de pesquisa para encontrar uma ferramenta pelo nome ou pela descrição. Você também pode filtrar por tipo ou campanha. ## Criar uma ferramenta Na aba **Ferramentas**, selecione **Criar ferramenta**. Informe um **Nome** (somente letras, números, sublinhados e hífens, sem espaços), por exemplo, `get_customer_info`. Em seguida, escreva uma **Descrição** que explique o que a ferramenta faz e **quando a IA deve usá-la**. Os agentes de IA leem esse texto para decidir se devem chamar a ferramenta, então uma descrição clara é importante. Selecione **Chamada de API** ou **Script JavaScript** (veja abaixo). Configure a ferramenta, teste e publique. ### Qual tipo devo usar? | | Chamada de API | Script JavaScript | | - | - | - | | **Ideal para** | Chamadas simples a um serviço externo | Lógica personalizada, várias etapas ou transformação de dados | | **Configuração** | Método, URL, cabeçalhos e autenticação | Código no editor integrado | | **Teste** | Execute um teste com dados de entrada de exemplo | Execute um teste com dados de entrada de exemplo e veja os logs | Comece com **Chamada de API** para integrações simples. Use **Script JavaScript** quando precisar de condições, loops, várias solicitações em uma ferramenta ou formatação personalizada. ### Ferramentas de chamada de API Uma ferramenta de API envia uma solicitação HTTP a um serviço quando é executada. * **Método** e **URL do endpoint**: escolha o método HTTP e informe a URL. Use `{parameter}` para valores que mudam a cada chamada, por exemplo, `https://api.example.com/orders/{order_id}`. * **Cabeçalhos**: adicione os cabeçalhos necessários para o serviço. * **Autenticação**: escolha uma credencial salva ou selecione **Novo recurso** para criar uma (veja [Autenticação](#autenticacao)). ### Ferramentas de script JavaScript Uma ferramenta de script executa seu JavaScript sempre que é chamada. Ela recebe os dados de entrada, executa o trabalho e retorna um resultado. O editor permite testar o script em tempo real e conferir a saída e os logs antes da publicação. Se o script importar outra ferramenta, o editor avisará quando ela usar uma **versão antiga**. Atualize a importação, faça o deploy e teste novamente para usar a versão mais recente. ### Esquema de entrada e saída Abra a aba **Esquema** para descrever sua ferramenta com JSON Schema: * **Esquema JSON de entrada**: as informações que a ferramenta espera, por exemplo, uma string `order_id`. * **Esquema JSON de saída**: o formato do resultado retornado. * **Resultado de exemplo**: um exemplo de resultado típico. Um bom esquema ajuda os agentes de IA a preencher os valores corretos e entender o resultado. ## Autenticação As ferramentas de API podem se autenticar no seu serviço. As credenciais são **criptografadas e armazenadas com segurança**. Depois de salvas, elas não voltam a ser exibidas em texto simples. | Tipo | Quando usar | | - | - | | **Sem autenticação** | A API é pública. | | **Cabeçalhos personalizados / chave de API** | O serviço espera uma chave em um cabeçalho, por exemplo, `Authorization` ou `X-API-Key`. | | **Parâmetros de consulta** | O serviço espera uma chave na URL, por exemplo, `?api_key=...`. | | **Credenciais de cliente OAuth 2.0** | O serviço emite tokens de uma URL de token usando um ID e um segredo do cliente. | | **Certificado de cliente (TLS mútuo)** | O serviço exige um certificado de cliente. Forneça a cadeia completa do certificado e a chave privada, ambas no formato PEM. | Para TLS mútuo, a chave privada não pode ser protegida por uma frase secreta. Exporte-a sem frase secreta e tente novamente se ocorrer um erro. As credenciais salvas aparecem na lista **Selecionar recurso de autenticação**, para que você possa reutilizá-las em várias ferramentas. ## Testar sua ferramenta Use o painel **Teste** ao lado do editor. 1. Em **Entrada simulada**, informe o JSON que a ferramenta deve receber, por exemplo, `{ "order_id": "12345" }`. 2. Selecione **Executar teste**. 3. Confira o resultado na aba **Saída** e os detalhes na aba **Logs**. O status será `SUCCESS` ou `ERROR`. Os testes são executados na **última versão salva**, não no texto exibido na tela. Se houver alterações não salvas, a Connectly avisará e oferecerá **Fazer deploy e testar** (scripts) ou **Salvar e testar** (ferramentas de API), que salva uma nova versão primeiro. Escolha **Testar versão salva** para testar a versão anterior. ## Versões, rascunhos e publicação Cada salvamento cria uma nova **versão** da ferramenta, para que você possa ver o que mudou e voltar a uma versão anterior. * Use o **seletor de versões** na parte superior do editor para alternar entre versões. * Ao salvar ou fazer deploy, escolha **Incremento automático** (a Connectly escolhe o próximo número) ou **Versão personalizada** (por exemplo, `2.0.0`). A versão personalizada deve ser maior que a atual. * Uma ferramenta começa como **Rascunho**. Selecione **Publicar** para disponibilizá-la. Você precisa salvar ou fazer deploy das alterações mais recentes antes de publicar. O editor também mostra quem criou a ferramenta e quem editou cada versão pela última vez, o que é útil quando várias pessoas da equipe trabalham na mesma ferramenta. As edições assistidas por IA são identificadas como **Assistente de IA**. ## Monitorar suas ferramentas ### Execuções A aba **Execuções** mostra cada execução, da mais recente para a mais antiga, e é atualizada conforme novas execuções chegam. Para cada uma, você pode ver o horário, a ferramenta, o status, a duração e o código de status. Selecione uma execução para abrir os logs, incluindo a execução, a sessão e a sala relacionadas. Use estes filtros para restringir a lista: * **Ferramenta**: escolha uma ferramenta ou pesquise pelo nome (use `|` para pesquisar várias). * **Status**: `Sucesso` ou `Falha`. * **Período**: de 15 minutos a 15 dias, ou um período personalizado. * **ID da execução, ID da sessão ou ID da sala**: vá diretamente para uma conversa ou execução. Quando um cliente relatar algo estranho em uma conversa, filtre pelo **ID da sala** para ver exatamente quais ferramentas foram executadas e o que retornaram. ### Taxa de sucesso A coluna **Atividade** na aba Ferramentas mostra rapidamente a saúde de cada ferramenta. Uma queda na taxa de sucesso costuma ser o primeiro sinal de que um serviço externo está fora do ar ou que uma credencial expirou. ### Datastore O **Datastore** é um armazenamento durável de chave e valor que suas ferramentas podem ler e gravar durante a execução, por exemplo, para lembrar a última escolha de um cliente. * Navegue e filtre as chaves por prefixo e veja o valor, o tamanho e a última atualização de cada uma. * Adicione, edite ou remova chaves. As alterações entram em vigor imediatamente. * Restaure um estado anterior. Você pode restaurar qualquer momento dentro da janela de retrocesso exibida na página. A Connectly salva primeiro um ponto de restauração do estado atual, então também é possível desfazer uma reversão. Ao restaurar um estado anterior, você descarta **tudo o que foi gravado depois do momento escolhido**, incluindo os dados que suas ferramentas gravaram desde então. ## Compartilhar uma ferramenta Você pode compartilhar uma ferramenta com outra empresa. 1. Abra a ação **Compartilhar** da ferramenta na lista. 2. Informe o ID da outra empresa e selecione **Compartilhar**. 3. Para parar de compartilhar, selecione **Cancelar compartilhamento** ao lado dessa empresa. A outra empresa verá a ferramenta em **Ferramentas compartilhadas**. Ela poderá visualizá-la e testá-la, mas não editá-la. As execuções compartilhadas aparecem como **Compartilhadas** em Execuções. ## Excluir uma ferramenta Selecione **Excluir** na linha da ferramenta. Isso remove a ferramenta **e todas as suas versões**, e não pode ser desfeito. Se houver campanhas usando a ferramenta, a confirmação vai listá-las (por exemplo, "3 campanhas usam esta ferramenta. As etapas de ferramenta delas deixarão de funcionar"). Atualize essas campanhas primeiro. As ferramentas usadas por um WhatsApp Flow são gerenciadas com o fluxo. Elas são excluídas automaticamente quando o fluxo é excluído ou descontinuado. Consulte [WhatsApp Flow Builder](/campaigns/whatsapp-flow-builder). ## Solução de problemas | Sintoma | O que verificar | | - | - | | Não consigo publicar a ferramenta | Salve ou faça deploy das alterações mais recentes, aguarde o carregamento da versão e confira se a descrição foi preenchida. | | O resultado do teste não corresponde às minhas alterações | O teste foi executado na última versão salva. Use **Fazer deploy e testar** ou **Salvar e testar**. | | O nome foi rejeitado | Use somente letras, números, sublinhados e hífens. | | Muitas execuções `Failed` | Abra **Execuções**, filtre por `Failed` e leia os logs. Verifique se as credenciais expiraram ou se a URL está inacessível. | | Erro de certificado em uma credencial de certificado de cliente | Confira se a cadeia e a chave estão no formato PEM e se a chave não tem uma frase secreta. | | O agente de IA nunca chama minha ferramenta | Reescreva a descrição para explicar claramente quando ela deve ser usada e adicione um esquema de entrada. | ## Próximas etapas Crie formulários dentro do WhatsApp e conecte-os a uma ferramenta. Envie um fluxo do seu próprio sistema. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.