> 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/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/controle-de-fluxo/agente.md).

# Agente

O módulo **Agente** permite criar um assistente de IA autônomo dentro do seu fluxo de chatbot. Com ele, você define as instruções que o agente deve seguir, quais ferramentas ele pode usar e como ele deve responder ao cliente — tudo sem precisar programar nada.

Ao ser ativado no fluxo, o agente interpreta a mensagem recebida, consulta suas instruções e ferramentas configuradas, e age de forma inteligente: respondendo, tomando decisões ou redirecionando o usuário para outro fluxo.

***

### 🧭 Como acessar

1. No menu lateral, clique em **Aplicativo**.
2. Selecione **Fluxos**.
3. Abra ou crie um fluxo existente.
4. No canvas do Builder, clique em **+** para adicionar um novo módulo.
5. Localize e selecione o módulo **Agente**.
6. O módulo será inserido no canvas. Clique duas vezes sobre ele para abrir as configurações.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F9PlqSiK1ScMmQtkcsc1j%2Fimage.png?alt=media&amp;token=b777bce0-58da-40d0-993e-cd27cd47b0ee" alt=""><figcaption><p>Imagem 1 - Menu lateral com "Aplicativo > Fluxos" destacado e o canvas com o módulo Agente inserido no Hyperflow Integrações.</p></figcaption></figure>

***

### 🔍 Conhecendo a tela

Ao abrir o módulo Agente, você verá uma janela de configuração com **cinco abas**:

* **Configurações** — define modelo, tom, limites e comportamento geral
* **Prompt** — escreve as instruções que guiam o agente
* **Ferramentas** — adiciona ações que o agente pode executar
* **Servidores MCP** — conecta servidores externos de ferramentas
* **Habilidades** — cria arquivos de instruções especializadas

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FzKOxiXUDrQQxuXDEOAQC%2F02-painel-cinco-abas.png?alt=media&amp;token=199ae7ec-c614-416f-a862-61571fa738b5" alt=""><figcaption><p>Imagem 2 - Janela de configuração do módulo Agente com as cinco abas visíveis no topo.</p></figcaption></figure>

***

#### ⚙️ Aba Configurações

Esta é a aba principal. Aqui você define o comportamento geral do agente.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FflfHmu0FJ9eBBzOQA2y7%2F03-aba-configuracoes-completa.png?alt=media&amp;token=94b6fdd6-3a74-4fae-848d-a5fe96e45427" alt=""><figcaption><p>Imagem 3 - Aba Configurações completa, mostrando o modo de execução, modelo e controles de temperatura.</p></figcaption></figure>

**🔀 Modo de execução**

O primeiro bloco define **como o agente vai operar** dentro do fluxo. Você escolhe entre dois modos:

| Modo                 | O que significa                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Execução em loop** | O agente continua respondendo a cada nova mensagem do cliente até usar uma ferramenta de saída. Ideal para conversas contínuas. |
| **Execução única**   | O agente responde uma vez e passa o controle para o próximo módulo do fluxo.                                                    |

Clique no modo desejado para selecioná-lo.

{% hint style="info" %}
Se você escolher **Execução em loop**, certifique-se de configurar ao menos uma ferramenta do tipo **Saída** na aba Ferramentas — ela será responsável por encerrar o ciclo quando o agente decidir.
{% endhint %}

***

**📝 Contexto**

Campo opcional para adicionar informações extras que o agente deve considerar ao responder. Use `{{ }}` para inserir variáveis do fluxo (como nome do cliente ou número do pedido).

**Exemplo:** `O cliente se chama {{ contact.name }} e está em dúvida sobre o pedido {{ order.id }}.`

***

**🧠 Modelo**

Selecione o modelo de inteligência artificial que o agente vai usar para processar e responder as mensagens. As opções disponíveis são:

* **GPT-4o** — modelo mais avançado, indicado para tarefas complexas
* **GPT-4o mini** — versão mais leve e rápida do GPT-4o
* **GPT-4 Turbo** — alta capacidade de raciocínio
* **GPT-3.5 Turbo** — opção econômica para fluxos simples
* **Claude 3.5 Sonnet** — modelo da Anthropic com excelente equilíbrio entre velocidade e qualidade
* **Claude 3 Haiku** — versão compacta e ágil da Anthropic
* **Gemini 1.5 Pro** — modelo do Google com grande janela de contexto
* **Gemini 1.5 Flash** — versão rápida do Gemini

{% hint style="warning" %}
A disponibilidade de cada modelo pode depender das integrações configuradas no seu ambiente. Caso algum modelo não apareça, consulte o administrador da plataforma.
{% endhint %}

***

**🌡️ Temperatura**

Controla o quanto as respostas do agente variam. Arraste o slider para ajustar:

* **Próximo de 0** — respostas mais previsíveis e precisas
* **Próximo de 2** — respostas mais criativas e variadas

O valor padrão é **0,7**, que equilibra precisão e naturalidade.

***

**🔢 Máximo de tokens**

Define o tamanho máximo da resposta gerada pelo agente. Um **token** equivale aproximadamente a 4 caracteres em inglês ou 3 em português.

* Valor mínimo: **1**
* Valor máximo: **128.000**
* Padrão: **1.024**

Aumente esse valor se o agente precisar dar respostas mais longas.

***

**💬 Configurações de resposta**

Dois campos complementares:

| Campo                    | O que faz                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Máximo de caracteres** | Limita o tamanho da resposta enviada ao cliente. Digite `0` para sem limite.                                               |
| **Atraso (ms)**          | Adiciona um tempo de espera em milissegundos antes de o agente enviar a resposta. Útil para simular um tempo de digitação. |

***

**🎭 Tom**

Selecione um ou mais tons que o agente deve usar ao responder. Clique nos chips para ativar ou desativar:

* **Amigável**
* **Formal**
* **Empático**
* **Profissional**
* **Casual**

***

**🆔 ID do Agente**

Exibe o identificador único do agente, gerado automaticamente. Você pode copiá-lo clicando no ícone ao lado — uma mensagem confirmará que foi copiado.

Esse ID pode ser usado para referenciar este agente em outras integrações ou configurações avançadas.

***

**🔧 Configurações avançadas**

Expanda esta seção para acessar opções adicionais:

| Opção                            | O que faz                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Ignorar mensagens anteriores** | O agente começa cada conversa do zero, sem considerar o histórico de mensagens.                                 |
| **Porta de exceção**             | Cria um caminho alternativo no fluxo para onde o agente é redirecionado caso ocorra um erro durante a execução. |

***

#### ✍️ Aba Prompt

Aqui você escreve as **instruções principais** que definem o comportamento do agente. É como orientar um colaborador antes de atender um cliente.

O editor suporta formatação de texto e uso de variáveis com `{{ }}`.

**Exemplo de instrução:**

> Você é um assistente de suporte da empresa Exemplo. Seu objetivo é ajudar clientes com dúvidas sobre pedidos e entregas. Seja objetivo, cordial e use o nome do cliente sempre que possível.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fhwd5hV9bdqgeKkfxlYGX%2F04-aba-prompt-instrucoes.png?alt=media&amp;token=583d848d-a945-46b7-bca3-24356101939f" alt=""><figcaption><p>Imagem 4 - Aba Prompt com exemplo de instruções preenchidas no editor.</p></figcaption></figure>

{% hint style="info" %}
Quanto mais clara e específica for a instrução, melhor o agente vai se comportar. Inclua o contexto do negócio, o tipo de cliente atendido e o objetivo da conversa.
{% endhint %}

***

#### 🧰 Aba Ferramentas

As ferramentas definem **o que o agente pode fazer** além de responder mensagens. Cada ferramenta aparece como uma opção de ação que o agente pode acionar durante a conversa.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FCJScrM5JDr4IvSCV88gT%2Fimage.png?alt=media&amp;token=65367259-3322-4c89-9754-581144505b60" alt=""><figcaption><p>Imagem 5 - Aba Ferramentas com a lista de ferramentas à esquerda e o editor de configuração à direita.</p></figcaption></figure>

**➕ Como adicionar uma ferramenta**

1. Clique em **Adicionar ferramenta**.
2. A ferramenta será criada com um nome padrão — clique para editá-la no painel à direita.
3. Escolha o tipo de ferramenta.
4. Preencha os campos conforme o tipo selecionado.
5. Clique em **Salvar alterações** para confirmar.

Para remover uma ferramenta, clique no ícone de lixeira ao lado do nome dela na lista.

***

**📂 Tipos de ferramenta**

Ao selecionar uma ferramenta, escolha um dos quatro tipos disponíveis:

***

**1️⃣ Personalizado**

Cria uma saída personalizada no módulo para que você possa conectar a qualquer outro módulo manualmente no canvas.

🎯 **Propósito** Use quando quiser que o agente tome uma ação específica e passe o controle para um módulo definido por você.

✅ **Como fazer na tela**

* Dê um nome à ferramenta (ex: "Encaminhar para humano")
* Descreva quando o agente deve usá-la (ex: "Acione quando o cliente pedir para falar com um atendente")
* Defina os parâmetros que o agente deve coletar (JSON Schema) — você pode clicar em **Gerar com IA** e descrever em texto o que precisa
* Conecte a saída criada ao módulo desejado no canvas

📌 **Resultado esperado** Uma porta de saída aparece no nó do agente. Conecte essa porta ao próximo módulo do fluxo.

***

**2️⃣ Pular**

Redireciona o fluxo para outro fluxo cadastrado na plataforma quando o agente decidir acionar essa ferramenta.

🎯 **Propósito** Use para transferir o atendimento para um fluxo específico — por exemplo, fluxo de vendas, cancelamento ou suporte técnico.

✅ **Como fazer na tela**

* Dê um nome à ferramenta (ex: "Ir para Vendas")
* Descreva quando o agente deve usá-la
* Selecione o **fluxo de destino** no campo indicado
* Configure os parâmetros que o agente deve passar ao fluxo de destino

📌 **Resultado esperado** Quando acionada, o agente encerra a conversa no fluxo atual e inicia o fluxo de destino selecionado.

{% hint style="warning" %}
O fluxo de destino precisa estar criado e publicado antes de ser selecionado aqui. Acesse **Aplicativo > Fluxos**, crie o fluxo e volte para concluir a configuração.
{% endhint %}

***

**3️⃣ Ferramenta**

Conecta o agente a uma ferramenta já configurada na plataforma (como consulta a sistemas externos, envio de dados, busca em bases de conhecimento, entre outras).

🎯 **Propósito** Use para que o agente possa executar ações integradas — buscar informações de um sistema, registrar dados ou consultar uma base de conhecimento.

✅ **Como fazer na tela**

* Clique no campo de seleção e pesquise a ferramenta desejada
* Após selecionar, o nome, a descrição e os parâmetros da ferramenta serão exibidos automaticamente

📌 **Resultado esperado** O agente passa a ter acesso a essa ferramenta durante as conversas e pode acioná-la quando necessário.

{% hint style="warning" %}
As ferramentas disponíveis para seleção precisam estar cadastradas previamente na plataforma. Caso a ferramenta que você precisa não apareça, entre em contato com o administrador.
{% endhint %}

***

**4️⃣ Saída**

Marca o ponto de **encerramento do agente** no fluxo. Quando o agente acionar essa ferramenta, ele sai do modo de loop e passa o controle para o próximo módulo.

🎯 **Propósito** Use sempre que o agente precisar finalizar sua atuação e continuar o fluxo — por exemplo, após coletar todas as informações necessárias.

✅ **Como fazer na tela**

* Dê um nome à saída (ex: "Concluído", "Dados coletados")
* Descreva quando o agente deve encerrar (ex: "Quando todas as informações forem confirmadas pelo cliente")
* Defina o que o agente deve retornar nesta saída (JSON Schema)

📌 **Resultado esperado** Uma porta de saída é criada no nó. Conecte-a ao próximo módulo para continuar o fluxo após o agente.

{% hint style="info" %}
Em fluxos com **Execução em loop**, ao menos uma ferramenta do tipo **Saída** é necessária para que o agente encerre o ciclo corretamente.
{% endhint %}

***

#### 🔌 Aba Servidores MCP

Os **Servidores MCP** permitem conectar o agente a servidores externos que oferecem ferramentas adicionais. Essa é uma configuração avançada para integrações personalizadas.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FVNNQFDLk8ZppeWN2gGgb%2Fimage.png?alt=media&amp;token=1e84b6a4-a88e-485b-845b-e46b50d13f1f" alt=""><figcaption><p>Imagem 6 - Aba Servidores MCP com um servidor cadastrado mostrando nome e URL;</p></figcaption></figure>

**➕ Como adicionar um servidor MCP**

1. Clique em **Adicionar servidor MCP**.
2. Preencha o **Nome** do servidor (ex: "Meu servidor de ferramentas").
3. Informe a **URL** de acesso ao servidor (ex: `https://mcp.exemplo.com`).
4. Para remover um servidor, clique no ícone de lixeira no card correspondente.

{% hint style="warning" %}
A URL do servidor MCP precisa ser fornecida pelo time técnico responsável pela integração. Não altere essa configuração sem orientação adequada.
{% endhint %}

***

#### 📚 Aba Habilidades

As **habilidades** são arquivos de instruções especializadas que ampliam as capacidades do agente. Pense nelas como "manuais internos" que o agente consulta para lidar com situações específicas.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FZpEzoa4whp8zoIcrhVsz%2Fimage.png?alt=media&amp;token=2ac76ecb-8885-4d27-ae6d-a308036889e8" alt=""><figcaption><p>Imagem 7 - Aba Habilidades com a lista de arquivos à esquerda e o editor de conteúdo à direita.</p></figcaption></figure>

**➕ Como criar uma habilidade**

1. Clique em **Adicionar novo arquivo**.
2. No painel à direita, preencha:
   * **Nome** — o nome da habilidade (o sistema adiciona `.md` automaticamente)
   * **Descrição** — explique quando o agente deve usar essa habilidade (2 a 3 linhas)
   * **Conteúdo** — escreva as instruções detalhadas no editor de texto
3. Clique em **Salvar alterações**.

Para remover uma habilidade, clique no ícone de lixeira ao lado do nome na lista.

***

### 💾 Salvando as configurações

Após configurar todas as abas necessárias, clique em **Salvar alterações** no rodapé da janela. As configurações serão aplicadas ao módulo e a janela será fechada.

O nó no canvas será atualizado mostrando um resumo visual das configurações: modelo selecionado, quantidade de servidores MCP, habilidades, arquivos e uma prévia do prompt.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F8hgssM50ar2PKE7FZF8U%2Fimage.png?alt=media&amp;token=e8ae63c1-d428-4f03-9942-cbd5dc823000" alt=""><figcaption><p>Imagem 8 - Nó do Agente no canvas após salvar, com chips de resumo e prévia do prompt visíveis.</p></figcaption></figure>

***

### 📌 Dicas úteis

* **Comece pelo Prompt.** A qualidade das instruções é o fator mais importante para o bom desempenho do agente. Seja claro sobre quem o agente é, o que ele pode e o que ele não deve fazer.
* **Use o modo Execução única** quando o agente precisar apenas responder uma pergunta e passar o controle adiante — isso evita que o fluxo fique em loop desnecessariamente.
* **Combine ferramentas do tipo Personalizado e Saída** para criar fluxos com caminhos diferentes dependendo da decisão do agente.
* **A função "Gerar com IA"** nos parâmetros de ferramentas ajuda a criar esquemas JSON sem precisar conhecer a sintaxe — basta descrever em português o que você precisa.
* O **ID do Agente** pode ser útil ao reportar um problema ou ao configurar integrações — guarde-o em um lugar acessível.

***

### 💡 Caso de uso

**Cenário:** Uma empresa de e-commerce quer que o agente identifique automaticamente se o cliente está com dúvida sobre **rastreamento de pedido** ou **troca de produto** e direcione para o fluxo correto.

**Configuração principal:**

1. **Modo de execução:** Loop — o agente continua respondendo até identificar a intenção do cliente.
2. **Modelo:** GPT-4o mini — velocidade e custo adequados para alto volume de atendimentos.
3. **Prompt:** "Você é um assistente de suporte da Loja Exemplo. Seu objetivo é entender se o cliente quer rastrear um pedido ou solicitar uma troca. Pergunte o número do pedido quando necessário. Não resolva outros assuntos — apenas identifique o motivo do contato e acione a ferramenta correta."
4. **Ferramentas configuradas:**
   * **Pular → Fluxo de Rastreamento** (acionada quando o cliente menciona entrega, prazo ou localização do pedido)
   * **Pular → Fluxo de Trocas** (acionada quando o cliente menciona troca, defeito ou produto errado)
   * **Saída → Outros assuntos** (acionada para qualquer outro tipo de solicitação)

**Resultado esperado no fluxo:** O agente conversa com o cliente, identifica a intenção e redireciona automaticamente para o fluxo adequado — sem necessidade de menus ou botões de seleção manual. O atendimento fica mais natural e eficiente.

***

### 📝 Resumo

* O módulo **Agente** adiciona um assistente de IA autônomo ao seu fluxo, capaz de interpretar mensagens e tomar decisões.
* Configure o comportamento na aba **Configurações** (modelo, temperatura, tom e modo de execução) e escreva as instruções na aba **Prompt**.
* Use a aba **Ferramentas** para definir o que o agente pode fazer: redirecionar fluxos, acionar integrações ou criar saídas personalizadas.
* O **modo em loop** mantém o agente ativo até ele acionar uma ferramenta de saída; o **modo único** faz o agente responder uma vez e seguir o fluxo.
* As abas **Servidores MCP** e **Habilidades** oferecem recursos avançados para ampliar as capacidades do agente com integrações externas e instruções especializadas.