--- title: Agente de IA description: Execute um agent configurado no Agent Builder diretamente dentro do seu fluxo. --- # Agente de IA · `agent` 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 Certifique-se de que o agent que você quer usar já está criado e publicado no Agent Builder.
 Arraste o nó **Agente de IA** para o canvas e conecte ao fluxo. No painel, selecione o **Agent** desejado na lista de agents disponíveis. Configure a **Mensagem de entrada** — geralmente {{userinput.query}} ou uma mensagem montada por um nó anterior. 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. 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](/guia/agents/memoria). --- ## 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](/guia/agents/memoria)) — 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. 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. 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 →](/guia/agents/o-que-e)** 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. 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.