Gestão de Agentes

Visão geral

1. Para que serve

O módulo Admin Agentes possui duas áreas: Agentes e Skills. Na primeira, você cadastra e administra os agentes que podem ser utilizados no Chat. Na segunda, mantém as capacidades que podem ser vinculadas a cada agente.

A listagem de agentes apresenta nome, função, quantidade de skills vinculadas, status e ações administrativas.

Agentes

2. Cadastrar um agente

1. Abra a aba Agentes.
2. Clique em Novo Agente.
3. Informe o Nome e a Função.
4. Descreva as orientações no campo Instrução Inicial / System Prompt.
5. Selecione os perfis que poderão acessar o agente.
6. Clique em Salvar.

O nome precisa ser informado para que o cadastro seja salvo. Os perfis selecionados são vinculados junto com a criação do agente.

Cadastro

3. Campos do agente

Atualização

4. Editar e controlar um agente

Na listagem, use Editar para atualizar o nome, a função e as instruções iniciais. Clique em Salvar para aplicar as alterações ou em Cancelar para sair sem salvar.

A área Vincular por Perfil permite revisar os perfis associados. Em uma edição, selecione ou desmarque os perfis e clique em Salvar perfis.

As ações Desativar e Ativar pedem confirmação. Um agente desativado deixa de aparecer no Chat, enquanto seu histórico e suas configurações são preservados.

Vínculos

5. Gerenciar skills de um agente

1. Localize o agente na aba Agentes.
2. Clique em Skills.
3. Marque as skills que o agente poderá utilizar ou desmarque as que devem ser retiradas.
4. Clique em Salvar Vinculações.
5. Use Cancelar para fechar sem aplicar as alterações.

A tela apresenta o nome da skill, sua categoria e uma caixa de seleção. Se não houver skills disponíveis, a interface informa essa situação.

Skills

6. Cadastrar e consultar skills

Na aba Skills, a tabela apresenta nome, categoria, descrição, quantidade de agentes vinculados e ações. As categorias disponíveis são Busca, Análise, Documentos, Integração e Geral.

Para cadastrar, clique em Nova Skill, informe o nome, selecione a categoria e preencha a descrição. O campo Config (JSON — opcional) pode receber uma configuração adicional no formato indicado pela tela. Finalize em Salvar.

Manutenção

7. Editar ou remover uma skill

Na aba Skills, clique em Editar para alterar nome, categoria, descrição ou configuração. Clique em Salvar ou Cancelar.

Para remover, selecione Remover e confirme o diálogo. A tela informa que a skill será removida e que os agentes que a utilizam perderão o vínculo.

Manutenção

8. Excluir um agente

1. Na aba Agentes, clique em Excluir.
2. Leia a confirmação apresentada.
3. Confirme somente após revisar o agente selecionado.

A confirmação informa que o agente será removido permanentemente e que a ação não poderá ser desfeita.

Acesso

9. Perfis disponíveis para vínculo

O formulário apresenta opções de vínculo por perfil. No código atual, estão definidos:

• Gestor: acesso total.
• DPO: sem dados operacionais.
• TI: leitura do catálogo.
• Usuário comum: leitura.

O vínculo concede acesso ao agente para os usuários que possuem os perfis selecionados. As permissões efetivas podem depender da configuração do ambiente.

Resumo

10. Principais fluxos

• Criar agente: Agentes → Novo Agente → preencher dados → selecionar perfis → Salvar.
• Editar agente: localizar → Editar → atualizar dados → Salvar.
• Vincular skills: localizar agente → Skills → selecionar capacidades → Salvar Vinculações.
• Criar skill: Skills → Nova Skill → preencher dados → Salvar.
• Controlar acesso: selecionar Desativar ou Ativar → revisar confirmação → confirmar.
• Excluir: selecionar Excluir → revisar confirmação → confirmar.

Orientações

11. Como criar um bom agente

O agente interpreta a solicitação do usuário, decide como conduzir a tarefa e utiliza as Skills vinculadas quando necessário. Por isso, o conteúdo da Função e da Instrução Inicial / System Prompt deve deixar claro o papel, o objetivo, as responsabilidades, os limites e o formato esperado da resposta.

Não inclua credenciais, tokens, senhas ou dados pessoais nas instruções. As orientações devem ser objetivas, não contraditórias e compatíveis com as Skills que serão vinculadas ao agente.

Orientações

12. Como criar uma boa Skill

Uma Skill representa uma capacidade ou atividade específica que pode ser usada pelo agente. No cadastro da aba Skills, utilize o Nome, a Categoria, a Descrição e, quando necessário, o campo Config (JSON — opcional) para registrar uma capacidade bem delimitada.

Prefira Skills pequenas e reutilizáveis, como Pesquisar dados, Identificar relacionamentos, Classificar informações ou Consolidar resultados. Evite uma Skill genérica, como Analisar tudo, que mistura várias responsabilidades.

Teste

13. Testar o agente e as Skills em conjunto

Antes de disponibilizar o agente, teste solicitações que representem o uso esperado. Por exemplo:

O fluxo esperado é:

1. O agente interpreta que o usuário deseja informações relacionadas a um cliente.
2. Seleciona uma Skill de pesquisa de registros.
3. Localiza o registro principal do cliente.
4. Utiliza Skills complementares, como identificação de relacionamentos, pesquisa de dados relacionados e consolidação dos resultados.
5. Organiza a resposta com resumo, resultados encontrados, informações relacionadas, origens e observações.

Em termos de fluxo, a solicitação passa por Usuário → Agente → Skills → Fontes de Dados → Resultado → Agente → Usuário. O teste deve confirmar se o agente escolhe as capacidades adequadas, respeita os limites definidos e informa quando não há evidência suficiente.

Teste também solicitações sem resultado, com dados ambíguos e com informações que exigem validação. O agente deve informar a limitação encontrada, sem inventar dados ou relacionamentos.

Referência

14. Modelos rápidos

Use os modelos abaixo como ponto de partida para preencher as instruções e descrições. Adapte o conteúdo à finalidade real do agente ou da Skill.

Depois de criar ou alterar o agente e suas Skills, faça o teste no Chat com diferentes tipos de solicitação antes de disponibilizá-lo aos usuários.