# Agilize Docs para IA - Página atual

Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize.
Use esta versão quando a pergunta do usuário estiver restrita ao documento atual.

Última geração: 2026-05-28T23:47:08.229Z

## Página

- Título: Agentes de IA em fluxos do bot
- URL humana: https://agilize.app/docs/configuracao/fluxos-automacoes/agentes-ia-fluxos-bot
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Como configurar conta de provedor, agente de IA, prompt, variáveis de saída, intenções e conexão com nodes em fluxos do bot.

## Seções

- Visão geral
- Quando usar
- Premissas importantes
- Configure a conta do provedor
- Crie o agente de IA
- Escreva o prompt do agente
- Configure variáveis de saída
- Configure intenções

## Conteúdo da página

# Agentes de IA em fluxos do bot

Agentes de IA ajudam o fluxo do bot a interpretar mensagens abertas, capturar informações importantes e escolher a próxima rota da conversa. Eles devem ser usados como parte de uma jornada desenhada, com intenção clara, fallback e transferência segura quando a IA não tiver confiança ou quando a decisão exigir atendimento humano.

Use este guia para configurar a conta do provedor, criar o agente, definir prompt, variáveis de saída, intenções e conectar o agente ao ponto correto do fluxo.

## Visão geral

---
title: "Como o agente de IA entra no fluxo"
caption: "A conta de integração fornece a chave, o agente define comportamento e o node conecta esse agente ao caminho do bot."
definition: |
  flowchart LR
    A[Conta do provedor de IA] --> B[Agente de IA]
    B --> C[Prompt e instruções]
    B --> D[Variáveis de saída]
    B --> E[Intenções]
    C --> F[Node Agente de IA no fluxo]
    D --> F
    E --> F
    F --> G{Intenção detectada?}
    G -->|Sim| H[Rota específica do fluxo]
    G -->|Não ou erro| I[Transbordo de segurança]
    H --> J[Mensagem, condição, integração ou transferência]
---

## Quando usar

Use agente de IA quando o cliente pode escrever de várias formas e o fluxo precisa interpretar contexto antes de decidir o caminho.

Bons casos:

- identificar se o cliente quer comprar, suporte, financeiro, segunda via ou atendimento humano;
- coletar dados em texto livre, como nome, e-mail, telefone, empresa, produto de interesse ou motivo do contato;
- classificar a intenção antes de transferir para um departamento;
- resumir uma triagem inicial antes de entregar ao operador;
- combinar perguntas abertas com rotas objetivas no fluxo.

Evite usar IA para substituir regras simples. Se a decisão depende apenas de um botão, horário, tag ou campo preenchido, um node de condição costuma ser mais previsível.

## Premissas importantes

O agente de IA executa dentro do momento atual do fluxo. Ele interpreta a mensagem recebida, pode responder ao cliente, preencher variáveis e escolher uma rota por intenção.

Ele não deve ser tratado como processo em segundo plano. Sozinho, o agente não cria lembretes futuros, não monitora prazos continuamente, não executa rotinas fora da conversa e não substitui nodes de espera, automações de CRM, templates, tarefas ou integrações.

Quando precisar aguardar prazo, disparar follow-up, criar tarefa, enviar mensagem posterior ou revalidar condição, use os nodes e automações próprias da plataforma. O agente pode decidir a rota, mas o fluxo deve executar a ação.

## Configure a conta do provedor

![Cadastro de conta de provedor de IA com nome, chave de API e provider](/docs/screenshots/ia-provider-conta-integracao.png)

A conta do provedor armazena a chave usada pelos agentes de IA do projeto.

Acesse [https://my.agilize.app/messenger/ai/providerAccount](https://my.agilize.app/messenger/ai/providerAccount).

Preencha:

| Campo | Como usar | Cuidado |
| --- | --- | --- |
| Name | Nome administrativo da conta, como `OpenAI - produção` ou `OpenAI - testes`. | Use nome que diferencie ambiente e finalidade. |
| ApiKey | Chave de API do provedor. | Trate como segredo. Não compartilhe em prints, tickets, prompts ou documentação. |
| Provider | Provedor da conta. Atualmente a opção configurável é `openai`. | Use a conta correta para evitar falhas no agente. |

Depois de salvar, essa conta fica disponível no cadastro do agente.

## Crie o agente de IA

![Cadastro de agente de IA com modelo, conta integrada, instruções, intenções e variáveis de saída](/docs/screenshots/ia-agente-configuracao.png)

Acesse [https://my.agilize.app/messenger/ai/agent](https://my.agilize.app/messenger/ai/agent).

Preencha:

| Campo | Como usar | Impacto |
| --- | --- | --- |
| Nome do Agente | Nome operacional do agente. | Ajuda a selecionar o agente correto no node do fluxo. |
| Modelo de IA | Modelo usado na execução. | Afeta custo, velocidade e capacidade de interpretação. |
| Conta Integrada | Conta de provedor criada anteriormente. | Define qual chave será usada para executar o agente. |
| Instruções do Agente | Prompt principal do agente. | Define comportamento, tom, limites, critérios de intenção e uso de variáveis. |
| Intenções | Rotas que o agente pode escolher. | Cada intenção vira uma saída no node do fluxo. |
| Variáveis de Saída | Dados que o agente pode capturar da conversa. | Podem alimentar mensagens, condições, cadastro e contexto para o operador. |
| Arquivos Treinamento (ChatGPT) | IDs e nomes de arquivos de apoio, quando usados. | Devem conter conteúdo estável e revisado. |

## Escreva o prompt do agente

O campo **Instruções do Agente** deve explicar o papel da IA, o limite da decisão e como escolher intenções.

Um prompt útil costuma ter:

- objetivo do agente;
- tom de resposta esperado;
- dados que devem ser coletados;
- quando responder ao cliente;
- quando escolher uma intenção e parar;
- quando encaminhar para atendimento humano;
- regras de segurança e fallback;
- exemplos curtos de mensagens do cliente e intenção esperada.

Exemplo de estrutura:

```text
Você é um agente de triagem comercial da Agilize.

Objetivo:
- entender a necessidade inicial do cliente;
- identificar se ele quer contratar, falar com suporte, tratar financeiro ou falar com um atendente;
- coletar nome, telefone, e-mail e empresa quando forem informados naturalmente.

Regras:
- faça perguntas curtas, uma por vez;
- não prometa prazos, descontos ou condições comerciais;
- se o cliente pedir humano, escolha a intenção falar_com_atendente;
- se não tiver segurança, escolha transbordo_seguro;
- quando identificar uma intenção, use exatamente uma das intenções configuradas.

Critérios:
- comercial: cliente quer conhecer, contratar, testar ou receber proposta;
- suporte: cliente relata erro, dificuldade de uso ou problema operacional;
- financeiro: cliente fala de boleto, cobrança, nota ou pagamento;
- falar_com_atendente: cliente pede pessoa, humano, consultor ou especialista.
```

Mantenha o prompt objetivo. Um prompt longo e contraditório tende a gerar rotas inconsistentes.

## Configure variáveis de saída

Variáveis de saída são dados que o agente pode extrair da conversa. No cadastro do agente, cada variável tem **Nome** e **Descrição**.

Exemplos:

| Nome | Descrição recomendada |
| --- | --- |
| `nome` | Nome da pessoa que está falando, sem saudação. |
| `email` | E-mail informado pelo cliente. |
| `telefone` | Telefone com DDI ou DDD quando disponível. |
| `empresa` | Nome da empresa ou organização citada pelo cliente. |
| `interesse` | Produto, serviço ou necessidade principal mencionada. |

Use nomes simples, sem espaços e estáveis. Esses nomes podem ser usados depois por outros nodes, por mensagens com variáveis, por condições e por cadastros.

Impactos importantes:

- variável bem descrita aumenta a chance de captura correta;
- variável com nome ambíguo dificulta manutenção do fluxo;
- se a variável puder ficar vazia, o fluxo precisa tratar esse cenário;
- se a variável for crítica, valide com uma pergunta específica antes de criar cadastro ou transferir;
- ao marcar **Fixar variáveis de saída na sala** no node, os valores capturados podem ficar destacados na conversa para apoiar o operador.

## Configure intenções

Intenções são os caminhos que o agente pode escolher. No cadastro do agente, cada intenção tem **Nome** e **Descrição**.

Exemplos:

| Nome | Descrição recomendada |
| --- | --- |
| `comercial` | Cliente quer conhecer, contratar, testar, receber proposta ou falar sobre compra. |
| `suporte` | Cliente relata problema, dúvida operacional, erro ou dificuldade de uso. |
| `financeiro` | Cliente fala de cobrança, boleto, nota fiscal, pagamento ou contrato. |
| `falar_com_atendente` | Cliente pede atendimento humano, consultor, vendedor ou especialista. |
| `transbordo_seguro` | O agente não tem segurança para classificar ou precisa encaminhar para humano. |

Cada intenção configurada no agente se torna uma saída no node **Agente de IA** quando o agente é selecionado no fluxo. A primeira saída é a rota de segurança para erro ou transbordo. As demais saídas seguem as intenções cadastradas.

As intenções devem representar rotas reais. Evite criar intenção sem próximo passo definido.

## Conecte o agente no fluxo do bot

Acesse [https://my.agilize.app/messenger/bot/flow](https://my.agilize.app/messenger/bot/flow), abra o fluxo e adicione o node **Agente de Inteligência Artificial** no ponto em que a conversa precisa de interpretação.

Configure o node:

| Campo | Como usar |
| --- | --- |
| Agente de IA | Selecione o agente cadastrado. |
| Modelo de IA | Confirme o modelo que será usado nesse ponto do fluxo. |
| Habilitar Transcrição de Áudio | Use quando mensagens de áudio puderem ser interpretadas pelo agente. |
| Manter contexto entre conversas | Use quando fizer sentido reutilizar contexto salvo na sala para novas interações. |
| Fixar variáveis de saída na sala | Use quando o operador precisa ver os dados capturados com destaque. |
| Omitir primeira mensagem do usuário | Use quando a mensagem que chegou ao node não deve ser considerada como primeira entrada do agente. |
| Sobrescrever Primeiro Prompt | Use para adicionar uma instrução temporária apenas naquele ponto do fluxo. |

Depois de selecionar o agente, conecte as saídas:

1. Conecte a saída de segurança a uma mensagem de fallback ou transferência humana.
2. Conecte cada intenção a um caminho específico.
3. Depois de cada intenção, use nodes apropriados: mensagem, condição, gerar lead, transferir departamento, chamar API, registrar tag ou finalizar.
4. Teste cada saída manualmente antes de publicar.

## Onde colocar o node

O node de IA funciona melhor depois que o fluxo já deu contexto mínimo ao cliente.

Bons pontos:

- depois da mensagem inicial de boas-vindas;
- depois de uma pergunta aberta, como “Como podemos ajudar?”;
- depois de coletar um dado básico que ajude a roteamento;
- antes da transferência para atendimento humano;
- antes de criar lead, quando a intenção comercial precisa ser confirmada.

Evite colocar o agente antes de explicar o objetivo da conversa. Sem contexto, a IA tende a interpretar mensagens curtas de forma menos confiável.

## Use nodes depois da IA

O agente decide ou captura, mas o fluxo executa.

Exemplos:

| Resultado da IA | Próximo node recomendado |
| --- | --- |
| Intenção `comercial` | Mensagem de confirmação, gerar lead e transferir para comercial. |
| Intenção `suporte` | Coletar descrição do problema, gerar suporte ou transferir para suporte. |
| Intenção `financeiro` | Enviar orientação inicial ou transferir para financeiro. |
| Variável `email` preenchida | Condição para validar se existe e usar em cadastro. |
| Variável `interesse` preenchida | Mensagem com resumo ou campo no lead. |
| Falha ou intenção incerta | Mensagem curta e transferência segura. |

Não deixe a saída do agente terminar sem ação. Cada rota deve ter continuidade clara.

## Boas práticas para prompts

- Escreva em português correto, com instruções objetivas.
- Separe objetivo, regras, intenções e exemplos.
- Use os mesmos nomes das intenções cadastradas.
- Explique quando o agente deve responder e quando deve apenas rotear.
- Inclua critérios de transbordo para humano.
- Evite pedir decisões que dependem de análise jurídica, financeira ou aprovação humana.
- Não prometa ações que o fluxo não executa.
- Não peça para o agente “lembrar depois” ou “monitorar o cliente”; use nodes de espera, automações ou tarefas.
- Revise periodicamente intenções que caem muito em fallback.
- Teste com mensagens reais de clientes, incluindo erros de digitação, áudio, frases curtas e pedidos ambíguos.

## Teste antes de publicar

Roteiro mínimo:

1. Teste uma mensagem para cada intenção.
2. Teste uma mensagem ambígua e confirme se cai no transbordo seguro.
3. Teste variáveis com dados completos e incompletos.
4. Teste áudio se a transcrição estiver habilitada.
5. Confira se variáveis destacadas aparecem para o operador quando essa opção estiver ativada.
6. Confirme se a conversa chega ao Flow com contexto suficiente quando houver transferência humana.
7. Revise se nenhuma saída ficou sem conexão.

## Problemas comuns

| Sintoma | Causa provável | Correção |
| --- | --- | --- |
| Agente sempre cai no transbordo | Conta, modelo, chave ou agente incompleto; intenção não conectada; mensagem sem contexto. | Revise conta integrada, node, intenções e saída de segurança. |
| Intenção errada | Prompt genérico ou descrição de intenção parecida. | Escreva critérios mais objetivos e exemplos de decisão. |
| Variável não aparece | Variável não foi configurada no agente ou não foi identificada na mensagem. | Revise nome, descrição e teste com frases mais realistas. |
| Operador recebe conversa sem contexto | Variáveis não foram capturadas, não foram fixadas ou o fluxo transferiu cedo demais. | Capture dados antes da transferência e ative destaque quando fizer sentido. |
| IA promete algo que a operação não faz | Prompt deixou margem para compromisso comercial ou operacional. | Inclua limites explícitos e direcione casos sensíveis para humano. |

## Próximos passos

- Para montar a jornada completa, veja [Guia geral de fluxos do bot](/docs/configuracao/fluxos-automacoes/guia-geral-de-fluxos-do-bot).
- Para entender a referência do node, veja [Agente de Inteligência Artificial](/docs/configuracao/referencias/nodes-fluxos-do-bot/agente-de-inteligencia-artificial).
- Para conectar o resultado a cadências e ações futuras, veja [Cadências de envio e follow-up por automação](/docs/configuracao/fluxos-automacoes/cadencias-envio-follow-up-automacao).