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

# Modos da inteligência artificial

> IA desligada, assistente e automática, herança por Inbox, overrides por conversa, simulador e handoff humano.

# Modos da inteligência artificial

A Orquena oferece três formas de operar a IA nas conversas:

```text theme={null}
Desligada
Assistente
Automática
```

Internamente:

```typescript theme={null}
type AiMode = 'OFF' | 'COPILOT' | 'AUTOPILOT'
```

A IA começa sempre desligada. Nenhuma organização recebe atendimento automático sem uma decisão explícita do proprietário.

## Desligada — `OFF`

Comportamento:

* Nenhuma sugestão é criada.
* Nenhuma mensagem é enviada automaticamente.
* O atendente lê e responde pela Orquena Inbox.
* Agendamento e contatos continuam funcionando normalmente.

Esse é o padrão de toda nova Inbox.

## Assistente — `COPILOT`

A IA ajuda o atendente sem enviar mensagens sozinha.

Exemplo:

```text theme={null}
Cliente:
Tem horário hoje à tarde?

Sugestões da Orquena:
[ Claro! Posso verificar os horários disponíveis para você. ]
[ Você possui preferência por algum profissional? ]
```

Ao clicar numa sugestão:

```text theme={null}
A sugestão é copiada para o campo de mensagem.
```

O atendente pode:

* Editar.
* Complementar.
* Apagar.
* Enviar.

Selecionar uma sugestão nunca significa enviá-la.

## Automática — `AUTOPILOT`

A IA funciona como uma secretária controlada.

Exemplo:

```text theme={null}
Cliente:
Tem horário hoje às 16h para cortar com o João?

IA:
1. Identifica a intenção.
2. Consulta o serviço de corte.
3. Localiza João.
4. Consulta a disponibilidade.
5. Responde com dados reais.
```

Quando o cliente confirma:

```text theme={null}
Criar hold
    ↓
Revalidar o horário
    ↓
Criar appointment
    ↓
Sincronizar Google Calendar
    ↓
Confirmar pelo WhatsApp
```

## Ferramentas controladas

A IA não consulta Prisma, SQL ou tabelas diretamente.

Ela chama ferramentas autenticadas e tipadas, por exemplo:

```text theme={null}
getBusinessInformation
listServices
listProfessionals
checkAvailability
createAppointmentHold
confirmAppointment
rescheduleAppointment
cancelAppointment
requestHumanHandoff
```

Cada ferramenta passa novamente por:

* Tenant confiável.
* Permissão.
* Regra de domínio.
* Idempotência.
* Auditoria.

## Restrições obrigatórias

A IA não pode:

* Inventar serviço.
* Inventar preço.
* Inventar profissional.
* Inventar horário disponível.
* Conceder desconto sem permissão.
* Confirmar sem consentimento.
* Cancelar sem confirmação.
* Reagendar sem confirmação.
* Fazer afirmação autoritativa fora do escopo cadastrado.
* Continuar quando uma regra exige humano.

Quando não puder prosseguir, cria um handoff.

## Configuração por Inbox e conversa

A Inbox possui um modo padrão.

Uma conversa pode ter um override próprio.

```typescript theme={null}
effectiveAiMode = conversation.aiModeOverride ?? inbox.defaultAiMode
```

Exemplo:

```text theme={null}
Default da Inbox: Desligada

José  → Assistente
João  → Automática
Maria → herda Desligada
```

Novas conversas herdam o default atual.

## Alterar o default

Ao trocar o default, a interface explica:

> Novas conversas e conversas sem configuração própria passarão a usar o novo modo.

Overrides existentes não são apagados silenciosamente.

A tela lista conversas diferentes do novo default:

```text theme={null}
☑ José — atualmente Assistente
☐ João — atualmente Automática
☑ Maria — atualmente Desligada

[ Selecionar todos ]
[ Desmarcar todos ]
[ Aplicar alteração ]
```

Para os itens selecionados, o override pode ser removido para que passem a herdar o novo default. Os itens desmarcados mantêm sua configuração individual.

Mudanças em grande volume são executadas em segundo plano e auditadas.

## Modo e estado não são a mesma coisa

Uma conversa pode estar configurada como Automática, mas momentaneamente controlada por um humano.

Estados operacionais:

```text theme={null}
AI_ACTIVE
HUMAN_REQUIRED
HUMAN_ACTIVE
PAUSED
```

### `AI_ACTIVE`

Aplica o modo efetivo:

* Desligada: nenhuma ação da IA.
* Assistente: sugestões.
* Automática: respostas automáticas permitidas.

### `HUMAN_REQUIRED`

A IA parou e solicitou ajuda.

### `HUMAN_ACTIVE`

Um atendente assumiu. A IA não envia respostas automáticas.

### `PAUSED`

Automação suspensa manualmente ou por kill switch.

## Quando solicitar humano

O handoff pode ocorrer quando:

* O cliente pede uma pessoa.
* A confiança está baixa.
* O pedido está fora do escopo.
* Uma ferramenta falha.
* Uma regra exige aprovação.
* Existe ambiguidade com impacto relevante.
* A operação ainda não é suportada.

## Resumo para o atendente

A Orquena gera um resumo com:

* Objetivo do cliente.
* Dados já coletados.
* O que a IA tentou fazer.
* Ferramentas que falharam.
* Motivo da interrupção.
* Próxima ação sugerida quando segura.

A notificação abre o mesmo chat.

## Mensagem de espera

Uma mensagem aprovada pode ser enviada uma vez:

> Chamei um atendente para continuar seu atendimento por aqui. Assim que possível, ele responderá nesta mesma conversa.

Ela não se repete para cada nova mensagem recebida.

## Atendimento humano

Controles:

```text theme={null}
[ Assumir conversa ]
[ Devolver para IA ]
[ Pausar automação ]
[ Resolver handoff ]
```

Ao enviar a primeira mensagem humana depois de um handoff, a conversa passa para `HUMAN_ACTIVE`.

## Retorno automático

O padrão planejado é retornar depois de 24 horas de inatividade, somente quando:

* Cliente e atendente não enviaram novas mensagens na janela.
* O handoff foi resolvido.
* A conversa não está pausada.

Ao retornar:

* Desligada continua sem IA.
* Assistente volta a sugerir.
* Automática volta a responder.

## Simulador do onboarding

O simulador usa dados reais do setup, mas uma conversa isolada e sem entrega externa.

Mensagem sugerida:

```text theme={null}
Olá! Meu nome é José.
Gostaria de agendar um corte na Barbearia do José amanhã.
```

A pessoa compara os três modos lado a lado:

### Desligada

Chat e campo de resposta humana.

### Assistente

Chat, sugestões e campo preenchível.

### Automática

Resposta produzida com ferramentas de catálogo e disponibilidade.

Depois escolhe:

```text theme={null}
○ Desligada
○ Assistente
○ Automática
```

Automática exige confirmação final:

```text theme={null}
[ Ativar atendimento automático ]
```

## Escopo inicial

Incluído:

* Mensagens de texto.
* Sugestão no composer.
* Atendimento automático de informações e agendamento.
* Handoff.
* Simulador.
* Override por conversa.
* Default por Inbox.
* Kill switch.

Futuro:

* Tom de voz configurável.
* Resposta por áudio.
* FAQ como etapa obrigatória.
* Ações comerciais avançadas.
* Ferramentas arbitrárias de terceiros.

## Segurança

* Toda resposta automática verifica o estado da conversa antes do envio.
* Takeover humano vence respostas ainda não entregues quando a transição já foi confirmada.
* Operações de escrita usam idempotência.
* Toda alteração de modo ou controle é auditada.
* A organização possui um kill switch para respostas automáticas.
* O simulador não envia mensagens reais.

## Fonte canônica

```text theme={null}
docs/prds/onboarding-inbox-ai-v1.md
docs/architecture/conversation-ai-control-v1.md
apps/ai-runtime/README.md
```