---
title: Instruções e Modelo
description: Como escrever boas instruções para o seu Agent e configurar o modelo de IA (LLM) certo para cada situação.
---

# 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.

<Captura legenda="Aba Identidade do Agent com os campos Nome, Descrição, Tipo, Modelo e Instrução (System Prompt)." src="/img/agent-instrucoes-campo.png" />

## 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'."

<Captura legenda="Campo Instrução (System Prompt) do Agent preenchido com um exemplo de instrução." src="/img/agent-instrucoes-campo.png" />

<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.

</Dica>

### 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.

<Cuidado>

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.

</Cuidado>

## 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 <code v-pre>{{ }}</code> 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 |
|----------|-------------|
| <code v-pre>{{event.contact.name}}</code> | Nome do contato |
| <code v-pre>{{userinput.query}}</code> | Última mensagem enviada pelo usuário |
| <code v-pre>{{conversation.id}}</code> | ID da conversa atual |
| <code v-pre>{{vars.nome_da_variavel}}</code> | Qualquer variável definida no fluxo |

<Captura legenda="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." src="/img/agent-instrucoes-campo.png" />

## 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 |

<Captura legenda="Aba Identidade do Agent com o seletor de Modelo e o campo Instrução (System Prompt)." src="/img/agents-wizard-identidade.png" />

<Cuidado>

**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.

</Cuidado>

**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.

<Cuidado>

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.

</Cuidado>

## Saiba mais

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