Agente de IA · agent

Referência do nó

KindagentCategoriaIA

Para que serve

Imagina que você tem um atendente muito bem treinado que sabe usar ferramentas, consultar documentos e tomar decisões por conta própria. O Agente de IA coloca esse atendente dentro do fluxo: quando o fluxo chega nesse bloco, o agent entra em ação, faz o trabalho dele (raciocínio, consultas, ações) e devolve o resultado para o fluxo continuar.

Quando usar

• Delegar ao agent uma tarefa que exige raciocínio e múltiplas etapas
• Integrar um atendente com IA em pontos específicos do fluxo (ex.: só para clientes VIP)
• Usar ferramentas MCP ou busca na web dentro do fluxo sem configurar tudo do zero
• Combinar a estrutura de um fluxo com a inteligência de um agent configurado separadamente

---

Como funciona

O Agente de IA é uma ponte entre o Flow Builder e o Agent Builder. Você configura o agent uma vez no Agent Builder (com instruções, memória, ferramentas, base de conhecimento) e depois o reutiliza em qualquer fluxo adicionando este nó.

Flow Builder
  ↓ (dados do contato, histórico, variáveis)
Agente de IA  →  Agent Builder (raciocínio + ferramentas)
  ↓ (resposta gerada pelo agent)
Próximo nó do fluxo

---

Passo a passo

1. ·
   Certifique-se de que o agent que você quer usar já está criado e publicado no Agent Builder.
   

   

   Tela de listagem de Agentes de IA, mostrando um agente do tipo LLM já publicado

2. ·
   Arraste o nó **Agente de IA** para o canvas e conecte ao fluxo.
3. ·
   No painel, selecione o **Agent** desejado na lista de agents disponíveis.
4. ·
   Configure a **Mensagem de entrada** — geralmente {{userinput.query}} ou uma mensagem montada por um nó anterior.
5. ·
   Salve. A resposta do agent fica disponível como {{agent.output}} para os nós seguintes.

---

Campos

Campo	O que faz
Agent	Qual agent executar (criado no Agent Builder)
Mensagem de entrada	O que o agent vai receber como input
Contexto adicional	Variáveis extras que o agent pode usar
Timeout	Tempo máximo de execução do agent (em segundos)

Saídas

Variável	Conteúdo
output	A resposta final gerada pelo agent
steps	Os passos intermediários realizados (para debugging)

---

Memória do Agent no nó (dois interruptores, não um só)

A memória de longo prazo de um Agent depende de dois interruptores independentes, e os dois precisam estar ligados para o ciclo completo funcionar:

Interruptor	Onde fica	Controla
memory_config.enabled	No Agent (Agent Builder)	Se a conversa é extraída e salva como fatos de memória quando ela fecha. Padrão: false.
Memória (memory.enabled)	No nó Agente de IA (Flow Builder)	Se este nó lê os fatos salvos e os injeta no contexto antes de responder. Padrão: false.

Ligar só um dos dois não é suficiente:

• Só memory_config.enabled (sem ligar a memória no nó): o Agent extrai e guarda fatos, mas este nó nunca os lê de volta — a memória fica acumulando sem uso.
• Só a memória no nó (sem memory_config.enabled no Agent): o nó tenta ler fatos, mas nunca houve extração — não há nada para recuperar.

Atenção

Fatos de memória só são extraídos quando a conversa fecha. Uma conversa que nunca é encerrada (fica aberta indefinidamente) não gera memória de longo prazo, mesmo com memory_config.enabled: true. Veja o funcionamento completo da extração em Memória do Agent.

---

Busca de memória sob demanda (memory_search)

Além do preâmbulo fixo de memória — os fatos mais relevantes (na quantidade configurada na memória do nó), injetados automaticamente no início de cada execução (ver Memória do Agent) — o Agent também ganha uma ferramenta chamada memory_search, que ele pode chamar durante a própria conversa sempre que precisar lembrar de algo específico que não veio no preâmbulo.

Funciona assim: o Agent formula uma busca (uma pergunta, um tema) e recebe de volta até 20 fatos de memória mais parecidos com aquela busca — busca semântica, não busca por texto exato. O grau mínimo de semelhança exigido é o mesmo configurado na memória do nó; o Agent não controla esse valor.

Quando a tool fica disponível, as duas condições precisam ser verdadeiras:

• Memória ligada no nó (memory.enabled: true) — o mesmo interruptor descrito acima.
• A conversa tem um contato identificado. Sem contato, não há de quem buscar memórias, e a tool não é anexada.

Vale o mesmo alerta dos dois interruptores: se o Agent nunca teve memory_config.enabled ligado (extração desligada), não existe fato nenhum salvo para essa busca encontrar — a tool fica disponível e roda, mas sempre volta vazia.

Atenção

O opt-out de memória do contato (LGPD) e a expiração dos fatos (retention_days, configurado no Agent) não filtram a leitura: tanto o preâmbulo automático quanto a busca sob demanda enxergam todos os fatos salvos do contato. Esses dois controles atuam na extração de novas memórias e no pruning, não na busca.

A ferramenta memory_search continua disponível mesmo quando uma skill ativa restringe quais ferramentas o Agent pode usar — ela fica no mesmo grupo de exceções da busca na base de conhecimento e do carregamento de skills.

---

Saída estruturada desativa ferramentas do Agent

Quando este nó chama um Agent com saída estruturada habilitada (schema definido para a resposta), o Agent responde sempre em JSON conforme esse schema — e os modelos de IA não permitem combinar uma resposta em formato fixo com o uso de ferramentas na mesma chamada. Por isso, nessa execução específica, o sistema desativa todos os seguintes recursos do Agent, mesmo que estejam configurados nele:

• Skills
• Servidores MCP
• Ferramentas de função
• Ferramentas embutidas
• Conhecimento (base de conhecimento)

Essa é uma limitação técnica dos modelos de IA quando pedem uma resposta em formato fixo, não um erro da plataforma. Se o Agent precisa usar ferramentas e retornar dado estruturado, prefira: (1) deixar o Agent responder livremente com ferramentas e extrair a estrutura depois com um nó Modelo de IA (LLM) ou Extrair parâmetros, ou (2) usar saída estruturada só em um Agent dedicado a classificação/extração, sem ferramentas.

Quando isso acontece, a execução mostra um aviso, visível em tempo real no painel de execução do Flow Builder, listando quantas skills, servidores MCP, ferramentas de função, ferramentas embutidas e itens de conhecimento foram descartados, e se a busca de memória (memory_search) foi suprimida.

Atenção

A busca de memória sob demanda (memory_search) também é desligada nesse cenário, pelo mesmo motivo — e agora ela entra na contagem do aviso acima, junto com skills, servidores MCP, ferramentas de função, ferramentas embutidas e conhecimento. Se um Agent com memória habilitada parar de buscar fatos sob demanda ao ligar saída estruturada, é esse o motivo, e o aviso no painel já sinaliza essa supressão.

Diferença entre Nó LLM e Nó Agent

	Nó LLM	Agente de IA
Raciocínio	Único passo	Multi-step (pensa, age, reavalia)
Ferramentas	Não	Sim (MCP, busca web, subagents)
Memória longa	Não	Sim (configurada no agent)
Configuração	No próprio nó	No Agent Builder, reutilizável

---

Saiba mais sobre o Agent Builder

Para aprender a criar e configurar agents completos — com instruções, memória, guardrails e ferramentas — acesse o guia dedicado:

Guia do Agent Builder →

Dica

O Agente de IA é ideal quando você quer que uma parte do fluxo seja "inteligente e autônoma" enquanto o resto do fluxo mantém controle total sobre o que acontece antes e depois.

Atenção

Um agent pode demorar mais para responder do que um nó LLM simples, porque ele pode executar várias etapas. Configure o timeout adequadamente para não ter respostas interrompidas em conversas longas.