System Requirements Document for agentes-comerciais-plataforma

1. Introduction

A agentes-comerciais-plataforma é uma plataforma de contratação e gestão de agentes comerciais de IA. O centro do produto é o agente comercial contratado — não um construtor genérico de chatbots. A empresa contratante escolhe o perfil do agente, informa como seu negócio vende, alimenta o agente com conhecimento privado e acompanha a operação, com encaminhamento para humano ou para compra.

O produto parte de um benchmark público — a página da Umbler Talk — usado como referência de produto e experiência, não como compromisso de contratação nem de reprodução integral daquela plataforma. O benchmark organiza a configuração do agente em três partes (comportamento, roteiro e conhecimento) e apresenta uma operação compartilhada entre IA e humanos, com acompanhamento e possibilidade de assumir a conversa. Esses recursos aparecem na oferta pública da Umbler; sua implementação interna e qualidade prática não são presumidas e entram na avaliação técnica do nosso produto.

O público-alvo são PMEs brasileiras que vendem por conversa e precisam de um agente comercial que qualifique leads, esclareça dúvidas, trate objeções com informação aprovada, encaminhe para um vendedor humano quando solicitado e direcione ao checkout autorizado — mantendo o conhecimento de cada empresa isolado e auditável.

O primeiro marco é esta especificação de produto (escopo, usuários, jornadas e limites), seguida de arquitetura, protótipo, implementação de uma jornada completa e piloto com empresas selecionadas.

2. System Overview

A plataforma entrega, na primeira versão:

• Portal da empresa contratante para contratação e configuração de um ou mais agentes.
• Três personas comerciais selecionáveis — Conservador, Descolado e Assertivo — que alteram a abordagem e não as permissões.
• Onboarding guiado em sete etapas, com revisão humana do que foi extraído de sites e documentos antes de virar verdade comercial.
• Conhecimento separado por empresa, vinculado apenas aos agentes autorizados.
• Um canal de atendimento inicial, onde o lead conversa com o agente de forma flexível e não linear.
• Caixa de entrada compartilhada com transferência para humano e retomada controlada.
• Direcionamento ao checkout autorizado.
• Histórico, auditoria e métricas básicas de conversas, qualificação, encaminhamentos e resultados comerciais.
• Ambiente de simulação antes da publicação, com aprovação da versão antes de ativar.

A tese de execução é: o modelo interpreta e redige; a aplicação autoriza ações e verifica dados comerciais. A conversa é flexível; as regras de execução são controladas.

Atores

• Empresa contratante (administrador da conta) — pessoa humana que contrata, configura, revisa, testa, aprova e acompanha.
• Atendente humano (responsável pela operação humana) — pessoa humana que assume atendimentos na caixa de entrada e retoma de forma controlada.
• Lead / cliente final em conversa — pessoa humana que conversa com o agente pelo canal de atendimento inicial.
• Sistema / aplicação — ator não-humano que autoriza ações, verifica dados comerciais e executa o encaminhamento.
• Provedores externos — CRM, agenda, checkout e pagamentos, conforme contratação; o processamento de pagamentos é do provedor, não da plataforma.

Exclusões da primeira versão

Construtor visual completo de automações; campanhas em massa; CRM completo; vários canais simultaneamente; processamento próprio de pagamentos; atualizações autônomas que alterem preços ou regras dos clientes.

2a. Product Interpretation and Delivery Boundary

Entrega e propriedade. A plataforma é entregue como aplicação web própria, com identidade de aplicação para a empresa contratante e o atendente humano, e um canal de atendimento inicial acessível ao lead. O agente comercial é configurado, testado e aprovado dentro da plataforma; a operação humana acontece na caixa de entrada da própria plataforma. Integrações com CRM, agenda, checkout e pagamentos são propriedade do provedor externo e configuradas conforme contratação — a plataforma não processa pagamentos.

Fronteira atual. Tudo o que está descrito nas seções 3 a 5 é escopo corrente: contratação e configuração de agentes, onboarding guiado, conhecimento isolado por empresa, canal de atendimento inicial, caixa de entrada com transferência, direcionamento ao checkout autorizado, histórico/auditoria/métricas básicas e ambiente de simulação.

Fronteira futura. Construtor visual completo de automações, campanhas em massa, CRM completo, múltiplos canais simultâneos, processamento próprio de pagamentos e atualizações autônomas de preços ou regras permanecem fora da primeira versão. "Agentes atualizados com o mercado" significa evoluir nossos métodos comerciais e templates após avaliação — não incorporar informações da internet às ofertas dos clientes sem aprovação.

O que não é presumido. A página pública da Umbler não comprova como ela implementa isolamento de dados entre empresas, resistência a instruções maliciosas, controle de permissões das ferramentas, versionamento e aprovação do conhecimento, validação de preços e condições, ou medição de qualidade dos agentes. Esses pontos entram na nossa avaliação técnica como requisitos a construir e verificar — não como capacidades herdadas. Para o nosso produto, o isolamento entre clientes é requisito de aceitação.

2c. Page Content and Component Coverage

Landing

• Informação/estado: proposta do produto como plataforma de contratação e gestão de agentes comerciais centrada no agente contratado; explicação da dualidade agente de IA ↔ atendente humano e da separação comportamento / roteiro / conhecimento; apresentação das três personas comerciais com um exemplo de fala real de cada uma na mesma objeção; caminho lead → agente → humano → checkout.
• Ações primárias: iniciar autoinscrição da empresa contratante; acessar a verificação de retorno.
• Ações de apoio: navegar pelas seções explicativas; ver o exemplo de conversa em duas camadas (bolha visível ↔ regra que autorizou).
• Entidades de domínio: persona comercial (Conservador, Descolado, Assertivo), agente comercial, conversa, regra autorizada.
• Responsabilidades de componente: hero dividido em duas metades por hairline de 1px; bloco de mockup de conversa; painel ink com log estruturado da mesma conversa; seletor de persona em três colunas; diagrama de fluxo lead → agente → humano → checkout.
• Estados: loading — esqueleto de painéis claro/escuro; empty — não aplicável (conteúdo estático); success — conteúdo renderizado com divisor central visível; error — fallback estático do conteúdo textual sem os mockups; recovery — recarregar a página mantém o conteúdo essencial legível.

Login

• Informação/estado: identificação da empresa contratante e do atendente humano; estado de sessão.
• Ações primárias: verificar identidade de retorno e entrar na área protegida.
• Ações de apoio: ir para a autoinscrição caso ainda não exista conta.
• Entidades de domínio: conta da empresa contratante, atendente humano, sessão.
• Responsabilidades de componente: formulário de verificação; mensagens de erro de credencial; link para Cadastro.
• Estados: loading — botão em processamento; empty — não aplicável; success — redirecionamento para Dashboard (empresa) ou Caixa de Entrada (atendente); error — credencial inválida com mensagem clara e sem revelar existência de conta; recovery — nova tentativa sem perder os campos digitados.

Cadastro

• Informação/estado: autoinscrição da empresa contratante que começa a usar a plataforma de forma independente, sem convite ou provisionamento estabelecido.
• Ações primárias: criar a conta da empresa contratante e estabelecer a identidade de primeiro uso.
• Ações de apoio: ir para Login caso já exista conta.
• Entidades de domínio: conta da empresa contratante, identidade de primeiro uso.
• Responsabilidades de componente: formulário de autoinscrição; validação de campos; confirmação de criação.
• Estados: loading — envio em processamento; empty — formulário inicial; success — conta criada e encaminhamento para o Dashboard para iniciar a contratação do agente; error — campo inválido ou conta já existente, com indicação do campo; recovery — corrigir o campo e reenviar sem perder o restante.

Dashboard

• Informação/estado: resumo da operação da empresa contratante e roteamento para contratação, configuração, onboarding, conhecimento, simulação, caixa de entrada, integrações e relatórios; estado de cada agente (rascunho, em simulação, ativo).
• Ações primárias: iniciar a contratação de um agente; retomar o onboarding; abrir a caixa de entrada; abrir relatórios.
• Ações de apoio: navegar para Conhecimento, Simulação, Integrações e Agentes.
• Entidades de domínio: agente comercial, persona, versão do agente, conversa, encaminhamento, resultado comercial.
• Responsabilidades de componente: cartões de estado por agente; atalhos de roteamento; indicador de pendências de aprovação.
• Estados: loading — esqueleto dos cartões; empty — nenhum agente contratado, com chamada para contratar o primeiro; success — cartões com estado atual; error — falha ao carregar dados com opção de recarregar; recovery — recarregar mantém o roteamento disponível.

Agentes

• Informação/estado: agentes contratados pela empresa; persona selecionada de cada agente; limites de atuação; estado da versão (rascunho, em simulação, ativa).
• Ações primárias: contratar um novo agente; escolher entre Conservador, Descolado e Assertivo; configurar comportamento, tom, intensidade comercial e limites de atuação.
• Ações de apoio: abrir o onboarding do agente; abrir a simulação; ativar uma versão aprovada.
• Entidades de domínio: agente comercial, persona comercial, limites de atuação, versão do agente.
• Responsabilidades de componente: lista de agentes; seletor de persona em três colunas com exemplo de fala na mesma objeção; painel de limites de atuação; indicador de que a persona muda a abordagem e não as permissões.
• Estados: loading — esqueleto da lista; empty — nenhum agente, com ação de contratar; success — agentes listados com persona e estado; error — falha ao salvar configuração com mensagem e retenção do valor anterior; recovery — reenviar a configuração sem perder o restante.

Onboarding

• Informação/estado: progresso nas sete etapas — (1) empresa e público, (2) catálogo comercial, (3) jornada, (4) argumentação, (5) regras, (6) operação humana, (7) simulação e publicação; para cada etapa, o que foi extraído versus o que foi revisado.
• Ações primárias: preencher cada etapa; revisar o que foi extraído; aprovar cada etapa.
• Ações de apoio: voltar a uma etapa anterior; abrir Conhecimento para alimentar com sites e documentos; abrir Simulação na etapa 7.
• Entidades de domínio: empresa e público, catálogo comercial (produtos, serviços, preços, condições, disponibilidade, links de compra), jornada de vendas, critérios de qualificação, regras de encaminhamento, argumentação (diferenciais comprováveis, objeções frequentes, respostas aprovadas), regras (descontos permitidos, assuntos proibidos, limites de negociação, exceções), operação humana (responsáveis, horários, filas, condições de transferência).
• Responsabilidades de componente: indicador de sete etapas; painel de extração que cruza de escuro (extraído, não confiável) para claro (revisado, publicado) a cada etapa aprovada; formulários por etapa; resumo do que foi aprovado.
• Estados: loading — carregamento da etapa atual; empty — etapa ainda não iniciada; success — etapa aprovada e painel claro; error — extração falhou ou campo obrigatório ausente, com a etapa mantida em escuro; recovery — corrigir ou reinserir a fonte e revisar novamente antes de aprovar.

Conhecimento

• Informação/estado: conhecimento separado por empresa; itens extraídos de sites e documentos aguardando revisão; itens revisados e tratados como verdade comercial; vínculo de cada item aos agentes autorizados.
• Ações primárias: alimentar o processo com sites e documentos; revisar cada informação extraída; vincular o conhecimento aos agentes autorizados.
• Ações de apoio: remover ou corrigir um item extraído; consultar quais agentes usam cada item.
• Entidades de domínio: documento, site, item de conhecimento, produto, serviço, preço, FAQ, política, agente autorizado.
• Responsabilidades de componente: área de ingestão; lista de itens extraídos com estado de revisão; controle de vínculo por agente; aviso explícito de que nada é publicado automaticamente como verdade comercial.
• Estados: loading — processamento da fonte; empty — nenhuma fonte adicionada; success — item revisado e vinculado; error — fonte inacessível ou extração vazia, com o item mantido como não confiável; recovery — reinserir a fonte ou preencher manualmente e revisar.

Simulação

• Informação/estado: conversas de teste com o agente; o que foi extraído e precisa de revisão; versão candidata do agente.
• Ações primárias: testar conversas; revisar o que foi extraído; aprovar a versão antes de ativar.
• Ações de apoio: repetir um cenário de teste; voltar ao onboarding para corrigir uma etapa.
• Entidades de domínio: conversa de simulação, versão do agente, item extraído, aprovação.
• Responsabilidades de componente: janela de conversa de teste; painel de regras que autorizaram cada resposta; controle de aprovação da versão.
• Estados: loading — agente preparando resposta; empty — nenhuma simulação iniciada; success — versão aprovada e pronta para ativação; error — resposta bloqueada por falta de condição comercial aprovada, exibida como bloqueio e não como invenção; recovery — corrigir a regra ou o dado comercial e repetir o teste.

Caixa de Entrada

• Informação/estado: atendimentos em andamento; quem está no controle de cada atendimento (agente de IA ou humano); estado de transferência; histórico da conversa.
• Ações primárias: assumir um atendimento; transferir para humano conforme condições configuradas; retomar de forma controlada.
• Ações de apoio: filtrar atendimentos; consultar o histórico da conversa; ver o motivo do encaminhamento.
• Entidades de domínio: atendimento, conversa, atendente humano, agente comercial, fila, condição de transferência, estado de controle.
• Responsabilidades de componente: lista de atendimentos; painel do agente e painel humano com transição de estado visível; selo de "humano no controle"; controle explícito de retomada.
• Estados: loading — carregamento da lista e da conversa; empty — nenhum atendimento ativo; success — atendimento assumido, painel do agente escurecido e painel humano aceso; error — falha ao assumir ou transferir, com o atendimento mantido no estado anterior; recovery — tentar novamente sem duplicar a transferência.

Atendimento

• Informação/estado: conversa do lead com o agente comercial pelo canal de atendimento inicial; preços e condições disponíveis; estado de qualificação; encaminhamento pendente ou concluído.
• Ações primárias: o lead pergunta, apresenta objeção, pede uma pessoa e é encaminhado ao checkout autorizado.
• Ações de apoio: retomar uma conversa; ver o link de compra autorizado.
• Entidades de domínio: lead, conversa, agente comercial, preço disponível, condição comercial, objeção, encaminhamento, checkout autorizado.
• Responsabilidades de componente: janela de conversa; bolhas de mensagem; indicação de transferência para humano; link de checkout autorizado.
• Estados: loading — agente preparando resposta; empty — conversa iniciada sem mensagens; success — resposta entregue com preço ou condição aprovada; error — condição comercial ausente, respondida sem invenção e com opção de encaminhamento humano; recovery — o lead pode pedir uma pessoa ou continuar a conversa.

Integrações

• Informação/estado: integrações com CRM, agenda, checkout e pagamentos conforme contratação; estado de conexão de cada integração; escopo autorizado.
• Ações primárias: configurar uma integração contratada; autorizar o uso pelo agente.
• Ações de apoio: desconectar uma integração; consultar quais agentes usam cada integração.
• Entidades de domínio: integração, CRM, agenda, checkout, pagamentos, credencial de integração, agente autorizado.
• Responsabilidades de componente: lista de integrações disponíveis por contratação; formulário de configuração; indicador de estado; aviso de que o processamento de pagamentos é do provedor.
• Estados: loading — verificação da conexão; empty — nenhuma integração contratada; success — integração conectada e vinculada; error — credencial inválida ou provedor indisponível, com a integração mantida desconectada; recovery — corrigir a credencial e reconectar.

Relatórios

• Informação/estado: histórico, auditoria e métricas básicas de conversas, qualificação, encaminhamentos e resultados comerciais.
• Ações primárias: consultar conversas, qualificação, encaminhamentos e resultados comerciais.
• Ações de apoio: filtrar por agente e por período; abrir uma conversa do histórico.
• Entidades de domínio: conversa, qualificação, encaminhamento, resultado comercial, registro de auditoria.
• Responsabilidades de componente: painel de métricas básicas; lista de conversas; registro de auditoria; filtros.
• Estados: loading — carregamento das métricas; empty — nenhum dado no período; success — métricas e histórico exibidos; error — falha ao carregar, com filtros preservados; recovery — recarregar ou ajustar o período.

3. Functional Requirements

Cada requisito é um ponto de história com proveniência (explicit, basic_default, required_inference), fatos de ciclo de vida e aceitação observável.

Contratação e configuração de agentes

FR-01 — Contratar um ou mais agentes comerciais (explicit) Como empresa contratante (administrador da conta), eu deveria contratar um ou mais agentes comerciais no portal, para que cada agente contratado seja o centro da operação.

• Gatilho/entrada: a empresa contratante acessa o portal e inicia a contratação.
• Resultado observável: o agente aparece na lista de agentes com estado inicial de rascunho.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao criar o agente mantém a lista inalterada e permite nova tentativa.
• Continuação: seguir para a configuração de comportamento e para o onboarding.

FR-02 — Escolher entre as três personas comerciais (explicit) Como empresa contratante, eu deveria escolher entre Conservador, Descolado e Assertivo ao configurar um agente, para que a abordagem comercial corresponda ao posicionamento do meu negócio.

• Gatilho/entrada: seleção de persona na configuração do agente.
• Resultado observável: o agente passa a usar a persona escolhida — Conservador (formal, cuidadoso, valoriza comprovação, reduz pressão), Descolado (conversacional, leve e direto, sem perder profissionalismo) ou Assertivo (proativo, trata objeções e propõe fechamento com mais iniciativa).
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao salvar mantém a persona anterior e permite reenviar.
• Continuação: configurar tom, intensidade comercial e limites de atuação.

FR-03 — Configurar comportamento, tom, intensidade comercial e limites de atuação (explicit) Como empresa contratante, eu deveria configurar comportamento, tom, intensidade comercial e limites de atuação do agente, para que a atuação comercial fique dentro do que autorizo.

• Gatilho/entrada: edição dos campos de comportamento do agente.
• Resultado observável: os limites ficam registrados na versão do agente e são aplicados na conversa.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao salvar preserva os valores anteriores.
• Continuação: seguir para o onboarding guiado.

FR-04 — A persona altera a abordagem, não as permissões (explicit) Como empresa contratante, eu deveria ter a garantia de que nenhum perfil de persona pode inventar descontos, criar falsa escassez, pressionar após uma recusa ou prometer resultados não autorizados, para que a escolha de persona não amplie o que o agente pode fazer.

• Gatilho/entrada: qualquer resposta do agente em qualquer persona.
• Resultado observável: respostas que exigiriam desconto não autorizado, falsa escassez, pressão após recusa ou promessa de resultado não autorizado são bloqueadas pela aplicação.
• Acesso: aplica-se a todos os agentes da empresa.
• Falha/recuperação: quando a resposta é bloqueada, o agente responde sem inventar e oferece encaminhamento humano.
• Continuação: a conversa segue com informação aprovada.

Onboarding guiado

FR-05 — Conduzir o onboarding guiado em sete etapas (explicit) Como empresa contratante, eu deveria percorrer um onboarding guiado em sete etapas — (1) empresa e público, (2) catálogo comercial, (3) jornada, (4) argumentação, (5) regras, (6) operação humana, (7) simulação e publicação —, para que o agente seja configurado a partir de como meu negócio realmente vende, e não de um único campo de prompt.

• Gatilho/entrada: início do onboarding para um agente.
• Resultado observável: cada etapa registra o que foi informado e o progresso fica visível.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: etapa incompleta permanece pendente e não avança.
• Continuação: avançar etapa a etapa até a simulação e publicação.

FR-06 — Etapa 1: empresa e público (explicit) Como empresa contratante, eu deveria informar o que vendo, para quem, meu posicionamento e meus canais de atendimento, para que o agente parta do contexto correto.

• Gatilho/entrada: preenchimento da etapa 1.
• Resultado observável: o contexto de empresa e público fica registrado na versão do agente.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: campo obrigatório ausente impede a aprovação da etapa.
• Continuação: seguir para o catálogo comercial.

FR-07 — Etapa 2: catálogo comercial (explicit) Como empresa contratante, eu deveria informar produtos e serviços, preços, condições, disponibilidade e links de compra, para que o agente responda com dados comerciais verificáveis.

• Gatilho/entrada: preenchimento da etapa 2.
• Resultado observável: o catálogo comercial fica registrado e vinculado ao agente.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: item sem preço ou condição fica marcado como incompleto e não é usado como verdade comercial.
• Continuação: seguir para a jornada.

FR-08 — Etapa 3: jornada (explicit) Como empresa contratante, eu deveria definir quando apresentar uma oferta, quais informações realmente qualificar e quando encaminhar, para que a jornada de vendas e os critérios de qualificação fiquem explícitos.

• Gatilho/entrada: preenchimento da etapa 3.
• Resultado observável: a jornada de vendas, os critérios de qualificação e as regras de encaminhamento ficam registrados.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: jornada sem critério de encaminhamento impede a aprovação da etapa.
• Continuação: seguir para a argumentação.

FR-09 — Etapa 4: argumentação (explicit) Como empresa contratante, eu deveria registrar diferenciais comprováveis, objeções frequentes e respostas aprovadas, para que o agente argumente apenas com o que foi aprovado.

• Gatilho/entrada: preenchimento da etapa 4.
• Resultado observável: diferenciais, objeções e respostas aprovadas ficam registrados e disponíveis ao agente.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: resposta não aprovada não é usada em conversa.
• Continuação: seguir para as regras.

FR-10 — Etapa 5: regras (explicit) Como empresa contratante, eu deveria definir descontos permitidos, assuntos proibidos, limites de negociação e exceções, para que a aplicação autorize ou bloqueie ações comerciais conforme minha decisão.

• Gatilho/entrada: preenchimento da etapa 5.
• Resultado observável: as regras ficam registradas e passam a autorizar ou bloquear ações do agente.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: regra conflitante é sinalizada e não é aplicada até ser resolvida.
• Continuação: seguir para a operação humana.

FR-11 — Etapa 6: operação humana (explicit) Como empresa contratante, eu deveria configurar responsáveis, horários, filas e condições de transferência, para que o encaminhamento humano aconteça conforme a operação real.

• Gatilho/entrada: preenchimento da etapa 6.
• Resultado observável: responsáveis, horários, filas e condições de transferência ficam registrados e passam a valer na caixa de entrada.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: ausência de responsável ou horário impede a aprovação da etapa.
• Continuação: seguir para simulação e publicação.

FR-12 — Etapa 7: simulação e publicação (explicit) Como empresa contratante, eu deveria testar conversas, revisar o que foi extraído e aprovar a versão antes de ativar, para que nenhuma versão entre em operação sem minha aprovação.

• Gatilho/entrada: conclusão das etapas 1 a 6 e abertura da etapa 7.
• Resultado observável: a versão só se torna ativa após aprovação explícita.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: versão não aprovada permanece em rascunho ou em simulação e não atende leads.
• Continuação: ativar a versão aprovada.

FR-13 — Alimentar o onboarding com sites e documentos (explicit) Como empresa contratante, eu deveria alimentar o processo com sites e documentos, para reduzir o esforço de preenchimento manual.

• Gatilho/entrada: indicação de um site ou documento como fonte.
• Resultado observável: o conteúdo é processado e apresentado como informação extraída.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: fonte inacessível ou extração vazia é sinalizada e nada é tratado como verdade comercial.
• Continuação: revisar o que foi extraído.

FR-14 — Revisar informações extraídas antes de tratá-las como verdade comercial (explicit) Como empresa contratante, eu deveria revisar as informações extraídas de sites e documentos antes que sejam tratadas como verdade comercial, para que nada seja publicado automaticamente.

• Gatilho/entrada: existência de itens extraídos aguardando revisão.
• Resultado observável: cada item passa de "extraído, não confiável" para "revisado, publicado" somente após revisão explícita.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: item não revisado permanece indisponível ao agente.
• Continuação: vincular o item revisado aos agentes autorizados.

Conhecimento

FR-15 — Manter conhecimento separado por empresa (explicit) Como empresa contratante, eu deveria ter meu conhecimento separado por empresa, para que apenas o meu conteúdo seja usado nas minhas conversas.

• Gatilho/entrada: qualquer consulta de conhecimento durante uma conversa.
• Resultado observável: a consulta retorna apenas documentos, histórico, credenciais e integrações da empresa dona da conversa.
• Acesso: aplica-se a todas as conversas e agentes.
• Falha/recuperação: tentativa de acesso cruzado é negada e registrada em auditoria.
• Continuação: a conversa segue com o conhecimento da própria empresa.

FR-16 — Vincular conhecimento apenas aos agentes autorizados (explicit) Como empresa contratante, eu deveria vincular cada item de conhecimento apenas aos agentes autorizados, para que um agente não use conteúdo que não lhe foi atribuído.

• Gatilho/entrada: atribuição de um item de conhecimento a um agente.
• Resultado observável: o agente usa somente os itens que lhe foram vinculados.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: item não vinculado não é usado pelo agente.
• Continuação: ajustar vínculos conforme a operação evolui.

Conversa e execução controlada

FR-17 — Conversa flexível e não linear (explicit) Como lead / cliente final em conversa, eu deveria conversar com o agente de forma flexível, sem uma sequência rígida, para resolver o que preciso na ordem em que preciso.

• Gatilho/entrada: mensagem do lead no canal de atendimento inicial.
• Resultado observável: o agente responde ao que foi perguntado, sem reiniciar um roteiro fixo.
• Acesso: canal de atendimento inicial, sem exigência de identidade de aplicação.
• Falha/recuperação: se a aplicação não autorizar a ação, o agente responde sem inventar e oferece encaminhamento humano.
• Continuação: a conversa segue até qualificação, encaminhamento humano ou checkout.

FR-18 — Responder o preço disponível quando perguntado (explicit) Como lead, eu deveria receber o preço disponível quando pergunto o preço, para decidir com informação concreta.

• Gatilho/entrada: pergunta de preço do lead.
• Resultado observável: o agente responde o preço aprovado no catálogo comercial.
• Acesso: canal de atendimento inicial.
• Falha/recuperação: se o preço não estiver aprovado, o agente não inventa e oferece encaminhamento humano.
• Continuação: o lead pode seguir para compra ou tirar outras dúvidas.

FR-19 — Não recomeçar a qualificação quando já há intenção de compra (explicit) Como lead, eu deveria não ser requalificado do zero quando já demonstro intenção de compra, para não repetir informações que já dei.

• Gatilho/entrada: sinal de intenção de compra na conversa.
• Resultado observável: o agente avança para oferta ou encaminhamento ao checkout em vez de reiniciar a qualificação.
• Acesso: canal de atendimento inicial.
• Falha/recuperação: se a intenção não for reconhecida, o agente pode perguntar de forma pontual, sem reiniciar o roteiro completo.
• Continuação: direcionamento ao checkout autorizado.

FR-20 — Argumentar objeções com informações aprovadas (explicit) Como lead, eu deveria ter minhas objeções tratadas com informações aprovadas, para receber uma resposta confiável.

• Gatilho/entrada: objeção apresentada pelo lead.
• Resultado observável: o agente responde usando diferenciais comprováveis e respostas aprovadas.
• Acesso: canal de atendimento inicial.
• Falha/recuperação: sem resposta aprovada para a objeção, o agente não inventa e oferece encaminhamento humano.
• Continuação: a conversa segue para qualificação, humano ou checkout.

FR-21 — Encaminhar quando o lead pede uma pessoa (explicit) Como lead, eu deveria ser encaminhado a uma pessoa quando peço, para falar com um humano quando quiser.

• Gatilho/entrada: pedido explícito de uma pessoa.
• Resultado observável: o atendimento é transferido para humano conforme as condições de transferência configuradas.
• Acesso: canal de atendimento inicial.
• Falha/recuperação: sem atendente disponível no horário, o lead é informado e o atendimento fica na fila configurada.
• Continuação: o atendente humano assume na caixa de entrada.

FR-22 — Não inventar condição comercial ausente (explicit) Como empresa contratante, eu deveria ter a garantia de que o agente não inventa quando falta uma condição comercial, para que nenhuma condição não autorizada chegue ao lead.

• Gatilho/entrada: pedido do lead que depende de condição comercial não aprovada.
• Resultado observável: a aplicação bloqueia a resposta inventada e o agente informa que não pode confirmar aquela condição.
• Acesso: aplica-se a todas as conversas.
• Falha/recuperação: o agente oferece encaminhamento humano em vez de improvisar.
• Continuação: o atendimento pode seguir com humano ou com informação aprovada.

FR-23 — O modelo interpreta e redige; a aplicação autoriza e verifica (explicit) Como empresa contratante, eu deveria ter a separação entre interpretação/redação do modelo e autorização/verificação da aplicação, para que a flexibilidade da conversa não amplie o que é permitido.

• Gatilho/entrada: qualquer resposta do agente que dependa de dado comercial ou ação.
• Resultado observável: a ação só é executada após autorização da aplicação e verificação do dado comercial.
• Acesso: aplica-se a todas as conversas.
• Falha/recuperação: verificação falha bloqueia a ação e registra o bloqueio.
• Continuação: o agente responde com alternativa aprovada ou encaminha para humano.

Operação humana

FR-24 — Caixa de entrada compartilhada entre IA e humanos (explicit) Como atendente humano (responsável pela operação humana), eu deveria acompanhar os atendimentos em uma caixa de entrada compartilhada com o agente de IA, para assumir quando necessário.

• Gatilho/entrada: abertura da caixa de entrada.
• Resultado observável: os atendimentos em andamento aparecem com o estado de controle de cada um.
• Acesso: destino protegido do atendente humano.
• Falha/recuperação: falha ao carregar mantém o estado anterior e permite recarregar.
• Continuação: assumir um atendimento.

FR-25 — Assumir o atendimento (explicit) Como atendente humano, eu deveria assumir um atendimento, para conduzir a conversa diretamente.

• Gatilho/entrada: ação de assumir sobre um atendimento.
• Resultado observável: o painel do agente escurece, o painel humano acende e um selo marca "humano no controle".
• Acesso: destino protegido do atendente humano.
• Falha/recuperação: falha ao assumir mantém o atendimento com o agente e permite nova tentativa.
• Continuação: o atendente conduz a conversa.

FR-26 — O agente deixa de responder quando o humano assume (explicit) Como atendente humano, eu deveria ter a garantia de que o agente deixa de responder naquele atendimento enquanto eu conduzo, para que o lead não receba respostas duplicadas ou conflitantes.

• Gatilho/entrada: atendimento assumido por humano.
• Resultado observável: nenhuma resposta do agente é enviada naquele atendimento enquanto o humano estiver no controle.
• Acesso: aplica-se ao atendimento assumido.
• Falha/recuperação: se o estado de controle se perder, o atendimento permanece com humano até retomada explícita.
• Continuação: retomada controlada quando o atendente devolver o atendimento.

FR-27 — Retomada controlada (explicit) Como atendente humano, eu deveria devolver o atendimento ao agente de forma explícita e controlada, para que o agente só volte a responder quando eu decidir.

• Gatilho/entrada: ação explícita de retomada.
• Resultado observável: o painel humano escurece, o painel do agente acende e o agente volta a responder naquele atendimento.
• Acesso: destino protegido do atendente humano.
• Falha/recuperação: falha na retomada mantém o humano no controle.
• Continuação: o agente segue a conversa com o contexto acumulado.

FR-28 — Transferência conforme condições configuradas (explicit) Como atendente humano, eu deveria receber atendimentos transferidos conforme responsáveis, horários, filas e condições de transferência configurados, para que a distribuição siga a operação definida.

• Gatilho/entrada: condição de transferência satisfeita ou pedido do lead.
• Resultado observável: o atendimento é direcionado ao responsável ou à fila configurada.
• Acesso: destino protegido do atendente humano.
• Falha/recuperação: sem responsável disponível, o atendimento permanece na fila e o lead é informado.
• Continuação: o atendente assume e conduz.

Direcionamento ao checkout

FR-29 — Direcionar ao checkout autorizado (explicit) Como lead, eu deveria ser direcionado ao checkout autorizado quando decido comprar, para concluir a compra pelo canal aprovado.

• Gatilho/entrada: decisão de compra na conversa.
• Resultado observável: o lead recebe o direcionamento para o checkout autorizado, com o link de compra aprovado.
• Acesso: canal de atendimento inicial.
• Falha/recuperação: checkout indisponível ou não configurado impede o direcionamento e o agente oferece encaminhamento humano.
• Continuação: a compra é concluída no provedor de checkout; a plataforma não processa pagamentos.

Integrações

FR-30 — Configurar integrações conforme contratação (explicit) Como empresa contratante, eu deveria configurar integrações com CRM, agenda, checkout e pagamentos conforme contratação, para conectar a operação comercial aos sistemas que já uso.

• Gatilho/entrada: configuração de uma integração contratada.
• Resultado observável: a integração fica conectada e vinculada aos agentes autorizados.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: credencial inválida ou provedor indisponível mantém a integração desconectada e sinaliza o erro.
• Continuação: usar a integração na operação.

FR-31 — Sem processamento próprio de pagamentos (explicit) Como empresa contratante, eu deveria ter a garantia de que a plataforma não processa pagamentos, para que o processamento permaneça com o provedor contratado.

• Gatilho/entrada: qualquer fluxo de compra iniciado na conversa.
• Resultado observável: a plataforma apenas direciona ao checkout autorizado; nenhum dado de pagamento é processado por ela.
• Acesso: aplica-se a todos os fluxos de compra.
• Falha/recuperação: falha no provedor é reportada como indisponibilidade do provedor.
• Continuação: o lead conclui a compra no provedor.

Histórico, auditoria e métricas

FR-32 — Histórico de conversas (explicit) Como empresa contratante, eu deveria consultar o histórico de conversas, para entender o que aconteceu em cada atendimento.

• Gatilho/entrada: consulta ao histórico.
• Resultado observável: as conversas da minha empresa ficam disponíveis com seus eventos.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao carregar preserva os filtros e permite recarregar.
• Continuação: abrir uma conversa específica.

FR-33 — Auditoria (explicit) Como empresa contratante, eu deveria consultar registros de auditoria, para verificar o que a aplicação autorizou, bloqueou e transferiu.

• Gatilho/entrada: consulta à auditoria.
• Resultado observável: os registros de autorização, bloqueio e transferência ficam disponíveis.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao carregar permite recarregar sem perder o período selecionado.
• Continuação: correlacionar o registro com a conversa correspondente.

FR-34 — Métricas básicas de conversas, qualificação, encaminhamentos e resultados comerciais (explicit) Como empresa contratante, eu deveria acompanhar métricas básicas de conversas, qualificação, encaminhamentos e resultados comerciais, para avaliar a operação.

• Gatilho/entrada: abertura dos relatórios.
• Resultado observável: as métricas básicas são exibidas por período e por agente.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: falha ao carregar mantém os filtros e permite recarregar.
• Continuação: ajustar configuração ou operação a partir do que foi observado.

Identidade e acesso

FR-35 — Autoinscrição da empresa contratante (required_inference) Como empresa contratante, eu deveria me autoinscrever para começar a usar a plataforma de forma independente, sem convite ou provisionamento estabelecido.

• Gatilho/entrada: início da autoinscrição a partir da Landing.
• Resultado observável: a conta da empresa contratante é criada e a identidade de primeiro uso é estabelecida.
• Acesso: interação anônima; o estado protegido permanece indisponível até a identidade ser estabelecida.
• Falha/recuperação: campo inválido ou conta já existente é sinalizado sem perder o restante do formulário.
• Continuação: seguir para o Dashboard e contratar o primeiro agente.

FR-36 — Verificação de retorno (required_inference) Como empresa contratante e como atendente humano, eu deveria verificar minha identidade ao retornar, para acessar o portal e a operação protegida com continuidade.

• Gatilho/entrada: acesso à verificação de retorno.
• Resultado observável: a sessão é restabelecida e o destino protegido correspondente é aberto.
• Acesso: interação anônima; o estado protegido permanece indisponível até a verificação.
• Falha/recuperação: credencial inválida é sinalizada sem revelar existência de conta e permite nova tentativa.
• Continuação: a empresa contratante segue para o Dashboard; o atendente humano segue para a Caixa de Entrada.

FR-37 — Aprovação da versão antes de ativar (required_inference) Como empresa contratante, eu deveria aprovar a versão do agente no ambiente de simulação antes de ativá-lo, para que nenhuma versão atenda leads sem minha aprovação.

• Gatilho/entrada: versão candidata pronta após a simulação.
• Resultado observável: a versão passa de "em simulação" para "ativa" somente após aprovação explícita.
• Acesso: destino protegido da empresa contratante.
• Falha/recuperação: sem aprovação, a versão permanece em simulação e não atende leads.
• Continuação: o agente ativo passa a atender no canal de atendimento inicial.

4. User Personas

Empresa contratante (administrador da conta)

Contexto de produto. É o dono da operação comercial ou gestor de vendas de uma PME brasileira que vende por conversa. Ele não quer um construtor de chatbots: quer contratar um agente comercial, ensinar como o negócio vende e acompanhar o que acontece. Seu registro emocional é de confiança controlada — tecnologia poderosa que precisa parecer auditável, não mágica.

Objetivo principal. Ter um agente comercial que converse de forma flexível com leads, responda com dados comerciais verificados, qualifique, encaminhe para humano ou para compra, e cuja atuação ele possa revisar, aprovar e auditar.

Responsabilidades aceitas. Contratar e configurar um ou mais agentes; escolher entre as três personas comerciais; conduzir o onboarding guiado nas sete etapas; alimentar o processo com sites e documentos; revisar o que foi extraído antes de tratá-lo como verdade comercial; vincular conhecimento apenas aos agentes autorizados; configurar integrações conforme contratação; testar conversas no ambiente de simulação; aprovar a versão antes de ativar; acompanhar histórico, auditoria e métricas básicas.

Entradas e decisões. O que vende, para quem, posicionamento e canais; produtos, serviços, preços, condições, disponibilidade e links de compra; quando apresentar oferta, o que qualificar e quando encaminhar; diferenciais comprováveis, objeções frequentes e respostas aprovadas; descontos permitidos, assuntos proibidos, limites de negociação e exceções; responsáveis, horários, filas e condições de transferência. Sua decisão mais crítica é a aprovação da versão — nada entra em operação sem ela.

Interações com outros participantes. Define as condições sob as quais o atendente humano recebe atendimentos. Sua configuração determina o que o lead ouve do agente. Depende do provedor externo para CRM, agenda, checkout e pagamentos.

Sucesso observável. O agente ativo responde com preço aprovado, não inventa condição ausente, encaminha quando o lead pede uma pessoa e direciona ao checkout autorizado; e ele consegue ver isso no histórico, na auditoria e nas métricas.

O que diferencia este papel. Ele é o único que autoriza — persona, regras, conhecimento, integrações e versão. Nenhum outro participante pode ampliar o que o agente pode fazer.

Atendente humano (responsável pela operação humana)

Contexto de produto. É a pessoa da operação comercial que trabalha lado a lado com o agente de IA na mesma caixa de entrada. Não configura o agente; ele assume conversas quando o lead pede uma pessoa ou quando as condições de transferência configuradas disparam.

Objetivo principal. Assumir o atendimento no momento certo, conduzir a conversa sem que o agente responda por cima, e devolver o atendimento ao agente de forma controlada quando fizer sentido.

Responsabilidades aceitas. Acompanhar os atendimentos na caixa de entrada compartilhada; assumir um atendimento; conduzir a conversa enquanto o agente deixa de responder naquele atendimento; retomar de forma explícita e controlada; receber atendimentos conforme responsáveis, horários, filas e condições de transferência.

Entradas e decisões. O estado de cada atendimento e quem está no controle; o motivo do encaminhamento; o histórico da conversa. Sua decisão central é assumir ou devolver o atendimento.

Interações com outros participantes. Recebe do lead o pedido de falar com uma pessoa ou chega por condição configurada pela empresa contratante. Compartilha o atendimento com o agente de IA, que silencia enquanto ele conduz.

Sucesso observável. Ao assumir, o painel do agente escurece, o painel humano acende e um selo marca "humano no controle"; o agente não envia nenhuma resposta naquele atendimento até a retomada explícita.

O que diferencia este papel. Ele conduz a conversa, mas não autoriza nada: não altera persona, regras, conhecimento nem versão do agente. Sua autoridade é sobre o atendimento em si.

Lead / cliente final em conversa

Contexto de produto. É a pessoa que chega pelo canal de atendimento inicial querendo informação ou compra. Não conhece a plataforma e não deveria precisar conhecer: para ele, existe apenas uma conversa.

Objetivo principal. Resolver o que precisa — saber preço, tirar dúvidas, tratar uma objeção, falar com uma pessoa ou comprar — sem repetir informações e sem receber resposta inventada.

Responsabilidades aceitas. Conversar com o agente de forma flexível e não linear; perguntar preço e receber o preço disponível; demonstrar intenção de compra sem ser requalificado do zero; apresentar objeções e receber argumentação aprovada; pedir uma pessoa e ser encaminhado; ser direcionado ao checkout autorizado.

Entradas e decisões. Suas mensagens são a entrada do sistema. Suas decisões são: continuar a conversa, pedir uma pessoa, ou seguir para o checkout.

Interações com outros participantes. Conversa com o agente comercial configurado pela empresa contratante e pode passar para o atendente humano quando pede ou quando as condições disparam. Conclui a compra no provedor de checkout, não na plataforma.

Sucesso observável. Recebe o preço aprovado quando pergunta; não é requalificado quando já demonstra intenção; recebe argumentação aprovada para sua objeção; é encaminhado quando pede uma pessoa; e chega ao checkout autorizado quando decide comprar.

O que diferencia este papel. É o único participante externo à operação e o destinatário final do resultado comercial. Sua jornada é o que a plataforma precisa tornar utilizável — e ele nunca vê as regras, apenas a conversa.

5. Core User Flows

Jornada 1 — A empresa contratante começa a usar a plataforma

1. A empresa contratante abre a Landing e entende que o produto é uma plataforma de contratação e gestão de agentes comerciais centrada no agente contratado, não um construtor de chatbots.
2. Ela inicia a autoinscrição e vai para Cadastro.
3. Em Cadastro, ela cria a conta da empresa contratante. A identidade de primeiro uso é estabelecida.
4. Resultado observável: a conta existe e ela é encaminhada ao Dashboard.
5. Continuação: no Dashboard, ela vê que nenhum agente foi contratado e inicia a contratação do primeiro.

Falha/recuperação: se um campo for inválido ou a conta já existir, o formulário sinaliza o campo e ela corrige sem perder o restante.

Jornada 2 — A empresa contratante contrata e configura um agente

1. No Dashboard, a empresa contratante inicia a contratação de um agente.
2. Em Agentes, ela escolhe entre Conservador, Descolado e Assertivo, vendo um exemplo de fala real de cada um na mesma objeção.
3. Ela configura comportamento, tom, intensidade comercial e limites de atuação.
4. Resultado observável: o agente aparece com a persona escolhida e estado de rascunho.
5. Continuação: ela segue para o Onboarding do agente.

Falha/recuperação: se o salvamento falhar, a persona anterior é mantida e ela reenvia.

Jornada 3 — A empresa contratante conduz o onboarding guiado

1. Em Onboarding, a empresa contratante preenche a etapa 1 — empresa e público: o que vende, para quem, posicionamento e canais de atendimento.
2. Ela preenche a etapa 2 — catálogo comercial: produtos e serviços, preços, condições, disponibilidade e links de compra.
3. Ela preenche a etapa 3 — jornada: quando apresentar uma oferta, quais informações realmente qualificar e quando encaminhar.
4. Ela preenche a etapa 4 — argumentação: diferenciais comprováveis, objeções frequentes e respostas aprovadas.
5. Ela preenche a etapa 5 — regras: descontos permitidos, assuntos proibidos, limites de negociação e exceções.
6. Ela preenche a etapa 6 — operação humana: responsáveis, horários, filas e condições de transferência.
7. Resultado observável: cada etapa aprovada faz o painel de extração cruzar de escuro (extraído, não confiável) para claro (revisado, publicado).
8. Continuação: ela segue para a etapa 7 — simulação e publicação.

Falha/recuperação: uma etapa com campo obrigatório ausente permanece pendente e não avança.

Jornada 4 — A empresa contratante alimenta o conhecimento e revisa o que foi extraído

1. Em Conhecimento, a empresa contratante indica sites e documentos como fontes.
2. O sistema processa as fontes e apresenta o conteúdo como informação extraída.
3. Ela revisa cada item extraído. Nada é publicado automaticamente como verdade comercial.
4. Ela vincula os itens revisados apenas aos agentes autorizados.
5. Resultado observável: os itens revisados passam a "revisado, publicado" e ficam disponíveis somente aos agentes vinculados.
6. Continuação: ela volta ao Onboarding para concluir as etapas restantes.

Falha/recuperação: se uma fonte estiver inacessível ou a extração vier vazia, o item permanece como não confiável e ela pode reinserir a fonte ou preencher manualmente.

Jornada 5 — A empresa contratante testa e aprova a versão

1. Na etapa 7 — simulação e publicação, a empresa contratante abre a Simulação.
2. Ela testa conversas com o agente e revisa o que foi extraído.
3. Ela observa, para cada resposta do agente, a regra e o dado comercial que a autorizaram.
4. Ela aprova a versão.
5. Resultado observável: a versão passa de "em simulação" para "ativa" e o agente começa a atender no canal de atendimento inicial.
6. Continuação: ela acompanha a operação pelo Dashboard e pelos Relatórios.

Falha/recuperação: se uma resposta for bloqueada por falta de condição comercial aprovada, ela corrige a regra ou o dado comercial e repete o teste. Sem aprovação, a versão não atende leads.

Jornada 6 — O lead conversa com o agente

1. O lead chega ao Atendimento, o canal de atendimento inicial, e conversa com o agente comercial.
2. Ele pergunta o preço. O agente responde o preço disponível aprovado no catálogo comercial.
3. Ele demonstra intenção de compra. O agente não recomeça a qualificação.
4. Ele apresenta uma objeção. O agente argumenta usando informações aprovadas.
5. Resultado observável: o lead recebe respostas concretas e verificadas, sem reinício de roteiro.
6. Continuação: ele pode seguir para o checkout autorizado ou pedir uma pessoa.

Falha/recuperação: se faltar uma condição comercial, o agente não inventa — informa que não pode confirmar e oferece encaminhamento humano.

Jornada 7 — O lead pede uma pessoa e o atendente humano assume

1. No Atendimento, o lead pede uma pessoa.
2. O sistema encaminha o atendimento conforme as condições de transferência configuradas (responsáveis, horários, filas).
3. Na Caixa de Entrada, o atendente humano vê o atendimento e assume.
4. Resultado observável: o painel do agente escurece, o painel humano acende e um selo marca "humano no controle". O agente deixa de responder naquele atendimento.
5. O atendente conduz a conversa com o lead.
6. Continuação: quando fizer sentido, ele faz a retomada controlada — o painel humano escurece, o painel do agente acende e o agente volta a responder com o contexto acumulado.

Falha/recuperação: se não houver atendente disponível no horário, o lead é informado e o atendimento permanece na fila configurada. Se a retomada falhar, o humano permanece no controle.

Jornada 8 — O lead é direcionado ao checkout autorizado

1. No Atendimento, o lead decide comprar.
2. O agente verifica a condição comercial e a aplicação autoriza a ação.
3. Resultado observável: o lead recebe o direcionamento para o checkout autorizado, com o link de compra aprovado.
4. Continuação: a compra é concluída no provedor de checkout. A plataforma não processa pagamentos.

Falha/recuperação: se o checkout estiver indisponível ou não configurado, o direcionamento não acontece e o agente oferece encaminhamento humano.

Jornada 9 — A empresa contratante configura integrações

1. Em Integrações, a empresa contratante configura as integrações contratadas — CRM, agenda, checkout e pagamentos.
2. Ela autoriza o uso por agentes específicos.
3. Resultado observável: a integração fica conectada e vinculada aos agentes autorizados.
4. Continuação: a operação passa a usar a integração.

Falha/recuperação: credencial inválida ou provedor indisponível mantém a integração desconectada e sinaliza o erro para correção.

Jornada 10 — A empresa contratante acompanha a operação

1. No Dashboard, a empresa contratante vê o estado de cada agente.
2. Em Relatórios, ela consulta histórico, auditoria e métricas básicas de conversas, qualificação, encaminhamentos e resultados comerciais.
3. Ela filtra por agente e por período e abre uma conversa do histórico.
4. Resultado observável: ela vê o que foi autorizado, bloqueado e transferido, e como a operação está performando.
5. Continuação: ela ajusta configuração, conhecimento ou regras e repete a simulação antes de aprovar uma nova versão.

Falha/recuperação: se o carregamento falhar, os filtros são preservados e ela pode recarregar.

Jornada 11 — A empresa contratante e o atendente humano retornam à plataforma

1. A empresa contratante ou o atendente humano acessa a verificação de retorno em Login.
2. Ele verifica sua identidade.
3. Resultado observável: a sessão é restabelecida e o destino protegido correspondente é aberto — Dashboard para a empresa contratante, Caixa de Entrada para o atendente humano.
4. Continuação: cada um retoma seu trabalho de onde parou.

Falha/recuperação: credencial inválida é sinalizada sem revelar existência de conta e permite nova tentativa sem perder os campos digitados.

6. Visuals Colors and Theme

A direção criativa é Dual-nature craft: the AI half and the human half in dialogue, com Adham Dannaway como musa. O vocabulário central é a composição em duas metades em diálogo — design ↔ código, antes ↔ depois — que mapeia exatamente a tese do produto: IA e humano na mesma caixa de entrada, extração automática versus revisão humana, persona versus permissões. É craft, não decoração.

Paleta (modo claro)

Proporção: ~70% paper/branco, ~25% ink, ~5% acento. Nada de azul, nada de gradiente.

Tipografia

• Headings: Archivo, pesos 500–700, tracking apertado (-0.02em), caixa alta em labels de seção. Títulos grandes, quase editoriais; wordmark e nomes das personas em peso 600. Nada de light, nada de serif.
• Body: Inter Tight.
• Escala modular 1.25: 12 / 15 / 19 / 24 / 30 / 38 / 48 / 64 / 88.
• Display: clamp(40px, 7vw, 88px) para o hero.
• Títulos de seção: clamp(28px, 4vw, 48px).
• Corpo: 15–17px com line-height 1.55.
• Monoespaçado (JetBrains Mono): apenas para dados, IDs de conversa, timestamps e o painel de código — nunca para copy corrida.

Linguagem de forma

Raios pequenos e consistentes: 4px em controles, 8px em cards, 0px em painéis de código e no divisor central. Sem pílulas, sem blobs, sem sombras difusas. Separação por hairlines de 1px e por contraste de superfície. O divisor vertical entre as duas metades é a forma-assinatura do sistema.

Layout

Grid de 12 colunas, gutter de 24px, margem de 32px em desktop e 16px em mobile. O hero é dividido em duas metades verticais (60/40) no desktop e empilhado no mobile. Cada seção alterna entre "painel claro" (conhecimento, operação humana) e "painel escuro" (execução, regras, logs) para materializar a dualidade. Espaçamento em escala de 8pt. Composições assimétricas com o conteúdo ancorado à esquerda e o artefato visual à direita — nada centralizado por padrão.

Imagem

Sem fotos de banco. A imagem é o próprio produto: mockups de conversa em painel claro com bolhas de chat, e ao lado o painel escuro com o JSON/YAML das regras que autorizam cada resposta. Diagramas de fluxo em linha fina de 1px mostrando o caminho lead → agente → humano → checkout, com nós em ink e o caminho autorizado em acento. Ícones de 1.5px stroke. Nada de ilustração decorativa.

7. Signature Design Concept

O divisor central de 1px que atravessa o hero e reaparece como transição entre seções, separando sempre "o que o cliente vê" (claro) de "o que o sistema autoriza" (escuro).

O hero ocupa a tela cheia, dividido verticalmente em duas metades por uma hairline de 1px.

Metade esquerda (60%) — o que o cliente vê. Ground paper #F4F1EA. Headline em Archivo 600 em clamp(40px, 7vw, 88px), alinhado à esquerda, quebrando em três linhas e ocupando toda a altura da metade: "O agente comercial que conversa — e a aplicação que autoriza." Abaixo, um bloco de mockup de conversa real com bolhas de chat: um lead pergunta preço, o agente responde o preço aprovado, e há um botão de transferência para humano.

Metade direita (40%) — o que o sistema autoriza. Painel ink #12100D full-bleed com texto #F4F1EA, exibindo a mesma conversa em formato de log estruturado: monoespaçado, com IDs, timestamps e o trecho de regra que autorizou cada resposta. A linha autorizada é destacada em #FF4A1C.

A metade escura é a prova da metade clara. Sem botão azul, sem gradiente, sem blob.

Movimentos-assinatura que o conceito implementa:

• O divisor central de 1px reaparece como transição entre seções.
• Componente de conversa em duas camadas: cada mensagem do agente mostra a bolha visível e, em hover, o painel escuro revela a regra e o dado comercial que a autorizou — a mesma conversa em dois registros.
• Seletor de persona em três colunas (Conservador / Descolado / Assertivo) com um exemplo de fala real de cada um na mesma objeção, mostrando que a persona muda o tom e não as permissões.
• Onboarding em sete etapas onde cada etapa aprovada faz o painel de extração cruzar de escuro (extraído, não confiável) para claro (revisado, publicado) — o progresso é literalmente uma mudança de superfície.
• Caixa de entrada com estado de transferência visível: ao assumir a conversa, o painel do agente escurece e um selo em acento marca "humano no controle", e o agente não volta a responder até a retomada ser explícita.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Sujeito focal: a conversa em duas camadas — a bolha de chat visível na metade clara e o log estruturado da mesma conversa na metade escura, com a linha autorizada em #FF4A1C.
• Tese input → transformação → outcome: a mensagem do lead entra na metade clara → a aplicação verifica o dado comercial e autoriza a ação → a linha correspondente acende em acento no painel escuro, provando que a resposta foi autorizada e não inventada. Nenhum comportamento novo é introduzido: apenas a dualidade já aceita é materializada.
• Vocabulário de movimento: transições de 160–220ms com easing cubic-bezier(0.2, 0.8, 0.2, 1), sem bounce. Reveals on scroll apenas com fade + 8px de translate. Hover em cards troca o conteúdo entre as duas metades (preview de conversa ↔ preview de regra).
• Primeiro frame composto: hero em tela cheia com o divisor de 1px já visível; headline em três linhas na metade esquerda; bloco de conversa com a pergunta de preço do lead e a resposta do agente; painel escuro à direita com o log estruturado e a linha autorizada já destacada em acento.
• Estado com movimento reduzido: a composição permanece completa e estática — headline, bloco de conversa e painel de log visíveis simultaneamente, sem transições e sem reveals; a linha autorizada permanece destacada em #FF4A1C como estado, não como animação.

Movimento na operação: na Caixa de Entrada, a transferência para humano é uma transição de estado — o painel do agente escurece e o painel humano acende — em 240ms. No Onboarding, cada etapa aprovada faz o painel de extração cruzar de escuro para claro.

9. Non-Functional Requirements

NFR-01 — Isolamento entre clientes como requisito de aceitação (explicit) Uma conversa não pode consultar documentos, histórico, credenciais ou integrações de outra empresa. O isolamento é verificado como critério de aceitação, não como capacidade presumida de terceiros. Racional: é o requisito de aceitação explicitamente declarado pelo usuário, e a página pública da Umbler não comprova como ela implementa isolamento de dados entre empresas.

NFR-02 — Autorização de ações pela aplicação, não pelo modelo (explicit) O modelo interpreta e redige; a aplicação autoriza ações e verifica dados comerciais. Nenhuma ação comercial é executada apenas por decisão do modelo. Racional: é a tese de execução declarada pelo usuário para combinar flexibilidade de conversa com regras de execução controladas.

NFR-03 — Limites invioláveis de persona (explicit) Nenhum perfil de persona pode inventar descontos, criar falsa escassez, pressionar após uma recusa ou prometer resultados não autorizados. A personalidade muda a abordagem, não as permissões. Racional: restrição explícita do usuário, aplicável a todas as personas.

NFR-04 — Nenhuma publicação automática de informação extraída (explicit) Informações extraídas de sites e documentos não podem ser publicadas automaticamente como verdade comercial; devem ser apresentadas para revisão. Racional: restrição explícita do usuário sobre a fronteira entre extração e aprovação.

NFR-05 — Silêncio do agente durante o controle humano (explicit) Quando o humano assume, o agente deixa de responder naquele atendimento até a retomada explícita. Racional: restrição explícita do usuário, necessária para evitar respostas duplicadas ou conflitantes.

NFR-06 — Nenhuma invenção de condição comercial ausente (explicit) Se falta uma condição comercial, o agente não inventa. Racional: restrição explícita do usuário sobre a integridade dos dados comerciais.

NFR-07 — Sem incorporação autônoma de informação da internet (explicit) "Agentes atualizados com o mercado" significa evoluir nossos métodos comerciais e templates após avaliação; não significa incorporar informações da internet às ofertas dos clientes sem aprovação. Racional: restrição explícita do usuário sobre a fronteira de atualização.

NFR-08 — Sem cópia da Umbler e sem contratação presumida (explicit) O produto não deve ser uma cópia da Umbler nem presumir contratação da Umbler; a página é referência de produto e experiência. Racional: restrição explícita do usuário sobre a relação com o benchmark.

NFR-09 — Mecanismos não comprovados entram como avaliação técnica (explicit) Não presumir capacidades não comprovadas pela página da Umbler — isolamento de dados, resistência a instruções maliciosas, controle de permissões de ferramentas, versionamento e aprovação do conhecimento, validação de preços e condições, medição de qualidade dos agentes. Esses pontos entram na avaliação técnica. Racional: restrição explícita do usuário sobre o que pode ser presumido do material comercial.

NFR-10 — Sem escolha impulsiva de ferramenta nem prazo sem dimensionamento (explicit) Antes da arquitetura, não escolher outra ferramenta por impulso nem prometer prazo sem dimensionamento. Racional: restrição explícita do usuário sobre o processo de planejamento.

NFR-11 — Continuidade de identidade para estado durável (required_inference) A empresa contratante e o atendente humano precisam de identidade de aplicação para retomar estado durável (agentes, versões, conhecimento, atendimentos) e para que decisões e transferências permaneçam vinculadas ao participante correto. O lead não precisa de identidade de aplicação para conversar no canal de atendimento inicial. Racional: inferência indispensável para tornar executável a continuidade aceita entre sessões; não introduz gestão de contas adjacente.

NFR-12 — Sem permissões diferenciadas além da separação de papéis aceita (required_inference) A separação entre a empresa contratante (que autoriza configuração, conhecimento, integrações e versão) e o atendente humano (que conduz atendimentos) é a única diferenciação de controle estabelecida. Não há RBAC adicional inferido. Racional: inferência limitada ao que a fonte aceita; evita inventar controle de permissões não estabelecido.

NFR-13 — Legibilidade e integridade de texto e controles em todos os viewports (explicit) Headlines, wordmarks, labels, números, textos de cards e controles permanecem inteiramente dentro do viewport e do container em 375px, 768px e 1280px, quebrando linha ou escalando (por exemplo, font-size: clamp(...) com seu tamanho mobile) para caber; nenhum outro elemento cobre qualquer parte deles. Imagem, decoração e movimento seguem a direção criativa e podem ser cortados, sangrados, rotacionados ou sobrepostos, desde que não cubram texto legível ou controle. Conteúdo móvel e rolável pode cruzar a borda por design, desde que cada item se torne inteiramente legível ao passar. Com prefers-reduced-motion, oferecer arranjo estático utilizável. Racional: restrição explícita de legibilidade e acessibilidade da direção criativa.

10. Tech Stack

A fonte não especifica tecnologia de implementação; as escolhas abaixo são defaults coerentes com o produto, marcados como não especificados pelo usuário.

• Frontend: React com TypeScript — aplicação web do portal da empresa contratante, da caixa de entrada e do canal de atendimento inicial. [Default — not specified by user]
• Backend: Python com FastAPI — autorização de ações, verificação de dados comerciais, isolamento por empresa, orquestração do agente e das transferências. [Default — not specified by user]
• Armazenamento: banco relacional para contas, agentes, versões, conhecimento revisado, conversas, transferências e registros de auditoria; armazenamento de objetos para documentos ingeridos. [Default — not specified by user]
• Cache e coordenação de estado em tempo real: Redis, para estado de controle de atendimento (agente ↔ humano), filas de transferência e sessões. [Default — not specified by user]
• Processamento assíncrono: worker dedicado para ingestão de sites e documentos e para o processamento de conversas, separado do processo da API. [Default — not specified by user]
• Containerização: Docker e docker-compose para o ambiente de desenvolvimento e execução local. [Default — not specified by user]
• Integrações externas: CRM, agenda, checkout e pagamentos via API/Webhook dos provedores contratados; a plataforma não processa pagamentos. [Default — not specified by user]

11. Assumptions and Constraints

Restrições vinculantes

1. Persona não altera permissões. Nenhum perfil pode inventar descontos, criar falsa escassez, pressionar após uma recusa ou prometer resultados não autorizados.
2. Extração não é publicação. Informações extraídas de sites e documentos devem ser apresentadas para revisão e não podem ser publicadas automaticamente como verdade comercial.
3. Isolamento entre clientes é requisito de aceitação. Uma conversa não pode consultar documentos, histórico, credenciais ou integrações de outra empresa.
4. Humano no controle silencia o agente. Quando o humano assume, o agente deixa de responder naquele atendimento.
5. Condição comercial ausente não é inventada.
6. Fora da primeira versão: construtor visual completo de automações, campanhas em massa, CRM completo, vários canais simultaneamente, processamento próprio de pagamentos e atualizações autônomas que alterem preços ou regras dos clientes.
7. "Agentes atualizados com o mercado" não significa incorporar informações da internet às ofertas dos clientes sem aprovação.
8. Sem cópia da Umbler e sem contratação presumida. A página é referência de produto e experiência.
9. Mecanismos não comprovados pela página da Umbler entram na avaliação técnica, não como capacidades presumidas.
10. Antes da arquitetura, não escolher outra ferramenta por impulso nem prometer prazo sem dimensionamento.

Suposições

1. A empresa contratante é a autoridade que autoriza persona, regras, conhecimento, integrações e versão do agente. (Suposição — derivada do escopo aceito.)
2. O atendente humano pertence à mesma empresa contratante e atua sobre os atendimentos dessa empresa. (Suposição — derivada do escopo aceito.)
3. O lead acessa o canal de atendimento inicial sem identidade de aplicação. (Suposição — derivada do escopo aceito.)
4. O provedor externo é responsável pelo processamento de pagamentos e pela disponibilidade do checkout. (Suposição — derivada do escopo aceito.)
5. A primeira versão opera com um único canal de atendimento inicial. (Suposição — derivada da exclusão explícita de vários canais simultaneamente.)

Fronteira de planejamento

O primeiro marco é esta especificação de produto (escopo, usuários, jornadas e limites), seguida de arquitetura (componentes, isolamento, integrações e custos estimados), protótipo (onboarding e operação simulada), implementação de uma jornada completa e piloto com empresas selecionadas. Cada etapa avança somente com sua condição declarada: aprovação do produto, revisão técnica, validação da experiência, testes funcionais e de segurança, e qualidade e custo medidos.

12. Glossary

• Agente comercial — o agente de IA contratado pela empresa contratante, centro do produto. Não é um construtor genérico de chatbots.
• Persona comercial — perfil de abordagem do agente: Conservador (formal, cuidadoso, valoriza comprovação, reduz pressão), Descolado (conversacional, leve e direto, sem perder profissionalismo) e Assertivo (proativo, trata objeções e propõe fechamento com mais iniciativa). Altera a abordagem, não as permissões.
• Comportamento — persona, tom, intensidade comercial e limites de atuação do agente.
• Roteiro — jornada de vendas, critérios de qualificação e regras de encaminhamento.
• Conhecimento — produtos, serviços, preços, FAQ, políticas e documentos do cliente, separados por empresa e vinculados apenas aos agentes autorizados.
• Onboarding guiado — processo de sete etapas: (1) empresa e público, (2) catálogo comercial, (3) jornada, (4) argumentação, (5) regras, (6) operação humana, (7) simulação e publicação.
• Informação extraída — conteúdo obtido de sites e documentos que ainda não foi revisado e não é tratado como verdade comercial.
• Verdade comercial — informação revisada e aprovada pela empresa contratante, usada pelo agente em conversa.
• Caixa de entrada compartilhada — superfície onde IA e humanos operam os mesmos atendimentos, com transferência e retomada controladas.
• Transferência — passagem do atendimento do agente para o atendente humano, conforme responsáveis, horários, filas e condições configuradas.
• Retomada controlada — devolução explícita do atendimento ao agente pelo atendente humano.
• Humano no controle — estado em que o atendente humano conduz o atendimento e o agente deixa de responder naquele atendimento.

• Checkout autorizado — destino de compra aprovado pela empresa contratante, operado por provedor externo; a plataforma não processa pagamentos.
• Simulação — ambiente onde a empresa contratante testa conversas, revisa o que foi extraído e aprova a versão antes de ativar.
• Versão do agente — configuração consolidada do agente que só se torna ativa após aprovação explícita.
• Isolamento entre clientes — requisito de aceitação: uma conversa não pode consultar documentos, histórico, credenciais ou integrações de outra empresa.
• Lead / cliente final — pessoa que conversa com o agente pelo canal de atendimento inicial.
• Umbler Talk — página pública de produto usada como benchmark de produto e experiência; não implica contratação nem reprodução integral da plataforma.