Cenários e fluxos guiados

Os cenários são fluxos de conversa pré-definidos dentro de um assistente. Cada cenário tem um título, uma descrição (que serve de gatilho semântico), uma instrução em linguagem natural com os passos a seguir e, opcionalmente, uma lista de ferramentas que o assistente pode chamar enquanto executa o cenário.

Os cenários complementam a base de conhecimento. Onde os documentos respondem a perguntas pontuais, os cenários cobrem interações com começo, meio e fim — qualificar um lead, abrir um chamado, agendar um retorno, validar um cupom. Os cenários ficam no detalhe do assistente em Cenários.

Como um cenário é estruturado

Cada cenário tem quatro elementos:

• Título — identificador legível.
• Descrição — frase que descreve quando o cenário se aplica. O motor compara essa descrição com o contexto da conversa para decidir se ativa o cenário. Descrições específicas ("cliente pedindo segunda via de boleto vencido") funcionam melhor que descrições genéricas ("dúvida financeira").
• Instrução — texto livre, em formato de passos, descrevendo o que o assistente deve fazer dentro do cenário. Aqui você pode mencionar ferramentas customizadas com a notação [@Nome da Ferramenta](tool://slug_da_ferramenta). Quando o assistente executa o cenário, ele segue essa receita.
• Habilitado — controle on/off. Cenários desligados não influenciam a conversa.

Cada cenário vive dentro de um único assistente. Diretrizes de resposta e guardrails do assistente são automaticamente herdados, então o cenário não precisa repeti-los.

Cenário 1 — Triagem inicial

Descrição (gatilho): "primeira mensagem do cliente, ainda não sabemos o motivo do contato".

Instrução:

1. Cumprimente o cliente pelo nome (se disponível em atributos do contato).
2. Pergunte qual o objetivo da conversa de forma aberta.
3. Se a resposta for relacionada a vendas, transfira para a equipe Comercial usando handoff.
4. Se for suporte técnico, siga com perguntas de diagnóstico antes de qualquer transferência.
5. Se for cobrança, ofereça primeiro a consulta de boleto via base de conhecimento.

Cenário 2 — Qualificação de lead

Descrição (gatilho): "cliente novo demonstrando interesse no produto".

Instrução:

1. Pergunte o nome da empresa e o número aproximado de funcionários.
2. Pergunte quais ferramentas de atendimento usam hoje.
3. Pergunte qual o principal objetivo ao buscar uma plataforma nova.
4. Após coletar as três respostas, registre como atributos do contato e faça handoff para a equipe Comercial com a mensagem de transferência configurada no assistente.

Esse é um cenário típico em que ferramentas customizadas entram: você pode anexar uma ferramenta [@Criar lead no CRM](tool://create_crm_lead) nas instruções para o assistente, ao final do cenário, registrar o lead automaticamente em um sistema externo.

Cenário 3 — Consulta de pedido

Descrição (gatilho): "cliente perguntando o status de um pedido específico".

Instrução:

1. Peça o número do pedido se ele ainda não foi informado.
2. Use [@Consultar pedido](tool://get_order_status) passando o número como parâmetro.
3. Se a ferramenta retornar status, formate a resposta humanizada (data prevista de entrega, transportadora, código de rastreamento).
4. Se a ferramenta retornar erro ou pedido não encontrado, peça que o cliente confirme o número e ofereça transferir para um humano caso ele insista que está correto.

Cenário 4 — Agendamento de retorno

Descrição (gatilho): "cliente quer marcar uma conversa com a equipe ou retomar contato em outro horário".

Instrução:

1. Pergunte qual o melhor dia e horário.
2. Pergunte qual o canal preferencial (WhatsApp, telefone, e-mail).
3. Crie um lembrete usando a ferramenta de agendamento conectada.
4. Confirme com o cliente os dados antes de fechar o cenário.

Cenário 5 — Encerramento por inatividade

Descrição (gatilho): "conversa parada há tempo, sem nova interação do cliente".

Instrução:

1. Envie uma mensagem perguntando se a dúvida foi resolvida.
2. Aguarde resposta. Se positiva, envie a mensagem de resolução configurada no assistente.
3. Se não houver resposta em 24 horas, encerre a conversa silenciosamente.

Tornando cenários robustos

• Seja específico nas descrições. O motor decide quando ativar um cenário comparando a descrição com o que está acontecendo na conversa. Descrições vagas ativam cenário no momento errado.
• Mencione ferramentas com a sintaxe oficial. A notação [@Título](tool://slug) é validada no salvamento — se a ferramenta não existir ou estiver desabilitada, o cenário não salva.
• Não duplique guardrails dentro da instrução. Tudo o que o assistente já não pode fazer continua valendo dentro do cenário.
• Teste no playground. Antes de habilitar um cenário em produção, simule no playground variações da mensagem que deveriam acionar (e que não deveriam). Veja Métricas, playground e acompanhamento.

Quando cenário não é a resposta

Se a interação é uma pergunta direta com resposta na base de conhecimento (FAQ ou documento), você não precisa de cenário — o assistente resolve com a base. Use cenários quando há passos a seguir, dados a coletar ou ferramentas a chamar numa ordem definida.