Tool

O módulo Tool define uma ferramenta — uma função com nome, descrição e parâmetros — que pode ser chamada por uma inteligência artificial para executar uma ação específica, como consultar uma informação ou realizar uma tarefa. Essa ferramenta pode ser usada por um módulo Agente IA dentro do próprio Hyperflow, ou disponibilizada para sistemas de IA externos através de um Servidor MCP.

A lógica real da ferramenta é construída com os módulos que você conecta depois do módulo Tool no fluxo — o Tool é apenas o ponto de entrada.

🧭 Como acessar

1

No menu lateral, clique em Gerenciamento de aplicativos.

2

Em seguida, clique em Fluxos.

3

Abra ou crie um fluxo e acesse a área de trabalho do fluxo.

4

No painel de módulos, localize a categoria Integração (identificada pela cor azul).

5

Arraste o módulo Tool para a área de trabalho do fluxo.

Imagem 1 - Novo módulo inserido na plataforma.

🔍 Conhecendo o módulo

Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela.

1️⃣ Nome da Ferramenta

Campo: Nome da ferramenta

🎯 Propósito

É o identificador único que o modelo de IA utiliza para “chamar” a função externa. Esse nome deve ser inequívoco e fácil de interpretar pelo modelo.

📐 Regras de nomenclatura (padrão snake_case)

• Utilize apenas:

  • Letras minúsculas

  • Números

  • Sublinhado (_)

• ❌ Não utilize:

  • Espaços

  • Letras maiúsculas

  • Caracteres especiais (exceto _)

✅ Recomendação

• Use nomes descritivos e objetivos

• Prefira o padrão verbo_substantivo

Exemplos:

• get_weather

• send_email

• search_database

• create_order

---

2️⃣ Descrição

Campo: Descrição *

🎯 Propósito

Este é o campo mais importante da Tool. A descrição é o texto que o modelo de IA lê para decidir se e quando a ferramenta deve ser utilizada.

Se a descrição for vaga ou ambígua, o modelo pode:

• Não usar a ferramenta quando deveria

• Usá-la em contextos incorretos

🧠 Boas práticas

• Explique claramente o que a ferramenta faz

• Descreva quando ela deve ser utilizada

• Informe limitações ou restrições

• Use linguagem direta e orientada a intenção do usuário

❌ Exemplo ruim

“Busca dados.”

✅ Exemplo bom

“Busca a previsão do tempo atual para uma cidade e estado. Deve ser utilizada sempre que o usuário perguntar sobre clima, temperatura ou condições meteorológicas de um local específico.”

---

3️⃣ Parâmetros (JSON Schema)

Campo: Parâmetros (JSON Schema)

🎯 Propósito

Define a estrutura de dados em JSON que o modelo de IA deve gerar como entrada para a função externa.

O modelo irá:

• Interpretar a intenção do usuário

• Gerar automaticamente esse JSON

• Enviar os dados para o fluxo configurado na Tool

---

📦 Formato esperado

Os parâmetros devem seguir o padrão JSON Schema, contendo obrigatoriamente:

🔹 type

• Define o tipo do objeto raiz

• Deve ser sempre:

"type": "object"

🔹 properties

• Lista todos os parâmetros esperados pela função

• Cada propriedade representa um campo que será enviado no JSON

🔹 required

• Array com os nomes dos campos que são obrigatórios

• Deve conter apenas propriedades definidas em properties

---

📌 Exemplo simplificado de JSON Schema

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "Nome da cidade"
    },
    "state": {
      "type": "string",
      "description": "Sigla do estado"
    }
  },
  "required": ["city", "state"]
}

---

✨ Gerar JSON Schema automaticamente com IA

Para facilitar a configuração das Ferramentas (Tools), não é necessário escrever o JSON Schema manualmente. Você pode utilizar o recurso Gerar com IA, que cria o schema automaticamente a partir de uma descrição em linguagem natural.

Imagem 2 - Gerando JSONSchema com IA.

🧠 Como funciona

A IA analisa a descrição informada e gera um JSON Schema válido e otimizado, incluindo:

• Estrutura correta (type: object)

• Definição dos parâmetros (properties)

• Tipos de dados (type)

• Descrições (description)

• Campos obrigatórios (required)

✅ Passo a passo

1. Clique em Gerar com IA

   • O botão fica localizado acima da área de texto do JSON Schema.

2. Descreva os parâmetros da ferramenta

   • Na caixa de diálogo, informe:

     • Quais parâmetros a ferramenta precisa

     • Quais são obrigatórios

     • Regras ou restrições (como valores permitidos, enums, formatos, etc.)

   Exemplo de descrição:

   “Uma ferramenta que obtém dados meteorológicos. Ela precisa do nome da cidade como parâmetro obrigatório e de um parâmetro opcional de unidade, que pode ser celsius ou fahrenheit.”

3. Clique em Gerar

   • A IA processará a descrição e preencherá automaticamente o campo de JSON Schema.

Clique em Gerar com IA para descrever em poucas palavras o que a ferramenta precisa receber, e deixar que a inteligência artificial monte o schema JSON automaticamente para você.

🔀 Saída do módulo

O módulo tem uma única saída, que dá início à lógica da ferramenta propriamente dita. Os módulos conectados depois processam a chamada e devem gerar a resposta que será devolvida a quem chamou a ferramenta.

Imagem 3 - Configuração de ferramenta MCP

💡 Caso de uso

Cenário: uma empresa quer que seu Agente de IA consiga consultar a previsão do tempo de uma cidade quando o cliente perguntar sobre isso.

Configuração:

1

Adicione o módulo Tool a um fluxo.

2

No campo Nome, defina consultar_previsao_tempo.

3

Na Descrição, escreva algo como "Consulta a previsão do tempo atual de uma cidade informada".

4

Em Parâmetros, use Gerar com IA descrevendo "cidade e unidade de temperatura (Celsius ou Fahrenheit)".

5

Conecte a saída do módulo a um módulo de Requisição HTTP, que consulta um serviço externo de previsão do tempo e devolve o resultado.

6

No módulo Agente IA, na aba de ferramentas, selecione essa Tool para que o agente possa usá-la durante a conversa.

Resultado: sempre que o cliente perguntar sobre o clima de uma cidade, o Agente de IA identifica a intenção, chama a ferramenta com os dados corretos e responde com a previsão consultada.

📌 Dicas úteis

• Escreva descrições objetivas — elas são o principal critério que a inteligência artificial usa para saber quando chamar a ferramenta.

• Use o botão Gerar com IA para economizar tempo ao montar o schema de parâmetros.

• Se remover ou renomear um módulo Tool que já está sendo usado por um Agente IA ou por um Servidor MCP, esses locais deixam de encontrar a ferramenta — revise essas referências antes de fazer alterações.

• Uma mesma Tool pode ser usada tanto por um Agente IA interno quanto disponibilizada externamente através de um Servidor MCP.

📝 Resumo

• O módulo Tool define uma ferramenta (nome, descrição e parâmetros) que pode ser chamada por uma inteligência artificial.

• A lógica da ferramenta é implementada pelos módulos conectados após o Tool no fluxo.

• Pode ser usada por um módulo Agente IA ou exposta a sistemas externos através de um Servidor MCP.

• O botão Gerar com IA ajuda a montar automaticamente o schema de parâmetros.