# Assistentes inteligentes - Agentes Os Assistentes de Inteligência Artificial permitem criar agentes inteligentes personalizados, capazes de responder usuários, consultar informações internas e executar ações externas de forma automatizada. Este artigo explica **como acessar, criar, configurar e expandir** um Assistente de IA. *** ### 📍 Como acessar os Assistentes de IA 1. No menu lateral esquerdo, clique em **Agentes**. 2. Você será direcionado para a tela de gerenciamento dos assistentes. Nesta tela, ficam listados todos os Assistentes de IA já criados.

Imagem 1 - Tela Agentes de IA.

*** ### 🔎 Como localizar um Assistente de IA * Utilize o campo **Pesquisar** para encontrar um assistente pelo **nome**. * A lista será filtrada automaticamente conforme o texto digitado.

Imagem 2 - Buscando agente específico por nome.

*** ### ➕ Como criar um novo Assistente de IA 1. Clique em **Novo modelo de assistente**. 2. Você deverá preencher um prompt com algumas informações básicas para start do novo assistente através da modal aberta.

Imagem 3 - Criação de assistente

{% hint style="info" %} É indispensável seguir as dicas para a criação de um bom assistente inteligente. {% endhint %}

Imagem 4 - Ao clicar em 'Gerar com IA' trás sugestão de nome, instruções, modelo e versão base a ser utilizada.

3. Devo configurar então o modelo e versão base que será utilizado para a geração de respostas por IA. 4. Tenho possibilidade de editar as instruções, nome do assistente sugerido, quais departamentos ele irá atuar, e se está online ou offline. *** ### 🧩 Configuração básica do Assistente Após criar o assistente usando a opção de 'Gerar com IA', valide e edite as informações, como: #### 🏷️ Nome do Assistente * Utilize um nome claro para facilitar a identificação do agente. #### 📁 Departamento * Pode-se informar um ou mais departamentos para que esse agente atue. Caso deixe vazio, irá para todos os departamentos. #### 🧾 Status do Assistente * Deixe 'Online' para caso vá iniciar o uso do assistente e caso precise realizar alguma alteração e testar, pode-se deixar offline.

Imagem 5 - Assistente gerado.

{% hint style="info" %} Após a inclusão do novo agente de IA, temos a possibilidade de utilizar um playground para testar o prompt e as configurações que colocamos até o presente momento na configuração do nosso assistente. {% endhint %} #### 🧠 Modelo de IA (LLM) * Escolha o modelo de Inteligência Artificial que será utilizado. * Estão disponíveis **diversos modelos do Gemini e do ChatGPT**. #### ✍️ Prompt do Assistente * Informe o prompt com as instruções que definem: * O papel do assistente * Seu comportamento * Tom de voz e forma de resposta 📌 O prompt é o principal responsável pela forma como o Assistente de IA irá se comportar.

Imagem 6 - Possibilidade de edição do prompt.

*** ### ⚙️ Configurações avançadas Após a criação, é possível ajustar configurações adicionais do assistente, como: * Estilo de comunicação * Regras de comportamento * Parâmetros de desempenho Essas configurações podem ser alteradas a qualquer momento.

Imagem 7 - Configurações disponíveis além da seleção de versão e modelo do assistente base.

*** ### 📚 Como adicionar uma base de conhecimento (RAG) A Base de Conhecimento permite que o Assistente de IA utilize conteúdos da sua empresa (como documentos, políticas, FAQs e materiais internos) para responder com mais contexto e precisão. #### ✅ Passo a passo 1. Acesse a configuração do assistente desejado. 2. Vá até a aba **Arquivos**. 3. Faça o **upload** dos arquivos que o assistente deverá consultar. Após o upload, esses arquivos passam a ser utilizados pelo assistente nas respostas.

Imagem 8 - Adilção de arquivos para base de conhecimento do assistente.

*** ### 📌 Limites e formatos suportados Antes de enviar seus arquivos, considere as regras abaixo: #### 📦 Limite por arquivo * **Tamanho máximo:** **50 MB** * **Quantidade máxima de páginas:** **512 páginas** #### 🧾 Formatos aceitos * **PDF** * **XLSX** * **DOCX** * **CSV** * **TXT** * **PPTX** * **JSON** * **HTML** #### 📁 Quantidade máxima de arquivos * É possível adicionar **até 3 arquivos distintos**, **independentemente do formato**. *** ### 🔗 Como criar uma Função Externa (Tool) A criação da função ocorre fora da configuração do Assistente de IA. #### 🌐 Onde criar 1. Acesse [**integracoes**](https://integracoes.hyperflow.global). 2. Crie um novo fluxo ou utilize um fluxo existente. #### 🧩 Configuração do fluxo 1. Adicione o módulo chamado **Tool** ao fluxo. 2. Configure a ação que será executada.

Imagem 9 - Módulo 'Tool'

### 🔄 Como funciona a Tool Uma Tool permite que o Assistente de IA **execute ações externas**, indo além de apenas responder com texto. De forma resumida, o funcionamento acontece assim: 1. **O usuário faz uma pergunta ou solicitação** 2. **O Assistente de IA identifica a intenção** de executar uma ação externa 3. **A Tool é acionada** com base na descrição configurada 4. **O Assistente gera automaticamente um JSON** com os parâmetros definidos no JSON Schema 5. **O fluxo externo é executado** (via Chamo Tool) 6. **O resultado retorna para o Assistente**, que utiliza essa informação para responder ao usuário 📌 Para o usuário final, todo esse processo acontece de forma transparente, como se o assistente estivesse apenas “respondendo normalmente”. Em resumo: > **A Tool conecta o Assistente de IA a sistemas e automações externas, permitindo ações reais durante a conversa.** {% hint style="info" %} Para entender como configurar esse módulo, deve-se ir para [Tool](https://help.hyperflow.global/docs/builder-de-chatbots/gatilho/tools). {% endhint %} *** ### 🤖 Vinculando MCP e Ferramentas ao Agente Para que um assistente de IA utilize as capacidades que você criou, é necessário configurá-lo no menu Assistentes inteligentes → Agentes. Dentro das configurações do agente, você encontrará a seção Ferramentas, dividida em duas abas principais. *** #### 🛠️ Aba Ferramentas: Nesta aba, você escolhe exatamente quais "habilidades" individuais o agente terá permissão para usar. * ✅ Selecionado: Lista as ferramentas que já estão ativas para este agente. No exemplo, o agente pode usar `busca_mensagem_feliz` e `consulta_status_emprestimo`. * 📦 Disponível: Exibe todas as outras ferramentas criadas na plataforma que ainda não foram vinculadas a este agente específico. * 🔍 Busca e Filtro: Permite localizar rapidamente ferramentas por nome ou função, facilitando a gestão quando você possui uma biblioteca extensa. * 🧬 Contexto de Parâmetros: Abaixo de cada ferramenta, você consegue visualizar quais parâmetros ela exige (ex: `categoria`, `id`, `periodoDoDia`), ajudando a entender o que o agente precisará perguntar ao usuário. > Dica de Ouro: Um agente pode ter múltiplas ferramentas e múltiplos servidores MCP conectados simultaneamente. A IA decidirá em tempo real qual deles utilizar com base na Descrição que você configurou em cada ferramenta.

Imagem 10 - Seleção de ferramentas disponíveis em que o agente utilizará de acordo com o seu próprio julgamento.

*** #### ➕ Como criar uma nova Ferramenta Para iniciar, acesse o menu MCP Servers → Ferramentas e clique no botão + Criar Ferramenta no canto superior direito. Você também pode criar uma ferramenta diretamente dentro da configuração de um Agente clicando no ícone de "+" na aba de ferramentas. Ao abrir o formulário de criação, preencha os seguintes campos: * 🏷️ Nome da ferramenta: Defina um identificador técnico (ex: `get_weather` ou `send_email`). Este nome é o que a IA usará internamente para chamar a função. * 📝 Descrição: Explique de forma clara o que a ferramenta faz e em quais situações a IA deve utilizá-la. Uma boa descrição ajuda o assistente a decidir quando essa ferramenta é necessária. * 🧩 Parâmetros (JSONSchema): Define a estrutura de dados que a ferramenta espera receber. Você pode escrever o código JSON manualmente ou utilizar o botão 🪄 Gerar com IA para criar a definição baseada em uma descrição simples.

Imagem 11 - Criação de uma nova ferramenta no Hyperflow Conversas.

{% hint style="info" %} **Um fluxo será criado em sua aplicação com esta ferramenta. Após a criação, você precisará configurar o fluxo em sua aplicação para completar a configuração da ferramenta.** {% endhint %} *** #### 🔄 Integração com o Editor de Fluxos Um ponto fundamental da Hyperflow é que toda ferramenta nasce com um fluxo associado. * ⚡ Criação de Fluxo: Ao salvar uma nova ferramenta, o sistema cria automaticamente um fluxo na sua aplicação dedicado a ela. * 🔗 Vínculo Direto: Na lista de ferramentas, você encontrará o link Abrir Fluxo. Ele leva você diretamente ao editor onde poderá configurar o nó *Tool* e definir a lógica de execução (o que acontece quando a ferramenta é chamada). * 🛠️ Configuração Final: Para que a ferramenta funcione, você precisará configurar os componentes dentro desse fluxo para completar a integração com seus sistemas externos. *** #### 📋 Gestão de Ferramentas Existentes Na tela principal de Ferramentas, você tem uma visão geral de todo o seu arsenal tecnológico: * 🔍 Busca: Localize rapidamente ferramentas pelo nome. * 📊 Parâmetros Visíveis: Veja rapidamente quais dados cada ferramenta exige (ex: `cep`, `cnpj`, `cidade`) sem precisar abrir as configurações. * 📈 Ordenação: Organize suas ferramentas por data de criação para facilitar a gestão de versões. *** #### 🔗 Aba MCPs: Conectando Servidores Externos Nesta aba, você integra o Agente a um servidor que expõe múltiplas funcionalidades de uma só vez. * 📍 Label do servidor: Um nome interno para identificar a conexão (ex: "API de Logística" ou "Ferramentas CRM"). * 🔗 URL do servidor: O endpoint do servidor MCP (suporta transportes SSE ou HTTP). É aqui que o agente enviará as requisições. * 🔐 Autenticação: Permite definir como o agente se identificará perante o servidor. Caso o servidor exija, você pode configurar o tipo de autenticação e adicionar Cabeçalhos Personalizados (Headers) como `api-key` ou `token`. * 🧪 Testar Conexão: Botão vital para garantir que a comunicação entre a Hyperflow e o servidor MCP está funcionando antes de salvar.

Imagem 12 - Adição de servidor MCP.

Imagem 13 - Aba de MCPs, listagem e possibilidade de edição, exclusão ou adição de novos servers.

*** ### 🧪 O Playground: Testando seu Agente O Playground simula uma interface de chat real, permitindo que você interaja com o agente para verificar se ele compreende as instruções do prompt e se sabe utilizar as ferramentas disponíveis. #### 🕹️ Como acessar e usar * Abertura: Dentro da tela de edição do Agente, clique no botão Playground localizado no canto superior direito. * Interface de Chat: Uma janela lateral se abrirá com o campo "Digite uma mensagem..." na parte inferior. * Interação: Você pode enviar perguntas ou comandos para testar cenários específicos (ex: "Qual o status do meu empréstimo?" ou "Busque o CEP 01001-000").

Imagem 14 - Playground para validações e testes do agente.

*** #### 🔍 O que validar no Playground? 1. Chamada de Ferramentas (Tool Calling): * Observe se, ao fazer uma pergunta técnica, o agente identifica a ferramenta correta (ex: `consulta_status_emprestimo`). * Verifique se ele consegue extrair os parâmetros necessários da conversa (como o `id` ou `categoria`) para executar a ação. 2. Conexão com Servidores MCP: * Teste se o agente consegue buscar dados de servidores externos configurados na aba MCP. * Se a resposta demorar ou falhar, utilize o botão Testar Conexão na aba de MCPs para garantir que a URL e a autenticação estão corretas. 3. Comportamento e Tom de Voz: * Valide se as respostas seguem as instruções definidas na aba Prompt e se o agente mantém o contexto da conversa. *** #### 💡 Dicas para um teste eficiente * Teste de Erro: Tente pedir algo que a ferramenta exige mas você não forneceu (ex: peça uma consulta de clima sem dizer a cidade) para ver se o agente sabe pedir a informação que falta. * Ajuste Fino: Se o agente não usar uma ferramenta quando deveria, volte na configuração da ferramenta e melhore a Descrição. Lembre-se: a IA decide usar a ferramenta com base no que você escreveu lá. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.hyperflow.global/docs/desk-hyperflow/assistentes-inteligentes-agentes.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.