¶ 
Harpia (Gestão 360) — Guia de Usuário: Módulo Configuração do Agente de IA
¶ 
Sumário
Cenário: Acessar a Configuração do Agente de IA
Cenário: Configurar o Provedor de IA
Cenário: Configurar modelos, limites e preços
Cenário: Gerenciar a Base de Conhecimento
Cenário: Configurar a integração com o Portal Wiki
Cenário: Definir o escopo de indexação do Wiki
Cenário: Acompanhar o uso do Agente de IA
Regras de Negócio Relacionadas
Veja Também
¶ Cenários
O Agente de IA é o motor por trás do Assistente Harpia (ver o guia "Módulo Assistente Harpia"): ele busca, na base de conhecimento, os trechos que respondem à pergunta do usuário e escreve a resposta com um modelo de inteligência artificial de um provedor externo. A tela Configuração do Agente de IA, no módulo de Administração, reúne tudo o que é preciso para manter esse motor funcionando: qual provedor e quais modelos usar, quanto se pode consumir por mês, quais documentos o Agente conhece e como acompanhar as perguntas que ele recebe.
¶ Cenário: Acessar a Configuração do Agente de IA
- No menu lateral, clique em "Administração" e, no submenu, em "Configuração do Agente de IA".
-
A tela abre com uma linha de botões, uma para cada aba: Provedor, Modelos, Base de Conhecimento, Integração Wiki, Escopo de Indexação e Acompanhamento. A aba ativa fica destacada em azul e o caminho no topo da tela (Administração / Agente de IA / aba) acompanha a aba escolhida. Pelo menu, a tela abre na aba Base de Conhecimento.
2.1. Em cada aba, o ícone de atualizar no canto superior direito do painel recarrega os dados da tela.
-
O que cada pessoa vê depende do perfil de acesso:
3.1. Administração do Agente: vê as seis abas e pode alterar todas as configurações.
3.2. Curadoria da base (equipe de suporte): vê apenas as abas Base de Conhecimento e Acompanhamento. Pode incluir documentos e respostas validadas e consultar as listas do acompanhamento, mas não vê os indicadores nem as ações de editar, reprocessar e excluir.
¶ Cenário: Configurar o Provedor de IA
O provedor é a empresa que fornece os modelos de inteligência artificial usados pelo Agente.
-
Clique na aba "Provedor".
1.1. Enquanto nenhum provedor tiver sido configurado, aparece o aviso azul "Nenhum provedor configurado ainda. Selecione um provedor e informe a API Key para ativar o Agente de IA."
-
No campo Provedor (Campo Obrigatório), escolha uma das opções: Google, OpenAI, Anthropic ou OpenRouter.
-
No campo API Key, informe a chave de acesso fornecida pelo provedor. O campo é obrigatório quando ainda não há chave salva ou quando o provedor é trocado — a chave de um provedor não vale para outro. Se o provedor continua o mesmo, deixe o campo em branco para manter a chave atual (o campo mostra "API Key já configurada — deixe em branco para manter"). O ícone de olho exibe ou oculta o que está sendo digitado.
-
Clique em "Salvar". O botão só fica habilitado quando os campos obrigatórios estão preenchidos. O sistema exibe a mensagem "Provedor salvo com sucesso." Caso o servidor recuse o cadastro, os motivos aparecem numa caixa de erros acima do formulário.
-
Trocando de provedor: ao salvar um provedor diferente do atual, o sistema pede confirmação com a mensagem "Você está trocando o provedor de IA de … para …. Essa troca marcará a base de conhecimento como pendente de reindexação. Deseja continuar?". Clique em "Confirmar troca" para seguir ou em "Cancelar" para desistir.
5.1. Depois da troca, aparece um aviso laranja: "Há uma reindexação da base de conhecimento pendente devido à última troca de provedor. Até que ela seja executada, as respostas do agente continuam usando os vetores gerados pelo provedor anterior."
5.2. Clique em "Reindexar agora" para refazer a indexação com o novo provedor. A operação reprocessa a base de conhecimento, os convênios e o Wiki de uma vez e pode demorar. Ao terminar, o sistema informa "Reindexação concluída (N trecho(s) indexado(s))." e o aviso some.
¶ Cenário: Configurar modelos, limites e preços
-
Clique na aba "Modelos".
1.1. Se nenhum provedor foi configurado, aparece o aviso "Configure um provedor primeiro." com o link "Ir para Provedor", e os campos de modelo e o botão Salvar ficam desabilitados.
-
Na parte superior, escolha os três modelos (Campo Obrigatório), todos listados a partir do provedor configurado:
2.1. Modelo de Embeddings: transforma os textos da base em representações numéricas, usadas para encontrar os trechos parecidos com a pergunta.
2.2. Modelo de Recuperação: reordena os trechos encontrados e escolhe os mais relevantes para a resposta.
2.3. Modelo de Geração: escreve a resposta final que o usuário lê.
-
Informe o Limite Mensal de Consumo de Tokens (Campo Obrigatório, valor maior que zero). Ao atingir esse limite, o Assistente deixa de responder novas perguntas até o início do mês seguinte.
3.1. O campo Tokens Consumidos no Mês é apenas informativo e mostra o total já usado, com o detalhamento "Interações do chat" e "Indexação da base".
3.2. O limite considera apenas as interações do chat, e a contagem reinicia no dia 1 de cada mês.
-
Em Limites de Requisição ao Provedor, defina quanto o sistema pode pedir ao provedor (todos Campo Obrigatório). Mantenha esses valores abaixo da cota contratada no console do provedor, por exemplo 80% das requisições por minuto do plano:
4.1. Requisições por Minuto: de 1 a 10.000 (padrão 120).
4.2. Requisições Simultâneas: de 1 a 100 (padrão 10).
4.3. Espera Máxima por Vaga (segundos): de 1 a 120 (padrão 20) — por quanto tempo uma pergunta aguarda uma vaga livre antes de falhar.
-
Em Preços dos Modelos (US$ por 1 milhão de tokens), informe o preço vigente de cada modelo, conforme a tabela do provedor (todos Campo Obrigatório, de 0 a 1.000, com até 4 casas decimais): Geração — Entrada, Geração — Saída, Reordenação — Entrada, Reordenação — Saída e Embeddings — Entrada. Os preços servem para registrar o custo estimado de cada pergunta, e as alterações valem apenas para as próximas perguntas.
-
Clique em "Salvar". O sistema exibe "Modelos, limites e preços salvos com sucesso."
6.1. Se algum valor estiver fora do intervalo ou vazio, o campo mostra a mensagem em vermelho (por exemplo, "Informe de 1 a 10.000") e o botão Salvar fica desabilitado até a correção.
¶ Cenário: Gerenciar a Base de Conhecimento
A base de conhecimento reúne tudo o que o Assistente pode consultar para responder: documentos enviados, respostas validadas pelo suporte e, se a integração estiver ativa, as páginas do Portal Wiki.
-
Clique na aba "Base de Conhecimento". A tabela lista os itens com Nome, Tipo (formato do arquivo ou "Resposta validada"), Assunto, Perfil, Status e Enviado em. Clique no título de uma coluna para ordenar. Sem nenhum item, a tabela mostra "Nenhum documento enviado ainda."
1.1. O Perfil indica quem pode receber informações daquele item: todos, interno ou externo.
1.2. O Status mostra se o item está ativo (já pode ser consultado), processando (sendo indexado) ou com erro. Use o filtro Status acima da tabela para ver só um desses grupos e clique no "x" do filtro para voltar a ver todos.
-
Enviar um documento: clique em "Enviar Documento". Um formulário se abre acima da tabela.
2.1. Em Arquivo (Campo Obrigatório), clique em "Selecionar arquivo" e escolha um arquivo .pdf, .docx, .pptx ou .md de até 20 MB. Arquivos de outro tipo ou maiores que o limite são recusados com as mensagens "Tipo de arquivo não permitido. Envie um arquivo .pdf, .docx, .pptx ou .md." e "O tamanho máximo do arquivo é de 20 MB."
2.2. O campo Nome (Campo Obrigatório) vem preenchido com o nome do arquivo e pode ser alterado.
2.3. Em Perfil (Campo Obrigatório), escolha Todos (padrão), Interno ou Externo para definir quem pode receber informações do documento.
2.4. Clique em "Enviar". O sistema exibe "Documento enviado com sucesso." e o item aparece no topo da tabela. Para desistir, clique em "Cancelar".
-
Cadastrar uma resposta validada: use este recurso para registrar uma pergunta frequente com a resposta oficial do suporte. Clique em "Cadastrar resposta validada" e preencha a janela:
3.1. Pergunta (Campo Obrigatório, até 1000 caracteres): escreva como o usuário faria a pergunta.
3.2. Resposta (Campo Obrigatório, até 10.000 caracteres): a resposta validada pelo suporte.
3.3. Perfil (Campo Obrigatório): Todos, Interno ou Externo. Aqui o campo não vem preenchido, para que quem cadastra escolha conscientemente quem poderá receber a resposta.
3.4. Assunto (Campo Obrigatório, até 100 caracteres): o tema da resposta, por exemplo "Prestação de contas".
3.5. Os contadores abaixo de cada campo mostram quantos caracteres já foram usados. Clique em "Salvar": o cadastro leva alguns segundos porque a resposta é indexada na hora. O sistema exibe "Resposta validada cadastrada com sucesso." Se algo falhar, a janela mostra o motivo, e o item pode ficar com status erro na tabela.
-
Ações sobre um item (somente administração do Agente): a coluna Ações traz três botões.
4.1. Editar (lápis): disponível apenas para respostas validadas e desabilitado enquanto o item estiver processando. Abre a mesma janela do cadastro, já preenchida.
4.2. Reprocessar (setas circulares): refaz a indexação do item. O sistema exibe "Reprocessamento do documento iniciado." Use quando o status estiver erro.
4.3. Excluir (lixeira): pede confirmação com a mensagem "Tem certeza que deseja remover o documento '…'?". Clique em "Sim" para excluir (o sistema exibe "Documento removido com sucesso.") ou em "Não" para desistir. Depois de excluído, o item deixa de ser usado nas respostas.
¶ Cenário: Configurar a integração com o Portal Wiki
A integração permite que o Agente use as páginas do Portal Wiki (os guias de usuário do Harpia) como fonte de respostas.
-
Clique na aba "Integração Wiki".
1.1. Enquanto nenhuma integração tiver sido configurada, aparece o aviso "Nenhuma integração com o Portal Wiki configurada ainda."
-
Preencha o Endereço do Portal Wiki (Campo Obrigatório), com o endereço completo do portal, por exemplo
https://wiki.exemplo.com.br. -
Preencha a Credencial — a chave de acesso ao portal. O campo é obrigatório apenas na primeira vez; depois, deixe em branco para manter a credencial atual ("Credencial já configurada — deixe em branco para manter"). O ícone de olho exibe ou oculta o que está sendo digitado.
-
Clique em "Salvar". O sistema exibe "Integração com o Portal Wiki salva com sucesso."
-
Clique em "Testar Conexão" para verificar se o Harpia consegue acessar o portal. O botão fica desabilitado até que o endereço e a credencial tenham sido salvos (ao passar o mouse, a dica explica: "Salve o endereço e a credencial antes de testar a conexão").
5.1. Se der certo, aparece a mensagem verde "Conexão com o Portal Wiki realizada com sucesso."; se não, a mensagem vermelha "Falha ao testar a conexão com o Portal Wiki."
5.2. Abaixo dos botões, o sistema registra o último teste, com data, hora e resultado (sucesso ou falha).
¶ Cenário: Definir o escopo de indexação do Wiki
-
Clique na aba "Escopo de Indexação".
1.1. Se a conexão com o Portal Wiki ainda não foi testada com sucesso, aparece o aviso "Teste a conexão na aba Integração antes de definir o escopo." com o link "Ir para Integração". Teste a conexão e volte a esta aba.
-
No campo Áreas do Portal Wiki a indexar, clique para abrir a lista de áreas disponíveis e marque as que o Agente deve consultar. Use a caixa de busca da lista para localizar uma área e o "x" ao lado de cada área marcada para removê-la.
- Clique em "Salvar Escopo". O sistema exibe "Escopo de indexação salvo com sucesso."
¶ Cenário: Acompanhar o uso do Agente de IA
A aba Acompanhamento mostra como o Assistente está sendo usado e quais perguntas ele não soube responder, para orientar a melhoria da base de conhecimento.
-
Clique na aba "Acompanhamento". Os filtros no topo valem para os indicadores, as listas e a exportação:
1.1. Data inicial e Data final (formato dd/mm/aaaa). Ao abrir a tela, o período é o dos últimos 30 dias, contando hoje.
1.2. Perfil: Todos, Interno ou Externo.
1.3. Clique em "Aplicar" para atualizar a tela. Se a data inicial for posterior à final, o sistema exibe "A data inicial deve ser anterior ou igual à data final." e, se uma das datas estiver vazia, "Informe a data inicial e a data final."
-
Indicadores (somente administração do Agente): logo abaixo dos filtros aparecem os cartões do período. Quando não houve nenhuma interação, o sistema avisa "Não há interações no período."
2.1. Total de perguntas, Perguntas — interno e Perguntas — externo: quantas perguntas foram feitas, no total e por perfil.
2.2. Conversas sociais: interações que não são perguntas sobre o sistema, como cumprimentos.
2.3. Falhas técnicas: vezes em que o Assistente não conseguiu responder por um problema técnico.
2.4. Indisponibilidades (limite de consumo): vezes em que o Assistente ficou indisponível porque o limite mensal de tokens foi atingido.
2.5. Taxa de respostas úteis: percentual das respostas avaliadas pelos usuários como úteis.
2.6. Taxa de fallback: percentual das perguntas para as quais o Assistente não encontrou resposta.
2.7. Tempo médio de resposta, Tokens consumidos, Custo estimado das interações e Custo estimado da ingestão: o tempo, o consumo e o custo estimado em US$ (com base nos preços da aba Modelos).
2.8. Em Tópicos mais frequentes, cada termo aparece com o número de vezes em que foi citado nas perguntas.
-
Perguntas sem resposta: a tabela lista as perguntas que o Assistente não soube responder, com Data/hora, Perfil e Pergunta, paginadas de 5 em 5 (use o seletor no rodapé para mudar o tamanho da página). Esta lista, e a do próximo item, também aparecem para a curadoria da base.
3.1. Clique em "Cadastrar resposta" na linha da pergunta para abrir a janela de resposta validada já com a Pergunta preenchida. Informe a resposta, o perfil e o assunto e salve (ver o cenário 1.4). Assim a lacuna passa a ser coberta pela base.
3.2. Clique em "Exportar XLSX" para baixar a lista em planilha. O botão fica desabilitado quando não há registros.
- Respostas avaliadas como não úteis: a tabela lista as respostas que receberam 👎 dos usuários, com Data/hora, Perfil, Pergunta, Resposta e Comentário (o texto que o usuário escreveu ao avaliar, se houver). Também tem o botão "Exportar XLSX". Use essa lista para revisar o conteúdo da base e corrigir ou cadastrar respostas melhores.
Informações do Documento
Histórico de Versões