9. Gestão de Agentes de IA

9.1 Entendendo o Agente de IA
9.2. Capacidade de Criação de Lead/OPV
9.3 Consulta de Produtos por Empreendimento

9.1 Entendendo o Agente de IA

Pré-requisitos

Antes de criar seu primeiro Agente de IA, é necessário que a equipe técnica da Dommus realize algumas configurações iniciais na sua conta. Essas configurações são feitas uma única vez.

Se sua empresa ainda não possui essas configurações, entre em contato com o time de suporte técnico da Dommus.

Após a conclusão, você poderá criar e gerenciar seus Agentes de IA normalmente.

1. Visão Geral

A Gestão de Agentes de IA permite que administradores do inquilino criem e configurem agentes de atendimento automatizados que representam a empresa em canais como WhatsApp. Cada agente é personalizado com identidade corporativa, tom de voz e capacidades específicas, funcionando como um representante virtual da organização.

Esta funcionalidade resolve a necessidade de oferecer atendimento automatizado sem exigir intervenção técnica da Dommus. O administrador configura o agente uma única vez, associa-o aos canais de comunicação desejados e o sistema provisiona automaticamente a integração com a OpenAI. Além disso, todas as ações são rastreadas para auditoria, garantindo conformidade e segurança.

A funcionalidade é utilizada por administradores que desejam implementar atendimento por IA, sem necessidade de conhecimento técnico profundo. Os benefícios incluem redução de custos operacionais, disponibilidade 24/7 de atendimento, e rastreabilidade completa de todas as interações automatizadas.

2. Como acessar

Configurações → Agentes de IA

Alternativamente, é possível vincular um agente a um canal diretamente na tela de Ramais, sem navegar até a Gestão de Agentes.

3. Conhecendo a tela

A tela de Gestão de Agentes de IA é organizada em uma listagem principal que exibe todos os agentes cadastrados no cliente. No topo, o botão "Mais" permite criar um novo agente. A tabela paginada apresenta as informações essenciais de cada agente, facilitando a visualização e o gerenciamento rápido.

Cada linha da tabela oferece ações diretas: editar configurações, ativar ou inativar o agente, e rotacionar a chave de API. Um agente inativo não será utilizado em novos atendimentos, mas suas configurações são preservadas para reativação posterior.

4. Campos da tela

Nome do Agente

Nome de apresentação do agente que será exibido aos clientes finais.

Tipo: Texto

Obrigatório: Sim

Regras:

Máximo de 100 caracteres.
Campo obrigatório para salvar.

Modelo do Agente

Define o tipo de agente a ser criado. O modelo pré-seleciona o modelo OpenAI recomendado e exibe apenas as capacidades disponíveis para esse modelo.

Tipo: Lista (select)

Opção: Atendimento Pré-Venda

Modelo de IA

Versão específica do modelo de inteligência artificial da OpenAI que será utilizada pelo agente.

Tipo: Lista (select)

Obrigatório: Sim

Regras:

Pré-preenchido automaticamente com o modelo padrão sugerido pelo Modelo do Agente selecionado.
Editável, permitindo seleção de outras versões disponíveis.
Exemplo de valores: gpt-4o-mini, gpt-4o, etc.

Chave de API OpenAI

Credencial fornecida pelo usuário interno para autenticar o agente junto à OpenAI.

Tipo: Texto (campo de senha)

Obrigatório: Sim (na criação); Opcional (na edição)

Regras:

Informada manualmente pelo operador durante a criação.
Persistida de forma cifrada no backend; nunca é exibida após o salvamento.
Na edição, um checkbox "Adicionar nova chave de API" permite informar uma nova chave sem alterar a anterior.
Se o checkbox estiver desmarcado, a chave existente é mantida sem alteração.
Se o checkbox estiver marcado e o campo vazio, validação impede o envio com mensagem "Informe a nova chave de API."

Usuário-ator (auditoria)

Usuário do sistema responsável pela criação ou edição do agente. Este campo é utilizado para rastreamento em logs de auditoria.

Tipo: Lista pesquisável (select)

Obrigatório: Sim

Regras:

Carregado com usuários ativos da sua base.
Campo obrigatório para salvar.

Personalidade

Descrição do tom de voz e estilo de comunicação do agente. Define como o agente se comportará nas interações com clientes.

Tipo: Área de texto (textarea)

Obrigatório: Sim

Regras:

Máximo de 1.000 caracteres.
Campo obrigatório para salvar.

Exemplo:

Você é o DOM, SDR da Construtora Dommus, construtora referência em imóveis de alto padrão. Seu objetivo é qualificar leads e agendar reuniões com os Consultores Executivos.

Tom de Voz e Linguagem: Formal, elegante, sofisticado, caloroso e genuinamente acolhedor. Português culto, impecável e fluido — proibido usar gírias, jargões agressivos de vendas ou linguagem robótica. Sempre trate por "Senhor(a)" ou pelo nome precedido de cortesia (ex.: "Sr. Eduardo").

Postura e Princípios: Consultiva e Discreta — priorize a escuta ativa, respeitando o tempo e a privacidade do cliente. Sofisticação Sem Pressa — esqueça gatilhos de urgência ("Últimas unidades!"). O alto padrão exige paciência e exclusividade. Limites — seja solícita e segura, mas nunca negocie preços ou invente dados técnicos; direcione dúvidas complexas ao consultor com elegância.

Políticas da Empresa

Permite cadastrar orientações e regras específicas da empresa que devem ser consideradas pelo Agente de IA durante os atendimentos.

Utilize este campo para informar políticas, procedimentos ou diretrizes que o agente deve seguir ao interagir com os clientes.

Nome da empresa

Nome da empresa representada pelo agente.

Tipo: Texto

Obrigatório: Sim

Regras:

Máximo de 200 caracteres.
Campo obrigatório para salvar.

Descrição da empresa

Informações sobre produtos, serviços, diferenciais e contexto geral da empresa. O agente utiliza essas informações para fornecer respostas contextualizadas aos clientes.

Tipo: Área de texto (textarea)

Obrigatório: Sim

Regras:

Máximo de 2.000 caracteres.
Campo obrigatório para salvar.

Exemplo:

Construtora Dommus — Referência em Imóveis de Alto Padrão

Desde 2018, a Dommus se posiciona como uma construtora diferenciada no mercado imobiliário de alto padrão. Nossa missão transcende a simples construção de empreendimentos; buscamos estabelecer relações duradouras e significativas com cada cliente, compreendendo profundamente seus objetivos, desejos e aspirações.

Acreditamos que excelência não se limita ao produto final. Acompanhamos nossos clientes em todas as etapas da jornada: na fase de exploração e dúvidas, durante o processo de aquisição e construção, e, principalmente, após a entrega, mantendo um relacionamento próximo e atencioso. Cada empreendimento Dommus é resultado de um compromisso inabalável com a qualidade, a sofisticação e o cuidado personalizado.

Nossos diferenciais incluem: arquitetura contemporânea e sustentável, acabamentos premium, localização estratégica em regiões valorizadas, e um atendimento consultivo que prioriza a escuta ativa e a exclusividade. Contamos com uma rede consolidada de fornecedores, parceiros e consultores especializados, todos alinhados à nossa filosofia de excelência.

Hoje, a Dommus é sinônimo de confiança, inovação e realização de sonhos imobiliários para famílias que buscam mais do que um lar — buscam um legado.

Temperatura

Parâmetro que controla a criatividade e variabilidade das respostas do agente. Valores mais baixos produzem respostas mais previsíveis; valores mais altos, mais criativas.

Tipo: Número (decimal)

Obrigatório: Sim

Regras:

Intervalo: 0 a 2.
Passo: 0,1.
Valor padrão: 1,0.
Campo obrigatório para salvar.

Identificador público da chave

Identificador único e público da chave de API OpenAI associada ao agente. Utilizado para rastreabilidade de custos e identificação da chave sem expor seu valor secreto.

Tipo: Texto (somente leitura)

Obrigatório: Não

Regras:

Gerado automaticamente pelo sistema ao criar o agente.
Exibido apenas após o salvamento.
Acompanhado de botão "Copiar" para facilitar a cópia para a área de transferência.
Nunca editável pelo usuário.

5. Funcionalidades

Gerenciar capacidades

As capacidades representam funcionalidades específicas que o agente pode executar. Cada modelo de agente possui um conjunto de capacidades compatíveis.

Passo a passo:

Gerenciar bases de conhecimento

As bases de conhecimento fornecem informações contextuais que o agente utiliza para responder perguntas dos clientes com precisão.

Passo a passo:

Gerenciar contatos de origem

Os contatos de origem representam os canais de comunicação (como números de WhatsApp) através dos quais o agente atenderá os clientes.

Passo a passo:

Ativar ou inativar agente

Um agente inativo não será utilizado em novos atendimentos, mas suas configurações são preservadas.

Passo a passo:

Na tabela de agentes, localize o agente desejado.
Na coluna "Ações", clique no ícone de ativar/inativar (alternador ou ícone específico).

Rotacionar chave de API

A rotação de chave permite gerar uma nova credencial OpenAI sem excluir o agente, mantendo a segurança.

Passo a passo:

Na tabela de agentes, localize o agente desejado.
Na coluna "Ações", clique no ícone de rotacionar chave (chave ou ícone específico).
Uma caixa de confirmação aparece: "Deseja rotacionar a chave de API? A chave atual será revogada."
Clique em "Confirmar".
O sistema gera uma nova chave OpenAI e revoga a anterior.
A lista é recarregada e uma mensagem de sucesso é exibida: "Chave de API rotacionada com sucesso."
O identificador público da chave (id_chave_api_openai) na tabela é atualizado.
O valor secreto da nova chave nunca é exibido no frontend.

Vincular agente de IA na tela de Ramais

É possível vincular um agente diretamente na tela de Ramais, sem navegar até a Gestão de Agentes.

Passo a passo:

Acesse Configurações → Ramais.
Na tabela de ramais, localize a coluna "Agente de IA".
Clique no select da linha desejada.
Selecione o agente desejado.

6. Regras de negócio

Modelo imutável: O Modelo do Agente não pode ser alterado após a criação. Se for necessário mudar o modelo, um novo agente deve ser criado.
Provisionamento automático: Ao criar um agente, o sistema provisiona automaticamente a integração com a OpenAI usando a chave informada. O operador não precisa fazer nada além de fornecer a chave.
Rastreabilidade de auditoria: O campo "Usuário-ator" registra qual usuário criou ou editou o agente, permitindo rastreamento completo em logs de auditoria.
Agente inativo preserva configuração: Inativar um agente não desvincula seus contatos de origem nem apaga suas configurações. O agente pode ser reativado posteriormente com todas as suas definições intactas.
Contatos de origem reatribuíveis: Um contato de origem pode ser reatribuído de um agente para outro sem restrições, permitindo flexibilidade na configuração de canais.
Capacidades contextuais: Apenas as capacidades compatíveis com o modelo selecionado são exibidas e disponíveis para vinculação.
Bases de conhecimento opcionais: Um agente pode operar sem bases de conhecimento vinculadas. As bases são opcionais e utilizadas para enriquecer as respostas do agente.
Tenant-scoped: Todos os agentes, capacidades e contatos são isolados por inquilino (tenant). Um usuário só consegue visualizar e gerenciar agentes do seu próprio inquilino.

7. Fluxo da funcionalidade

Fluxo de criação e configuração completa de um agente:

Administrador acessa Configurações → Agentes de IA.
Clica em "Novo Agente".
Modal abre com a aba "Dados do Agente".
Seleciona o Modelo do Agente (ex: "Atendimento Pré-Venda").
Preenche Nome, Chave de API OpenAI, Usuário-ator, Personalidade, Nome da empresa e Descrição da empresa.
Ajusta Modelo de IA e Temperatura conforme necessário.
Clica em "Salvar".
Sistema valida os dados e cria o agente com a chave cifrada.
Modal fecha e mensagem de sucesso é exibida.
Lista é recarregada exibindo o novo agente.
Administrador clica em "Editar" para abrir o modal novamente.
Agora as abas "Capacidades", "Bases de Conhecimento" e "Contatos de Origem" estão disponíveis.
Na aba "Capacidades", adiciona as capacidades desejadas (ex: "Consulta de Disponibilidade", "Agendamento de Visita").
Na aba "Bases de Conhecimento", vincula bases relevantes (se disponíveis).
Na aba "Contatos de Origem", vincula os canais de comunicação (números de WhatsApp).
Clica em "Salvar".
Agente está pronto para atender clientes nos canais vinculados.

8. Observações

Chave de API nunca é exibida: Por razões de segurança, o valor secreto da chave de API OpenAI nunca aparece no frontend em nenhuma circunstância, nem durante a criação, edição ou rotação.
Identificador público para rastreabilidade: O campo id_chave_api_openai (identificador público) é exibido para permitir rastreamento de custos e auditoria, sem expor a chave secreta.
Operação de rotação de chave é atômica: O backend garante que a nova chave seja criada, o registro atualizado e a chave anterior revogada de forma atômica. Em caso de erro parcial, a chave anterior permanece válida.
Modelo OpenAI não validado em tempo de configuração: Se um modelo OpenAI inexistente for informado, a validação ocorre apenas no primeiro atendimento. A UI exibe um aviso informativo durante a edição.
Abas de edição não aparecem na criação: As abas "Capacidades", "Bases de Conhecimento" e "Contatos de Origem" só são exibidas no modal de edição, após o agente ser criado. Isso simplifica o fluxo de criação inicial.
Capacidades com slug não encontrado: Se uma capacidade tiver seu slug removido do código, ela aparecerá na UI com uma badge "indisponível" e um tooltip explicativo, sem bloquear a edição dos demais campos.
Integração com Twilio: A coexistência de um Agente de IA da Dommus e uma integração Twilio é permitida. O Agente de IA da Dommus tem prioridade no fluxo de atendimento, conforme informado ao operador.
Alterações entram em vigor imediatamente: Qualquer alteração salva em um agente entra em vigor imediatamente para novos atendimentos. Atendimentos em andamento não são afetados.
Cópia de identificador público: O botão "Copiar" ao lado do id_chave_api_openai facilita a cópia do identificador para a área de transferência, útil para rastreamento externo.

9.2. Capacidade de Criação de Lead/OPV

Visão Geral

A funcionalidade Envio do Lead ao CRM - Dommus Prospecta permite que o Agente de IA envie automaticamente para o Dommus Prospecta os leads identificados durante os atendimentos realizados pelo WhatsApp.

Com a integração, o lead é criado no CRM com as informações de Empreendimento, Mídia, Origem e Campanha, facilitando a continuidade do atendimento comercial.

Antes de Começar

Antes de utilizar a funcionalidade, é necessário:

Ter um Agente de IA cadastrado no Dommus Conecta.
Ter um ramal de WhatsApp configurado e associado ao Agente de IA.
Ativar a capacidade Envio do Lead ao CRM - Dommus Prospecta no Agente de IA.
Configurar os mapeamentos de Mídias, Origens e Campanhas no Dommus Prospecta.

Como Configurar

1. Ativar a capacidade no Agente de IA

Acesse Configurações > Agentes de IA, localize o agente desejado e clique em Editar.

Na aba Capacidades, adicione a opção Envio do Lead ao CRM - Dommus Prospecta.

2. Configurar o ramal do WhatsApp

Acesse Configurações > Ramais e, na seção WhatsApp, edite o ramal utilizado no atendimento.

Confira se o Agente de IA está corretamente associado ao ramal.

3. Configurar os mapeamentos

No Dommus Prospecta, acesse Configurações > Mapeamentos.

Configure as informações utilizadas pela integração:

Configuração	Valor utilizado
Mídia	WHATSAPP
Origem	CENTRAL DE ATENDIMENTO
Campanha	CAMPANHA PADRÃO

Como Funciona

Após as configurações, o fluxo ocorre automaticamente:

O cliente inicia um atendimento pelo WhatsApp.
O Agente de IA realiza o atendimento e identifica o empreendimento de interesse.
A capacidade envia as informações do lead para o Dommus Prospecta.
O lead é criado como uma oportunidade no CRM.
O registro fica disponível em Lista de Oportunidades.

Identificação do Empreendimento

O Agente de IA tenta identificar o empreendimento durante a conversa com o cliente.

Caso não consiga identificar a informação durante o atendimento, o sistema utiliza o empreendimento configurado no contato de origem.

Pontos de Atenção

Verifique se a capacidade Envio do Lead ao CRM - Dommus Prospecta está ativa no Agente de IA.
Confirme se o ramal do WhatsApp está associado ao agente correto.
Mantenha os mapeamentos de Mídia, Origem e Campanha configurados no Dommus Prospecta.
A oportunidade somente poderá ser criada corretamente se as informações necessárias estiverem devidamente mapeadas.

Resultado

Após o atendimento, a oportunidade criada pelo Agente de IA pode ser consultada na tela Lista de Oportunidades do Dommus Prospecta.

9.3 Consulta de Produtos por Empreendimento

Visão Geral

A capacidade Consulta de Produtos - Empreendimentos permite que o agente de IA consulte informações dos empreendimentos cadastrados no sistema e utilize esses dados durante o atendimento aos clientes.

A partir da configuração do empreendimento e da habilitação dessa capacidade, o agente pode consultar informações como:

Unidades disponíveis;
Valores;
Atrativos e características do empreendimento;
Características das unidades, como tipologia, área, quartos, suítes, banheiros e vagas;
Fotos cadastradas.

Antes de Começar

Para utilizar a capacidade, é necessário:

Possuir um empreendimento cadastrado em VENDE > Configurações > Gestão de Empreendimentos;
Configurar o empreendimento para exibição aos clientes;
Preencher corretamente as informações das unidades;
Habilitar a capacidade Consulta de Produtos - Empreendimentos no agente de IA.

Como Configurar

1. Configurar o Empreendimento

Acesse VENDE > Configurações > Gestão de Empreendimentos e edite o empreendimento que será disponibilizado para consulta.

Na aba Cadastro, confira as seguintes configurações:

Exibir para o Cliente (chatbots)?

Deve estar habilitado para permitir que o empreendimento seja consultado pelo agente de IA.

Tipo

Deve estar configurado como:

Empreendimento de Fato - Lançamento, Incorporação, Loteamento e Afins

Empreendimentos configurados como Catálogo de Imóveis Avulsos não terão suas unidades consultadas por essa capacidade.

2. Conferir as Informações das Unidades

As unidades devem estar cadastradas com suas respectivas informações, como:

Tipologia;
Disponibilidade;
Valores;
Área;
Quartos;
Suítes;
Banheiros;
Vagas;
Galeria de fotos.

3. Habilitar a Capacidade de IA

No Dommus Conecta, na configuração do agente de IA, habilite a capacidade:

Consulta de Produtos - Empreendimentos

Após essas configurações, o agente estará apto a consultar os dados dos empreendimentos configurados.

Informações Consultadas pelo Agente

Durante o atendimento, o agente de IA pode consultar e apresentar ao cliente as informações cadastradas no empreendimento.

Unidades Disponíveis

Permite consultar as unidades disponíveis para venda e suas respectivas características.

Valores

Permite consultar os valores cadastrados para as unidades.

Atrativos do Empreendimento

Permite utilizar as características e informações cadastradas sobre o empreendimento para complementar a apresentação ao cliente.

Características das Unidades

O agente pode consultar informações como:

Tipologia;
Área;
Quartos;
Suítes;
Banheiros;
Vagas.

Galeria

Quando houver imagens cadastradas, as fotos vinculadas às unidades também podem ser utilizadas na consulta.

O Que Acontece Depois

Com o empreendimento corretamente configurado e a capacidade Consulta de Produtos - Empreendimentos habilitada, o agente passa a consultar essas informações durante os atendimentos.

Por exemplo, ao receber uma solicitação sobre determinado empreendimento, o agente pode consultar as unidades disponíveis e apresentar ao cliente opções com seus respectivos valores e características.

Em Caso de Erro

Caso o agente não encontre as informações do empreendimento, verifique:

Se Exibir para o Cliente (chatbots)? está habilitado;
Se o Tipo do empreendimento está configurado corretamente;
Se existem unidades cadastradas e disponíveis;
Se as informações das unidades estão preenchidas;
Se a capacidade Consulta de Produtos - Empreendimentos está habilitada para o agente.

Se as configurações estiverem corretas e o agente continuar sem consultar os dados, procure o suporte da Dommus.

Boas Práticas e Pontos de Atenção

Mantenha as informações dos empreendimentos e unidades atualizadas.
Mantenha os valores e a disponibilidade das unidades atualizados.
Preencha as características das unidades para permitir respostas mais completas.
Cadastre fotos na galeria sempre que disponíveis.
A qualidade das informações apresentadas pelo agente depende dos dados cadastrados no sistema.