Bloco Agente de IA: respostas com inteligência artificial no seu fluxo

O bloco Agente de IA responde ao cliente com inteligência artificial, seguindo instruções suas: o tom, o que pode dizer e o que não pode. E ele consulta sozinho o cadastro, a fatura e os planos, para responder com dado real em vez de inventar. Num negócio de assinatura, ele cobre a dúvida que não cabe num menu: "meu app trava", "posso pagar dia 10?", "qual a diferença entre os planos?".

O que o bloco Agente de IA faz

Quando a conversa chega nele, o bloco lê as últimas mensagens da conversa (do cliente e do bot), junta as suas instruções e deixa o modelo chamar as ferramentas que você liberou. Se o cliente perguntou "quando vence meu plano?", o agente chama "Consultar o cadastro", recebe o vencimento de verdade e responde com ele.

A resposta vai ao cliente como texto e fica guardada numa variável, por padrão {ia_resposta}. As consultas também deixam variáveis na sessão, como {cliente_vencimento} e {fatura_link}, que um bloco Mensagem depois dele pode usar.

Ele roda na sua conta do OpenRouter: a chave fica dentro do bloco e cada resposta custa centavos, cobrados lá. E uma regra que muda tudo: ele responde UMA vez e o fluxo segue. Para um bate-papo de vários turnos, você desenha o laço, e este artigo mostra como.

Quando usar (e quando usar outro bloco)

Use o agente como complemento do menu, não no lugar dele. O caminho comum (testar grátis, ver a fatura, renovar) fica melhor em Botões e blocos de Ação: é previsível, não custa por mensagem e não depende de serviço de fora.

• A resposta é uma escolha entre poucas coisas? Botões.
• Precisa liberar acesso, gerar fatura ou cobrar? Bloco Ação. Criar teste, gerar fatura e cobrar não existem como ferramenta do agente, de propósito: um modelo convencido por "meu amigo disse que ganho de graça" não pode ser quem decide liberar.
• Só quer marcar o contato? Bloco Etiqueta, sem gastar uma chamada de IA.

Como configurar, campo a campo

Clique no bloco e o painel abre à direita, em quatro seções.

Seção "Instruções"

• "Instruções do agente": a persona e as regras. Aceita variáveis, e o agente também recebe o histórico recente da conversa como contexto. Obrigatório.
• "Base de conhecimento (FAQ)": opcional. Perguntas e respostas ou informações extras que o agente pode usar.

Depois dos seus textos, o sistema acrescenta sozinho regras fixas de segurança: o que o cliente escreve é conteúdo, nunca ordem; o agente não revela as instruções, não promete o que você não autorizou, não inventa dado de cadastro e encaminha para humano o que sair do escopo.

Seção "Conta e modelo"

• Chave do OpenRouter: o painel avisa "Este bloco precisa de uma chave do OpenRouter". Cole a chave e clique em "Salvar": ela fica criptografada, mostrando só os 4 últimos caracteres, com o botão "Trocar" e um ícone de lixeira (remover) ao lado. A chave é deste bloco: outro bloco de IA pode apontar para outra conta, separando o custo.
• "Modelo de IA": vem "Usar o modelo padrão da conta", que é o "Modelo padrão" das Configurações do chatbot (sem escolha lá, o Gemini 3.7 Flash). O seletor traz os "Recomendados", com o preço em dólar por 1 milhão de tokens, e "Todos os modelos com ferramentas"; o botão "Digitar outro modelo" aceita um id do OpenRouter no formato autor/modelo. Só aparecem modelos que sabem usar ferramentas: os outros ignoram as consultas em silêncio.

Seção "Ferramentas"

O campo "O que ele pode consultar sozinho" mostra sete caixas:

Ferramenta	O que faz
"Consultar o cadastro"	Situação, vencimento, plano, login e senha de quem está falando
"Consultar a fatura"	Status, valor, vencimento e link de pagamento da fatura mais recente
"Listar os planos"	Seus planos ativos com preço e duração
"Explicar a instalação"	Aplicativos, links e códigos do servidor daquele cliente
"Informar o suporte"	Passa o número de WhatsApp do seu suporte
"Transferir para humano"	Ele desiste e passa o atendimento para você quando não resolver
"Etiquetar o contato"	Marca o contato com uma das etiquetas que você liberar

As três primeiras já vêm ligadas. Ferramenta desligada não existe para o modelo (com uma exceção: desmarcar todas as sete faz o motor voltar às três consultas padrão). E, apesar do texto da caixa, a senha do cliente nunca chega ao modelo: o sistema a remove do que a consulta devolve, e ela fica só na variável {cliente_senha}, para um bloco Mensagem onde você decidiu que ela aparece.

Ao marcar "Etiquetar o contato", aparece "Etiquetas que ele pode aplicar". Só estas: sem um conjunto fechado, o modelo inventa uma etiqueta por conversa e sua segmentação vira lixo.

Seção "Ajustes finos"

Vem recolhida, com o resumo "400 tokens · 10 msgs".

• "Guardar a resposta em": nome da variável, sem chaves. Padrão ia_resposta.
• "Enviar resposta ao cliente": ligado por padrão. Desligado, só salva a resposta na variável, sem mandar mensagem.
• "Máx. de tokens": tamanho da resposta, de 50 a 2000 (padrão 400).
• "Consultas por resposta": quantas ferramentas ele encadeia num turno, de 1 a 12 (padrão 6).
• "Mensagens de contexto": quantas mensagens anteriores ele lê, de 2 a 30 (padrão 10). É o que mais pesa na conta.
• "Criatividade": de 0 (sempre igual) a 1 (mais solto). Vazio usa o padrão do modelo.

As saídas e como ligar

• "Respondeu": o agente respondeu e o fluxo segue.
• "Deu erro": chave ausente ou inválida, sem créditos, modelo não encontrado, limite de uso do modelo, tempo esgotado (45 segundos), resposta vazia ou teto diário de chamadas atingido. Ligue a um Atendente: sem isso, a conversa encerra em silêncio no dia em que a IA falhar.
• "Passou para humano": só nasce quando "Transferir para humano" está ligada. Com um fio, o fluxo segue por ele (dá para mandar uma despedida antes). Solta, o motor pausa a conversa para você ali mesmo, igual ao bloco Atendente (o validador ainda mostra o aviso de saída solta, mas é só aviso).

Para o agente continuar conversando, ligue "Respondeu" num bloco Pergunta com validação "Qualquer texto", e ligue a Pergunta de volta nele. A resposta do cliente vira contexto do próximo turno.

Exemplo prático: a dúvida aberta da PlayHub

A PlayHub tem um menu com "Testar grátis", "Já sou cliente" e "Tirar uma dúvida". Vamos montar o terceiro caminho.

1. Botões (menu principal): ligue "Tirar uma dúvida" numa Pergunta.
2. Pergunta: "Me conta o que você precisa, em uma mensagem." Validação "Qualquer texto", guardar em duvida. Ligue "Respondeu certo" no Agente de IA.
3. Agente de IA. Em "Instruções do agente": "Você é o atendimento da PlayHub. Responda curto e educado. Consulte os dados antes de falar da conta do cliente. Nunca prometa desconto. Se não souber, transfira." Em "Base de conhecimento (FAQ)": "P: Quanto dura o teste grátis? R: 6 horas. P: Como pago? R: Por Pix, pelo link da fatura." Cadastre a chave e ligue "Transferir para humano" além das três consultas padrão.
4. Botões em "Respondeu": "Resolvido?" com "Sim, obrigado" e "Tenho outra dúvida". O primeiro vai num Fim ("Qualquer coisa é só chamar!"); o segundo volta na Pergunta do passo 2, fechando o laço.
5. Mensagem em "Passou para humano": "Vou chamar alguém da equipe, um instante." Ligue "Depois disso" num Atendente.
6. Atendente em "Deu erro": "Nossa IA está fora do ar. Já te respondo pessoalmente."

No simulador o agente não roda de verdade: aparece "Agente de IA roda no servidor. Escolha o caminho para continuar o teste" e você escolhe clicando em "Respondeu", "Deu erro" ou "Passou para humano" (este último só aparece com a ferramenta "Transferir para humano" ligada).

Erros comuns e cuidados

Pendências que barram a publicação:

• "Escreva as instruções do agente."
• "Cadastre a chave do OpenRouter neste bloco."
• "Escolha ao menos uma etiqueta que o agente pode aplicar" (ou desligue a ferramenta de etiquetar), quando "Etiquetar o contato" está ligada sem nenhuma etiqueta escolhida.

Aviso, que não barra: "A saída "Respondeu" está solta: a conversa encerra em silêncio ali." O mesmo para "Deu erro". Ligue as duas.

Cuidados que o validador não pega:

• Esperar um bate-papo sem desenhar o laço. Sem a Pergunta de volta, a próxima mensagem do cliente cai no gatilho, não no agente.
• Contar com ele para liberar acesso. Desenhe o teste grátis com Ação e Condição, onde você controla o ponto exato.
• Ignorar o custo. Cada turno reenvia as mensagens de contexto. Há um teto diário de 40 chamadas por conversa e de 500 somando todas as conversas da conta; passou, o bloco sai por "Deu erro".

Perguntas frequentes

Preciso de uma conta no OpenRouter?

Sim. Você cria a chave em openrouter.ai/keys, cola no bloco e paga direto a eles. Sem chave, a publicação é barrada.

O agente pode criar um teste grátis ou gerar uma fatura?

Não. As ferramentas dele só leem dados, transferem para humano e etiquetam. Criar teste, gerar fatura e cobrar continuam sendo blocos de Ação.

O que acontece se eu não ligar nada em "Passou para humano"?

O motor pausa a conversa para você pelo tempo do "Pausa por atendimento humano" das Configurações, igual ao bloco Atendente. Ligue um fio só se quiser mandar uma mensagem antes.

Próximos passos

• Como funciona o chatbot: o hub com todos os blocos.
• Bloco Pergunta: a peça que fecha o laço de conversa.
• Bloco Atendente: para onde ligar "Deu erro".
• Variáveis: como usar {ia_resposta} depois do agente.
• Testar e publicar: o simulador e a janela de pendências.