Playground de agentes do Microsoft 365

O Agents Playground facilita a depuração de aplicativos baseados em bot ou agente. Você pode conversar com seu bot e ver suas mensagens e Cartões Adaptáveis conforme eles aparecem em diferentes canais. Você não precisa de uma conta de desenvolvedor do Microsoft 365, túnel ou registro de aplicativo cliente real e aplicativo para usar o Agents Playground.

A imagem a seguir mostra um aplicativo de exemplo exibindo um Cartão Adaptável com uma lista de comandos no Agents Playground. Ele também fornece uma descrição dos comandos para que você possa testar seu aplicativo sem pesquisar manualmente o código:

A seguir estão as vantagens do Agents Playground:

• Ambiente de sandbox: O ambiente de sandbox do Agents Playground emula o comportamento, a aparência e a experiência do usuário do real.

• Túnel: um serviço de túnel externo não é necessário, pois o Agents Playground é executado em um servidor local com o qual seu bot pode se comunicar.

• Reduzir as dependências da conta: o locatário do Microsoft 365 Developer e as permissões de upload do aplicativo não são necessárias para depurar o aplicativo.

• Iterações rápidas de loop interno: otimiza o processo de fazer alterações no design do aplicativo e na lógica do aplicativo sem precisar reimplantar o aplicativo na nuvem.

• Dados e atividades simulados: o Agents Playground facilita o teste de cenários complexos, como enviar uma mensagem de boas-vindas quando um novo membro entra no canal, usar dados fictícios e gatilhos de atividade.

• Confiável: o Agents Playground é confiável, pois o Cartão Adaptável do aplicativo utiliza a mesma tecnologia de renderização do Teams ou do WebChat.

• Integração com aplicativos existentes: o Agents Playground se integra facilmente a aplicativos existentes criados com o Agent SDK ou o SDK do Teams.

• Suporte para diferentes escopos: o Agents Playground oferece suporte a testes nos escopos de chat pessoal, de equipe e em grupo.

Pré-requisitos

Certifique-se de instalar as seguintes ferramentas para criar e implantar seus aplicativos no Agents Playground:

Entenda o Agents Playground

O Agents Playground é um pacote npm que tem um comando CLI chamado teamsapptester. Quando você executa teamsapptester starto , ele abre um aplicativo Web em seu computador local que emula o Teams ou o cliente WebChat e o serviço Bot Framework. Esse aplicativo Web não precisa de nenhum recurso de nuvem, pois usa dados fictícios para simular as informações contextuais.

Para usar um aplicativo no Agents Playground, você precisa fornecer:

• Ponto de extremidade da mensagem: um ponto de extremidade de mensagem é o URL que vincula o Agents Playground e seu aplicativo. Você pode atualizar o endpoint com a variável de ambiente, iniciar o Agents Playground com --app-endpointoption BOT_ENDPOINT ou apenas usar o valor padrão de http://localhost:3978/api/messages.
• Arquivo de configuração (opcional): um arquivo de configuração informa o Agents Playground sobre suas informações contextuais personalizadas no Teams. O arquivo é nomeado .m365agentsplayground.yml na pasta raiz do projeto. Se o Teams não conseguir encontrar esse arquivo, ele usará a configuração padrão. Para obter mais informações, consulte Personalizar o contexto do Teams.

Experiência do Agents Playground no Agents Toolkit

O Agents Playground oferece uma experiência de depuração mais rápida para aplicativos quando comparado ao ambiente real.

Gatilhos de atividade

Você pode simular uma atividade no Agents Playground usando gatilhos de atividade. Existem dois tipos de gatilhos de atividade:

1. Gatilhos de atividade predefinidos
2. Gatilhos de atividade personalizados

Gatilhos de atividade predefinidos

O Agents Playground fornece gatilhos de atividade predefinidos para testar as funcionalidades do seu aplicativo.

Os gatilhos de atividade predefinidos estão disponíveis no menu Simular uma atividade no Agents Playground.

Para simular Adicionar atividade do usuário , siga estas etapas:

1. No Agents Playground, vá para Simular uma atividade e selecione Adicionar usuário.

   

   Uma janela pop-up é exibida para visualizar o manipulador de atividades.

2. Selecione Enviar atividade.

   

   O aplicativo envia uma resposta.

   

Gatilhos de atividade personalizados

Você pode usar a atividade personalizada para personalizar gatilhos de atividade, como , reactionsAddedpara atender aos requisitos do seu aplicativo de bot. O Agents Playground preenche automaticamente as propriedades necessárias da atividade. Você também pode modificar o tipo de atividade e adicionar mais propriedades.

1. Selecione Simular uma atividade>personalizada.

   

2. Adicione messageReaction para personalizar a atividade na propriedade type e invocar a atividade personalizada.

   {
     "type": "messageReaction",
     "reactionsAdded": [
       {
         "type": "like"
       }
     ],
     "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
   }
   

3. Selecione Enviar atividade.

   

   O bot envia um onReactionsAdded manipulador em resposta.

   

Configurar o Agents Playground para autenticação

Ao depurar um aplicativo que requer autenticação, você pode configurar a ID do cliente e o segredo do cliente do Microsoft Entra, com uma ID de locatário opcional. Se você criou seu bot usando o Serviço de Bot de IA do Azure, as credenciais estarão disponíveis no Serviço de Aplicativo do bot emConfiguração de Configurações>. Se você não tiver certeza dos valores, poderá removê-los do arquivo de configuração do aplicativo em execução local e, em seguida, executar o aplicativo no Agents Playground. Se o aplicativo não exigir que essas configurações sejam executadas, você não precisará defini-las.

Variável de ambiente/Linha de comando

Antes de iniciar o Agents Playground, você pode definir as seguintes variáveis de ambiente: AUTH_CLIENT_ID, AUTH_CLIENT_SECRETe AUTH_TENANT_ID. Esses valores são usados para a configuração de autenticação padrão.

Ao executar o Agents Playground na linha de comando, você também pode usar as opções: --client-id, --client-secret, e --tenant-id. Essas opções substituem as configurações de variável de ambiente padrão.

Interface do lado do cliente

Depois que o Agents Playground for iniciado, você ainda poderá configurar a autenticação por meio da interface do cliente da seguinte maneira:

1. Selecione Configurar Autenticação.

   

2. Preencha os campos no formulário e selecione Salvar.

   

O painel de log mostra a mensagem se a configuração foi definida com êxito.

Lógica de autenticação

O Agents Playground adquire um token JWT usando as configurações de autenticação fornecidas e o inclui no cabeçalho Authorization ao se comunicar com o aplicativo. O token JWT no cabeçalho de resposta do aplicativo também é validado pelo Agents Playground. Para obter mais detalhes sobre o processo de autenticação, consulte Autenticação com a API do Bot Connector.

Suporte a vários canais

Quando você executa o Agents Playground como uma ferramenta autônoma, o Microsoft Teams (msteams) é usado como o canal padrão. Quando o playground é iniciado por meio do Microsoft 365 Agents Toolkit, o canal padrão é emulator. Você pode alterar o canal definindo a DEFAULT_CHANNEL_ID variável de ambiente ou usando a --channel-id opção ao iniciar o Agents Playground na linha de comando.

Atualmente, as IDs de canal aceitas são: msteams, directline, webchate emulator. Quando você define uma ID de canal, as propriedades das mensagens enviadas ao aplicativo são alteradas de acordo para simular um ambiente real. Para os directline canais andwebchat, um cliente correspondente é exibido e a renderização do card difere da do canal do Teams.

Personalizar o contexto do Teams

O arquivo de configuração na pasta raiz do projeto permite que você personalize as informações de contexto do Teams, como chats, equipes e usuários. Ele fornece dados fictícios para testar APIs ou métodos do Bot Framework do SDK do Agents ou do SDK do Teams, como TeamsInfo.getTeamMembers.

Configuração padrão

O Agents Playground contém um arquivo de configuração integrado na pasta raiz do projeto.

# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.1/config.schema.json
# Visit https://aka.ms/teams-app-test-tool-config-guide for more details on this file.

# This configuration file customizes the Teams context information like chats, teams, and users.
# It contains mock data for testing Bot Framework APIs or Bot Builder SDK methods such as TeamsInfo.getTeamMembers().
# You can customize this file to change API response if your bot code uses these APIs.
version: "0.1.1"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
  id: 00000000-0000-0000-0000-00000000000011
  name: Test Bot
  agenticAppId: 00000000-0000-0000-0000-000000000100
  agenticUserId: agentic-user-id
  tenantId: 00000000-0000-0000-0000-000000000001
  role: agenticUser
currentUser:
  id: user-id-0
  name: Alex Wilber
  userPrincipleName: alexw@example.com
  aadObjectId: 00000000-0000-0000-0000-0000000000020
  givenName: Alex
  surname: Wilber
  email: alexw@example.com
users:
  - id: user-id-1
    name: Megan Bowen
    userPrincipleName: meganb@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000021
    givenName: Megan
    surname: Bowen
    email: meganb@example.com
  - id: user-id-2
    name: Adele Vance
    userPrincipleName: adelev@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000022
    givenName: Adele
    surname: Vance
    email: adelev@example.com
  - id: user-id-3
    name: Isaiah Langer
    userPrincipleName: isaiah@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000023
    givenName: Isaiah
    surname: Langer
    email: isaiahl@example.com
  - id: user-id-4
    name: Patti Fernandez
    userPrincipleName: pattif@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000024
    givenName: Patti
    surname: Fernandez
    email: pattif@example.com
  - id: user-id-5
    name: Lynne Robbins
    userPrincipleName: lynner@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000025
    givenName: Lynne
    surname: Robbins
    email: lynner@example.com
personalChat:
  id: personal-chat-id
groupChat:
  id: group-chat-id
  name: Group Chat
team:
  id: team-id
  name: My Team
  aadGroupId: 00000000-0000-0000-0000-000000000031
  channels:
    - id: channel-announcements-id
      name: Announcements

Personalizar o arquivo de configuração

Se o código do bot usar APIs do Bot Framework, você poderá modificar o arquivo de configuração para personalizar as respostas da API. Por exemplo, considere um bot de notificação do DevOps do Azure instalado em uma equipe que busca bugs inativos do DevOps do Azure. Ele identifica os proprietários dos bugs inativos, recupera seus endereços de email e envia notificações diárias para seus chats pessoais.

Para testar de forma abrangente esse bot no Agents Playground, atualize o arquivo de configuração com os endereços de e-mail corretos dos proprietários de bugs inativos.

1. Crie um arquivo nomeado .m365agentsplayground.yml na pasta raiz do projeto.

2. Copie a configuração padrão de dados fictícios e cole-a no .m365agentsplayground.yml arquivo.

3. Vá para a users seção e atualize o name, userPrincipleNamee email do usuário necessário.

   users:
       - id: user-id-1
         name: Megan Bowen
         userPrincipleName: meganb@example.com
         aadObjectId: 00000000-0000-0000-0000-0000000000021
         givenName: Megan
         surname: Bowen
         email: some-real-user@real-domain.onmicrosoft.com
   

4. Salve o arquivo e selecione F5 para depurar no Agents Playground.

É importante entender que a atualização do arquivo de configuração tem três impactos principais:

• Ele afeta as respostas retornadas pelas APIs do Bot Framework Connector. Por exemplo, TeamsInfo.getPagedMembers().
• Ele modifica os detalhes no conteúdo da atividade. Por exemplo, activity.recipient.
• Isso influencia a interface do usuário no Agents Playground. Por exemplo, nomes de chat de grupo.

Limitações

• Os recursos de bot ou agente habilitados por meio do manifesto do aplicativo Teams não estão disponíveis, pois o Agents Playground não os processa.

• O Agents Playground não dá suporte a todos os tipos de cartões, exceto Cartões Adaptáveis.

• O Agents Playground não oferece suporte aos seguintes recursos do Cartão Adaptável:

  • Pesquisa de digitação antecipada
  • Menção do usuário
  • Stageview
  • Largura total

• O Agents Playground não oferece suporte às seguintes experiências:

  • Dispositivo móvel
  • Reunião

• O Agents Playground pode emular as seguintes experiências:

  Recursos	Depurar no Agents Playground	Depurar seu aplicativo localmente
  Envio / recebimento básico de mensagens	Disponível	Disponível
  APIs do Bot Framework (TeamsInfo.getPagedMembers()...)	Disponível (responder com dados simulados)	Disponível
  Envio de eventos do Teams	Disponível (atividade simulada)	Disponível
  Indicador de digitação	Não disponível	Disponível
  Guia, Extensão de mensagem, Diálogos (chamados de módulos de tarefa no TeamsJS v1.x), Logon Único (SSO) e Cartões não Adaptáveis	Não disponível	Disponível

Depurar um aplicativo existente com o Agents Playground

Certifique-se de ter um aplicativo existente criado usando o Agents Toolkit. Para depurar seu aplicativo com o Agents Playground, siga estas etapas:

1. Abra a pasta do projeto do bot existente no Kit de Ferramentas de Agentes.

2. Vá para EXPLORER.vscode>.

3. Selecione launch.json e adicione o seguinte código ao final do arquivo:

   // .vscode/launch.json 
   
   { 
       ... 
       "compounds": [ 
           ... 
           { 
               "name": "Debug in Microsoft 365 Agents Playground", 
               "configurations": [ 
                   "Attach to Local Service" 
               ], 
               "preLaunchTask": "Start App in Microsoft 365 Agents Playground", 
               "presentation": { 
                   "group": "1-local", 
                   "order": 1 
               }, 
               "stopAll": true 
           }, 
       ] 
   } 
   

4. Acesse tasks.json e adicione o seguinte código ao final do arquivo:

       { 
         "label": "Start Microsoft 365 Agents Playground", 
         "type": "shell", 
         "command": "npm run dev:teamsfx:launch-playground", 
         "isBackground": true, 
         "options": { 
           "env": { 
             "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin:${env:PATH}" 
           } 
         }, 
         "windows": { 
           "options": { 
             "env": { 
               "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin;${env:PATH}" 
             } 
           } 
         }, 
         "problemMatcher": { 
           "pattern": [ 
             { 
               "regexp": "^.*$", 
               "file": 0, 
               "location": 1, 
               "message": 2 
             } 
           ], 
           "background": { 
             "activeOnStart": true, 
             "beginsPattern": ".*", 
             "endsPattern": "Listening on" 
           } 
         }, 
         "presentation": { 
           "panel": "dedicated", 
           "reveal": "silent" 
         } 
       }, 
     ],
   }
   

5. Em EXPLORER, crie um arquivo .localConfigs.playground e adicione o seguinte código:

   // .localConfigs.playground
   # A gitignored place holder file for local runtime configurations when debug in Agents Playground
   BOT_ID=
   BOT_PASSWORD=
   TEAMSFX_NOTIFICATION_STORE_FILENAME=.notification.playgroundstore.json
   

6. Vá para o EXPLORER>env.

7. Crie um arquivo .env.playground e adicione o seguinte código:

   // .env.playground
   # This file includes environment variables that can be committed to git. It's gitignored by default because it represents your local development environment
   # Built-in environment variables
   TEAMSFX_ENV=playground
   # Environment variables used by Agents Playground
   TEAMSAPPTESTER_PORT=56150
   

8. Se você tiver variáveis de ambiente personalizadas, defina seus valores em .env.playground ou .env.playground.user.

9. Adicione uma chave OpenAI ou uma chave OpenAI do Azure e um ponto de extremidade em .env.playground.user.

   # SECRET_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_API_KEY=***********
   SECRET_AZURE_OPENAI_ENDPOINT=<https://your-openai-service-name.openai.azure.com/>
   

10. Acesse package.json e adicione o seguinte código à scripts propriedade:

    "scripts": {
        ... 
        "dev:teamsfx:playground": "env-cmd --silent -f .localConfigs.playgroundnd npm run dev", 
        "dev:teamsfx:launch-playground": "env-cmd --silent -f env/.env.playground teamsapptester start", 
        ... 
    },
    

11. No painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D) e selecione Depurar no Microsoft 365 Agents Playground na lista suspensa.

    

O Agents Playground depura com êxito o bot existente.

Desativando a coleta de dados

Se você decidir que não deseja permitir que o Agents Playground colete dados de uso, poderá desativar facilmente a coleta de dados adicionando uma opção --disable-telemetry ao iniciar o Agents Playground por meio da linha de comando.

Perguntas frequentes

Exemplo de código

Guias passo a passo

Siga o guia passo a passo para depurar um chat bot de IA usando o Agents Playground.

Confira também

• Visão geral do Kit de Ferramentas de Agentes do Microsoft 365
• Instalar o Kit de Ferramentas de Agentes do Microsoft 365
• Criar bots para o Teams
• Teams SDK
• Cartão Adaptável
• SDK de agentes