Compartilhar via

Aplicação de extensão de mensagem de depuração no Microsoft 365 Agents Playground

Pode depurar capacidades de extensão de mensagens baseadas em bots, tais como comandos de pesquisa, comandos de ação e desfraldamento de ligações com o Agents Playground (anteriormente conhecido como Ferramenta de Teste de Aplicações do Teams) num ambiente simulado. A ferramenta de teste ajuda-o a identificar e resolve problemas antes de implementar a extensão num ambiente ativo.

Agents Playground melhora a funcionalidade das extensões de mensagens baseadas em bot, que são criadas com base no Bot Framework. Quando uma extensão de mensagem é ativada, o Agents Playground envia um pedido de invocação para a aplicação. Em seguida, a aplicação processa este pedido e devolve uma resposta de invocação, que o Agents Playground compõe e apresenta.

Observação

A experiência do utilizador para acionar a extensão de mensagens no Ambiente de Trabalho dos Agentes é diferente do Teams, uma vez que o objetivo do Agents Playground é testar e depurar a lógica da aplicação e simplificar o fluxo.

Pré-requisitos

Certifique-se de que instala as seguintes ferramentas para criar e implementar o bot no Agents Playground:

  Instalar Para usar...
  Toolkit de Agentes do Microsoft 365 Uma extensão do Microsoft Visual Studio Code que cria um projeto estruturado para a sua aplicação. Utilize a versão de versão mais recente.
  Node.js Ambiente de runtime do JavaScript de back-end. Para obter mais informações, veja Node.js tabela de compatibilidade de versões para o tipo de projeto.
  Visual Studio Code Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Utilize a versão mais recente.

Criar e executar a aplicação de exemplo

  1. Aceda ao exemplo.

  2. Clone o repositório para testar a aplicação de exemplo.

    git clone https://github.com/OfficeDev/microsoft-365-agents-toolkit-samples.git

  3. Aceda a Visual Studio Code.

  4. SelecioneAbrir Pasta de Ficheiros>.

  5. Aceda à localização onde clonou o repositório teamsFx-samples e selecione a pasta test-tool-sample-app .

  6. Selecione Selecionar Pasta.

    Captura de ecrã a mostrar a pasta da aplicação de exemplo Agents Playground.

  7. No painel esquerdo, selecione Microsoft 365 Agents Toolkit.

  8. No painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D) e selecione Depurar no Ambiente de Trabalho dos Agentes do Microsoft 365 (Pré-visualização) na lista pendente.

  9. Agents Playground abre o bot numa página Web.

    Captura de ecrã a mostrar que o Ambiente de Trabalho dos Agentes é aberto numa página Web.

  10. Na área de composição da mensagem, escreva help. Agents Playground apresenta todos os comandos de extensão de mensagem na aplicação de exemplo.

    Captura de ecrã a mostrar a ajuda na área de composição de mensagens do Ambiente de Trabalho dos Agentes.

  11. Selecione o + ícone para apresentar o tipo de extensão de mensagem:

    • Comando de Pesquisa

    • Comando de Ação

    • Desfraldamento da Ligação

    Captura de ecrã a mostrar a lista de extensões de mensagens.

  12. Selecione o tipo de extensão de mensagem que pretende depurar.

  13. Com base na opção selecionada no passo anterior, selecione o seguinte separador:

    Comando de Pesquisa

    Para testar um Comando de Pesquisa no Playground de Agentes, siga estes passos:

    1. Introduza as palavras-chave que pretende procurar na extensão da mensagem.

    2. Agents Playground envia um pedido de composeExtension/query invocação.

      Captura de ecrã a mostrar os comandos de pesquisa invocados.

    3. Os resultados da pesquisa são apresentados.

    4. Para rever os detalhes do pedido e os resultados, marcar o Painel de Registos.

    Para cenários que requerem configurações mais avançadas:

    1. Selecione o + ícone na área de composição de mensagens.

    2. Selecione Comando de Pesquisa.

    3. Selecione Especificar ID de Comando ou Parâmetro.

    4. Atualize os valores de ID de Comando e Nome do parâmetro.

      Captura de ecrã a mostrar o comando de pesquisa para configurações avançadas.

    5. Quando a extensão da mensagem é acionada, obtém estes valores predefinidos a partir do contexto.

    Observação

    Não é obrigatório incluir o ID de comando ou o nome do parâmetro para testar a extensão da mensagem. Adicione-as se precisar de testar a funcionalidade.

    Comando de Ação

    Pode testar um Comando de Ação no Ambiente de Trabalho dos Agentes das seguintes formas:

    1. Selecione o + ícone na área de composição de mensagens.

    2. Selecione Comando de Ação.

      Captura de ecrã a mostrar o comando de ação.

Detetei um problema

Pode criar uma caixa de diálogo com um Comando de Ação de duas formas:

Caixa de diálogo Criar com Cartões Ajustáveis

Na caixa de diálogo da extensão de mensagem baseada em ação, selecione Cartões Ajustáveis. Agents Playground obtém dinamicamente a caixa de diálogo da extensão da mensagem. Envia um composeExtension/fetchTask pedido de invocação e, em seguida, apresenta o Cartão Ajustável com base na resposta recebida da aplicação.

Captura de ecrã a mostrar como criar caixa de diálogo com Cartões Ajustáveis.

Caixa de diálogo Criar com lista estática de parâmetros

Na caixa de diálogo da extensão de mensagem baseada em ação, selecione Lista estática de parâmetros. Agents Playground compõe os parâmetros que forneceu numa caixa de diálogo. Para obter mais informações sobre parâmetros, veja composeExtensions.commands.

O código seguinte é um exemplo da lista estática de parâmetros no formato JSON:

[{
  "name": "title",
  "title": "Card title",
  "description": "Title for the card",
  "inputType": "text"
},
{
  "name": "subTitle",
  "title": "Subtitle",
  "description": "Subtitle for the card",
  "inputType": "text"
},
{
  "name": "text",
  "title": "Text",
  "description": "Text for the card",
  "inputType": "textarea"
}]

Captura de ecrã a mostrar como criar uma lista estática de parâmetros no ambiente de trabalho dos agentes.

A lista estática de parâmetros está disponível na composeExtensions propriedade no manifesto da aplicação. Por exemplo, veja manifest.json.

Submeter formulário dentro da caixa de diálogo

Depois de criar uma caixa de diálogo com Cartões Ajustáveis ou uma lista estática de parâmetros e selecionar submeter, o Agents Playground envia um pedido de invocação com o nome de composeExtension/submitAction.

Com base na resposta de invocação da extensão de mensagem, o Agents Playground efetua uma das seguintes ações:

  • Compõe um Cartão Ajustável a partir da resposta de invocação e insere-o na área de composição de mensagens.

  • Compõe um Cartão Ajustável a partir da resposta de invocação dentro da caixa de diálogo. Isto é útil quando o formulário é extenso e precisa de ser dividido em vários cartões.

  • Apresenta uma mensagem de texto simples da resposta de invocação dentro da caixa de diálogo.

Observação

Não é obrigatório incluir o ID de comando para testar a extensão da mensagem. Adicione-as se precisar de testar a funcionalidade.

Para testar uma Ligação Desfraldado no Parque Desfraldamento de Agentes, siga estes passos:

  1. Selecione o + ícone na área de composição de mensagens.

  2. Selecione Desfraldar Ligação.

    Captura de ecrã a mostrar como criar uma ligação a desenrolar-se no ambiente de trabalho dos agentes.

    É apresentada uma caixa de diálogo Introduzir um URL .

  3. Na caixa de diálogo Introduzir um URL , introduza um URL à sua escolha.

  4. Selecione Enviar para Conversação.

    Captura de ecrã a mostrar como criar uma ligação a desenrolar-se no ambiente de trabalho dos agentes.

    O Agents Playground aciona um composeExtension/queryLink pedido de invocação com o URL para a extensão da mensagem. Pode rever o Cartão Ajustável que o Agents Playground compõe com base na resposta de invocação da aplicação.

Observação

A experiência do utilizador para testar a desfraldamento da ligação no Ambiente de Trabalho dos Agentes difere da experiência no Teams. No entanto, ainda pode testar ou depurar a lógica da aplicação com o Agents Playground de uma forma simples.

Detetei um problema

Limitações

A tabela seguinte lista as funcionalidades para cada tipo de extensão de mensagem que não são suportadas:

Tipo de extensão de mensagem Funcionalidades não suportadas
Comando de Pesquisa Acionar a partir da caixa de comandos.
Esquema de grelha para resultados de pesquisa.
Enviar a composeExtension/selectItem atividade de invocação quando um item dos resultados da pesquisa é selecionado.
Paginação para resultados de pesquisa adicionais.
Comando de Ação Acionar a partir da caixa de comandos.
Criar uma caixa de diálogo com a vista Web incorporada.
Compor a atividade de invocação botMessagePreview .
Desfraldamento da Ligação Compor a pré-visualização card a partir da resposta de invocação.
Enviar atividade de invocação de para zero casos de composeExtension/anonymousQueryLink instalação.

FAQ sobre a extensão de mensagens Agents Playground


Como posso utilizar as propriedades "commandId" ou "parameters.name" para um Comando de Pesquisa no Ambiente de Trabalho dos Agentes?

Quando utiliza a caixa de pesquisa numa extensão de mensagem baseada em pesquisa no Teams, a sua aplicação recebe uma atividade de invocação que inclui dois parâmetros. Por vezes, a sua aplicação poderá ter de utilizar activity.value.commandId ou activity.value.parameters[0].name gerir diferentes comportamentos de comandos de pesquisa no processador de atividades para a composeExtension/query atividade de invocação, como o handleTeamsMessagingExtensionQuery método no SDK do Bot Framework para JavaScript. No entanto, a sua aplicação não precisa dela porque o Teams só suporta um único comando de pesquisa e pode deixá-los vazios.

Se a sua aplicação utilizar estes dois parâmetros, pode fornecer entradas adicionais ao selecionar Specify Command ID or Parameter e atualizar os valores necessários. Agents Playground inclui estes parâmetros no payload de atividade de invocação durante uma pesquisa. Se não os especificar, o payload evita estes parâmetros.

Captura de ecrã a mostrar o ID de comando especificado ou o Parâmetro.

No Teams, os parâmetros estão disponíveis no manifesto da aplicação. Uma vez que o Agents Playground não processa o manifesto, tem de introduzir os parâmetros manualmente.



Como posso utilizar a propriedade "commandId" para um Comando de Ação no Ambiente de Trabalho dos Agentes?

No Teams, as caixas de diálogo são acionadas a partir de comandos de ação e a sua aplicação recebe uma composeExtension/fetchTask atividade ou composeExtension/submitAction invoca. Esta atividade inclui o activity.value.commandId parâmetro . No entanto, a sua aplicação utiliza este parâmetro para diferenciar entre comandos no processador de atividades para estas atividades de invocação, como os handleTeamsMessagingExtensionFetchTask métodos ou handleTeamsMessagingExtensionSubmitAction no SDK do Bot Framework para JavaScript.

Para testar vários comandos de ação, tem de introduzir o Command ID no respetivo campo. Se não atualizar, os IDs de comando não serão incluídos no payload da atividade.

Captura de ecrã a mostrar o parâmetro ID do comando no Comando de Ação.

No Teams, os comandos estão disponíveis no manifesto da aplicação. Uma vez que o Agents Playground não processa o manifesto, tem de introduzir os comandos manualmente.



Como funciona uma lista estática de parâmetros no Agents Playground?

A lista estática de parâmetros é o método simples para criar caixas de diálogo para comandos de ação. No entanto, não pode formatar a lista estática.

Quando cria uma caixa de diálogo com uma lista estática de parâmetros, a extensão da mensagem recebe uma composeExtension/submitAction atividade de invocação após a submissão do utilizador da caixa de diálogo.

Captura de ecrã a mostrar a lista estática do parâmetro no Comando de Ação.

No Teams, os parâmetros estão disponíveis no manifesto da aplicação. Uma vez que o Agents Playground não processa o manifesto, tem de introduzir os parâmetros manualmente.


Confira também