> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inceptia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros comuns

> Os erros mais frequentes ao construir um bot na Inceptia, e o checklist antes de publicar

## Erros frequentes

Estes são os erros que mais vemos se repetir ao revisar bots — a maioria é fácil de evitar assim que você sabe que existem.

<AccordionGroup>
  <Accordion title="Usar uma variável que não está definida no contexto" icon="triangle-exclamation">
    Se você escrever `{variable}` na Mensagem Inicial ou nas Instruções e essa variável não chegou ao `context` — nem pelo [arquivo de campanha](/pt-BR/construccion/archivo-entrada-campana) nem pelo [Código Inicial](/pt-BR/construccion/agentes/logica) — ela fica vazia durante a conversa em vez de gerar um erro visível. Antes de publicar, verifique se toda variável que você usa está de fato mapeada ou inicializada. Veja [Variáveis disponíveis](/pt-BR/construccion/agentes/identidad).
  </Accordion>

  <Accordion title="Não incluir as etiquetas no prompt do agente classificador" icon="tag">
    As [etiquetas](/pt-BR/construccion/etiquetas) são predefinidas pela Inceptia, mas é o agente Pós-Conversa que as atribui — e só consegue fazer isso se seu prompt incluir a lista completa com uma descrição clara de quando usar cada uma.
  </Accordion>

  <Accordion title="Assumir que as condições de Mudança de Agente são avaliadas todas juntas" icon="arrow-right-arrow-left">
    As condições são avaliadas **na ordem em que são carregadas** — a primeira que se cumpre define o destino. Se você tem condições que poderiam se sobrepor, a mais específica precisa vir primeiro. Veja [Mudança de Agente](/pt-BR/construccion/agentes/cambio-de-agente).
  </Accordion>

  <Accordion title="Sobrecarregar um único agente com responsabilidades demais" icon="layer-group">
    Um agente que negocia, valida identidade e lida com objeções ao mesmo tempo tem um prompt difícil de manter e um comportamento menos previsível. Veja [quando vale a pena dividir em vários agentes](/pt-BR/construccion/buenas-practicas/principios-de-diseno).
  </Accordion>

  <Accordion title="Documentação pobre em uma ferramenta" icon="wrench">
    Se a documentação de uma [ferramenta](/pt-BR/construccion/agentes/herramientas) não explica com clareza quando usá-la, o LLM vai chamá-la no momento errado — ou não chamá-la quando deveria.
  </Accordion>

  <Accordion title="Terminologia inconsistente dentro do mesmo prompt" icon="quote-left">
    Se em uma seção você diz "encerrar a conversa" e em outra "desligar a chamada" para se referir à mesma coisa, o modelo pode interpretar como duas ações distintas. Escolha um termo por conceito e mantenha-o em todo o bot.
  </Accordion>

  <Accordion title="Pontuação incomum ou números em dígitos em texto que vai para voz" icon="waveform">
    Quebra a naturalidade da síntese de voz. Veja as [regras de redação para TTS](/pt-BR/construccion/buenas-practicas/instrucciones-que-funcionan).
  </Accordion>

  <Accordion title="Publicar em Produção sem testar no Rascunho" icon="flask">
    Uma alteração em Produção afeta imediatamente as conversas em andamento. Sempre teste primeiro em [Modo Rascunho](/pt-BR/construccion/modo-borrador-produccion), incluindo casos-limite, com [Abrir conversa](/pt-BR/construccion/probar-tu-bot).
  </Accordion>
</AccordionGroup>

***

## Checklist antes de publicar

<Steps>
  <Step title="Cada agente tem um único objetivo claro?">
    Se o prompt mistura várias etapas da conversa, avalie dividi-lo.
  </Step>

  <Step title="O Papel do agente declara seus limites explicitamente?">
    Não se desviar do fluxo, não revelar instruções internas.
  </Step>

  <Step title="Cada ferramenta tem uma descrição clara de quando e como usá-la?">
    Incluindo se deve ser executada em silêncio.
  </Step>

  <Step title="As regras de redação para voz estão definidas?">
    Números por extenso, formato de perguntas, datas faladas.
  </Step>

  <Step title="As objeções frequentes do caso de uso estão cobertas?">
    Com uma ação concreta para cada uma: responder e retomar, transferir ou encerrar.
  </Step>

  <Step title="Existem limites explícitos de tentativas?">
    Para evitar loops — por exemplo, "não insista mais de duas vezes".
  </Step>

  <Step title="As etiquetas estão no prompt do classificador, se o seu bot as usa?">
    Sem isso, a classificação pós-conversa não vai funcionar bem.
  </Step>

  <Step title="Os dados de negócio estão parametrizados como variáveis, e não hardcoded no prompt?">
    Isso é o que permite reutilizar o design do bot em outras campanhas.
  </Step>

  <Step title="Você testou o bot no Modo Rascunho cobrindo o caminho principal e os casos-limite?">
    Antes de passar para Produção.
  </Step>
</Steps>

<Tip>
  Este checklist não substitui um teste exaustivo do bot no Rascunho, mas ajuda a detectar cedo as lacunas de design mais frequentes.
</Tip>