> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/desk-hyperflow/assistentes-inteligentes-agentes.md).

# Assistentes inteligentes - Agentes

Crie e gerencie agentes de IA com funções e conhecimentos específicos.

## 🧑‍💻 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.

***

### 📍 Como acessar

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.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FGpD8R8q6sVwyDkxIGodv%2Fimage.png?alt=media&amp;token=2cc9dd6a-0f4d-4042-a835-003dca55bceb" alt=""><figcaption><p>Imagem 1 - Tela principal com a lista de assistentes cadastrados e seleção do menu lateral com o item 'Agentes' destacado.</p></figcaption></figure>

***

### 🔎 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.

***

### ➕ Como criar um novo Assistente de IA

**🎯 Propósito**

Cadastrar um novo assistente inteligente para atender conversas de forma automática.

**✅ Como fazer na tela**

1. Clique em **Novo modelo de assistente**.
2. Na janela que abrir, preencha um prompt com as informações básicas para geração do assistente.
3. Após isso, configure o **modelo** e a **versão** de IA que será usada para gerar as respostas.
4. Edite as instruções geradas, o **nome** sugerido, os **departamentos** onde o assistente vai atuar e se ele estará **online** ou **offline**.
5. Clique em **Criar**.

**📌 Resultado esperado**

O assistente é criado e a tela de configuração completa é aberta para ajustes.

{% hint style="info" %}
É indispensável seguir as dicas para a criação de um bom assistente inteligente. O campo de prompt é o principal responsável pela forma como o Assistente de IA irá se comportar.
{% endhint %}

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FJY9qFVbDpbjv3eDTN6R7%2Fimage.png?alt=media&amp;token=79914e85-98b6-4a47-b41f-8c174d557195" alt=""><figcaption><p>Imagem 2 - Tela inicial de criação do assistente inteligente, contendo campo para inserção de prompt inicial e botões para configurar manualmente, geração do prompt com IA ou cancelar a ação.</p></figcaption></figure>

***

### 🧩 Configuração básica do Assistente

Após criar o assistente, valide e edite as informações principais:

#### 🏷️ Nome do Assistente

Utilize um nome claro para facilitar a identificação do agente na plataforma.

#### 📁 Departamento

Informe um ou mais departamentos nos quais esse agente vai atuar. Se deixar vazio, o assistente atuará em todos os departamentos.

#### 🧾 Status do Assistente

| Status      | Quando usar                                                           |
| ----------- | --------------------------------------------------------------------- |
| **Online**  | Quando o assistente estiver pronto para atender                       |
| **Offline** | Quando precisar fazer alterações ou testes sem impactar o atendimento |

{% hint style="info" %}
Após criar o assistente, você pode usar o **Playground** para testar o prompt e as configurações antes de colocá-lo em produção.
{% endhint %}

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FAJz3kSwzEsLPkwHJB5Bb%2Fimage.png?alt=media&amp;token=713d4a3c-b7ce-437a-8283-09d0323b16fc" alt=""><figcaption><p>Imagem 3 - Nome do assistente, imagem do assistente e seleção de departamentos, além do status do AI.</p></figcaption></figure>

#### 🧠 Modelo de IA

Escolha o modelo de Inteligência Artificial que será utilizado. Estão disponíveis modelos do **Gemini**, do **ChatGPT** e os modelos nativos da Hyperflow.

**📷 Inserir print:** seletor de modelo com os grupos Hyperflow, Gemini e ChatGPT visíveis

**🔷 Modelos Hyperflow (recomendados)**

Os modelos **Hyperflow Pro** e **Hyperflow Lite** são gerenciados diretamente pela Hyperflow e oferecem **orquestração inteligente com fallback entre múltiplos provedores**: se o modelo principal ficar indisponível, a conversa continua automaticamente em outro — zero atendimentos perdidos.

| Modelo             | Indicação                                             | Melhor para                                                               |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| **Hyperflow Pro**  | Qualidade máxima com fallback multi-provedor          | Interações que exigem maior precisão e sofisticação nas respostas         |
| **Hyperflow Lite** | Alto volume e baixo custo com fallback multi-provedor | Operações com grande quantidade de atendimentos e foco em custo-benefício |

{% hint style="info" %}
Os modelos Hyperflow não exigem configuração de chave de API própria — o consumo é gerenciado pela Hyperflow e cobrado de forma proporcional ao uso real (tokens de entrada + saída), como adicional ao plano contratado.
{% endhint %}

{% hint style="warning" %}
Os modelos Hyperflow Pro e Hyperflow Lite **não estão disponíveis** quando a opção **Usar chave própria** está ativada. Para utilizá-los, mantenha a chave de API padrão da conta.
{% endhint %}

#### ✍️ 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

{% hint style="warning" %}
O prompt é o principal responsável pela forma como o Assistente de IA irá se comportar. Quanto mais claro e detalhado, melhores serão as respostas.
{% endhint %}

***

### ⚙️ Configurações avançadas

Após a criação, é possível ajustar configurações adicionais, como:

* Estilo de comunicação
* Regras de comportamento
* Parâmetros de desempenho

Essas configurações podem ser alteradas a qualquer momento.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FHqejk5zVWyyqzKSCKPzD%2Fimage.png?alt=media&amp;token=76e91761-0364-48d0-a939-dd56d468c503" alt=""><figcaption><p>Imagem 4 - Configurações avançadas do AI, qual modelo, Configurações de resposta, tom de voz, entre outros.</p></figcaption></figure>

***

### 📚 Base de Conhecimento (Arquivos)

A Base de Conhecimento permite que o Assistente de IA utilize conteúdos da sua empresa — documentos, políticas, FAQs e materiais internos — para responder com mais contexto e precisão.

**🎯 Propósito**

Dar ao assistente acesso a informações específicas do negócio para que ele responda com base nesses documentos.

**✅ Como fazer na tela**

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.

**📌 Resultado esperado**

O assistente consulta o conteúdo dos arquivos ao formular as respostas, tornando-as mais precisas e contextualizadas.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fs14LqM3xpaKpRXYYmL30%2Fimage.png?alt=media&amp;token=8c6a2b23-c0aa-414c-9065-62fa791038ef" alt=""><figcaption><p>Imagem 5 - Arquivos com lista de documentos carregados</p></figcaption></figure>

#### 📦 Limites e formatos suportados

| Regra                                    | Limite      |
| ---------------------------------------- | ----------- |
| Tamanho máximo por arquivo               | 50 MB       |
| Quantidade máxima de páginas por arquivo | 512 páginas |
| Quantidade máxima de arquivos            | 10 arquivos |

**Formatos aceitos:** PDF, XLSX, DOCX, CSV, TXT, PPTX, JSON, HTML

***

### 🔗 Ferramentas (Tools)

Uma Tool permite que o Assistente de IA execute ações externas, indo além de apenas responder com texto — como consultar sistemas, buscar dados ou acionar integrações.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FhX0pZmX4IFLC95CEZXCa%2Fimage.png?alt=media&amp;token=c47fe69a-d315-407d-81c7-f37b2bcf9e28" alt=""><figcaption><p>Imagem 6 - Módulo 'Tool'</p></figcaption></figure>

#### 🔄 Como funciona uma Tool

Quando o usuário faz uma solicitação que exige uma ação externa, o processo 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 conjunto de dados com os parâmetros definidos
5. O fluxo externo é executado
6. O resultado retorna para o assistente, que utiliza essa informação para responder ao usuário

{% hint style="info" %}
Para o usuário final, todo esse processo acontece de forma transparente — como se o assistente estivesse apenas "respondendo normalmente".
{% endhint %}

#### 🌐 Como criar uma Ferramenta

Você pode criar uma ferramenta de dois lugares:

**Opção 1 — Diretamente na configuração do assistente (recomendado)**

1. Dentro da configuração do assistente, acesse a aba **Ferramentas**.
2. Clique no ícone **+** no canto superior da aba.
3. A janela **Criar Ferramenta** abrirá. Preencha os campos e clique em **Criar Ferramenta**.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fzrlfu8v3N5YSZ49Tp0Ad%2Fimage.png?alt=media&amp;token=75c2ce6f-cdd2-4252-9127-0b6409549ecd" alt=""><figcaption><p>Imagem 7 - Criação do assistente pelo Assistente Inteligente.</p></figcaption></figure>

**Opção 2 — Pelo menu MCP Servers no Hyperflow Integrações**

1. Acesse **MCP Servers → Ferramentas** no menu lateral.
2. Clique em **+ Criar Ferramenta** no canto superior direito.
3. Preencha os campos e salve.

{% hint style="warning" %}
**Importante:** ao criar uma ferramenta, o sistema gera automaticamente um fluxo dedicado a ela no Hyperflow Integrações. Para que a ferramenta funcione, você precisará acessar esse fluxo e configurar a lógica de execução. Para entender como configurar o módulo **Tool** no fluxo, acesse a documentação do módulo [Tool](https://help.hyperflow.global/docs/builder-de-chatbots/gatilho/tools).
{% endhint %}

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fui2R90bkGSWDEzsQOMBD%2Fimage.png?alt=media&amp;token=807686ed-04ff-45b2-b716-58cdde75d908" alt=""><figcaption><p>Imagem 8 - Modal "Criar Ferramenta" com campos de nome, descrição e parâmetros.</p></figcaption></figure>

#### ➕ Como preencher os campos de uma Ferramenta

| Campo                  | O que preencher                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Nome da ferramenta** | Identificador interno (ex: `get_weather`, `consulta_status`). É o nome que a IA usará para chamar a função                                                                     |
| **Descrição**          | Explique 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 usá-la                                        |
| **Parâmetros**         | Define a estrutura de dados que a ferramenta espera receber. Você pode preencher manualmente ou usar **Gerar com IA** para criar a definição a partir de uma descrição simples |

***

### 🤖 Vinculando Ferramentas e MCPs ao Agente

Para que um assistente utilize as ferramentas criadas, acesse a aba **Ferramentas** dentro da configuração do agente.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F2XUBREyrQwa0OcrfLUC3%2Fimage.png?alt=media&amp;token=e30a1ac2-be45-41ea-8bf5-a7f2f597cd16" alt=""><figcaption><p>Imagem 9 - Aba Ferramentas do agente com lista "Selecionado"</p></figcaption></figure>

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FfrkMn2g9OPBXC2alLDBB%2Fimage.png?alt=media&amp;token=f2a745ca-b116-4660-abe6-ca59113b6e8e" alt=""><figcaption><p>Imagem 10 - Aba Ferramentas do agente com lista "Disponível"</p></figcaption></figure>

#### 🛠️ Aba Ferramentas

Nesta aba, você escolhe quais habilidades individuais o agente terá permissão para usar.

| Seção                      | O que mostra                                                                    |
| -------------------------- | ------------------------------------------------------------------------------- |
| **Selecionado**            | Ferramentas já ativas para este agente                                          |
| **Disponível**             | Ferramentas criadas na plataforma ainda não vinculadas a este agente            |
| **Busca e Filtro**         | Localiza ferramentas por nome ou função                                         |
| **Contexto de Parâmetros** | Exibe quais dados cada ferramenta exige (ex: `categoria`, `id`, `periodoDoDia`) |

{% hint style="info" %}
**Dica:** um agente pode ter múltiplas ferramentas e múltiplos servidores MCP conectados ao mesmo tempo. A IA decide em tempo real qual utilizar, com base na descrição configurada em cada ferramenta.
{% endhint %}

#### 🔗 Aba MCPs — Conectando Servidores Externos

Nesta aba, você integra o agente a um servidor que expõe múltiplas funcionalidades de uma só vez.

| Campo                         | O que preencher                                                      |
| ----------------------------- | -------------------------------------------------------------------- |
| **Label do servidor**         | Nome interno para identificar a conexão (ex: "API de Logística")     |
| **URL do servidor**           | Endereço do servidor MCP. Suporta transportes SSE ou HTTP            |
| **Autenticação**              | Tipo de autenticação exigida pelo servidor (ex: chave de API, token) |
| **Cabeçalhos personalizados** | Headers adicionais caso o servidor exija (ex: `api-key`, `token`)    |

Após preencher, clique em **Testar Conexão** para garantir que a comunicação está funcionando antes de salvar.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F470q8VlfZcnNDZPri1E2%2Fimage.png?alt=media&amp;token=7d7d3e0e-25f4-4f6f-b06b-7372e4a9b1fa" alt=""><figcaption><p>Imagem 11 - Adição de um servidor MCP com campos de URL, autenticação e botões de ação.</p></figcaption></figure>

***

### 🧪 Playground — Testando o 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 sabe utilizar as ferramentas disponíveis.

**✅ Como acessar e usar**

1. Dentro da tela de edição do agente, clique no botão **Playground** no canto superior direito.
2. Uma janela lateral abre com o campo **"Digite uma mensagem..."**.
3. Envie perguntas ou comandos para testar cenários específicos.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FGAcvH8dm6RJMUfi0xfmi%2Fimage.png?alt=media&amp;token=8b8c5f3d-659f-4431-a1af-6c9e861b1cc0" alt=""><figcaption><p>Imagem 12 - Janela do Playground aberta com uma conversa de teste em andamento</p></figcaption></figure>

#### 🔍 O que validar no Playground

**Chamada de Ferramentas:**

* Verifique se, ao fazer uma pergunta técnica, o agente identifica e aciona a ferramenta correta.
* Observe se ele extrai os parâmetros necessários da conversa para executar a ação.

**Conexão com MCPs:**

* Teste se o agente consegue buscar dados de servidores externos configurados.
* Se a resposta demorar ou falhar, clique em **Testar Conexão** na aba MCPs para verificar URL e autenticação.

**Comportamento e Tom de Voz:**

* Valide se as respostas seguem as instruções definidas no prompt e se o agente mantém o contexto da conversa.

#### 💡 Dicas para um teste eficiente

* **Teste de erro:** peça algo que a ferramenta exige mas não forneça o dado — veja se o agente sabe solicitar 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**. A IA decide usar a ferramenta com base no que está escrito lá.

***

### 💡 Caso de uso

**Cenário:** uma empresa de crédito recebe centenas de mensagens por dia com clientes perguntando sobre o status de empréstimos, parcelas em atraso e simulações. A equipe de atendimento não consegue responder tudo com agilidade.

**Configuração do assistente:**

1. Criam um assistente chamado *"Assistente Financeiro"* associado ao departamento **Crédito**.
2. No **Prompt**, definem que o assistente deve responder dúvidas sobre empréstimos com linguagem clara e empática, sem oferecer produtos não solicitados.
3. Na aba **Arquivos**, sobem a política de crédito e o FAQ de dúvidas frequentes (PDF, máx. 50 MB).
4. Cria-se uma **Tool** chamada `consulta_status_emprestimo` no Hyperflow Integrações, configurada para buscar o status do contrato em um sistema externo.
5. Vinculam a ferramenta ao assistente na aba **Ferramentas**.
6. Testam no **Playground** pedindo "Qual o status do meu empréstimo?" e verificam se o assistente aciona a ferramenta corretamente e solicita o dado faltante (ex: CPF ou número do contrato).

**Resultado:** o assistente resolve automaticamente as consultas de status sem intervenção humana. Quando o cliente tem uma solicitação que exige análise manual, o assistente informa e direciona para o atendimento humano.

***

### 📝 Resumo

* O **Assistente Inteligente** é um agente de IA que atende conversas automaticamente no Hyperflow Conversas.
* Ele é criado via **Novo modelo de assistente** e configurado com prompt, modelo de IA, departamentos e status.
* Os modelos **Hyperflow Pro** e **Hyperflow Lite** são os mais recomendados: gerenciados pela Hyperflow, com fallback automático entre provedores e sem necessidade de chave de API própria.
* A **Base de Conhecimento** permite carregar até 3 arquivos (máx. 50 MB cada) para que o assistente responda com base nos documentos da empresa.
* **Ferramentas (Tools)** são criadas no Hyperflow Integrações e vinculadas ao agente para que ele execute ações externas durante a conversa.
* **Servidores MCP** conectam o agente a sistemas externos que expõem múltiplas funcionalidades de uma só vez.
* O **Playground** permite testar o comportamento do agente antes de colocá-lo em produção.