Skip to main content

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

image.png

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.

image.png

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.

image.png

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

image.png

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.

    image.png


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.

    image.png


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.


image.png

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.

image.png

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.

image.png

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:

  1. Abra o modal de edição do agente (conforme descrito acima).
  2. Clique na aba "Capacidades".
  3. A aba exibe a lista de capacidades atualmente vinculadas ao agente.

    image.png


  4. Para adicionar uma capacidade:
    • Selecione a capacidade e selecione o botão "+ Adicionar".
    • Um select pesquisável aparece com as capacidades disponíveis (excluindo as já vinculadas).
    • Selecione uma capacidade.
    • Clique no botão verde de confirmação.

      image.png


  5. Para remover uma capacidade:
    • Clique no ícone de lixeira (remover) ao lado da capacidade desejada.

      image.png


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:

  1. Abra o modal de edição do agente.
  2. Clique na aba "Bases de Conhecimento".
  3. A aba exibe a lista de bases atualmente vinculadas ao agente.
  4. Se não houver bases cadastradas no sistema, a mensagem "Nenhuma Base de Conhecimento cadastrada." é exibida.
  5. É permitido ter zero bases vinculadas.

image.png

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:

  1. Abra o modal de edição do agente.
  2. Clique na aba "Contatos de Origem".
  3. A aba exibe a lista de contatos de origem atualmente vinculados ao agente.
  4. Para adicionar um contato:
    • Clique no campo "Selecione" ou no botão "+ Adicionar".
    • Um select pesquisável aparece com os contatos disponíveis
    • Contatos já vinculados a outro agente exibem uma indicação visual ("vinculado ao Agente X") e podem ser reatribuídos.
    • Selecione um contato.
    • Clique no botão verde de confirmaçãoimage.png
  5. Para remover um contato:
    • Clique no ícone de lixeira (remover) ao lado do contato desejado.

      image.png

    • O contato é removido e uma mensagem de sucesso é exibida: "Contato de Origem removido com sucesso."

Ativar ou inativar agente

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

Passo a passo:

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

    image.png

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:

  1. Na tabela de agentes, localize o agente desejado.
  2. Na coluna "Ações", clique no ícone de rotacionar chave (chave ou ícone específico).
  3. Uma caixa de confirmação aparece: "Deseja rotacionar a chave de API? A chave atual será revogada."
  4. Clique em "Confirmar".
  5. O sistema gera uma nova chave OpenAI e revoga a anterior.
  6. A lista é recarregada e uma mensagem de sucesso é exibida: "Chave de API rotacionada com sucesso."
  7. O identificador público da chave (id_chave_api_openai) na tabela é atualizado.
  8. 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:

  1. Acesse Configurações → Ramais.

    image.png

  2. Na tabela de ramais, localize a coluna "Agente de IA".
  3. Clique no select da linha desejada.
  4. 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:

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

8. Validações e mensagens

SituaçãoMensagem
Campo obrigatório não preenchido"Este campo é obrigatório." (inline, borda vermelha)
Temperatura fora do intervalo 0-2"A temperatura deve estar entre 0 e 2." (inline)
Chave de API vazia ao marcar "Adicionar nova chave""Informe a nova chave de API." (inline)
Sucesso ao criar agente"Agente criado com sucesso." (toast verde)
Sucesso ao editar agente"Agente atualizado com sucesso." (toast verde)
Sucesso ao ativar/inativar"Agente [ativado/inativado] com sucesso." (toast verde)
Sucesso ao rotacionar chave"Chave de API rotacionada com sucesso." (toast verde)
Sucesso ao vincular capacidade"Capacidade vinculada com sucesso." (toast verde)
Sucesso ao remover capacidade"Capacidade removida com sucesso." (toast verde)
Sucesso ao vincular base"Base de Conhecimento vinculada com sucesso." (toast verde)
Sucesso ao remover base"Base de Conhecimento removida com sucesso." (toast verde)
Sucesso ao vincular contato"Contato de Origem vinculado com sucesso." (toast verde)
Sucesso ao remover contato"Contato de Origem removido com sucesso." (toast verde)
Sucesso ao vincular agente em ramal"Agente atualizado no ramal com sucesso." (toast verde)
Erro genérico ao salvar"Erro ao salvar agente. Tente novamente." (Swal.fire)
Erro genérico ao atualizar"Erro ao atualizar agente. Tente novamente." (Swal.fire)
Erro genérico ao carregar lista"Erro ao carregar agentes." (Swal.fire)
Confirmação de ativar/inativar"Deseja [ativar/inativar] o agente '[nome]'?" (Swal.fire)
Confirmação de rotacionar chave"Deseja rotacionar a chave de API? A chave atual será revogada." (Swal.fire)
Confirmação de remover capacidade"Deseja remover a capacidade '[nome]'?" (Swal.fire)
Confirmação de remover base"Deseja remover o vínculo com a base '[nome]'?" (Swal.fire)
Confirmação de remover contato"Deseja remover o vínculo do contato '[nome]'?" (Swal.fire)
Confirmação de vincular em ramal"Deseja vincular o agente '[nome]' ao ramal '[nome]'?" (Swal.fire)
Confirmação de desvincular em ramal"Deseja desvincular o agente deste ramal?" (Swal.fire)
Aviso: Bases não cadastradas"Nenhuma Base de Conhecimento cadastrada." (informativo)
Aviso: Modelo não editável"O Modelo não pode ser alterado após a criação do Agente." (tooltip)
Aviso: Integração Twilio presente"O Agente Dommus tem prioridade no fluxo de atendimento sobre a integração Twilio." (informativo)
Aviso: Integração Twilio em ramal"Este ramal usa integração Twilio. O Agente de IA da Dommus terá prioridade se selecionado." (informativo)
Estado vazio: Nenhum agente"Nenhum agente cadastrado. Clique em 'Novo Agente' para começar."

9. 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.

Back to top