## Visão geral

O **Maestro** é o motor de IA da plataforma: alimenta o Cérebro da conta, o copiloto, os robôs e o
onboarding generativo. A integração é gerenciada pelo operador no console administrativo — sem
necessidade de reimplantar o serviço para alterar a configuração.

## Pré-requisitos

- Acesso ao console do operador (Super Admin).
- URL interna do serviço Maestro e a chave administrativa fornecidas na implantação.

## Passo a passo

1. Acesse o console do operador → configurações do Maestro.
2. Preencha a **URL da API** (endereço interno) e, se houver, a **URL pública** (usada nos webhooks
   dos robôs).
3. Informe a **chave administrativa** — ela fica mascarada e nunca é exibida novamente.
4. Escolha o **modo de onboarding** para novas contas: desligado, guiado (wizard) ou automático.
5. Defina o **modelo vertical padrão** aplicado quando o cadastro não informa segmento.
6. Salve e use **"Testar conexão"** para validar.

## Configurações & opções

- **Maestro habilitado**: chave geral. Desligado, todas as superfícies de IA respondem com um estado
  claro de "desativado pelo operador" em vez de erros de conexão.
- **Permitir chaves por conta (BYOK)**: controla se contas podem usar as próprias chaves de IA
  (veja o artigo "Tokens de IA por conta").
- A configuração do painel tem precedência sobre variáveis de ambiente; ambientes provisionados por
  variável continuam funcionando.

### Pausa por atendimento humano

Quando uma conversa é assumida ou atribuída a uma pessoa, o estado de pausa é gravado de forma
durável e continua válido após reiniciar a API, os workers ou o cache. A retomada só libera o robô
depois de uma confirmação válida; estado desconhecido é tratado como pausado.

Cada robô também define o que reter das mensagens recebidas durante a pausa: **descartar** (padrão),
guardar apenas a **mais recente** ou guardar **um conjunto limitado** por quantidade e idade. Retomar
a conversa nunca reproduz essas mensagens sozinho. Uma eventual reprodução é uma ação separada,
explícita e confirmada pelo operador.

Para processar uma fila retida com segurança:

1. Remova o atendente humano da conversa, quando ele ainda estiver atribuído.
2. No painel **Maestro** da conversa, selecione **Retomar** e aguarde a confirmação. Essa ação libera
   somente mensagens novas.
3. O cartão **Mensagens recebidas durante a pausa** aparece apenas depois da retomada confirmada.
4. Selecione **Processar mensagens retidas**, leia o impacto e escolha **Confirmar processamento**.

Cada tentativa usa um identificador único e seguro para repetição: se a resposta da rede se perder,
tentar novamente não processa a mesma fila duas vezes. Sem confirmação, com estado desconhecido ou
enquanto houver um atendente atribuído, a plataforma mantém a fila bloqueada.

## Casos de uso

- Trocar a chave administrativa após rotação de credenciais, sem reiniciar serviços.
- Ativar o onboarding automático apenas depois de validar o guiado em contas-piloto.

## Dicas, limites e boas práticas

- Rotacione a chave administrativa periodicamente e após qualquer suspeita de exposição.
- Mantenha a URL interna acessível apenas na rede privada; exponha somente a URL pública.

## Solução de problemas

O diagnóstico mostra um dos cinco estados:

- **OK**: serviço acessível e autenticado.
- **Falha de autenticação**: a chave administrativa não confere com a do serviço — atualize um dos
  lados.
- **Inacessível**: a URL não responde (DNS, rede, serviço parado). O detalhe indica a causa.
- **Desativado**: a chave geral "Maestro habilitado" está desligada.
- **Não configurado**: falta a chave administrativa.

Durante **Inacessível** ou uma resposta inválida, respostas automáticas, ferramentas com efeito e
Follow-ups configurados para respeitar o atendimento humano ficam bloqueados até o estado voltar a
ser conhecido.

Se o onboarding generativo estiver ativo e o Maestro indisponível, as contas continuam sendo
provisionadas com os modelos verticais — nada fica bloqueado.

## Veja também

- Tokens de IA por conta (BYOK)
- Uso e limites de consumo
- Onboarding com IA