Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
O Depurador de Agentes é uma ferramenta de diagnóstico que ajuda a carregar uma conversação gravada e a analisar cada decisão tomada por um agente. Para cada turno de conversação, pode rever o caminho de execução, a temporização dos passos, a utilização de tokens, as fontes de conhecimento, os argumentos dos passos e a racionalização do orquestrador.
O Depurador de Agentes suporta duas origens de dados:
- Transcrição de Conversação (Dataverse): Quando uma conversação é executada no Copilot Studio, a plataforma regista um registo de atividades como uma Transcrição de Conversação no Dataverse. O Depurador de Agentes consulta esses registos diretamente, por isso qualquer agente publicado com dados de transcrição está imediatamente disponível.
- Instantâneo do Copilot Studio (ZIP): O painel de testes do Copilot Studio inclui uma opção Transferir instantâneo que exporta a conversação de teste atual como um ficheiro ZIP. Carregar esse ficheiro no Depurador de Agentes dá-lhe uma visão completa da análise sem uma ligação ao Dataverse. Este método é útil para depurar conversações de pré-produção, reproduzir problemas offline ou partilhar uma sessão com falhas com um colega.
Ambas as origens de dados alimentam a mesma interface de análise. Os painéis, os detalhes dos passos e as visualizações são os mesmos, independentemente de como os dados são carregados.
Pré-requisitos
Para utilizar o Depurador de Agentes, certifique-se de que os seguintes pré-requisitos são cumpridos:
- O agente está presente no Inventário de Agentes e tem pelo menos uma transcrição de conversação registada associada. Pode verificar esta condição abrindo a vista de lista de Inventário de Agentes, selecionando o agente e selecionando Mostrar mais para expandir os campos adicionais. O campo A Transcrição Está Disponível tem de estar definido como Sim. A sincronização do Inventário de Agentes define automaticamente este campo quando existe pelo menos uma transcrição de conversação para o agente no Dataverse.
- O utilizador com sessão iniciada tem o direito de acesso CSK - Administrador ou Administrador de Sistema no ambiente do kit.
- O utilizador com sessão iniciada tem acesso de Leitura nas tabelas
conversationtranscripts,botebotcomponentsno ambiente de destino.
Nota
Se o agente que está a depurar estiver num ambiente diferente daquele em que o kit está instalado, tem de autenticar a ligação ao Dataverse no ambiente remoto com as mesmas permissões de leitura.
Selecionar uma conversação
Quando abre o Depurador de Agentes, a barra de filtro disponibiliza os controlos necessários para localizar uma conversação para analisar.
| Filtro | Descrição |
|---|---|
| Ambiente | Preenchido com os nomes distintos de ambientes encontrados no Inventário de Agentes. Ao selecionar um ambiente, a lista pendente Agente fica limitada aos agentes registados nesse ambiente. |
| Agente | Mostra os agentes no ambiente selecionado cujo campo A Transcrição Está Disponível está definido como Sim. Selecionar um agente carrega as 50 conversações mais recentes dentro do intervalo de tempo selecionado na lista pendente ID de Conversação. |
| ID de Conversação | Mostra as 50 conversações únicas mais recentes para o agente selecionado dentro do intervalo de tempo configurado. Escrever na caixa aciona uma pesquisa completa em todas as transcrições desse agente (até 100.000 registos), para que possa encontrar conversações mais antigas ou específicas, independentemente do intervalo de tempo. |
| Intervalo de tempo | Limita a lista ID de Conversação a um período específico. Escolha entre Últimos 30 minutos, Última hora, Últimas 4 horas, Últimas 24 horas, Últimos 7 dias ou Intervalo personalizado. Quando seleciona Intervalo personalizado, são apresentados seletores de data e hora para definir um carimbo de data/hora de início e de fim. |
| Apenas conversações com erros | Filtra a lista pendente ID de Conversação para mostrar apenas as conversações que contenham pelo menos um passo com falhas ou um erro do sistema. Utilize esta opção ao fazer a triagem de incidentes ou ao rever agentes com problemas de fiabilidade conhecidos. |
Depois de selecionar um ID de Conversação, a opção Analisar fica disponível. Selecione-a para abrir a vista de análise.
Nota
Escrever diretamente um ID de Conversação pesquisa sempre todas as transcrições, independentemente do intervalo de tempo ativo. O filtro Conversações com erro apenas analisa o conteúdo das transcrições no lado do cliente e demora mais tempo do que a consulta padrão. Deixe-o desativado, a menos que necessite especificamente de filtrar por erros.
Carregar um instantâneo a partir do Copilot Studio
O separador Carregar Instantâneo fornece um ponto de entrada alternativo que não requer acesso ao Dataverse. Em vez de selecionar uma conversação em direto nas listas pendentes, é carregado um ficheiro ZIP de instantâneo transferido a partir do painel de teste do Copilot Studio.
Para transferir um instantâneo a partir do Copilot Studio:
- Abra o seu agente no Copilot Studio e aceda ao painel Testar o seu agente.
- Execute ou reveja uma conversação.
- Selecione Transferir instantâneo na barra de ferramentas do painel de teste.
O Copilot Studio transfere um ficheiro .zip que contém:
-
dialog.json: Todas as atividades do Bot Framework para a conversação (obrigatório). -
botContent.yml: As definições completas de componentes e fluxos do agente, utilizadas para resolver os nomes dos passos (opcional; se ausente, são apresentados os nomes não processados dos esquemas).
Para carregar um instantâneo no Depurador de Agentes:
- Mude para o separador Carregar Instantâneo no cabeçalho do Depurador de Agentes.
- Arraste e largue o ficheiro
.zipna zona de colocação, ou selecione para procurá-lo.
O Depurador de Agentes valida o ZIP, extrai os ficheiros e abre a vista de análise. Não é necessário selecionar qualquer ambiente, agente ou conversação. Todas as métricas de informação geral são derivadas do ficheiro carregado.
Utilize o modo Carregar Instantâneo quando precisar de:
- Depurar uma conversação que ocorreu no painel de teste antes de o agente ter sido publicado.
- Analisar uma conversação de um ambiente no qual não é possível autenticar-se.
- Reproduzir problemas offline ou partilhar uma sessão com falhas com um colega sem conceder acesso ao Dataverse.
- Validar o comportamento dos agentes num ambiente de desenvolvimento local.
Analisar uma conversação
A vista de análise é aberta depois de selecionar Analisar ou carregar um instantâneo. Contém uma linha de resumo Informações gerais no topo, uma secção de análise expansível com quatro painéis (Caminho de execução, Linha cronológica de desempenho, Detalhes do agente e Recomendações), e um esquema de dois painéis que apresenta a Pré-visualização da conversação juntamente com o painel Informações de depuração.
Informações gerais
A linha de informações gerais mostra mosaicos com métricas resumidas relativas à conversação.
| Campo | Description |
|---|---|
| Sessões | Número de sessões de conversação. Ocorrem várias sessões quando um utilizador retorna à mesma conversação após um período de inatividade. |
| Turnos | Número de mensagens dos utilizadores na conversação. |
| Resultado | Resultado da sessão comunicado pela plataforma, tal como Resolvido, Escalado, Abandonado ou SystemError. |
| Duração | Duração total da conversação desde a primeira até à última atividade. |
| Hora de Início | Quando a conversação teve início (hora local). |
| Canal | Canal de comunicação utilizado, como webchat ou msteams. Mostrado quando disponível. |
| Modelo | O modelo de IA utilizado pelo orquestrador do agente para esta conversação. |
Quando um agente em direto é carregado, é apresentada uma ligação Abrir agente no cabeçalho de informações gerais. A ligação abre a página de configuração do agente no Copilot Studio.
Caminho de execução
O caminho de execução compõe a ordem completa de execução em todos os turnos de conversação como um diagrama de fluxo dirigido. Os passos fluem da esquerda para a direita conforme a ordem de execução. Linhas verticais tracejadas marcam os limites entre turnos, e cada mensagem do utilizador inicia uma nova secção. As etiquetas de turno são apresentadas no topo de cada secção. Ao selecionar uma etiqueta de turno, a Pré-visualização da conversação desloca-se até essa mensagem.
Cada tipo de passo utiliza uma cor distinta, e uma legenda na parte inferior do diagrama mapeia as cores para categorias de passos como Tópico, Conhecimento, Ferramenta, Conector, Fluxo, Código, MCP e Agente Ligado. Cada nó mostra o nome do passo e a duração da execução. Os passos com falhas estão realçados a vermelho. Os agentes ligados são apresentados como caixas de contentores que agrupam os passos subordinados que executaram.
Linha cronológica de desempenho
A linha cronológica de desempenho mostra um gráfico em cascata dos tempos de execução dos passos agrupados por turno de conversação. As barras dos passos são dimensionadas em função da duração total do turno para tornar visível o tempo relativo. A codificação por cores corresponde à legenda do caminho de execução, e os passos com falhas são apresentados a vermelho.
O painel inclui as seguintes funcionalidades:
- Os botões Expandir/Fechar Tudo alternam todas as secções de turno ao mesmo tempo. Cada secção de turno também é expansível individualmente.
- As estatísticas por turno mostram o número de passos, o nome e a duração do passo mais lento, e o número de falhas.
- Um resumo global no topo mostra o total de passos, o tempo total decorrido, o passo mais lento em toda a conversação e o número total de falhas.
- Os passos com duração inferior a 10 segundos são assinalados com um indicador de aviso.
Detalhes do agente
O painel de detalhes do agente mostra a configuração completa do agente tal como se encontrava no momento em que a conversação foi analisada. A informação está organizada em seis separadores.
| Tab | Descrição |
|---|---|
| Descrição geral | Mosaicos de KPI para Tópicos, Ferramentas, Conhecimento, Agentes de Elemento Subordinado, Modo de orquestração, Idioma, Modo de Autenticação, Conhecimento do Modelo, Pesquisa Semântica e Modelos Mais Recentes. Cada mosaico inclui uma descrição que explica a definição. |
| Instruções | O pedido de sistema completo do agente, tal como configurado no Copilot Studio. |
| Tópicos | Todos os tópicos com nome, descrição, variáveis de entrada/saída e estado Ativado/Desativado. |
| Ferramentas | Todas as ferramentas com nome, descrição, destaque de tipo (MCP, Fluxo, Conector, Pedido) e estado Ativado/Desativado. |
| Conhecimento | Todas as fontes de conhecimento com nome, destaque de tipo (SharePoint, Web, Dataverse, Ficheiro), URL e estado Ativado/Desativado. |
| Agentes | Todos os agentes de elemento subordinado ligados com nome, tipo de relação e estado Ativado/Desativado. |
Recomendações
O painel de recomendações deteta automaticamente os problemas na conversação e apresenta-os como cartões acionáveis com classificações de gravidade.
| Gravidade | Descrição |
|---|---|
| Alta | Provavelmente causou uma resposta com falhas ou incorreta. Investigue imediatamente. |
| Média | Experiência degradada ou risco de fiabilidade. Reveja assim que possível. |
| Baixa | Ineficiência menor ou nota informativa. |
São detetados os seguintes tipos de problemas:
| Problema | Gravidade | Descrição |
|---|---|---|
| Passo com falhas ou erro | Alta | Um passo devolveu um erro ou uma exceção. |
| Bloqueio de IA Responsável | Alta | O conteúdo foi filtrado pelo sistema de IA Responsável. |
| Escalamento da conversação | Alta | A conversação foi entregue a um agente humano. |
| Abandono da conversação | Alta | O utilizador saiu sem obter resolução. |
| Tópico de contingência acionado | Alta | O agente falhou em encaminhar a mensagem do utilizador para um tópico. |
| Passo lento (>10s) | Meio | Um passo demorou mais de 10 segundos a executar. |
| Falha na pesquisa na base de dados de conhecimento | Meio | Foi consultada uma fonte de conhecimento, mas não devolveu resultados. |
| Aproximação ao limite de tokens | Meio | A utilização de tokens aproximou‑se do limite da janela de contexto do modelo. |
| Erro no passo de código | Alta | Um passo de código Python gerou uma exceção. |
| Falha na inicialização do MCP | Alta | Um servidor MCP falhou em inicializar durante a conversação. |
Cada cartão de recomendação mostra o ícone e a cor de gravidade, um destaque de categoria, o título e a descrição do problema detetado, uma sugestão sobre como investigá‑lo ou resolvê‑lo, e um botão Aceder ao turno que desloca a Pré-visualização da Conversação até à mensagem de utilizador relevante. Quando não são detetados problemas, o painel mostra uma mensagem de estado vazio.
Pré-visualização da conversação
O painel de pré-visualização da conversação apresenta o histórico completo da conversação tal como foi apresentado ao utilizador, incluindo bolhas de mensagens do bot e do utilizador, Cartões Adaptativos compostos inline, chips de ações sugeridas e pedidos de comentários.
Selecionar uma bolha de mensagem do utilizador carrega os passos desse turno no painel Informações de depuração. A mensagem selecionada é realçada para que possa monitorizar o turno que está ativo. O painel é deslocável de forma independente. Selecionar Ver JSON no cabeçalho de pré-visualização da conversação abre o diálogo JSON da transcrição completa.
Informações de depuração
O painel de informações de depuração mostra detalhes ao nível dos passos para o turno de mensagem do utilizador selecionado. O painel inclui uma lista de passos à esquerda e uma vista de detalhes de passos que é aberta quando um passo é selecionado.
A lista de passos mostra todos os passos do orquestrador executados no turno selecionado, com um ícone e cor de passo que indicam o tipo de passo, o nome do passo (resolvido para um nome a apresentar intuitivo quando possível), a duração da execução e um indicador de êxito ou de falha. Os passos que pertencem a um agente ligado são agrupados dentro de um cartão de contentor expansível que mostra o nome do agente e o tempo total de execução. Um botão Carregar detalhes do agente ligado no contentor carrega a transcrição completa do agente de elemento subordinado a pedido.
São suportados os seguintes tipos de passos:
| Tipo | Descrição |
|---|---|
| Tópico | Um tópico nomeado na lista de tópicos do agente. |
| Tópico de Sistema | Um tópico de plataforma incorporado, tal como Saudação, Contingência ou Escalar. |
| Conhecimento | Um passo de pesquisa de fonte de conhecimento. |
| Ferramenta / Ação | Um fluxo do Power Automate ou uma ação de conector. |
| Código | Um passo de execução de código Python. |
| Pedido Personalizado | Um passo de pedido de IA generativa personalizado. |
| Racionalização | Um passo de racionalização interno utilizado pelo orquestrador. |
| Servidor MCP | Uma invocação de ferramenta de Model Context Protocol. |
| Agente Ligado | Delegação para um agente de elemento subordinado ligado. |
Selecionar um passo abre um painel de detalhes com as seguintes secções, mostradas quando os dados estão presentes na transcrição:
- Processo de pensamento: O texto da racionalização do orquestrador registado antes de o passo ter sido invocado. Mostra como o modelo decidiu chamar este passo e o que esperava dele.
- Tipo de passo: Etiqueta classificada para o passo.
- Argumentos: Uma vista de árvore JSON expansível dos parâmetros de entrada passados ao passo. Inclui uma opção de cópia para capturar o JSON para pedidos de suporte.
- Observação: A saída ou o valor devolvido pelo passo. Também apresentada como uma árvore JSON expansível com suporte de cópia.
- Pré-visualização de código: Para os passos de código Python, o código fonte é mostrado com realce de sintaxe.
- Utilização de tokens: Número de tokens do pedido, número de tokens de conclusão e total para o passo, juntamente com o nome do modelo utilizado.
- Fontes de conhecimento: Fontes pesquisadas, resultados devolvidos (saída) e fontes efetivamente citadas na resposta final. Cada entrada mostra o nome da fonte, o tipo, o URL quando disponível e uma ligação para abrir a fonte.
- Informações do servidor MCP: Para passos MCP, mostra a versão do protocolo do servidor, as capacidades declaradas e a lista de ferramentas fornecidas pelo servidor durante a inicialização.
- Informações de erro: Quando um passo falha, mostra o código de erro, a mensagem de erro e (para bloqueios de IA responsável) a categoria de segurança de conteúdo que acionou o filtro.
- Cartões Adaptativos: Quando o passo produz uma resposta de Cartão Adaptativo, o cartão é composto inline no painel de detalhes exatamente como o utilizador o teria visto.
Transcrição JSON
Quando seleciona Ver JSON no cabeçalho de pré-visualização da conversação, é aberta uma caixa de diálogo que mostra as atividades completas da transcrição não processada com realce de sintaxe, pesquisa em texto completo na árvore JSON e uma opção de copiar para a área de transferência para todo o payload.
Utilize esta vista quando:
- Precisar de inspecionar um tipo de evento que não é apresentado no painel Informações de depuração.
- Pretender copiar campos específicos para um pedido de suporte.
- Estiver a investigar comportamentos inesperados nas vistas analisadas.
Resolução de Problemas
As secções seguintes descrevem problemas comuns e como os resolver.
O agente não é apresentado no menu pendente Ambiente ou Agente
O agente não está sincronizado com o Inventário de Agentes ou não tem transcrições de conversações.
Para resolver este problema:
- Execute uma sincronização manual do Inventário de Agentes para o ambiente.
- Verifique se o registo do agente existe na tabela Detalhes do Agente no Dataverse.
- Verifique se a coluna A Transcrição Está Disponível está definida como Sim no registo. A sincronização define este campo quando existe pelo menos uma transcrição.
Para mais informações, consulte Monitorizar agentes utilizando o Inventário de Agentes no Kit de Agente do Copilot.
O ID da conversação não foi encontrado na lista pendente
Para desempenho, a lista pendente pré‑carrega apenas as 50 conversações mais recentes dentro do intervalo de tempo ativo. As transcrições mais antigas continuam a existir no Dataverse, mas não são apresentadas por predefinição. Alternativamente, a transcrição pode ainda não ter sido escrita se a conversação acabou de terminar.
Para resolver este problema:
- Escreva o ID da conversação diretamente no campo ID da Conversação. Escrever aciona uma pesquisa completa em todas as transcrições desse agente, ignorando o intervalo de tempo.
- Se o intervalo de tempo for limitado (por exemplo, Últimos 30 minutos), expanda-o ou mude para um intervalo personalizado que abranja a data da conversação.
- Se a conversação terminou, aguarde 35-40 minutos para que a transcrição seja escrita no Dataverse e depois atualize.
A análise é carregada, mas não são apresentados passos no painel de Informações de depuração
A transcrição existe, mas contém apenas atividades do tipo mensagem sem eventos de rastreio de diagnóstico. Este problema normalmente acontece quando a conversação provém de um canal que não emite dados de rastreio, como certos canais personalizados ou versões de esquemas mais antigas.
Para resolver este problema:
- Selecione Ver JSON no cabeçalho de pré-visualização da conversação para confirmar que as atividades estão presentes.
- Procure entradas
type: "trace"outype: "event". Se estiverem ausentes, o canal pode não emitir dados de rastreio.
Acesso negado ou página em branco ao carregar
As funções ou permissões estão em falta num ou em ambos os ambientes.
Para resolver este problema:
- No ambiente do kit, certifique‑se de que o utilizador tem a função CSK - Administrador ou Administrador de Sistema.
- No ambiente de destino, certifique-se de que o utilizador com sessão iniciada tem acesso de leitura às tabelas
conversationtranscripts,botebotcomponents.
As transcrições são apresentadas incompletas (mensagens iniciais em falta)
As conversações longas são divididas por vários registos do Dataverse (limite de 1 MB por registo). Se a política de retenção remover alguns registos, a transcrição unida tem lacunas.
Para resolver este problema:
- O Dataverse remove por predefinição transcrições de conversações com mais de 30 dias. Se a retenção for o problema, atualize o agendamento da tarefa de eliminação em massa em Power Apps>Definições>Definições avançadas>Gestão de Dados>Eliminação de Registos em Massa.
- Se a retenção não for a causa, verifique se todos os registos de transcrição da conversação existem na tabela
conversationtranscriptsdo Dataverse.
Os passos apresentam nomes de esquema não processados em vez de nomes de tópicos legíveis
A consulta à tabela botcomponents falhou ou o registo do componente foi eliminado.
Para resolver este problema:
- Verifique se o utilizador com sessão iniciada tem acesso de leitura à tabela
botcomponentsno ambiente de destino. - Se o componente foi eliminado do Copilot Studio, não existe registo correspondente e o Depurador de Agentes recorre ao nome de esquema não processado, como
cr123_mytopic. Este comportamento é esperado para tópicos ou ações eliminadas.
O painel de detalhes do agente não mostra dados
A obtenção da configuração do agente falhou ou a ligação do utilizador com sessão iniciada não tem acesso de leitura às tabelas bot e botcomponents no ambiente de destino.
Para resolver este problema:
- Verifique o acesso de leitura às tabelas
botebotcomponentspara a referência de ligação utilizada pela aplicação. - Se o agente foi eliminado ou a sua publicação foi anulada depois de a conversação ter sido gravada, os respetivos registos de configuração podem já não existir. Neste caso, o painel Detalhes do agente permanece vazio, mas os painéis de transcrição e depuração continuam totalmente funcionais.
O painel de recomendações não mostra problemas, mas a conversação falhou
As recomendações provêm de padrões nos eventos de rastreio da transcrição. Se a transcrição não tiver dados de rastreio ou se a falha ocorrer fora da conversação (por exemplo, um tempo limite de rede silencioso que a transcrição não regista), o sistema não gera quaisquer recomendações.
Para resolver este problema:
- Abra o JSON da transcrição para procurar payloads de erro não processados que não são apresentados como uma recomendação.
- Verifique o caminho de execução para quaisquer passos mostrados a vermelho. Estes passos indicam falhas que não mapeiam para um padrão de recomendação conhecido.