Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O Depurador de Agentes é uma ferramenta de diagnóstico que ajuda você a carregar uma conversa gravada e inspecionar cada decisão tomada pelo agente. Para cada turno de conversa, você pode revisar o caminho de execução, o tempo da etapa, o uso de tokens, fontes de conhecimento, argumentos da etapa e o raciocínio do orquestrador.
O Depurador de Agentes oferece suporte a duas fontes de dados:
- Transcrição de Conversa (Dataverse): quando uma conversa é executada no Copilot Studio, a plataforma grava um registro de atividades como uma Transcrição de Conversa no Dataverse. O Depurador de Agentes consulta esses registros diretamente, então qualquer agente publicado com dados de transcrição fica imediatamente disponível.
- Instantâneo do Copilot Studio (ZIP): o painel de teste do Copilot Studio inclui a opção Instantâneo de Download que exporta a conversa de teste atual como um arquivo ZIP. Enviar esse arquivo para o Depurador de Agentes te dá a visão completa da análise sem conexão com o Dataverse. Esse método é útil para depurar conversas de pré-produção, reproduzir problemas offline ou compartilhar uma sessão com falha com um colega.
Ambas as fontes de dados alimentam a mesma interface de análise. Os painéis, detalhes das etapas e visualizações são os mesmos independentemente de como os dados são carregados.
Pré-requisitos
Para usar o Depurador de Agentes, verifique se os seguintes pré-requisitos foram atendidos:
- O agente está presente no Estoque de Agentes e tem pelo menos uma transcrição de conversa registrada contra ele. Você pode verificar essa condição abrindo a visualização de lista de Estoque de Agentes, selecionando o agente e selecionando Mostrar mais para expandir os campos adicionais. O campo Está Disponível para Transcrição deve ser definido como Sim. A sincronização do Estoque de Agentes define automaticamente esse campo quando existe pelo menos uma transcrição de conversa para o agente no Dataverse.
- O usuário conectado possui o direito de acesso CSK - Administrador ou Administrador do Sistema no ambiente do kit.
- O usuário conectado tem acesso de Leitura nas
conversationtranscriptstabelasbot, ebotcomponentsno ambiente de destino.
Observação
Se o agente que você está depurando estiver em um ambiente diferente do que o kit está instalado, você deve autenticar a conexão do Dataverse no ambiente remoto com as mesmas permissões de leitura.
Selecionar uma conversa
Quando você abre o Depurador de Agentes, a barra de filtro fornece os controles necessários para localizar uma conversa para analisar.
| Filtro | descrição |
|---|---|
| Ambiente | Preenchido pelos nomes distintos de ambientes encontrados no Estoque de Agentes. Selecionar um ambiente reduz o menu suspenso Agente a agentes registrados naquele ambiente. |
| Agente | Mostra agentes no ambiente selecionado cujo campo Está Disponível para Transcrição está definido como Sim. Selecionar um agente carrega as 50 conversas mais recentes dentro do intervalo de tempo selecionado no menu suspenso ID da Conversa. |
| ID da Conversa | Mostra as 50 conversas únicas mais recentes para o agente selecionado dentro do intervalo de tempo configurado. Digitar na caixa aciona uma busca completa em todas as transcrições desse agente (até 100.000 registros), então você pode encontrar conversas antigas ou específicas independentemente do intervalo de tempo. |
| Intervalo de tempo | Reduz a lista de ID de Conversa para uma janela específica. Escolha entre Últimos 30 minutos, Última hora, Últimas 4 horas, Últimas 24 horas, Últimos 7 dias ou Faixa personalizada. Quando você seleciona Faixa personalizada, os selecionadores de data e hora aparecem para definir um carimbo de hora de início e fim. |
| Apenas conversas de erro | Filtra o menu suspenso ID de Conversa para conversas que contenham pelo menos uma etapa com falha ou erro do sistema. Use essa opção ao fazer triagem de incidentes ou revisar agentes com problemas conhecidos de confiabilidade. |
Depois que você seleciona um ID de Conversa, a opção Analisar fica disponível. Selecione-a para abrir a exibição de análise.
Observação
Digitar um ID de Conversa diretamente sempre busca todas as transcrições, independentemente do intervalo de tempo ativo. O filtro Apenas conversas de erro digitaliza o conteúdo da transcrição do lado do cliente e demora mais do que a consulta padrão. Deixe desativado, a menos que precise filtrar especificamente por erros.
Faça upload de uma foto do Copilot Studio
A guia Fazer Upload do Instantâneo oferece um ponto de entrada alternativo que não requer acesso ao Dataverse. Em vez de selecionar uma conversa ao vivo nos menus suspensos, você envia um arquivo ZIP do instantâneo baixado do painel de teste do Copilot Studio.
Para baixar um instantâneo do Copilot Studio:
- Abra seu agente no Copilot Studio e vá para o painel Testar seu agente.
- Executar ou revisar uma conversa.
- Selecione Baixar instantâneo na barra de ferramentas do painel de teste.
O Copilot Studio baixa um arquivo .zip que contém:
-
dialog.json: Todas as atividades do Bot Framework para a conversa (obrigatórias). -
botContent.yml: As definições completas de componentes e fluxos do agente, usadas para resolver nomes de etapas (opcional; se ausentes, nomes brutos dos esquemas são mostrados).
Para fazer upload de um snapshot no Depurador de Agentes:
- Mude para a guia Fazer Upload do Instantâneo no cabeçalho do Depurador de Agentes.
- Arraste e solte o arquivo
.zipna zona para soltar, ou selecione para procurá-lo.
O Depurador de Agentes valida o ZIP, extrai os arquivos e abre a exibição de análise. Não é necessário selecionar ambiente, agente ou conversa. Todas as métricas gerais de informação são obtidas do arquivo carregado.
Use o modo Fazer Upload do Instantâneo quando precisar:
- Depure uma conversa que aconteceu no painel de teste antes da publicação do agente.
- Analise uma conversa de um ambiente com o qual você não pode autenticar.
- Reproduza problemas offline ou compartilhe uma sessão com falha com um colega sem conceder acesso ao Dataverse.
- Valide o comportamento do agente em um ambiente de desenvolvimento local.
Analise uma conversa
A exibição de análise se abre depois que você seleciona Analisar ou carrega um instantâneo. Ele contém uma linha de resumo de Informações Gerais na parte superior, uma seção de análise recolhível com quatro painéis (Caminho de execução, Linha do tempo de desempenho, Detalhes do agente e Recomendações) e um layout de dois painéis que mostra a Visualização da conversa junto com o painel Informações de depuração.
Informações gerais
A linha de informações gerais mostra blocos de métrica resumida para a conversa.
| Campo | descrição |
|---|---|
| Sessões | Número de sessões de conversa. Ocorrem várias sessões quando um usuário retorna à mesma conversa após a inatividade. |
| Turnos | Número de mensagens de usuário na conversa. |
| Resultado | Resultado da sessão reportado pela plataforma, como Resolvido, Escalonado, Abandonado ou SystemError. |
| Duration | Duração total da conversa da primeira à última atividade. |
| Hora de Início | Quando a conversa começou (horário local). |
| Canal | Canal de comunicação utilizado, como webchat ou msteams. Mostrado quando disponível. |
| Modelo | O modelo de IA usado pelo orquestrador do agente para essa conversa. |
Quando um agente humano é carregado, um link Abrir agente aparece no cabeçalho de informações gerais. O link abre a página de configuração do agente no Copilot Studio.
Caminho de execução
O caminho de execução apresenta a ordem completa de execução em todos os turnos de conversa como um diagrama de fluxo direcionado. As etapas fluem da esquerda para a direita em ordem de execução. Linhas verticais tracejadas marcam os limites de curva, e cada mensagem de usuário inicia uma nova seção. Rótulos de turno aparecem no topo de cada seção. Selecionar um rótulo de turno rola a Visualização da conversa até essa mensagem.
Cada tipo de etapa usa uma cor distinta, e uma legenda na parte inferior do diagrama mapeia as cores para categorias de etapas como Tópico, Conhecimento, Ferramenta, Conector, Fluxo, Código, MCP e Agente Conectado. Cada nó mostra o nome da etapa e a duração da execução. As etapas com falha são destacadas em vermelho. Agentes conectados aparecem como caixas de contêiner que agrupam as etapas filho que executaram.
Linha do tempo de desempenho
A linha do tempo de desempenho mostra um gráfico em cascata com os tempos de execução das etapas agrupados por turno de conversa. As barras de etapa são ajustadas à duração total da curva para tornar o tempo relativo visível. A codificação por cores corresponde à legenda do caminho de execução, e as etapas com falha aparecem em vermelho.
O painel inclui os seguintes recursos:
- Os botões Expandir/Recolher Todos alternam todas as seções de turno ao mesmo tempo. Cada seção de turno também pode ser expandida ou recolhida individualmente.
- Estatísticas por turno mostram a contagem de etapas, o nome e duração das etapas mais lentos, e a contagem de falhas.
- Um resumo global no topo mostra o total de etapas, o tempo total decorrido, a etapa mais lenta em toda a conversa e a contagem total de falhas.
- Etapas mais lentas que 10 segundos são sinalizadas com um indicador de alerta.
Detalhes do agente
O painel de detalhes do agente mostra a configuração completa do agente como ele existia no momento em que a conversa foi analisada. As informações estão organizadas em seis guias.
| Tabulação | descrição |
|---|---|
| Visão geral | Blocos de KPI para Tópicos, Ferramentas, Conhecimento, Agentes Filhos, Modo de Orquestração, Linguagem, Modo de Autenticação, Conhecimento do Modelo, Busca Semântica e Modelos Mais Recentes. Cada bloco inclui uma dica de ferramenta que explica o cenário. |
| Instruções | O prompt completo do sistema do agente conforme configurado no Copilot Studio. |
| Tópicos | Todos os tópicos com nome, descrição, variáveis de entrada/saída e status Habilitado/Desativado. |
| Ferramentas | Todas as ferramentas com nome, descrição, notificação de tipo (MCP, Fluxo, Conector, Prompt) e status de Ativado/Desativado. |
| Conhecimento | Todas as fontes de conhecimento com nome, notificação de tipo (SharePoint, Web, Dataverse, Arquivo), URL e status de Habilitado/Desativado. |
| Agentes | Todos os agentes filhos conectados com nome, tipo de relacionamento e status Habilitado/Desativado. |
Recomendações
O painel de recomendações detecta automaticamente os problemas na conversa e os apresenta como cartões acionáveis com classificações de gravidade.
| Gravidade | descrição |
|---|---|
| Alto | Provavelmente causou uma resposta com falha ou incorreta. Investigue imediatamente. |
| Médio | Experiência degradada ou risco de confiabilidade. Revisar em breve. |
| Baixo | Pequena ineficiência ou nota informativa. |
Os seguintes tipos de problemas são detectados:
| Problema | Gravidade | descrição |
|---|---|---|
| Etapa com falha ou erro | Alta | Uma etapa retornava um erro ou uma exceção. |
| Bloco de IA responsável | Alta | O conteúdo foi filtrado pelo sistema de IA Responsável. |
| Escalonamento de conversa | Alta | A conversa foi transferida a um agente humano. |
| Abandono de conversa | Alta | O usuário saiu sem uma solução. |
| Tópico de fallback acionado | Alta | O agente não encaminhou a mensagem do usuário para um tópico. |
| Etapa lenta (>10s) | Medium | Uma etapa levava mais de 10 segundos para ser executada. |
| Falha na pesquisa de conhecimento | Medium | Uma fonte de conhecimento foi consultada, mas não retornou resultados. |
| Limite de tokens se aproximando | Medium | O uso de tokens chegou próximo do limite da janela de contexto do modelo. |
| Erro na etapa do código | Alta | Uma etapa de código em Python gerou uma exceção. |
| Falha na inicialização de MCP | Alta | Falha na inicialização do servidor MCP durante a conversa. |
Cada cartão de recomendação mostra o ícone e a cor de gravidade, uma notificação de categoria, o título e a descrição do problema detectado, uma sugestão de como investigar ou resolvê-lo, e um botão Ir para o turno que rola a Visualização da conversa até a mensagem do usuário relevante. Quando nenhum problema é detectado, o painel mostra uma mensagem de estado vazio.
Visualização da conversa
O painel de visualização da conversa mostra toda a troca de conversas como ela apareceu para o usuário, incluindo bolhas de mensagens do bot e do usuário, Cartões Adaptáveis renderizados em linha, chips de ação sugeridos e prompts de comentários.
Selecionar uma bolha de mensagem de usuário carrega essas etapas do turno no painel Informações de Depuração. A mensagem selecionada é destacada para que você possa acompanhar qual turno está ativo. O painel pode ser rolado independentemente. Selecionar Visualizar JSON no cabeçalho de visualização da conversa abre o diálogo JSON da transcrição completa.
Informações de depuração
O painel de informações de depuração mostra detalhes em nível de etapa para o turno de mensagem do usuário selecionado. O painel inclui uma lista de etapas à esquerda e uma exibição de detalhes de etapas que se abre quando você seleciona uma etapa.
A lista de etapas mostra cada etapa do orquestrador executado para o turno selecionado, com um ícone e cor de etapa que indicam o tipo de etapa, o nome da etapa (resolvida para um nome amigável quando possível), a duração da execução e um indicador de sucesso ou falha. Etapas que pertencem a um agente conectado são agrupadas dentro de um cartão de contêiner recolhível que mostra o nome do agente e o tempo total de execução. Um botão Carregar detalhes do agente conectado no contêiner carrega a transcrição completa do agente filho sob demanda.
Há suporte para os seguintes tipos de etapas:
| Tipo | descrição |
|---|---|
| Tópico | Um tópico nomeado na lista de tópicos do agente. |
| Tópico do sistema | Um tópico de plataforma integrado, como Saudação, Fallback ou Escalonar. |
| Conhecimento | Uma etapa de pesquisa da fonte de conhecimento. |
| Ferramenta/Ação | Um fluxo ou ação do conector do Power Automate. |
| Código | Uma etapa de execução de código em Python. |
| Prompt Personalizado | Uma etapa personalizada de prompt de IA generativa. |
| Raciocinador | Uma etapa de raciocínio interna usada pelo orquestrador. |
| Servidor MCP | Invocação de uma ferramenta de Protocolo de Contexto de Modelo. |
| Agente Conectado | Delegação para um agente filho conectado. |
Selecionar uma etapa abre um painel de detalhes com as seguintes seções, mostradas quando os dados estão presentes na transcrição:
- Processo de pensamento: o texto de raciocínio do orquestrador gravado antes que a etapa fosse invocada. Mostra como o modelo decidiu chamar essa etapa e o que esperava dela.
- Tipo de etapa: rótulo classificado para a etapa.
- Argumentos: uma exibição em árvore JSON recolhível dos parâmetros de entrada passados para a etapa. Inclui uma opção de cópia para capturar o JSON para tíquetes de suporte.
- Observação: o valor de saída ou retorno da etapa. Também exibido como uma árvore JSON recolhível com suporte a cópia.
- Visualização do código: para as etapas do código Python, o código-fonte é mostrado com destaque da sintaxe.
- Uso do token: contagem de tokens de prompt, contagem de tokens de conclusão e total para a etapa, junto com o nome do modelo utilizado.
- Fontes de conhecimento: fontes pesquisadas, resultados retornados (saída) e fontes realmente citadas na resposta final. Cada entrada mostra o nome da fonte, tipo, URL quando disponível e um link para abrir a fonte.
- Informações do servidor MCP: para etapas MCP, mostra a versão do protocolo do servidor, capacidades declaradas e a lista de ferramentas fornecidas durante a inicialização.
- Informações de erro: quando uma etapa falhou, 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 Adaptáveis: quando a etapa produz uma resposta de Cartão Adaptável, o cartão é renderizado em linha no painel de detalhes exatamente como o usuário o teria visto.
JSON de Transcrição
Quando você seleciona Exibir JSON no cabeçalho de visualização da conversa, um diálogo é aberto mostrando as atividades completas da transcrição bruta com realce de sintaxe, busca em texto completo dentro da árvore JSON e uma opção de copiar para a área de transferência para todo o conteúdo.
Usa esta exibição quando:
- Você precisa inspecionar um tipo de evento que não aparece no painel Informações de Depuração.
- Você quer copiar campos específicos para um tíquete de suporte.
- Você está investigando comportamentos inesperados nas exibições analisadas.
Solução de problemas
As seções a seguir descrevem problemas comuns e como resolvê-los.
Agente não aparece no menu suspenso Ambiente ou no menu suspenso do Agente
O agente não está sincronizado com o Estoque de Agentes, ou não tem transcrições de conversas.
Para resolver o problema:
- Execute uma sincronização manual do Estoque de Agentes para o ambiente.
- Verifique se o registro do agente existe na tabela de Detalhes do Agente no Dataverse.
- Verifique se a coluna Está Disponível para Transcrição está definida como Sim no registro. A sincronização define esse campo quando existe pelo menos uma transcrição.
Para mais informações, consulte Monitorar agentes usando o Estoque de Agentes no Kit do Agente do Copilot.
O ID da conversa não aparece no menu suspenso
Para desempenho, o menu suspenso faz carregamento prévio apenas de 50 conversas mais recentes dentro do intervalo de tempo ativo. Transcrições antigas ainda existem no Dataverse, mas não aparecem por padrão. Como alternativa, a transcrição pode ainda não estar escrita se a conversa acabou de terminar.
Para resolver o problema:
- Digite o ID da conversa diretamente no campo ID da Conversa. A digitação aciona uma pesquisa completa em todas as transcrições por aquele agente, ignorando o intervalo de tempo.
- Se o intervalo de tempo for restrito (por exemplo, Últimos 30 minutos), amplie ou mude para um intervalo personalizado que abrange a data da conversa.
- Se a conversa acabou de terminar, espere de 35 a 40 minutos para a transcrição ser escrita no Dataverse e então atualize.
Analise cargas, mas nenhuma etapa aparece no painel de informações de depuração
A transcrição existe, mas contém apenas atividades do tipo mensagem sem eventos diagnósticos de rastreamento. Esse problema normalmente acontece quando a conversa veio de um canal que não emite dados de rastreamento, como certos canais personalizados ou versões antigas do esquema.
Para resolver o problema:
- Selecione Exibir JSON no cabeçalho de visualização da conversa para confirmar que as atividades estão presentes.
- Procure as entradas
type: "trace"outype: "event". Se estiverem ausentes, o canal pode não emitir dados de rastreamento.
Acesso negado ou página em branco ao carregar
Funções ou permissões estão ausentes em um ou ambos os ambientes.
Para resolver o problema:
- No ambiente do kit, certifique-se de que o usuário tem a função de CSK - Administrador ou Administrador do Sistema.
- No ambiente de destino, certifique-se de que o usuário conectado tem acesso de leitura para as tabelas
conversationtranscripts,botebotcomponents.
As transcrições parecem incompletas (mensagens antigas faltando)
Conversas longas são divididas entre múltiplos registros do Dataverse (limite de 1 MB por registro). Se a política de retenção eliminar alguns registros, a transcrição integrada apresenta lacunas.
Para resolver o problema:
- O Dataverse elimina por padrão transcrições de conversas com mais de 30 dias. Se a retenção for o problema, atualize a programação de tarefas de exclusão em massa no Power Apps>Configurações>Configurações avançadas>Gerenciamento de Dados>Exclusão em Massa de Registros.
- Se a retenção não for a causa, verifique se todos os registros de transcrição da conversa existem na tabela
conversationtranscriptsno Dataverse.
As etapas mostram nomes brutos de esquemas em vez de nomes de tópicos legíveis
A consulta da tabela botcomponents falhou, ou o registro do componente foi excluído.
Para resolver o problema:
- Verifique se o usuário conectado tem acesso de leitura para a tabela
botcomponentsno ambiente de destino. - Se o componente foi excluído do Copilot Studio, não existe registro correspondente e o Depurador de Agentes volta ao nome bruto do esquema, como
cr123_mytopic. Esse comportamento é esperado para tópicos ou ações excluídas.
O painel de detalhes do agente não mostra dados
A busca de configuração do agente falhou, ou a conexão do usuário conectado não tem acesso de leitura às tabelas bot e botcomponents no ambiente de destino.
Para resolver o problema:
- Verifique o acesso de leitura às tabelas
botebotcomponentspara a referência de conexão usada pelo aplicativo. - Se o agente foi excluído ou teve a publicação cancelada após a gravação da conversa, seus registros de configuração talvez não existam mais. Neste caso, o painel Detalhes do agente permanece vazio, mas os painéis de transcrição e depuração ainda estão totalmente funcionais.
O painel de recomendações não mostra problemas, mas houve falha na conversa
As recomendações vêm de padrões nos eventos de rastreamento da transcrição. Se a transcrição não tiver dados de rastreamento, ou se a falha ocorrer fora da conversa (por exemplo, um tempo limite silencioso da rede que a transcrição não registra), o sistema não gera nenhuma recomendação.
Para resolver o problema:
- Abra o JSON da transcrição para procurar conteúdo de erro bruto que não sejam apresentados como recomendação.
- Verifique o caminho de execução para quaisquer etapas mostradas em vermelho. Essas etapas indicam falhas que não seguem um padrão de recomendação conhecido.