Agentes de IA — contrato, entrega e carteira

Princípios comuns a todos os agentes desta página:

• Valores vêm sempre do código. O modelo não dá preço, prazo contratual nem desconto. Os valores saem da Proposta aceita, do catálogo precificado pelo porte ou do valor-hora da Organização.
• Todo agente funciona sem IA. Cada um tem a opção "sem IA" (usarIA: false) ou um fallback determinístico, e a Radhr AI segue quando a IA falha ou o limite mensal da Organização é atingido.
• Custo registrado. Cada chamada grava uma linha em ia_chamadas com o rótulo do agente.

Detalhes de fila, cache, limite de IA e segurança estão em [Orquestração, memória e contexto dos agentes](ia/orquestracao).

Contract Builder

Rótulo técnico: contrato — src/contratos.ts (modelo determinístico em src/contrato-modelo.ts).

• Objetivo: gerar o contrato do Cliente a partir da versão aceita da Proposta. Quem monta o contrato é o modelo determinístico: 14 cláusulas obrigatórias, todas com valores. A IA só escreve texto narrativo, que o código valida.
• Gatilho:
• a conversão do lead em Cliente (POST /radar/lead/:id/converter), que gera o contrato em rascunho;
• o botão no Cliente 360 (POST /radar/cliente/:id/contratos);
• "regenerar" na página do contrato (POST /radar/contrato/:id), com ou sem IA.

Contrato assinado ou cancelado não é regenerado.

• **Entradas (adaptarComIA):** nome e setor do cliente, a dor relatada, os itens contratados com o motivo de cada um, o resumo da Triagem, a última reunião (resumo e decisões) e as 8 últimas notas.
• Saídas: o JSON {considerandos, clausulas[≤3]}, que entra em montarContrato. O resultado grava uma versão em contrato_versoes (markdown, cláusulas, hash SHA-256, gerado_por: 'contract-builder') e o evento contrato_gerado (com ia e clausulas_ia). Não grava em analises_ia.
• Modelo e versão do prompt: MODELO (claude-sonnet-5), maxTokens: 900, thinking: 'disabled'. Não há constante de versão do prompt.
• Validação em código:
• Todo trecho da IA com um R$ que não esteja entre os valores permitidos da Proposta (valoresPermitidos: total, mensal, desconto, à vista, parcela e preço de cada item) é descartado.
• Todo trecho com percentual também é descartado.
• O texto final passa por validarContrato: as cláusulas obrigatórias precisam estar presentes e não pode haver valor fora da Proposta. Havendo problema, a geração é recusada.
• Fallback: sem IA, o contrato sai só do modelo, com o aviso "a IA não contribuiu".
• Handoff humano: o contrato nasce em rascunho. O Consultor revisa, edita (cada edição vira uma nova versão), ajusta as datas e envia para assinatura. O aditivo (criarAditivo / montarAditivo) é determinístico e não usa IA.

Scope Builder

Rótulo técnico: escopo — src/escopo.ts (gerarEscopo, adaptarComIA, planejar).

• Objetivo: montar o projeto (Escopo) a partir do contrato. Parte do escopo padrão de cada item vendido e aplica só as adaptações que o contexto do cliente justifica.
• Gatilho:
• a cadeia:assinado quando o contrato é assinado (agente escopo da fila). Só gera se o contrato ainda não tiver escopo; se o contrato assinado for um aditivo, o mesmo agente aplica a mudança (aplicarPorAditivo, sem IA);
• o botão no contrato (POST /radar/contrato/:id/escopo), com opção "sem IA".
• Entradas:
• lead de origem (empresa, setor, porte, ferramentas, dor);
• resumo da Triagem;
• última reunião;
• 8 últimas notas;
• itens vendidos (não recorrentes) com o escopo padrão de cada um. O escopo padrão vem do catálogo em banco (escopo_padrao), da semente ou dos entregáveis do catálogo em código.
• Saídas: {adaptacoes[{item, acao: adicionar|remover|renomear, titulo, novo_titulo, motivo, entregavel, horas}], riscos_iniciais[]}. O código grava escopos (status planejado, gerado_por: 'scope-builder'), as escopo_itens com origem modelo ou ia e justificativa, e o evento escopo_gerado. Em seguida roda o Scope Validator.
• Modelo e versão do prompt: MODELO, maxTokens: 1200, thinking: 'disabled'. Não há constante de versão.
• **Validação em código (interpretarBuilder e planejar):**
• No máximo 12 adaptações e 5 riscos. Horas só entre 0 e 80.
• Uma adaptação só vale se apontar para um item vendido.
• Remover nunca apaga um entregável. Renomear só troca uma etapa que existe. Adicionar não duplica título.
• Prazos são calculados pelo código: o prazo_dias do item é distribuído em sequência a partir do início do contrato (ou do kickoff, ou de hoje). Horas padrão: 8 por entregável e 4 por etapa.
• Fallback: sem IA, o escopo sai só do modelo (aviso "a IA não contribuiu").
• Handoff humano: o Consultor edita as etapas, responsáveis, prazos e status em /radar/escopo/:id e move o projeto pela máquina de estados escopo.

Scope Validator

Rótulo técnico: escopo_validador — src/escopo.ts (validarEscopo).

• Objetivo: conferir o contrato contra o escopo de execução. Primeiro por regras, depois pela leitura do modelo.
• Gatilho:
• ao fim do Scope Builder;
• o botão "validar de novo" (POST /radar/escopo/:id);
• depois de aplicar uma mudança de escopo (sem IA).
• Entradas: o trecho do contrato até a cláusula 3 (até 6.000 caracteres), as etapas não canceladas (fase, título, entregável, horas, prazo, status, justificativa), o que as regras já apontaram e os riscos iniciais do Builder.
• Saídas: escopos.validacao = {regras[], ia: {inconsistencias[], riscos[], saude} | null, em}, a escopos.saude recalculada e o evento escopo_validado.
• Modelo e versão do prompt: MODELO, maxTokens: 900, thinking: 'disabled'. Não há constante de versão.
• Validação em código:
• As regras determinísticas (regrasDoEscopo) apontam:
• item vendido sem etapa (alta);
• entregável sem prazo;
• etapa sem item vendido;
• dependência circular (alta);
• último prazo depois do fim do contrato (alta);
• horas acima de 1,5 × 40 h por item.
• Da IA, o código aceita no máximo 8 inconsistências (gravidade só alta/media/baixa) e 6 riscos, e remove riscos quase repetidos (semQuaseRepetidos).
• A saúde do projeto é calculada pelo código (saudeDoEscopo: atrasos, ritmo e gravidade alta nas regras ou nas inconsistências da IA). O campo saude devolvido pelo modelo fica guardado, mas não define a cor.
• Fallback: as regras sempre rodam. Sem IA, ia: null.
• Handoff humano: o validador só aponta problemas. Quem corrige é o Consultor.

Change Request Analyzer

Rótulo técnico: mudanca — src/mudancas.ts (analisarMudanca, consolidar).

• Objetivo: estimar o impacto de um pedido de mudança de escopo (etapas novas e removidas, horas, dias, valor) e recomendar aprovar, negociar ou recusar.
• Gatilho:
• o formulário no escopo (POST /radar/escopo/:id/mudancas);
• o portal do cliente (POST /portal/:token/mudanca, em segundo plano);
• a ação solicitar_mudanca do Copiloto, depois da confirmação;
• "reanalisar" em /radar/mudanca/:id (ação reanalisar).
• Entradas: o pedido (tipo, origem, título, descrição), o escopo atual (etapas com fase, horas e status), o contrato (título, valor, fim, regras fixas de suporte, exclusões e licenças) e o valor-hora de referência da Organização (config.comercial.valor_hora).
• Saídas: mudancas.analise (AnaliseMudanca), mais impacto_valor, impacto_horas, impacto_dias e exige_aditivo. A mudança passa de solicitada para analisada pela máquina mudanca.
• Modelo e versão do prompt: MODELO, maxTokens: 900, thinking: 'disabled'. Não há constante de versão.
• **Validação em código (interpretarAnalise e consolidar):**
• Limites: horas entre 0,5 e 200, dias entre −60 e 180, no máximo 10 itens.
• itens_removidos só aceita títulos exatos de etapas existentes que não estejam concluídas nem canceladas.
• O valor é sempre horas líquidas × valor-hora. O modelo nunca dá valor.
• "Dentro do escopo" só vale se a IA disser que sim e as horas líquidas forem ≤ 0.
• A cláusula aplicável e a exigência de aditivo são decididas pelo código.
• Fallback: sem IA, consolidar roda só com o pedido: nenhuma etapa nova ou removida e impacto zero, porque nada foi estimado. A recomendação é negociar (aprovar só para remoção), com o aviso de que horas, valor e prazo não foram estimados. Aprovar uma adição ou alteração assim exige que o Consultor informe o valor (0 é uma decisão explícita de não cobrar). O campo vem em branco e obrigatório, e o servidor recusa sem ele (semEstimativa). Isso vale também para a mudança ainda não analisada. Valor negativo ou inválido é sempre recusado, nunca trocado pelo impacto calculado.
• Handoff humano: toda decisão é humana, em /radar/mudanca/:id. O Consultor aprova ou rejeita, e pode ajustar valor e prazo; o admin pode conceder cortesia. Com custo ou prazo, o código gera o aditivo e o escopo só muda depois que o aditivo é assinado. Remoções sem custo e cortesias são aplicadas na hora.

Motor de risco do cliente

Rótulo técnico: risco_cliente — src/risco.ts (ANALISE_RISCO_CLIENTE, avaliarRiscoCliente). Roda no esqueleto executarAnalise.

• Objetivo: ler risco de churn, de atraso ou comercial de cada Cliente, no mesmo formato dos cartões "Em risco" da Home. O risco do lead vem junto da próxima ação (ver [agentes comerciais](ia/agentes-comerciais)).
• Gatilho:
• a cadeia:convertido, na conversão;
• a cadeia:cliente_movimento, depois de uma nota, de uma oportunidade aberta ou de uma tarefa concluída no 360 (POST /radar/cliente/:id);
• o cron diário 0 11 * * MON-FRI (8h em Brasília, antes do digest), por organização;
• o botão "avaliar risco" no 360 (POST /radar/cliente/:id, com forcar).
• Entradas: o cliente (status, desde quando, valor contratado, kickoff), os 40 últimos eventos (com o texto das notas), as tarefas abertas, as oportunidades e o que as regras já apontaram.
• Saídas: analises_ia tipo risco_cliente (alvo cliente) com {nivel, tipo, motivo, acao, sinais} e o evento risco_cliente_gerado.
• Modelo e versão do prompt: MODELO, maxTokens: 600, thinking: 'disabled', VERSAO_RISCO_CLIENTE = 'risco-cliente-v1'.
• Validação em código:
• nivel e motivo são obrigatórios. tipo fora do vocabulário vira churn.
• O hash não inclui a data. Contam o que um humano fez (eventos automáticos, inclusive o desta análise, ficam de fora), as tarefas, as oportunidades, o status, o kickoff e as regras calculadas agora (chave e nível; o título com contagem de dias fica de fora). Com o quadro igual, o cron diário reaproveita a leitura. Uma tarefa que vence, um silêncio que cruza o limite ou um kickoff sem registro mudam as regras e pedem nova leitura.
• O nível final é o pior entre as regras e o modelo (riscosDeCliente conta etapa atrasada, tarefa vencida, kickoff sem registro, silêncio de 21 ou 45 dias, bounce, renovação ou upsell parado).
• Fallback: o regra do esqueleto gera a mesma saída só com as regras (grava modelo: 'regra').
• Handoff humano: o status do cliente muda sozinho pela máquina de estados: alto passa ativo/expandido para em_risco, e baixo devolve em_risco para ativo. A ação corretiva é do Consultor: o risco vira cartão na Home e no 360.

Expansion Opportunity Agent

Rótulo técnico: expansao — src/expansao.ts (ANALISE_EXPANSAO). Roda no esqueleto executarAnalise.

• Objetivo: sugerir até 3 oportunidades de upsell reais para o Cliente, com motivo e momento, e avaliar o risco da renovação.
• Gatilho:
• o cron 30 11 * * MON (segunda, 8h30 em Brasília), antes do relatório, com até 30 clientes por rodada;
• a cadeia:escopo_concluido, quando o projeto é encerrado (com forcar);
• o botão "reler" no 360, que despacha na fila e a página consulta GET /radar/cliente/:id/expansao até a leitura chegar.
• Entradas:
• o cliente (setor, porte, status, valor contratado) e a dor original;
• o resumo da Triagem;
• o que já foi contratado;
• as oportunidades abertas, os projetos e os contratos;
• o risco atual e a renovação pela regra;
• o que clientes parecidos (primeiro os do mesmo setor) compraram depois;
• as sugestões por regra;
• o catálogo, sem o que o cliente já comprou.
• Saídas: analises_ia tipo expansao (alvo cliente) com {sugestoes[{catalogo_chave, titulo, motivo, momento, valor, origem}], renovacao, resumo, ia}. Lida pela Home, pelo 360, pelo relatório semanal (carteira) e pelo Copiloto (ler_cliente).
• Modelo e versão do prompt: MODELO_PROXIMA_ACAO (claude-opus-5), maxTokens: 900, thinking: 'disabled', versão 'expansao-v1'.
• **Validação em código (aplicar → consolidar):**
• Só entram chaves que existem no catálogo (código ou banco), com agente válido.
• Sai o que já foi comprado, o repetido e o que já está aberto.
• **O preço é dado pelo porte (precoDeCatalogo). O modelo nunca dá preço.**
• As sugestões por regra completam a lista até 4 itens.
• A renovação vem sempre das datas do contrato. O modelo só pode subir o risco dela.
• O hash inclui o mês.
• Fallback: sugestoesPorRegra — primeiro as relações de expansão da organização (catalogo_relacoes, da etapa 5 do onboarding, da auditoria ou de gente: de = chave comprada, família foundation/ai/sprint ou curinga "qualquer produto"; para = chave do item; o momento sai do texto do gatilho — "60 dias"/"fim do contrato" → fim do contrato, "concluído"/"entregue" → agora se o projeto já fechou, "90" → 90 dias, senão 30 dias), depois as regras padrão do código (Foundation sem AI Layer → SDR; Foundation sem Sprint → Sprint Completo; agentes sem sustentação), que só valem na organização 1 ou enquanto a organização não cadastrou relação nenhuma, e o que os parecidos compraram; mais renovacaoDe. As relações também entram no prompt do modelo ("RELAÇÕES DE EXPANSÃO DA ORGANIZAÇÃO").
• Handoff humano: a sugestão vira ação na Home e no 360, e um clique do Consultor abre a Oportunidade. A exceção é a renovação: o código abre sozinho (abrirRenovacaoSeDevida) quando o contrato principal termina em até 60 dias.

Relatório executivo semanal

Rótulo técnico: relatorio — src/relatorio.ts (narrar).

• Objetivo: narrar a semana para os sócios em 3 parágrafos: SEMANA, TRAVADO e FOCO. Os números são do código; o modelo só escreve sobre eles.
• Gatilho:
• o cron 30 11 * * MON (segunda, 8h30), por organização;
• a prévia em GET /radar/relatorio;
• "Enviar agora" (POST /radar/relatorio/enviar).
• Entradas: números da semana e da anterior, pipeline, quem mais se moveu, riscos, ganhos e carteira (clientes, em risco, renovando, contratado, renovações em 60 dias, expansão sugerida e aberta, margem média).
• Saídas: o texto entra no e-mail enviado aos admins (sócios) da organização com e-mail e no evento relatorio_semanal_enviado (campo narrativa). Fica também em analises_ia tipo relatorio, com alvo organizacao, e a chamada vai para ia_chamadas (rótulo relatorio).
• Cache: por hash da versão do prompt + entrada. Abrir a prévia de novo com os mesmos dados não chama o modelo, e o envio de segunda reaproveita a narrativa de uma prévia com os mesmos números. Qualquer número ou lista diferente gera um hash novo. Prévias simultâneas com a mesma entrada, no mesmo isolate, esperam a mesma chamada. Entre isolates ainda pode sair uma chamada a mais, mas as duas entram em ia_chamadas e o uso do mês fica correto.
• Modelo e versão do prompt: MODELO (padrão de chamarClaude), maxTokens: 600, thinking: 'disabled', versão 'relatorio-v1' (constante local VERSAO_PROMPT).
• Validação em código: só trim, e a recusa é descartada. O e-mail apenas separa os parágrafos e põe os rótulos em negrito.
• Fallback: "Narrativa indisponível nesta semana." Os números e as listas saem de qualquer jeito. Isso vale também quando a Organização atinge o limite de IA (chamarClaude).
• Handoff humano: nenhum (informativo).
• Custo: entra no uso de IA do mês da Organização (até 25/09/2026, narrar não gravava em ia_chamadas).

Copiloto

Rótulo técnico: copiloto — src/copiloto.ts. Páginas em src/radar/copiloto.ts.

• Objetivo: dar ao Consultor uma conversa com a Radhr AI para consultar dados e propor ações, com confirmação humana obrigatória para qualquer ação.
• Gatilho: /radar/copiloto (página cheia) e o painel flutuante (GET /radar/copiloto/painel, POST /radar/copiloto/stream, atalho ⌘J). O painel manda o caminho da página aberta (contextoValido) para que "este lead" e "este cliente" tenham um id. Só a partir do plano Profissional: sem o recurso, a página explica e as APIs devolvem 402.
• Entradas: o system prompt (montarSistema: quem pergunta, papel, id, data de Brasília, regras de ação e de dados, vocabulário), um bloco separado sem cache com a página aberta, e o histórico da conversa em copiloto_conversas.mensagens.
• Ferramentas:
• Leitura, executadas na hora: hoje, buscar_leads, ler_lead, listar_clientes, ler_cliente (inclui projetos, mudanças e expansão), metricas, catalogo, consultar_documentacao e link_portal (o link do portal que já existe, só para quem pode enviá-lo: admin ou dono do cliente; nunca gera nem envia). O resultado vai ao modelo como tool_result, cortado em 60.000 caracteres.
• Ação, nunca executadas pelo modelo: registrar_nota, criar_tarefa, concluir_tarefa, mudar_estagio, enviar_email, solicitar_mudanca, abrir_oportunidade.
• Saídas: o texto em streaming e as ações pendentes em copiloto_conversas.pendentes. Com a decisão, a ação passa para auditoria e gera o evento copiloto_acao no alvo. Custo por rodada em ia_chamadas e somado em copiloto_conversas.custo_usd e chamadas.
• Modelo e versão do prompt: MODELO_COPILOTO = MODELO (claude-sonnet-5), max_tokens: 2000, tool use com tool_choice: auto, até MAX_RODADAS = 6 rodadas por pergunta. Não há constante de versão.
• **Validação em código (validarAcao, antes de propor):**
• O Consultor só age nos seus leads e clientes (ou nos sem dono); o admin age em todos.
• Datas no formato AAAA-MM-DD.
• Não existe estágio ganho pelo Copiloto: só pela conversão.
• E-mail exige que o lead tenha e-mail.
• Textos com tamanho máximo.

O que é recusado volta ao modelo como "Ação recusada pela Radhr AI: …".

• Fallback: erro da API tira a pergunta da conversa e mostra "A IA não respondeu". Sem rodadas restantes, devolve uma resposta fixa.
• Handoff humano: toda ação é uma proposta. O Consultor confirma (e pode editar o corpo do e-mail ou o texto da nota) ou descarta, e só então executarAcao roda as mesmas rotinas das páginas da Radhr AI. Depois de cada decisão, o modelo dá o fecho em uma frase.
• Memória: uma conversa ativa por usuário, com validade de 7 dias (expira_em, padrão da migração 0015). O histórico é cortado para as últimas 60 mensagens (MAX_MENSAGENS), sem separar um tool_use do seu tool_result.
• Limite de IA da Organização: o Copiloto monta a chamada no SDK (cliente(), por causa do tool use), mas confere iaBloqueada(env, 'copiloto') antes de cada pedido:
• Pergunta no limite: o modelo não é chamado, a pergunta não entra na conversa e o Consultor lê AVISO_LIMITE_IA (o Copiloto volta no mês seguinte ou quando o limite for ampliado; as telas e regras da Radhr AI seguem).
• Confirmar ou descartar uma ação pendente: a decisão executa e é auditada normalmente. Só o fecho do modelo fica de fora, e a nota [Radar] da decisão continua na conversa.
• A checagem acontece antes do pedido, não entre as rodadas: uma pergunta em andamento pode passar do teto em até MAX_RODADAS chamadas.

Nota (ADR-0015)

Contract Builder e Scope Builder passaram a emitir os eventos contrato_criado e escopo_criado para os webhooks de saída do Integration Hub; os prompts não mudaram.