Instruções e Modelo

Pensa assim: as instruções do Agent são o "manual de treinamento" do seu atendente virtual. Quanto mais claro e detalhado for esse manual, melhor ele vai se comportar. O modelo de IA (também chamado de LLM — o tipo de inteligência artificial que entende e gera texto) é o "cérebro" que vai executar essas instruções — e escolher o cérebro certo faz diferença no custo e na qualidade das respostas.

Aba Identidade do Agent com os campos Nome, Descrição, Tipo, Modelo e Instrução (System Prompt).

Tipos de Agent

Antes de configurar, escolha o tipo certo para o seu caso de uso:

Tipo	Quando usar
LLM	Conversas simples com um único modelo. Ideal para começar.
Sequencial	Tarefas com etapas definidas em sequência (ex.: coletar dados → validar → responder).
Paralelo	Quando você quer consultar várias fontes ao mesmo tempo (mais rápido).
Loop	Quando o Agent precisa repetir um ciclo até atingir um resultado (ex.: refinar uma resposta).

Campo: Instruções

As instruções são o texto que define a personalidade, o escopo e as regras de comportamento do Agent — o que na área de IA às vezes é chamado de "system prompt".

Boas práticas para escrever instruções:

• Comece com identidade: "Você é um assistente de atendimento da empresa X."
• Defina o tom: "Responda de forma educada, direta e em português."
• Liste o que pode e o que não pode: "Não forneça preços. Não discuta concorrentes."
• Dê exemplos de resposta para casos comuns: o Agent vai aprender o padrão.
• Inclua como lidar com o que não sabe: "Se não souber a resposta, diga 'Não tenho essa informação e vou verificar com nossa equipe'."

Campo Instrução (System Prompt) do Agent preenchido com um exemplo de instrução.

Dica

Escreva as instruções como se estivesse explicando para uma pessoa nova na empresa. Não use siglas internas sem explicá-las — o Agent não conhece o contexto da sua empresa a não ser pelo que você escrever aqui.

Regra de Voz: fale DIRETO ao contato (sem narração interna)

Agents que respondem ao cliente no WhatsApp têm um erro comum: o modelo começa a "apresentar" a resposta como se estivesse entregando uma tarefa, em vez de falar diretamente como o atendente.

Exemplos de respostas erradas que o modelo pode gerar:

• "Negócio criado e tag adicionada! Agora vou responder o Lucas. Preciso criar o produto primeiro... Primeiro, a conversa: *Ótimo, Lucas!*…"
• "Perfeito! Aqui está o atendimento: Olá, Lucas! Entendi, você quer saber sobre atraso de viagem."

Por que acontece: o modelo trata as ações internas (como atualizar o CRM) como parte do próprio raciocínio e narra tudo em voz alta, para só depois "entregar" a mensagem ao contato como se fosse um produto pronto.

Como corrigir nas instruções: inclua uma orientação de voz explícita. Exemplo de bloco para adicionar no campo de instruções:

VOZ: você fala DIRETO ao contato no WhatsApp, em 1ª pessoa, como se a mensagem já estivesse na tela dele. A sua saída É a mensagem — sem moldura.
- NUNCA narre ações internas (criar/mover negócio, aplicar tag, associar produto, consultar sistema).
- NUNCA anuncie o que vai fazer ("Agora vou...", "Preciso criar...", "Vou verificar...").
- NUNCA use preâmbulo de entrega ("Perfeito! Aqui está:", "Primeiro, a conversa:", "Aqui está o atendimento:").
- Confirmações ao contato são naturais e sobre o serviço ("Pronto, agendei para...", "Enviei o contrato!"), nunca sobre operações internas de sistema.

Coloque esse bloco antes das regras de negócio, para que o modelo trate a voz como uma restrição de formato, não como detalhe opcional.

Atenção

Agents orquestradores (que apenas roteiam a conversa para outro agent, sem falar com o contato) não devem receber essa regra — eles nunca devem gerar texto para o lead. A regra de voz é exclusiva para agents que efetivamente respondem na conversa.

Campo: Modelo de Mensagem

O modelo de mensagem (template) define como a entrada do cliente chega até o Agent. Você pode usar variáveis do fluxo para enriquecer essa entrada com contexto.

Exemplo:

Cliente: {{event.contact.name}}
Mensagem: {{userinput.query}}
Histórico de compras: {{vars.purchase_history}}

As variáveis entre {{ }} são preenchidas automaticamente com dados do fluxo no momento em que o Agent é acionado. Isso permite que o Agent já receba contexto do cliente sem precisar perguntar.

Variáveis disponíveis comuns:

Variável	O que contém
{{event.contact.name}}	Nome do contato
{{userinput.query}}	Última mensagem enviada pelo usuário
{{conversation.id}}	ID da conversa atual
{{vars.nome_da_variavel}}	Qualquer variável definida no fluxo

Formulário de Identidade do Agent com os campos Nome, Descrição, Tipo, Modelo e Instrução, onde variáveis do fluxo também podem ser referenciadas.

Modelo e Configuração

Aqui você escolhe qual IA vai "pensar" pelas instruções que você escreveu.

Campos de configuração:

Campo	O que faz
Provedor	Quem fornece o modelo: OpenAI, Anthropic, Google, etc.
Modelo	O modelo específico: gpt-4o, claude-sonnet-4-5, gemini-pro, etc.
Modo	Conversacional (chat) ou geração de um único texto (completion)
Parâmetros avançados	Temperatura, tamanho máximo de resposta, e outros controles avançados de geração

Aba Identidade do Agent com o seletor de Modelo e o campo Instrução (System Prompt).

Atenção

Atenção ao escolher entre um modelo nativo e o mesmo modelo via OpenRouter. O catálogo mostra, para vários modelos, duas entradas com o mesmo nome amigável — uma servida diretamente pelo provedor (ex.: OpenAI, Google, xAI) e outra servida via OpenRouter (um serviço intermediário que dá acesso a vários provedores com uma única credencial). Elas usam credenciais diferentes e o comportamento em runtime muda conforme qual você escolhe:

• Se o identificador do modelo não tem / (ex.: gpt-4o-mini, o1, gemini-2.5-flash) → o Agent usa a credencial nativa do provedor correspondente (OpenAI, Google, xAI etc.), configurada em Conexões.
• Se o identificador do modelo tem / (ex.: openai/gpt-4o-mini, google/gemini-2.5-flash) → o Agent usa a credencial do OpenRouter.

O seletor de modelo no Flow Builder mostra o identificador completo (abaixo do nome, na lista e no campo já selecionado) exatamente para deixar isso claro. Se o identificador não tiver a credencial correspondente configurada no workspace, o Agent falha ao tentar chamar o modelo. Confira sempre o identificador — não só o nome — antes de salvar.

Dica de escolha de modelo:

• Para conversas longas e complexas → modelos maiores (gpt-4o, claude-opus)
• Para respostas rápidas e custo menor → modelos menores (gpt-4o-mini, claude-haiku)
• Para análise de imagens → modelos com suporte a visão

Max Iterations

Para Agents do tipo Loop ou Sequencial, você pode definir o número máximo de repetições ou passos. Isso evita loops infinitos caso algo inesperado aconteça.

Valor padrão: varia por tipo. Recomendamos começar com 10 e ajustar conforme o comportamento observado.

Atenção

Valores muito altos de Max Iterations podem aumentar o custo (mais chamadas ao modelo de IA) e o tempo de resposta. Monitore o comportamento e ajuste com base em uso real.

Saiba mais

• Memória — fazer o Agent lembrar de conversas anteriores
• Ferramentas do Agent — conectar sistemas externos, skills e sub-agents
• Avaliação de Agents (Eval) — pontuar as respostas do Agent contra um conjunto de testes
• Otimização de instruções (Optimizer) — reescrever a instrução automaticamente com base no Eval