Utilizar o modo de programador para testar e depurar agentes no Microsoft 365 Agents Toolkit

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

O teste é uma parte importante do processo de desenvolvimento de agentes declarativos para Microsoft 365 Copilot Chat. Pode utilizar o modo de programador enquanto testa o seu agente para verificar se e como o orquestrador do Copilot seleciona as suas fontes de conhecimento para utilizar em resposta a pedidos específicos.

Além disso, pode utilizar a funcionalidade Pré-visualizar a sua aplicação (F5) no Microsoft 365 Agents Toolkit para testar os seus agentes num ambiente de desenvolvimento local. Esse recurso fornece uma maneira interativa de validar o comportamento e solucionar problemas diretamente da interface de desenvolvimento.

Utilizar o modo de programador no Copilot Chat e Agents Toolkit

Você pode testar seu agente no Agents Toolkit no Visual Studio Code selecionando Visualizar seu aplicativo (F5) no painel Agents Toolkit. Isso inicia seu agente em uma experiência de Copilot Chat baseada em navegador, permitindo que você valide rapidamente como ele se comporta em resposta a solicitações.

Captura de ecrã de Visual Studio Code a mostrar a funcionalidade

Depois de selecionar seu agente no Microsoft 365 Copilot Chat, ative o modo de desenvolvedor digitando -developer on. Para desativar o modo de desenvolvedor, digite -developer off.

Captura de ecrã de Copilot Chat sessão em que o utilizador escreveu

Enquanto o modo de programador estiver ativado, um card com informações de depuração é devolvido sempre que o orquestrador faz pesquisas nos conhecimentos (dados), capacidades ou competências (ações ou plug-ins) da sua empresa. No Kit de Ferramentas do Agente, essas informações de depuração aparecem no painel Depurar e incluem os seguintes campos:

  • Metadados do agente: identificadores para o agente e conversação
  • Recursos: uma lista de recursos configurados para o agente, juntamente com suas estatísticas de status de execução e resposta (se executadas)
  • Ações: uma lista de ações configuradas para o agente
    • Funções correspondentes: status de funções correspondentes na pesquisa de índice de aplicações em tempo de execução
    • Funções selecionadas para execução: status de funções selecionadas para invocação com base no raciocínio do orquestrador

Secção de metadados do agente

Os metadados do agente fornecem detalhes importantes sobre o agente e a sessão de depuração atual, incluindo:

  • Resumo - Uma visão geral de alto nível das fontes de conhecimento configuradas e suas estatísticas de uso
  • ID do agente - Um identificador exclusivo para o agente, que inclui o ID do título e o ID do manifesto
  • Versão do agente – O número da versão do agente atualmente em uso
  • ID da conversação - identificador da sessão de chat ativa ou da conversação
  • ID do Pedido - Identificador do pedido específico na conversação

Captura de ecrã da sessão do Agents Toolkit em que o Copilot devolveu um card com informações de depuração a mostrar os metadados do agente

Capacidades do agente

A seção de recursos do agente exibe os recursos configurados para o agente, definindo o escopo de suas fontes de conhecimento acessíveis. Os detalhes a seguir são fornecidos para cada recurso usado pelo prompt.

  • Execução status – indica se o recurso foi usado durante a orquestração
  • Arquivo de log de diagnóstico – Um arquivo de .txt para download contendo resultados detalhados de execução, incluindo mensagens de sucesso ou falha, que pode ajudar na solução de problemas e validação

Captura de ecrã da sessão do Kit de Ferramentas do Agente em que o Copilot devolveu uma card com informações de depuração que mostram as capacidades do agente configuradas

Ações do agente

A seção Ações do agente fornece informações detalhadas sobre como as ações do agente (funções ou plug-ins) são processadas durante a orquestração. Estas informações dividem-se em três áreas principais: metadados de ação, correspondência e seleção de funções e detalhes de execução.

Captura de ecrã da sessão do Kit de Ferramentas do Agente em que o Copilot devolveu uma card com informações de depuração a mostrar as ações do agente configuradas

Metadados de ação

Esta secção apresenta informações gerais sobre as ações registadas para o seu agente. Estas informações incluem o ID da Ação (o identificador exclusivo da ação) e o número da versão (a versão da definição da ação em utilização).

Correspondência e seleção de funções

Esta parte mostra como o orquestrador interpretou o pedido do utilizador e se alguma função foi considerada relevante para a execução:

  • Funções correspondentes – Funções que correspondem semanticamente ao pedido do utilizador durante a pesquisa de índice de aplicações em tempo de execução. Se não forem devolvidas funções correspondentes para o pedido em questão, é provável que o pedido não tenha menção explicitamente o nome da ação.

  • Funções selecionadas para execução – Funções escolhidas para invocação com base no raciocínio do orquestrador e na relevância para o pedido. Se nenhuma ação foi habilitada, a seção ações indica que não há nenhuma ação habilitada.

Detalhes da execução

Os detalhes de execução da ação incluem a função e o respetivo status, juntamente com a latência, as informações do pedido (ponto final do pedido, método HTTP, cabeçalhos do pedido) e a resposta.

Resolver problemas de falhas

Seguem-se falhas comuns que poderá encontrar ao depurar o seu agente e as possíveis causas para as falhas.

Sem informações de depuração

Depois de iniciar o agente, marcar que a conexão com o navegador seja marcada como bem-sucedida no painel de depuração. Se não estiver, tente executar F5 novamente no Visual Studio Code para iniciar uma nova sessão.

Captura de ecrã da sessão do Agent Toolkit em que a ligação ao browser é efetuada com êxito

Se a ligação for bem-sucedida, mas não vir informações de depuração, pode dever-se ao facto de o orquestrador não precisar dos seus dados ou capacidades do Microsoft 365 para responder. Nenhum card de informações de depuração é retornado neste caso.

As informações de depuração também não são devolvidas em casos de limitação de capacidade, em que normalmente é apresentada uma mensagem de erro para tentar novamente mais tarde.

Informações de depuração com Sem funções selecionadas para execução

Se nenhuma função de ação corresponder à intenção de pesquisa do prompt, as informações de depuração card relatórios Nenhuma função selecionada para execução. É provável que a descrição do comando no manifesto não esteja semanticamente relacionada com a intenção de pesquisa do pedido fornecido.

Se o Copilot tiver correspondido anteriormente e executado as suas funções com êxito, os pedidos poderão ser limitados.

Depurar informações vazias ou com falha Sem detalhes de execução de função

Para plug-ins de API, se houver falha ou nenhum detalhe de execução de função, isso indica uma falha durante a tentativa do agente de atribuir parâmetros à função selecionada do plug-in. Se a falha for consistente, é mais provável que seja devido a uma ação pouco clara ou descrições de parâmetros, URLs de host inválidos ou outros problemas com sua definição de API Open.

Para plug-ins de extensão de mensagens, a melhor prática é otimizar para respostas com menos de nove segundos. Para obter mais informações, consulte os requisitos técnicos dos plug-ins de extensão de mensagens.

Atualmente, o limite de tempo limite para a execução do Copilot de uma API de plug-in está definido em 10 segundos.

Comunicar um problema

Comunique quaisquer comentários ou problemas com o seu agente utilizando os botões de polegar para cima ou polegar para baixo. Inclua a #extensibility etiqueta no seu relatório.

Captura de ecrã das opções de Copilot Chat polegar para cima ou polegar para baixo