IA na Radhr AI (visão do usuário)

Objetivo

A IA da Radhr AI trabalha em dois lugares: dentro das telas, onde cada agente faz uma tarefa fechada (ler o site, sugerir a Próxima ação, montar o contrato, estimar uma mudança de escopo), e no Copiloto, a conversa em que o Consultor consulta o sistema e pede ações. A regra que vale para todos é a mesma: o modelo lê, sugere e escreve; o código valida números, chaves do Catálogo e permissões, e nada que muda dado de cliente acontece sem uma regra determinística ou uma confirmação humana. Este documento é a visão de quem usa. O detalhe técnico de cada agente (entradas, prompt, versão, validação, fallback) está em ia/agentes.

Fluxo

Um evento de negócio (handoff, reunião registrada, abertura de proposta, silêncio, conversão, assinatura, movimento no escopo, projeto encerrado) entra na fila de agentes, que roda a análise correspondente em segundo plano. Os crons diário e semanal rodam as leituras periódicas (risco, Delivery Advisor, Customer Success, expansão, relatório).
O agente monta o prompt com a identidade da organização ("Você é o … de <organização>") e as seções do perfil de IA que lhe interessam. Antes de chamar o modelo, a Radhr AI confere se já existe uma análise para os mesmos dados (hash da entrada, que inclui a versão do perfil); se existe, reaproveita.
Antes de cada chamada, a Radhr AI confere o limite de IA da organização; atingido, não chama o modelo e segue pela regra.
A resposta do modelo passa pela validação em código (formato, vocabulário, chaves, valores). Inválida, o agente cai na regra determinística quando ela existe.
O resultado aparece na tela com a família visual da IA (selo "IA", cartão .r-ia) e, quando cabe, com o motivo; o custo da chamada fica registrado.
No Copiloto (⌘J em qualquer tela ou /radar/copiloto), o Consultor pergunta; o modelo consulta com as ferramentas de leitura e, quando o Consultor pede uma ação, registra uma ação pendente.
O Consultor confirma (podendo editar o e-mail ou a nota) ou descarta. Só na confirmação o código executa, com checagem de papel, e registra copiloto_acao na linha do tempo do alvo.

Regras de negócio

Onde a IA aparece: Agente SDR e Detalhamento no site; resumo, leitura do site, Próxima ação com risco do lead, Estratégia da proposta, Reunião → CRM e rascunho na página do lead; briefing na Home; risco do cliente, Expansão e Customer Success (plano de sucesso) no Cliente 360; Contract Builder no contrato; Scope Builder, Scope Validator e Delivery Advisor no projeto; Change Request Analyzer na mudança; narrativa do Relatório semanal; Copiloto. O onboarding (agente de perfil) e o Organization Auditor cuidam do perfil da organização (ver ia/organization-intelligence). Vive em src/agentes.ts, src/fila.ts e nos módulos de cada agente.
Cada agente fala como a organização. O prompt começa com a identidade (nome da organização e a primeira frase do resumo do negócio, se houver) e traz um bloco com as seções do perfil de IA vigente que aquele agente usa (produtos, tom, regras de proposta, contrato, entrega, escalação…). Instruções e conhecimento escritos pela organização entram como dados delimitados: não sobrepõem as regras do código. Sem perfil publicado, a Witbiz usa o perfil importado do código e as demais organizações só a identidade com o nome. Vive em src/perfil/contexto.ts (contextoOrganizacional, identidadeDoAgente, blocoPerfil).
Perfil novo refaz a análise. A versão do perfil entra no hash das análises; publicar uma versão nova faz a próxima leitura chamar o modelo de novo. Vive em src/perfil/contexto.ts e nos módulos dos agentes.
Vocabulário proibido sai da resposta. Na Próxima ação, na Estratégia e no Customer Success, termos do vocabulário proibido do perfil são removidos do texto antes de gravar, com o evento vocabulario_proibido_removido. Vive em src/perfil/contexto.ts (limparSaida).
Modelos: o padrão é Sonnet (claude-sonnet-5); Próxima ação, Estratégia da proposta e Expansão usam Opus (claude-opus-5). Vive em src/claude.ts, src/proxima-acao.ts, src/estrategia.ts e src/expansao.ts.
Expansão segue o catálogo da organização. As relações de expansão cadastradas (catalogo_relacoes: de um item ou família comprada para o item a sugerir, com gatilho que define o momento) vêm antes das regras do código; as regras da Witbiz só valem na organização 1 ou enquanto a organização não cadastrou relação nenhuma. O modelo recebe as relações como contexto e continua sem dar preço. Vive em src/expansao.ts (sugestoesPorRegra).
Delivery Advisor e Customer Success só sugerem. O Delivery Advisor diz a próxima entrega, o que atrasa e quem acionar (uma sugestão por escopo por dia); o Customer Success monta o plano de sucesso do cliente (marcos, próximo check-in com rascunho de mensagem, hora do NPS, riscos do relacionamento; um por cliente por mês). Nenhum dos dois muda dado ou envia mensagem; ambos têm fallback por regra e podem ser dispensados. Vive em src/entrega.ts e src/sucesso.ts.
O modelo nunca define preço. Na Pré-proposta, na Expansão e na Proposta, o modelo escolhe itens pela chave do Catálogo e o código precifica pelo porte. Vive em src/agente.ts, src/expansao.ts, src/propostas.ts.
No contrato, a IA escreve só texto: considerandos e até 3 cláusulas; trecho com R$ fora da proposta ou com percentual é descartado. Vive em src/contratos.ts.
No projeto, a IA só adapta com justificativa e nunca remove entregável; na mudança, só remove etapas que existem com o título exato, e o valor é horas × valor-hora pelo código. Vive em src/escopo.ts e src/mudancas.ts.
Próxima ação em vocabulário fechado: enviar e-mail, WhatsApp, ligar, propor horário, ajustar a pré-proposta, gerar a proposta, aguardar, marcar como perdido. O desfecho (executada, editada, dispensada) é registrado. Vive em src/proxima-acao.ts.
Estado nunca muda por decisão livre do modelo. Estágio do lead não muda pela Reunião → CRM; status do cliente muda só pela máquina de estados a partir do nível de risco consolidado; oportunidade de upsell só nasce por clique ou confirmação. Vive em src/reuniao.ts, src/risco.ts, src/estados.ts.
Copiloto, leitura: hoje, buscar_leads, ler_lead, listar_clientes, ler_cliente, metricas, catalogo e consultar_documentacao executam na hora e não filtram por dono. A exceção é link_portal: o link dá acesso sem login aos dados do Cliente, então só sai para quem pode enviar o portal (admin, ou o Consultor dono do Cliente ou de Cliente sem dono; portal.enviar no RBAC v2), e só se o portal já existe. catalogo devolve só os itens e agentes do catálogo ativos na organização; consultar_documentacao lê a documentação da Radhr AI e os documentos da própria organização (quando os dois divergem, cita os dois e diz qual é a regra da casa). Vive em src/copiloto.ts (lerFerramenta).
Copiloto com a identidade da organização: o prompt diz que ele é o Copiloto do sistema de receita da organização e traz o bloco do perfil; e-mails confirmados saem pelo remetente da organização (domínio próprio verificado) com o nome do Consultor. Pergunta à documentação sem fonte entra na fila de revisão do Knowledge Center. Vive em src/copiloto.ts (montarSistema, executarAcao).
Copiloto, ação: registrar_nota, criar_tarefa, concluir_tarefa, mudar_estagio, enviar_email, solicitar_mudanca, abrir_oportunidade nunca executam pelo modelo. O código valida argumentos e papel antes de propor; o que não pode ser feito volta ao modelo como recusa. Vive em src/copiloto.ts (validarAcao, executarAcao).
Papel mínimo nas ações: consultor age nos leads e clientes de que é dono ou que não têm dono; admin em todos. mudar_estagio para "ganho" é recusado: ganho só pela conversão em Cliente. Vive em src/copiloto.ts.
O que as ferramentas devolvem é dado, não instrução: texto de nota, e-mail ou WhatsApp não comanda o Copiloto; qualquer ação ainda depende da confirmação. Vive em src/copiloto.ts (montarSistema).
Conversa do Copiloto: uma por usuário, válida por 7 dias, guarda as últimas 60 mensagens, até 6 rodadas de consulta por pergunta; a página aberta entra como contexto ("este lead", "este cliente"). Vive em src/copiloto.ts e na migração 0015.
Limite de IA: vale o limite mensal definido na organização; sem ele, a IA incluída no plano (teste US$ 5, Essencial US$ 20, Profissional US$ 80, Escala US$ 250; interno sem limite). Atingido, o modelo não é chamado, o evento limite_ia_atingido é registrado e as regras determinísticas seguem. Vive em src/planos.ts (limiteIaDoPlano), src/organizacao.ts (limiteIaAtingido) e src/claude.ts (chamarClaude).
Uma porta só para o limite: iaBloqueada() vale para chamarClaude e também para o Copiloto, o Agente SDR e o Organization Auditor, que chamam a API direto. No limite, o SDR mostra ao visitante o formulário de contato e passa o lead a Handoff (motivo limite_ia); o Copiloto não leva a pergunta ao modelo e mostra o aviso (confirmar ou descartar uma ação pendente ainda executa; só o fecho da IA fica de fora). O uso do mês fica em cache de 5 minutos. Vive em src/claude.ts, src/copiloto.ts, src/agente.ts e src/organizacao.ts.
Custo: cada chamada grava rótulo, modelo, tokens (incluindo cache) e custo em US$ em ia_chamadas (inclusive resumo e narrativa do relatório); as análises guardam o custo também em analises_ia. Vive em src/claude.ts (registrarChamadaIA, custoUsd).
Registro central dos agentes: a página de IA do Knowledge Center mostra, por agente, chamadas, custo total e médio, análises gravadas, quantas foram refeitas desde o perfil vigente e a taxa de fallback por regra dos últimos 30 dias (alerta acima de 20%). É só leitura. Vive em src/agentes-registro.ts.
Excedente de IA (custo + 30%, com autorização) é condição comercial do plano; o código não libera excedente sozinho: quem ajusta o limite é a Witbiz em /radar/organizacoes. Vive em src/planos.ts.

Casos de uso

"O que eu faço agora?" Pergunte ao Copiloto; ele lê a Home e responde com links para os leads.
Cobrar uma proposta. Na página do lead, peça ao Copiloto o e-mail de cobrança; ele propõe enviar_email, você edita o texto na ação pendente e confirma.
Registrar o que ficou combinado. Peça "crie uma tarefa para ligar amanhã"; confirme a ação pendente.
Mudança pedida por telefone. Diga ao Copiloto qual projeto e o que mudou; ele propõe solicitar_mudanca e, confirmada, a análise de impacto roda na hora.
Projeto travado. Abra o escopo e leia o Delivery Advisor: próxima entrega, o que atrasa e quem acionar.
Hora de falar com o cliente. O plano de sucesso no Cliente 360 traz o próximo check-in com uma mensagem rascunho; você decide se e como enviar.
Entender uma sugestão da IA. Toda saída da IA nas telas traz o motivo (Próxima ação, risco, expansão, adaptação de escopo); leia antes de agir.
Limite atingido no meio do mês. As telas continuam funcionando com regras; peça à Witbiz para ajustar o limite ou mudar de plano.

Telas

/radar/copiloto: conversa completa, ações pendentes com Confirmar e Descartar (e edição de e-mail e nota), auditoria e "Nova conversa".
Painel flutuante do Copiloto (⌘J, /radar/copiloto/painel e /radar/copiloto/stream): a mesma conversa em streaming, com sugestões conforme a página aberta e o custo da conversa.
/radar/ (Home): briefing narrado e ações sugeridas pela IA na fila, com selo "IA".
/radar/lead/:id, /radar/cliente/:id, /radar/contrato/:id, /radar/escopo/:id, /radar/mudanca/:id: cartões da IA com o motivo e botões para regenerar ou reanalisar. No escopo, o cartão do Delivery Advisor ("Reler hoje", "Dispensar hoje"); no 360, o do plano de sucesso (reler, dispensar). Em JSON: /radar/escopo/:id/entrega e /radar/cliente/:id/sucesso.
/radar/conhecimento/ia (Witbiz): agentes com o registro central dos últimos 30 dias; o admin da Witbiz vê outra organização com ?org=.
/radar/organizacao: uso de IA do mês por rótulo contra o limite.
/radar/metricas: custo de IA do período, por rótulo e por lead qualificado.

Permissões

admin: usa o Copiloto e confirma ações em qualquer lead ou cliente da organização.
consultor: usa o Copiloto; as ações só são propostas em leads e clientes dele ou sem dono. As ferramentas de leitura enxergam a organização inteira.
financeiro e leitura: perguntam ao Copiloto e ao assistente de documentação, mas não propõem nem confirmam ações. O prompt diz que o papel só consulta; validarAcao recusa a ação antes de ela virar pendente; confirmar pela tela é recusado com 403 (src/radar/permissoes.ts).
**Papéis v2 (flag rbac_v2):** perguntar ao Copiloto = copiloto.perguntar (todos os papéis); propor e confirmar ações = copiloto.executar (owner, admin, master, sales nos seus, operation; o consultor antigo vira sales). Reler o Delivery Advisor exige escopos.validar (src/rbac/engine.ts).
cliente: não usa a IA da Radhr AI. O cliente só conversa com o Agente SDR no site, antes de virar lead.
Gating de plano: o Copiloto exige o recurso copiloto (Profissional, Escala, teste e interno); no Essencial, a página explica e as rotas devolvem 402. O Customer Success depende da flag customer_success (Profissional ou superior) e o cartão do Delivery Advisor da flag delivery_advisor (planos pagos); as duas nascem desligadas. Os demais agentes existem em todos os planos, dentro do limite de IA (src/planos.ts, src/flags.ts, src/radar/copiloto.ts).

Perguntas frequentes

O Copiloto pode enviar um e-mail sem eu ver? Não. Toda ferramenta de ação vira uma ação pendente; o e-mail só sai quando você confirma, e você pode editar o texto antes. Isso é garantido pelo código, não pelo prompt.

Por que o Copiloto recusou mover o lead para "ganho"? Ganho só acontece pela conversão em Cliente, que cria empresa, contato, cliente e contrato juntos.

Posso confiar nos valores que a IA mostra? Preços, totais e valores de mudança vêm do código (Catálogo, proposta, valor-hora). O que a IA escreve é texto e recomendação; confira sempre o motivo.

O que acontece quando o limite de IA acaba? As análises param de chamar o modelo e a Radhr AI segue pelas regras: a Próxima ação da IA deixa de ser gerada (a Home continua com os cartões por regra), risco do cliente e expansão saem só das regras, contrato e escopo saem só do modelo determinístico, Delivery Advisor e Customer Success saem por regra e a Home usa a frase padrão no lugar do briefing. O Copiloto mostra o aviso do limite e não responde; o Agente SDR passa o visitante ao formulário de contato.

Por que a IA fala o nome da minha empresa e não "Witbiz"? Porque cada agente recebe a identidade e o perfil de IA da organização. Ajuste o perfil em /radar/organizacao/perfil; a versão nova entra no hash e as próximas análises são refeitas.

Onde vejo quanto a IA custou? Em /radar/organizacao (mês atual, por rótulo) e em /radar/metricas (período). Cada conversa do Copiloto mostra o próprio custo no painel.

A IA lê meus e-mails e mensagens de WhatsApp? Ela lê o que está registrado na Radhr AI (notas, e-mails enviados, mensagens recebidas pelo WhatsApp integrado, transcrições) quando monta uma análise ou quando o Copiloto consulta um lead ou cliente.

Onde está o detalhe de cada agente? Em ia/agentes: gatilho, entradas, saídas, modelo e versão do prompt, validação em código, fallback e handoff humano de cada um.

AI Source Analyzer / AI Channel Analyzer (`fonte_analista`)

Objetivo: ler os números dos canais de entrada (Lead Source Intelligence, ADR-0015) e devolver uma leitura executiva, até 6 insights e até 5 recomendações de orçamento (aumentar, reduzir, escalar, interromper, manter).
Gatilho: cron semanal nas organizações com lead_intelligence; botão "Analisar agora" em /radar/origens (fila, forçado). Idempotente por hash do snapshot (canais arredondados, modelo, janela, versão do perfil). A Analise é criada por chamada (analiseDeFontes): o snapshot fica num fechamento local, nunca em variável de módulo — duas organizações no mesmo isolate não se misturam.
Entradas: snapshot em texto do motor puro (snapshotTexto: totais, canais com leads, conversão, receita atribuída, custo, CAC, ROI, LTV, retenção, churn, payback, tempos, Health, Quality; campanhas; previsões de 30 dias; anomalias) + identidade e perfil da organização (SECOES_RELATORIO).
Saídas: JSON {leitura, insights[], recomendacoes[]} gravado em analises_ia (alvo organização) e em origem_insights (chave ia:); evento fonte_analise_gerada.
Modelo e versão do prompt: Sonnet (MODELO), fonte-analista-v1, sem raciocínio estendido, 1.800 tokens.
Validação em código: canais só do snapshot; todo número com dois ou mais algarismos no texto precisa existir no snapshot (numerosEstranhos); ações só do vocabulário; saída vazia → inválida.
Fallback: saidaPorRegra (insights e recomendações do motor), marcado por_regra e modelo = 'regra'.
Handoff humano: a tela mostra a leitura com a origem (modelo ou regra); o consultor dispensa insights; nenhuma recomendação muda orçamento sozinha. As perguntas naturais (fonte_perguntas) seguem a mesma validação.

Perguntas naturais sobre os canais (`fonte_perguntas`)

Objetivo: responder uma pergunta do consultor sobre os canais quando a regra (responderPergunta) não cobre.
Gatilho: POST /radar/origens/perguntar, só depois de a regra devolver null. Entradas: a pergunta (≤ 400 caracteres) e o snapshot. Saídas: até 3 frases. Modelo: Sonnet, sem raciocínio, 400 tokens, sem versão de prompt (não é idempotente: cada pergunta é uma chamada, contada em ia_chamadas). Validação: numerosEstranhos — número fora do snapshot derruba a resposta. Fallback: texto fixo pedindo para perguntar por receita, clientes, conversão, ROI, CAC, retenção, campanhas, parceiros ou onde investir. Handoff: a resposta aparece na tela, nunca age.

Perguntas de diagnóstico dos Radhr Forms (`forms_perguntas`)

Objetivo: sugerir três perguntas de diagnóstico para um formulário a partir do ICP do perfil da organização.
Gatilho: abertura do editor de formulários. Entradas: dores e segmentos do idealCustomerProfile.
Saídas: JSON {perguntas: [3]} (≤ 120 caracteres cada). Modelo: Sonnet, 300 tokens. Validação: exatamente 3 strings com mais de 8 caracteres; senão PERGUNTAS_IA_PADRAO. Fallback: as três perguntas padrão. Handoff: o admin copia a pergunta para um campo do tipo "Pergunta de IA"; nada é publicado sozinho.