Analisar agentes através da Ferramenta de Revisão de Agentes no Kit de Agente do Copilot

A Ferramenta de Revisão de Agentes é uma avaliação automatizada da qualidade e um sistema de revisão de conformidade para agentes do Microsoft Copilot Studio e Agentes Declarativos do Microsoft 365. Ajuda criadores, administradores e equipas de governação a identificar problemas, antipadrões e lacunas de conformidade antes que atinjam os utilizadores finais.

À medida que as organizações dimensionam as suas implementações do Copilot Studio, revendo manualmente a configuração de cada agente, as instruções e a estrutura dos tópicos torna-se impossível. A Ferramenta de Revisão de Agentes automatiza essa revisão através de análise com tecnologia de IA, revelando conclusões acionáveis em menos de 60 segundos.

Adequa-se a:

• Criadores: obtenha comentários acionáveis para melhorar a qualidade do agente antes da sua implementação.
• Administradores e equipas do Centro de Excelência: imponha normas de governação em todos os agentes de um ambiente.
• Diretores de segurança e de conformidade: verifique se os agentes seguem as diretrizes de privacidade, segurança e precisão.

Capacidades chave

Introdução: o dashboard

Quando abre a Ferramenta de Revisão de Agentes, aparece-lhe o Dashboard, o centro que lhe mostra todos os agentes no seu ambiente e o seu estado de revisão.

Esquema do dashboard

O dashboard mostra tudo num relance: a barra de separadores entre agentes do Copilot Studio e do Microsoft 365, quatro cartões estatísticos que resumem o estado de funcionamento do portefólio, a barra de ferramentas de pesquisa, a grelha paginada de agentes e o botão Carregar ZIP para revisões offline.

Cartões estatísticos

Os quatro cartões estatísticos fornecem um instantâneo do estado de funcionamento do seu portefólio de agentes:

Grelha de agentes

Selecionar um ambiente

Por predefinição, a ferramenta mostra agentes do ambiente onde foi instalado. Se necessita de rever um agente de um ambiente diferente, utilize o seletor de ambientes na barra de ferramentas do dashboard. As listas pendentes mostram todos os ambientes do Power Platform a que tem acesso.

Depois de selecionar um ambiente diferente, a grelha de agentes atualiza para mostrar agentes desse ambiente. Agora, pode rever qualquer um desses agentes. O resultado da revisão é armazenado no ambiente atual (base), não aquele que selecionou.

Modos de revisão

A ferramenta suporta dois modos de revisão distintos, acessíveis a partir da barra de separadores no topo do dashboard.

Revisão de agentes do Copilot Studio

Este modo revê agentes criados no Microsoft Copilot Studio. Faz a leitura diretamente a partir do Dataverse, sem necessidade de carregamento de ficheiros.

O que analisa:

• Configurações de tópicos (nomes, descrições, variáveis).
• Configurações da ferramenta e de ações (contagem, descrições, encaminhamento).
• Tipos de fontes de conhecimento.
• Cobertura de casos de teste.
• Instruções do agente (modo generativo).
• Metadados do agente (linguagem, autenticação, definições de IA).

Para iniciar uma revisão:

1. Localize o seu agente na grelha.
2. Selecionar Rever. A análise começa automaticamente.
3. O painel de progresso mostra o que está a acontecer em tempo real.
4. Os resultados aparecem no painel de revisão, quando concluídos.

Pode rever qualquer agente novamente em qualquer altura. Cada revisão cria um novo registo no Dataverse. A grelha mostra sempre o resultado de revisão mais recente.

Revisão de agentes declarativos (Microsoft 365 Copilot)

Este modo revê Agentes Declarativos do Microsoft 365, que são definidos por um ficheiro JSON de manifesto e implementados para o ecossistema do Microsoft 365 Copilot.

Pode submeter um Agente Declarativo para revisão de duas formas:

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

O que acontece durante uma revisão

Quando seleciona Rever, a ferramenta executa uma análise automatizada que, normalmente, termina em menos de 60 segundos. O painel de progresso mantém o utilizador informado durante o processo.

A análise abrange três coisas sequencialmente:

1. Análise de configuração: a ferramenta lê a configuração completa do agente do Dataverse (cada tópico, ferramenta, fonte de conhecimento, caso de teste e instrução). Verifica campos em falta em todos os componentes e mede coisas como a contagem de ferramentas e testa a cobertura em relação às melhores práticas documentadas da Microsoft.
2. Avaliação de padrões com tecnologia de IA: um modelo de IA revê a mesma configuração para avaliar a qualidade, não apenas a completude. Verifica se os nomes de tópicos e descrições são suficientemente claras para o orquestrador generativo encaminhar corretamente, se os vários tópicos se sobrepõem de formas que possam causar confusão no encaminhamento e se as descrições da ferramenta dão à IA orientação suficiente para invocar a ferramenta certa no momento certo.
3. Verificação de conformidade da instrução: um segundo modelo de IA lê as instruções de sistema do agente e verifica-as em relação aos 15 critérios das melhores práticas da orientação do modo generativo da Microsoft, incluindo âmbito, segurança, qualidade da resposta e experiência do utilizador. Para cada critério que não satisfaz as instruções, destaca uma conclusão específica e uma recomendação concreta.

Depois de os três passos estarem concluídos, é gerado automaticamente um relatório PDF e os resultados abrem no painel de revisão.

Padrões detetados

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

Todos os 18 padrões

Para cada padrão em falha, a ferramenta mostra que tópicos são afetados, o valor atual que acionou a conclusão, a sugestão de melhoria e uma ligação para a documentação relevante do Microsoft Learn.

Categorias de padrões

A grelha de resultados agrupa padrões em sete categorias, ordenados da seguinte forma:

Lógica da gravidade

A combinação de palavras-chave correspondentes e a contagem de tópicos determinam a gravidade do padrão:

A gravidade impulsiona tanto o distintivo visual na grelha de resultados como o nível de erro SARIF no relatório exportado.

Critérios de conformidade

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

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

Todos os 15 critérios

Discriminação por categorias

Como são calculadas as classificações

Todas as classificações estão numa escala de 0–100 e são deterministas. As mesmas entradas produzem sempre a mesma classificação.

Classificação do padrão

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

• Total de padrões = 10 deterministas + quantos padrões detetados pela IA forem devolvidos (até 8).
• Padrões passados = contagem onde o estado do padrão é pass.
• O resultado é arredondado para o número inteiro mais próximo.

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

Classificação da instrução

A classificação da instrução utiliza um sistema ponderado de pontos baseado na gravidade inerente de cada critério:

Instruction Score = (Earned Points / 35) × 100

• Para cada um dos 15 critérios, se não for encontrada qualquer questão para esse critério, são adicionados os seus pontos de gravidade inerentes.
• Se forem detetadas "instruções em falta", todos os critérios falham e a pontuação é 0.
• O resultado é limitado para 100 e arredondado para o número inteiro mais próximo.

Exemplo: 3 critérios Alto e 2 Médio falham:

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

Classificação global

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

Ambas as dimensões têm o mesmo peso. Se apenas uma dimensão estiver disponível (por exemplo, não existirem instruções), a pontuação dessa dimensão é utilizada diretamente.

Classificação de cores e guia de etiquetas

Rever resultados

Após concluída a revisão, o painel de revisão mostra os resultados. O painel tem três separadores.

Separador Descrição Geral

O separador Descrição Geral oferece-lhe um resumo de alto nível:

• Classificação global: um medidor circular colorido a verde, âmbar ou vermelho.
• Classificação Padrão e Classificação de Instrução lado a lado.
• Metadados do agente: nome, ambiente, idioma, modo de autenticação, definições de IA.
• Resumo gerado por IA: uma descrição em linguagem natural das conclusões mais significativas.
• Reveja o carimbo de data/hora e a fonte de dados (ambiente em direto ou carregar ZIP).

Separador Padrão

O separador Padrões mostra a grelha completa de todos os 18 padrões avaliados, com estas colunas:

Pode ordenar a grelha por qualquer coluna. Por predefinição, os padrões reprovados aparecem primeiro, ordenados por gravidade (Alta, depois Média, depois Baixa).

Separador Conformidade

O separador Conformidade mostra todos os 15 critérios de instruções:

Desagregação em detalhe do padrão

Quando seleciona Detalhes de qualquer padrão reprovado, o painel Detalhes do Padrão abre-se. Mostra:

• Nome e descrição do padrão: o que este padrão verifica.
• Porque é importante: o impacto deste antipadrão na qualidade do agente.
• Tabela de tópicos afetados: cada tópico com o seu valor atual e a substituição sugerida pela IA.
• Recomendação: uma ação concreta para resolver o problema.
• Saber mais: uma ligação direta para a documentação relevante do Microsoft Learn.

Desagregação em detalhe de conformidade

Quando seleciona Detalhes sobre qualquer critério de conformidade reprovado, abre-se o painel Detalhes de Conformidade. Mostra:

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

Exporte os resultados

Pode exportar resultados em três formatos a partir do cabeçalho do painel de revisão.

Relatório PDF

Um relatório PDF polido, legível por humanos, adequado para partilhar com as partes interessadas ou anexar a uma auditoria de governação.

Conteúdo:

• Resumo executivo com classificações e métricas-chave
• Resultados de avaliação de padrões (estado, gravidade, tópicos afetados)
• Conclusões de conformidade (todos os 15 critérios)
• Recomendações para todas as edições encontradas
• Metadados do agente (nome, ambiente, data de avaliação)

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

O PDF é gerado automaticamente no final de cada revisão e armazenado no Dataverse juntamente com o registo da análise. Downloads subsequentes obtêm o ficheiro armazenado sem repetir a análise.

Exportação SARIF

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

Casos de utilização:

• Carregar para o GitHub Advanced Security para anotações de PR baseadas em SARIF
• Importar para as verificações de controlo de qualidade do Azure DevOps
• Processo com ferramentas de terceiros que consomem SARIF (SonarQube, Visual Studio Code, etc.)

Descriçã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 ao nível de Gravidade para SARIF:

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

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

Exportar para Excel

Um livro de Excel com várias folhas para análise de dados, relatórios e arquivo.

Os cabeçalhos estão a negrito com fundos de cor da marca. As células de classificação e severidade possuem no código de cores verde, âmbar ou vermelho. As larguras das colunas ajustam-se automaticamente.

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

Abordagem profunda à revisão de agentes declarativos

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

O que verifica a revisão do Agente Declarativo

A revisão valida primeiro a estrutura do manifesto, verificando que todos os campos obrigatórios estão presentes e que o esquema está bem formado. Depois, executa uma avaliação de IA com cinco critérios de qualidade e gera um relatório PDF. A verificação de conformidade de instrução com 15 critérios (específica para agentes do Copilot Studio) não se aplica aqui.

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

Verificação de estado de funcionamento do manifesto (validação local)

Antes de a IA executar, uma verificação determinista de estado de funcionamento valida a estrutura do manifesto:

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

Quaisquer falhas na verificação de estado de funcionamento aparecem como problemas nos resultados da revisão do Agente Declarativo, independentemente da avaliação da IA.

Submeta um Agente Declarativo para revisão

Através de carregar ZIP (mais comum):

1. Exporte o Agente Declarativo da sua ferramenta de criação como um pacote ZIP.
2. Selecione Carregar ZIP no cabeçalho da página Ferramenta de Avaliação de Agentes.
3. Se o ZIP contiver vários agentes, um painel seletor permite-lhe escolher qual pode rever.
4. A revisão é executada automaticamente.

Através do catálogo do Microsoft 365 (requer configuração do Graph API):

1. Selecione Ligar ao Microsoft 365 no separador Agentes do Microsoft 365.
2. Conclua o assistente de autorização do Graph API.
3. Os seus Agentes Declarativos destacados aparecem na grelha de Agentes Declarativos.
4. Selecione Rever em qualquer Agente Declarativo.

Segurança e acesso aos dados

Esta secção descreve como a Ferramenta de Revisão de Agentes gere a segurança e o acesso aos dados.

Armazenamento de dados

Todos os resultados das revisões são armazenados na cat_agentreviews tabela Dataverse. Cada registo armazena:

Segurança ao nível da linha

A tabela cat_agentreviews utiliza o âmbito de leitura ao nível do utilizador (Básico) no Dataverse. Os utilizadores só podem ver as revisões que criaram. As avaliações de outro utilizador nunca são visíveis, mesmo no mesmo ambiente. O Dataverse aplica esta segurança de forma nativa, não o código da aplicação.

Ambientes de origem

Os utilizadores podem rever agentes de ambientes a que têm acesso, não apenas do ambiente atual. O dashboard suporta revisões entre ambientes através do seletor de ambientes. As revisões de outros ambientes estão identificadas com o URL do ambiente de origem para que apareçam corretamente quando a ferramenta carrega.

As revisões com origem num carregamento ZIP são sempre apresentadas, independentemente do ambiente a que a ferramenta está ligada.

Que dados saem do ambiente

• A configuração do agente (tópicos, ferramentas, instruções) é enviada para os modelos de IA através do Dataverse PredictV2. 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 qualquer serviço de terceiros ou ponto final externo.
• Os resultados da revisão (incluindo o PDF) são armazenados exclusivamente no Dataverse.

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

Na primeira vez que um utilizador abre a Ferramenta de Avaliação de Agentes, é guiado por uma visita de boas-vindas pelas partes principais da interface:

1. Os cartões estatísticos do dashboard e o que representam
2. Como ler a grelha de agentes
3. Como iniciar uma revisão
4. Como interpretar os resultados
5. As opções de exportação

O progresso da visita persiste no Dataverse, por isso não se repete após a conclusão. Os utilizadores podem reabrir a visita a qualquer momento a partir da secção Ajuda/Ligações Rápidas no cabeçalho da página.

Perguntas mais frequentes

Esta secção aborda questões comuns sobre a Ferramenta de Revisão de Agentes.

Quanto tempo demora a revisão?

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

A ferramenta modifica o meu agente?

Não. A ferramenta é inteiramente apenas de leitura no que diz respeito aos dados do agente. Só lê a configuração do agente. Todas as gravações vão para a tabela cat_agentreviews.

Posso rever um agente depois de fazer alterações?

Sim. Cada revisão cria um novo registo. A grelha mostra sempre a revisão mais recente. As revisões antigas permanecem no Dataverse e podem ser acedidas programaticamente, se necessário.

E se o meu agente estiver num ambiente diferente?

Utilize o seletor de ambientes no dashboard para apontar a ferramenta para outro ambiente a que tenha acesso. A revisão decorre nesse ambiente e o resultado é armazenado no ambiente atual.

Posso rever agentes que não criei?

Sim. Pode rever qualquer agente a que tenha acesso de leitura no Dataverse. No entanto, só pode ver as revisões que criou (segurança ao nível da linha). As revisões de outros utilizadores não são visíveis.

O que é SARIF e preciso dele?

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

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

Sim. A ferramenta só mostra agentes que têm IA generativa ativada, por isso espera-se que todos os agentes na grelha tenham instruções. Se a verificação de conformidade não reportar instruções, a orquestração generativa do agente está ativa, mas ainda não foram escritas instruções do sistema. É fortemente recomendada a adição de instruções.

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

A orientação da Microsoft refere que um tom profissional e educado já é o comportamento padrão dos agentes do Copilot Studio. As instruções para o tom só são necessárias se quiser utilizar um tom que não seja predefinido. Este critério é Baixo porque falhar raramente causa problemas do lado do utilizador.

Fazer uma revisão consome créditos do Copilot?

Sim. Cada revisão invoca modelos de IA três vezes: para avaliação de padrões, conformidade de instruções e geração de PDFs. Cada invocação consome créditos do Copilot do teu inquilino. Reavaliar o mesmo agente também consome créditos, por isso faça as alterações primeiro e depois volte a rever.

Posso exportar todas as revisões de uma vez?

Sim. Use o botão Exportar Tudo na barra de ferramentas da grelha dos agentes para gerar um livro de Excel que inclua todos os agentes revistos na vista atual.

Informações relacionadas

• Descrição geral do Kit do Agente do Copilot
• Instalar Kit de Agente do Copilot
• Orientação em modo generativo
• Configurar agentes no Kit de Agente do Copilot
• Inventário de Agentes no Kit do Copilot Studio.