Builder · Atualizado em 06/10/2026
Como usar o agente de IA no Builder
Configure o bloco Agente de IA: modelo, chave, instruções, direcionamentos e ferramentas, e teste antes de publicar o fluxo.
O bloco Agente de IA conversa com o contato usando um modelo de linguagem, seguindo instruções que você escreve. Ele continua respondendo no mesmo bloco até decidir direcionar o contato para outro caminho do fluxo.
Quando usar
Use o agente quando as perguntas do contato são abertas demais para um menu, por exemplo dúvidas sobre prazo, troca ou produtos. Prefira blocos comuns quando o caminho é previsível: um menu com três opções é mais barato de manter e mais fácil de testar. Um bom desenho combina os dois, com o agente cuidando das dúvidas e blocos comuns cuidando do que precisa de resposta exata.
Pré-requisitos
- Um fluxo aberto no Builder e permissão para editá-lo.
- Uma chave de acesso do provedor de IA que você escolher, cadastrada como variável sensível do fluxo. Veja variáveis sensíveis.
- Para publicar, a permissão de publicar fluxo.
Passo a passo
- Abra o fluxo e clique na aba Builder.
- Clique em Adicionar bloco e, no painel NOVO BLOCO, escolha Agente de IA.
- Clique no bloco criado. A primeira aba se chama Instruções.
- Na seção Modelo da LLM, escolha o Provedor (Anthropic ou OpenAI) e preencha Modelo. O campo sugere modelos e aceita outro nome digitado.
- Em Chave do provedor (variável sensível), deixe a opção Padrão ou escolha a variável sensível que guarda a chave. Se o fluxo ainda não tem essa variável, o painel avisa; clique em Abrir Variáveis sensíveis para cadastrá-la.
- Se quiser, ajuste Temperatura e Max tokens. Valores baixos de temperatura deixam as respostas mais previsíveis.
- Em Histórico de mensagens, ligue Armazenar histórico de mensagens para o agente lembrar o que já foi dito e informe a Quantidade de mensagens.
- Em Resposta, deixe ligado Enviar resposta ao contato e, se precisar usar o texto em outro bloco, ligue Salvar resposta em variável e preencha Nome da variável.
- Em Instruções para o agente, escreva o que ele deve fazer. Use
{{variável}}para trazer dados do fluxo, e Adicionar instrução para separar assuntos. - Abra a aba Condições de saída para definir os direcionamentos e a Saída de exceção.
- Se o agente precisar consultar algo, abra a aba Ações e adicione uma base de conhecimento, uma conexão MCP ou uma ferramenta.
- Teste no painel Teste de fluxo em construção e publique com Publicar fluxo.
Campos da tela
| Campo | O que faz |
|---|---|
| Provedor | Escolhe entre Anthropic e OpenAI. Cada agente tem o seu. |
| Modelo | Nome do modelo. É obrigatório. |
| Temperatura | Controla a variação das respostas. O limite é 1 para Anthropic e 2 para OpenAI. Alguns modelos não aceitam temperatura e o painel avisa. |
| Max tokens | Tamanho máximo da resposta, de 1 a 8192. |
| Chave do provedor (variável sensível) | Nome da variável sensível com a chave. O padrão é ANTHROPIC_API_KEY ou OPENAI_API_KEY, conforme o provedor. |
| Armazenar histórico de mensagens | Guarda as mensagens trocadas como contexto. O histórico é apagado quando o contato sai do bloco. |
| Quantidade de mensagens | De 1 a 100 mensagens. Se vazio, vale 50. |
| Enviar resposta ao contato | Envia ao contato o texto gerado. |
| Salvar resposta em variável | Guarda o texto em uma variável. O nome aceita letras, números, "_" e pontos. |
| Instruções para o agente | Orientações do agente. Pelo menos uma instrução é obrigatória. |
Direcionamentos e saída de exceção
Na aba Condições de saída, o item Direcionar para bloco aceita até 25 saídas. Cada direcionamento vira uma ferramenta do agente: quando ele a chama, o contato segue para o bloco escolhido.
- Nome: letras minúsculas, números e "_", com 3 caracteres ou mais, sem repetir.
- Instruções para o agente: descreva quando usar o direcionamento. É obrigatório.
- Schema dos parâmetros (JSON): opcional. Define o que o agente deve informar ao direcionar. O fluxo lê o resultado em
{{aiagent.parameters}}. - Direcionar usuário para: o bloco de destino.
A Saída de exceção define para onde o contato vai se o agente falhar, por exemplo por provedor indisponível, chave ausente, recusa ou excesso de chamadas de ferramentas. O motivo fica em {{aiagent.errorCode}}. Enquanto o agente conversa, a próxima mensagem do contato volta para o mesmo bloco.
Ferramentas do agente
Na aba Ações, a seção Ferramentas reúne o que o agente pode usar durante a conversa.
- Adicionar base de conhecimento: permite que o agente consulte os documentos da conta.
- Conectar MCP: conecta ferramentas externas por uma URL HTTPS pública. Informe Nome do servidor e URL do servidor MCP. Cabeçalhos de autenticação usam o nome de uma variável sensível, nunca o valor.
- Adicionar ferramenta: transforma uma ação do catálogo em ferramenta. O nome da ferramenta aceita letras minúsculas, números, "-" e "_", com no mínimo 3 caracteres, e a Descrição diz quando ela deve ser usada.
Exemplo na Loja Girassol
A Loja Girassol cria um agente para dúvidas de entrega.
- Provedor e modelo escolhidos, com a chave padrão cadastrada nas variáveis sensíveis.
- Instrução: "Você atende a Loja Girassol. Responda dúvidas sobre prazo e entrega em tom cordial. Se o cliente pedir para falar com uma pessoa, use o direcionamento atendimento."
- Um direcionamento chamado
atendimento, com a descrição "Use quando o cliente pedir um atendente", leva ao bloco Atendimento humano. - A Saída de exceção leva ao mesmo bloco Atendimento humano, para que ninguém fique sem resposta.
Resultado esperado
O fluxo contém o bloco configurado, sem marcas de erro. No teste, o agente responde seguindo as instruções e o direcionamento leva ao bloco certo. Depois de publicado, o contato conversa com o agente nesse ponto do fluxo.
Boas práticas
- Sempre aponte a Saída de exceção para um bloco que resolva a conversa, como o atendimento humano.
- Não escreva chaves, senhas nem dados pessoais nas instruções.
- Teste perguntas fora do assunto para ver se o agente respeita os limites que você deu.
Limitações
- O agente faz no máximo 6 chamadas ao modelo por resposta. Cada rodada de ferramentas conta como uma chamada.
- O histórico guardado por contato e por bloco tem tamanho limitado, e o resultado de uma ferramenta enviado ao modelo é truncado em 4 KB.
- Conexões MCP usam o transporte Streamable HTTP. Conexões antigas com outro transporte aparecem com aviso e não são executadas até você editar a conexão.
- Sem a chave do provedor, o fluxo publicado segue a saída de exceção.
Problemas comuns
- O painel mostra que o fluxo não tem a variável sensível: cadastre a chave em Configuração, aba Variáveis, seção VARIÁVEIS SENSÍVEIS, com o nome exato mostrado no aviso.
- O teste responde com [Simulação]: a chave não foi encontrada. O teste só chama o provedor de verdade quando a variável existe.
- O bloco fica vermelho: confira se há modelo, ao menos uma instrução, nomes de direcionamento válidos e destino escolhido para cada um.
- O campo Temperatura está desabilitado: o modelo escolhido não aceita temperatura e o valor guardado é ignorado.
- O agente nunca direciona: revise a descrição do direcionamento. Ela precisa dizer com clareza em que situação ele deve ser usado.
Próximos passos
Perguntas frequentes
Onde encontro o agente de IA?
No Builder, clique em Adicionar bloco e escolha Agente de IA no painel NOVO BLOCO.
Onde coloco a chave do provedor?
Em Configuração, aba Variáveis, seção VARIÁVEIS SENSÍVEIS. O bloco só guarda o nome da variável; o valor da chave nunca fica no desenho do fluxo.
O que acontece se o agente falhar?
O contato segue para o bloco definido em Saída de exceção. O código do motivo fica na variável aiagent.errorCode.
O teste usa a IA de verdade?
Só quando a chave do provedor existe nas variáveis sensíveis do fluxo. Sem chave, o teste responde em modo simulação, com o prefixo [Simulação].
Preciso publicar depois de editar?
Sim. Teste a mudança e publique uma nova versão para que ela passe a valer para os contatos.
Esse artigo foi útil?
Obrigado pelo retorno!