Analisar agentes usando a Ferramenta de Revisão de Agentes do Kit do agente do Copilot

A Ferramenta de Revisão de Agentes é um sistema automatizado de avaliação de qualidade e de conformidade para agentes do Microsoft Copilot Studio e Agentes Declarativos do Microsoft 365. Ela ajuda criadores, administradores e equipes de governança a identificar problemas, antipadrões e lacunas de conformidade antes que cheguem aos usuários finais.

À medida que as organizações escalam suas implantações do Copilot Studio, revisar manualmente a configuração, as instruções e a estrutura de tópicos de cada agente torna-se impossível. A Ferramenta de Revisão de Agentes automatiza essa análise por meio de análises baseadas em IA, normalmente revelando descobertas acionáveis em menos de 60 segundos.

É para:

• Criadores: receba comentários acionáveis para melhorar a qualidade dos agentes antes da implantação.
• Administradores e equipes de CoE: aplique padrões de governança em todos os agentes em um ambiente.
• Diretores de segurança e conformidade: verifique se os agentes seguem as diretrizes de privacidade, segurança e precisão.

Principais recursos

Introdução: O painel

Quando você abre a Ferramenta de Avaliação de Agentes, você entra no Painel, o hub central que mostra todos os agentes no seu ambiente e o status de avaliação deles.

Layouts do painel

O painel mostra tudo rapidamente: a barra de abas alternando entre agentes do Copilot Studio e do Microsoft 365, quatro cartões de estatísticas resumindo a integridade do portfólio, uma barra de pesquisa, a grade de agentes paginada e o botão Upload de ZIP para avaliações offline.

Cartões de estatísticas

Os quatro cartões de estatísticas oferecem uma visão instantânea da integridade do seu portfólio de agentes:

Grade de agentes

Selecionar um ambiente

Por padrão, a ferramenta mostra agentes do ambiente em que você a instalou. Se precisar revisar um agente de um ambiente diferente, use o seletor de ambiente na barra de ferramentas do painel. A lista suspensa lista todos os ambientes do Power Platform aos quais você tem acesso.

Depois que você seleciona um ambiente diferente, a grade de agentes é atualizada para mostrar os agentes desse ambiente. Você poderá então avaliar qualquer um desses agentes. O resultado da avaliação é armazenado no ambiente atual (inicial), não no que você selecionou.

Modos de avaliação

A ferramenta oferece suporte a dois modos distintos de avaliação, acessíveis pela barra de guias na parte superior do painel.

Avaliação de agentes do Copilot Studio

Este modo avalia agentes criados no Microsoft Copilot Studio. Ele lê diretamente do Dataverse — não é necessário upload de arquivos.

O que ele analisa:

• Configurações de tópicos (nomes, descrições, variáveis).
• Configurações de ferramentas e ações (contagem, descrições, roteamento).
• Tipos de fonte de conhecimento.
• Cobertura do caso de teste.
• Instruções do agente (modo generativo).
• Metadados do agente (idioma, autenticação, configurações de IA).

Para iniciar uma avaliação:

1. Encontre seu agente na grade.
2. Selecione Revisar. O trabalho de análise é iniciado automaticamente.
3. Um painel de progresso mostra o que está acontecendo em tempo real.
4. Os resultados são abertos no painel de avaliação após a conclusão.

Você pode avaliar qualquer agente novamente a qualquer momento. Cada avaliação cria um registro no Dataverse. A grade sempre mostra o resultado da avaliação mais recente.

Avaliação de agentes declarativos (Microsoft 365 Copilot)

Este modo avalia os Agentes Declarativos do Microsoft 365, que são definidos por um arquivo JSON de manifesto e implantados no ecossistema do Microsoft 365 Copilot.

Você pode enviar um Agente Declarativo para avaliação de duas maneiras:

O que ele analisa (5 critérios, não 15):

O que acontece durante uma avaliação

Quando você seleciona Avaliar, a ferramenta executa uma análise automatizada que normalmente é concluída em menos de 60 segundos. Um painel de progresso mantém você informado enquanto ele avalia.

A análise cobre três pontos em sequência:

1. Análise da configuração: a ferramenta lê a configuração completa do agente no Dataverse — cada tópico, ferramenta, fonte de conhecimento, caso de teste e instrução. Ela verifica campos ausentes em todos os componentes e mede coisas como contagem de ferramentas e cobertura de testes com base nas melhores práticas documentadas da Microsoft.
2. Avaliação de padrões baseada em IA: um modelo de IA revisa a mesma configuração para avaliar a qualidade, não só a integridade. Ele analisa se os nomes e descrições dos tópicos são claros o suficiente para que o orquestrador generativo roteie corretamente, se vários tópicos se sobrepõem de formas que causam confusão no roteamento, e se as descrições das ferramentas fornecem à IA orientações suficientes para invocar a ferramenta certa no momento certo.
3. Verificação de conformidade das instruções: um segundo modelo de IA lê as instruções do sistema do agente e as verifica em relação a 15 critérios de melhores práticas das orientações de modo generativo da Microsoft — abrangendo escopo, segurança, qualidade das respostas e experiência do usuário. Para cada critério que as instruções não atendam, ele revela uma descoberta específica e uma recomendação concreta.

Após a conclusão das três etapas, um relatório em PDF é gerado automaticamente e os resultados são abertos no painel de avaliação.

Padrões detectados

Padrões identificam antipadrões específicos ou melhores práticas ausentes na configuração de um agente. A ferramenta verifica 18 padrões em 7 categorias.

Todos os 18 padrões

Para cada padrão com falha, a ferramenta mostra quais tópicos são afetados, o valor atual que desencadeou a descoberta, uma melhoria sugerida e um link para a documentação relevante do Microsoft Learn.

Categorias de padrões

A grade de resultados agrupa os padrões em sete categorias, classificadas na seguinte ordem:

Lógica de gravidade

A combinação de correspondência de palavras-chave e contagem de tópicos determina a gravidade do padrão:

A gravidade determina o selo visual na grade de resultados e o nível de erro SARIF no relatório exportado.

Critérios de conformidade

Esta parte da avaliação mede a qualidade das instruções do sistema de um agente — o texto em linguagem natural que o criador fornece nas configurações Generativas do Copilot Studio. Essas instruções definem como o agente se comporta em todas as conversas.

Os 15 critérios derivam das orientações de modo generativo da Microsoft e representam as melhores práticas mais impactantes para a qualidade da instrução.

Todos os 15 critérios

Detalhamento das categorias

Como as pontuações são calculadas

Todas as pontuações estão na escala de 0 a 100 e são determinísticas. As mesmos entradas sempre produzem a mesma pontuação.

Pontuação do padrão

Pattern Score = (Passed Patterns / Total Patterns) × 100

• Padrões totais = 10 determinísticos + quantos padrões detectados pela IA forem retornados (até 8).
• Padrões aprovados = contagem em que o status do padrão é pass.
• O resultado é arredondado para o inteiro mais próximo.

Exemplo: 15 padrões no total, 12 aprovados = Pontuação do Padrão de 80.

Pontuação da instrução

A pontuação da instrução usa um sistema de pontos ponderados com base na gravidade inerente de cada critério:

Instruction Score = (Earned Points / 35) × 100

• Para cada um dos 15 critérios, se não for encontrado nenhum problema para esse critério, seus pontos de severidade inerentes serão adicionados.
• Se forem detectadas "instruções ausentes", haverá falha em todos os critérios e a pontuação será 0.
• O resultado é limitado a 100 e arredondado para o inteiro mais próximo.

Exemplo: 3 critérios Alto e 2 Médio têm falha:

• Pontos ganhos: (4 × 3) + (4 × 2) + (2 × 1) = 12 + 8 + 2 = 22 pontos.
• Pontuação = (22 / 35) × 100 = 63.

Pontuação geral

Overall Score = (Pattern Score × 0.5) + (Instruction Score × 0.5)

Ambas as dimensões têm peso igual. Se somente uma dimensão estiver disponível (por exemplo, não existirem instruções), a pontuação dessa dimensão será usada diretamente.

Guia de cores e rótulos da pontuação

Analisar resultados

Após o término da avaliação, o painel de avaliação exibe os resultados. O painel tem três guias.

Guia Visão geral

A guia Visão Geral oferece um resumo de alto nível:

• Pontuação geral: um medidor circular colorido em verde, amarelo ou vermelho.
• Pontuação do padrão e Pontuação da instrução lado a lado.
• Metadados do agente: nome, ambiente, idioma, modo de autenticação, configurações de IA.
• Resumo gerado por IA: uma descrição em linguagem natural das descobertas mais significativas.
• Carimbo de data/hora da avaliação e a fonte dos dados (ambiente ativo ou upload do ZIP).

Guia Padrões

A guia Padrões mostra a grade completa de todos os 18 padrões avaliados, com estas colunas:

Você pode classificar a grade por qualquer coluna. Por padrão, padrões com falha aparecem primeiro, classificados por gravidade (Alta, Média e Baixa).

Guia Conformidade

A guia Conformidade mostra todos os 15 critérios de instrução:

Detalhamento do padrão

Quando você seleciona Detalhes de qualquer padrão com falha, o painel Detalhes do Padrão é aberto. Ela mostra:

• Nome e descrição do padrão: o que esse padrão verifica.
• Por que isso importa: o impacto desse antipadrão na qualidade do agente.
• Tabela de tópicos afetados: cada tópico com seu valor atual e a substituição sugerida pela IA.
• Recomendação: uma ação concreta para resolver o problema.
• Saiba mais: um link direto para a documentação relevante do Microsoft Learn.

Detalhamento da conformidade

Quando você seleciona Detalhes em qualquer critério de conformidade com falha, o painel Detalhes da Conformidade é aberto. Ela mostra:

• Nome do critério, categoria e gravidade
• O que o critério verifica: uma explicação em linguagem simples
• Problema específico encontrado: a análise da IA sobre o que está ausente ou incorreto
• Recomendação: linguagem ou padrões exatos para adicionar às instruções do agente
• Exemplo: quando disponível, um exemplo de instrução em conformidade
• Saiba mais: link para as orientações relevantes do Microsoft Learn

Exportar resultados

Você pode exportar resultados em três formatos a partir do cabeçalho do painel de avaliação.

Relatório em PDF

Um relatório em PDF bem elaborado, legível por humanos, adequado para compartilhamento com stakeholders ou anexado a uma auditoria de governança.

Conteúdo:

• Resumo executivo com pontuações e principais métricas
• Resultados da avaliação de padrões (status, gravidade, tópicos afetados)
• Descobertas de conformidade (todos os 15 critérios)
• Recomendações para cada problema encontrado
• Metadados do agente (nome, ambiente, data da avaliação)

Padrão do nome do arquivo: {AgentName}_review_{YYYY-MM-DD}.pdf

O PDF é gerado automaticamente ao final de cada avaliação e armazenado no Dataverse junto com o registro da avaliação. Downloads subsequentes recuperam o arquivo armazenado sem executar novamente a análise.

Exportação de SARIF

SARIF (Static Analysis Results Interchange Format v2.1.0) é um formato JSON projetado para integração com ferramentas para desenvolvedores e pipelines de CI/CD.

Casos de uso:

• Upload para o GitHub Advanced Security para anotações de PR baseadas em SARIF
• Importar para verificações de portão de qualidade do Azure DevOps
• Processar com ferramentas de terceiros que consomem SARIF (SonarQube, Visual Studio Code, entre outras)

Visão geral da estrutura:

{
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "Copilot Studio Agent Review Tool",
        "version": "1.0"
      }
    },
    "results": [
      {
        "ruleId": "pat-007",
        "level": "error",
        "message": { "text": "Excessive Tools Usage: 28 tools exceed the recommended limit of 25" },
        "properties": {
          "category": "Architecture",
          "recommendation": "Reduce tool count to 25 or fewer"
        }
      }
    ]
  }]
}

Mapeamento do nível de gravidade para SARIF:

• Alta = "error"
• Média = "warning"
• Baixa = "note"

Padrão do nome do arquivo: {AgentName}_review.sarif

Exportação do Excel

Uma pasta de trabalho do Excel com várias planilhas para análise de dados, relatórios e arquivamento.

Os cabeçalhos são em negrito com planos de fundo com as cores da marca. As células de pontuação e gravidade são codificadas por cores verde, amarelo ou vermelho. As larguras das colunas se ajustam automaticamente.

Padrão do nome do arquivo: {AgentName}_review_{YYYY-MM-DD}.xlsx

Aprofundamento sobre a avaliação de agente declarativo

Os Agentes Declarativos do Microsoft 365 são um tipo diferente de agente dos agentes do Copilot Studio. Eles são definidos inteiramente por um arquivo de manifesto JSON e implantados no ecossistema do Microsoft 365.

O que a avaliação do Agente Declarativo verifica

A avaliação primeiro valida a estrutura do manifesto, verificando que todos os campos exigidos estejam presentes e que o esquema esteja bem formado. Em seguida, executa uma avaliação de IA em relação aos cinco critérios de qualidade e gera um relatório em PDF. A verificação de conformidade das instruções com 15 critérios (específica para agentes do Copilot Studio) não se aplica aqui.

Os cinco critérios de avaliação do Agente Declarativo

Verificação da integridade do manifesto (validação local)

Antes da execução da IA, um exame determinístico de integridade valida a estrutura do manifesto:

• Campos obrigatórios presentes (name, description, instructions)
• Compatibilidade de versão do esquema
• Referências de plug-ins de ação válidas
• Contagem de iniciadores de conversa dentro dos limites (3 a 12)
• Declarações de capacidades corretamente formadas

Qualquer falha na verificação de integridade aparece como problemas nos resultados da avaliação do Agente Declarativo, independentemente da avaliação da IA.

Enviar um Agente Declarativo para avaliação

Via upload de ZIP (mais comum):

1. Exporte o Agente Declarativo da sua ferramenta de criação como um pacote ZIP.
2. Selecione Upload de ZIP no cabeçalho da página Ferramenta de Avaliação de Agentes.
3. Se o ZIP contiver vários agentes, um painel seletor permitirá que você escolha qual deles deve avaliar.
4. A avaliação é feita automaticamente.

Por meio do catálogo do Microsoft 365 (requer configuração da API do Graph):

1. Selecione Conectar-se ao Microsoft 365 na guia Agentes do Microsoft 365.
2. Conclua o assistente de autorização da API do Graph.
3. Seus Agentes Declarativos implantados aparecem na grade de Agentes Declarativos.
4. Selecione Avaliar em qualquer Agente Declarativo.

Segurança e acesso a dados

Esta seção descreve como a Ferramenta de Revisão de Agentes lida com a segurança e o acesso a dados.

Armazenamento de dados

Todos os resultados da avaliação são armazenados na tabela cat_agentreviews do Dataverse. Cada registro armazena:

Segurança no nível da linha

A tabela cat_agentreviews usa o escopo de leitura em nível de usuário (Básico) no Dataverse. Os usuários podem ver somente as avaliações que criaram. As avaliações de outro usuário nunca ficam visíveis, mesmo no mesmo ambiente. O Dataverse aplica essa segurança nativamente, não o código do aplicativo.

Ambientes de origem

Os usuários podem avaliar agentes de ambientes aos quais têm acesso, não apenas do ambiente atual. O painel oferece suporte a revisões entre ambientes por meio do seletor de ambiente. Avaliações de outros ambientes são marcadas com a URL do ambiente de origem para que apareçam corretamente quando a ferramenta é carregada.

Avaliações obtidas a partir de um upload de ZIP sempre são exibidas, independentemente do ambiente ao qual a ferramenta está conectada.

Quais dados deixam o ambiente

• A configuração do agente (tópicos, ferramentas, instruções) é enviada aos modelos de IA por meio do PredictV2 do Dataverse. Isso segue o caminho padrão de invocação do modelo de IA do Dataverse e está sujeito às mesmas políticas de residência de dados que qualquer operação de IA do Dataverse.
• Nenhum dado é enviado para nenhum serviço de terceiros ou ponto de extremidade externo.
• Os resultados da revisão (incluindo o PDF) são armazenados exclusivamente no Dataverse.

Experiência de primeira execução e tour de boas-vindas

Na primeira vez que um usuário abre a Ferramenta de Avaliação de Agentes, um tour de boas-vindas o guia pelas partes principais da interface:

1. Os cartões de estatísticas do painel e o que eles representam
2. Como ler a grade de agentes
3. Como iniciar uma avaliação
4. Como interpretar os resultados
5. As opções de exportação

O progresso do tour persiste no Dataverse para que o tour não se repita após o término. Os usuários podem reabrir o tour a qualquer momento na seção Ajuda/Links Rápidos no cabeçalho da página.

Perguntas frequentes

Esta seção responde a perguntas comuns sobre a Ferramenta de Avaliação de Agentes.

Quanto tempo leva uma avaliação?

Um agente típico com menos de 20 tópicos termina em menos de 60 segundos. A ferramenta tem um tempo limite de dois minutos. Agentes muito grandes (mais de 50 tópicos, muitas ferramentas) podem chegar perto do limite.

A ferramenta modifica meu agente?

Não. A ferramenta é totalmente somente leitura em relação aos dados do agente. Ele só lê a configuração do agente. Todas as gravações vão para a tabela cat_agentreviews.

Posso reavaliar um agente após fazer alterações?

Sim. Cada avaliação cria um registro. A grade sempre mostra a avaliação mais recente. Avaliações antigas permanecem no Dataverse e podem ser acessadas de forma programática se necessário.

E se meu agente estiver em um ambiente diferente?

Use o seletor de ambiente no painel para apontar a ferramenta para outro ambiente ao qual você tenha acesso. A avaliação é executada em relação a esse ambiente e o resultado é armazenado no ambiente atual.

Posso avaliar agentes que não criei?

Sim. Você pode avaliar qualquer agente ao qual tiver acesso no Dataverse. No entanto, você pode ver somente as avaliações que criou (segurança em nível de linha). Avaliações de outros usuários não ficam visíveis.

O que é SARIF e eu preciso dele?

SARIF é um formato padrão para resultados de análise estática. Você só precisa disso se estiver integrando verificações de qualidade de agentes em um pipeline de CI/CD (GitHub Actions ou Azure DevOps). Para a maioria dos usuários, exportações em PDF e Excel são suficientes.

A ferramenta diz que meu agente não tem instruções. Isso é um problema?

Sim. A ferramenta só mostra agentes que tenham IA generativa ativada, então todo agente na grade deve ter instruções. Se a verificação de conformidade não reportar instruções, a orquestração generativa do agente está ativa, mas nenhuma instrução do sistema foi gravada ainda. Adicionar instruções é altamente recomendável.

Por que "Persona e Tom" é de baixa gravidade?

A orientação da Microsoft observa que um tom profissional e educado já é o comportamento padrão para os agentes do Copilot Studio. Instruções para o tom só são necessárias se você quiser um tom que não seja padrão. Esse critério é Baixo porque falha nele raramente causa problemas para o usuário.

Fazer uma avaliação consome créditos do Copilot?

Sim. Cada avaliação invoca modelos de IA três vezes — para avaliação de padrões, conformidade das instruções e geração de PDFs. Cada invocação consome créditos do Copilot do seu locatário. Reavaliar o mesmo agente também consome créditos, portanto, faça suas alterações primeiro e depois reavalie.

Posso exportar todas as avaliações de uma vez?

Sim. Use o botão Exportar Tudo na barra de ferramentas da grade de agentes para gerar uma pasta de trabalho do Excel abrangendo todos os agentes avaliados na exibição atual.

Informações relacionadas

• Visão geral do Kit do Agente do Copilot
• Instalar o Kit do Agente do Copilot
• Orientações do modo generativo
• Configurar agentes no Kit do agente do Copilot
• Estoque de Agentes do Kit do agente do Copilot