Ambiente de Trabalho dos Agentes do Microsoft 365

Observação

O Microsoft 365 Agents Playground (anteriormente conhecido como Ferramenta de Teste de Aplicações do Teams) está disponível na versão de pré-lançamento mais recente do Microsoft 365 Agents Toolkit (anteriormente conhecido como Teams Toolkit). Certifique-se de que instala a versão de pré-lançamento mais recente do Toolkit de Agentes.

O Agents Playground facilita a depuração de bots ou aplicações baseadas em agentes. Pode conversar com o bot e ver as respetivas mensagens e Cartões Ajustáveis à medida que aparecem em canais diferentes. Não precisa de uma conta de programador do Microsoft 365, túnel ou registo de aplicações e aplicações cliente reais para utilizar o Agents Playground.

A imagem seguinte mostra uma aplicação de exemplo a apresentar um Cartão Ajustável com uma lista de comandos no Agents Playground. Também fornece uma descrição dos comandos para que possa testar a sua aplicação sem procurar manualmente o seu código:

Captura de ecrã a mostrar o Cartão Ajustável Do Ambiente de Trabalho dos Agentes.

Seguem-se as vantagens do Ambiente de Trabalho dos Agentes:

Ambiente sandbox: o ambiente sandbox do Agents Playground emula o comportamento, o aspeto e a experiência do utilizador do verdadeiro.
Túnel: um serviço de túnel externo não é necessário, uma vez que o Agents Playground é executado num servidor local com o qual o bot pode comunicar.
Reduzir dependências de conta: o inquilino do Programador do Microsoft 365 e as permissões de carregamento da aplicação não são necessárias para depurar a aplicação.
Iterações rápidas do ciclo interno: otimiza o processo de efetuar alterações à estrutura da aplicação e à lógica da aplicação sem ter de reimplementar a aplicação na cloud.
Dados e atividades fictícios: o Agents Playground facilita o teste de cenários complexos, como enviar uma mensagem de boas-vindas quando um novo membro se junta ao canal, através de dados fictícios e acionadores de atividade.
Fiável: o Agents Playground é fiável, uma vez que o Cartão Ajustável da aplicação utiliza a mesma tecnologia de composição que no Teams ou No WebChat.
Integração com aplicações existentes: o Agents Playground integra-se facilmente com aplicações existentes criadas com o SDK do Agente ou o SDK do Teams.
Suporte para diferentes âmbitos: o Agents Playground suporta testes em âmbitos de chat pessoais, de equipa e de grupo.

Pré-requisitos

Certifique-se de que instala as seguintes ferramentas para criar e implementar as suas aplicações no Agents Playground:

	Instalar	Para usar...
	Toolkit de Agentes	Uma extensão do Microsoft Visual Studio Code que cria um projeto estruturado para a sua aplicação. Utilize a versão de pré-lançamento 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.

Compreender o Playground de Agentes

Agents Playground é um pacote npm que tem um comando da CLI chamado teamsapptester. Quando executa teamsapptester starto , abre uma aplicação Web no seu computador local que emula o cliente teams ou WebChat e o serviço Bot Framework. Esta aplicação Web não precisa de recursos na cloud, uma vez que utiliza dados fictícios para simular as informações contextuais.

Para utilizar uma aplicação no Agents Playground, tem de fornecer:

Ponto final da mensagem: um ponto final de mensagem é o URL que liga Os Agentes Playground e a sua aplicação. Pode atualizar o ponto final com a variável de ambiente, iniciar o BOT_ENDPOINT Agents Playground com a opção --app-endpointou utilizar apenas o valor predefinido de http://localhost:3978/api/messages.
Ficheiro de configuração (Opcional): um ficheiro de configuração informa o Agents Playground sobre as suas informações contextuais personalizadas no Teams. O ficheiro tem o nome .m365agentsplayground.yml na pasta raiz do projeto. Se o Teams não conseguir localizar este ficheiro, utiliza a configuração predefinida. Para obter mais informações, veja Personalizar o contexto do Teams.

Agents Playground experience in Agents Toolkit

O Agents Playground oferece uma experiência de depuração mais rápida para aplicações em comparação com o ambiente real.

Visual Studio Code
Linha de comando

Abra o Visual Studio Code.
Selecione o ícone do Toolkit de Agentes do Microsoft 365 na Barra de Atividade do Visual Studio Code.
Selecione Criar um Novo Agente/Aplicação.
Selecione Agente para o Teams.
Selecione Agente Geral do Teams para criar um agente. Se precisar de uma funcionalidade diferente para o agente, escolha uma opção diferente.
Selecione Azure OpenAI e introduza a chave de serviço. Se estiver a utilizar o OpenAI, escolha uma opção diferente.
Selecione JavaScript.
Selecione Pasta predefinida.

Para alterar a localização predefinida, siga estes passos:
1. Selecione Procurar.
2. Selecione a localização da área de trabalho do projeto.
3. Selecione Selecionar Pasta.
Introduza um nome adequado para a sua aplicação e, em seguida, selecione a tecla Enter .

É apresentada uma caixa de diálogo onde tem de escolher sim ou não para confiar nos autores dos ficheiros nesta pasta.
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.
Agents Playground abre a aplicação numa página Web.

Detetei um problema

Pode utilizar a linha de comandos para JavaScript e TypeScript ou C# para depurar a sua aplicação no Agents Playground. Para começar, selecione o seguinte idioma:
- JavaScript/TypeScript
- C#
1. Execute o seguinte comando para instalar a CLI do Playground de Agentes a partir do npm:
```
npm i @microsoft/m365agentsplayground
```
2. Utilize o atk comando da CLI do Toolkit de Agentes do Microsoft 365 (anteriormente conhecido como CLI do Teams Toolkit) para criar o seu primeiro projeto. Inicie pela pasta onde deseja criar a pasta do projeto.
```
atk new   
```
  Pode utilizar a CLI para criar uma nova aplicação do Teams. A CLI dá-lhe uma série de perguntas. Utilize as teclas de seta para selecionar uma opção. Depois de fazer uma escolha, selecione Enter para confirmar. Depois de introduzir um nome adequado para a sua aplicação, o projeto é criado.
3. Execute o seguinte comando para implementar a sua aplicação e instalar as dependências necessárias e os pacotes npm:
```
atk deploy --env=playground
```
4. Execute o seguinte comando para iniciar a sua aplicação:
```
npm run dev:teamsfx:testtool
```
5. Execute o seguinte comando num terminal separado para iniciar o Agents Playground:
```
npm run dev:teamsfx:launch-testtool
```
1. Criar uma nova aplicação.
2. Transfira a CLI do Playground dos Agentes a partir da versão do GitHub .
3. Deszipe o pacote transferido para uma pasta. Encontrará um ficheiro teamsapptester.exebinário executável .
4. Copie o teamsapptester.exe ficheiro para a pasta onde criou a sua aplicação.
5. Abra a linha de comandos e aceda à pasta onde criou a sua aplicação.
6. Execute o seguinte comando para iniciar o perfil:
```
dotnet run --launch-profile "Microsoft 365 Agents Playground (browser)"
```
7. Execute o seguinte comando num terminal separado para definir o ponto final da mensagem do bot:
  1. Para a Linha de Comandos:
    
    set BOT_ENDPOINT=http://127.0.0.1:5130/api/messages
  2. Para o PowerShell:
    
    $env:BOT_ENDPOINT = "http://127.0.0.1:5130/api/messages"
8. Execute o seguinte comando para iniciar o Agents Playground:
  1. Para a Linha de Comandos:
    
    teamsapptester.exe start
  2. Para o PowerShell:
    
    teamsapptester.exe start
  Se o Agents Playground para C# não iniciar devido a um conflito de porta, altere o número de porta do Agents Playground na TEAMSAPPTESTER_PORT variável de ambiente onde executa teamsapptester.exe start.
1. Agents Playground abre a aplicação numa página Web.

Detetei um problema

Acionadores de atividade

Pode simular uma atividade no Ambiente de Trabalho dos Agentes através de acionadores de atividade. Existem dois tipos de acionadores de atividade:

Acionadores de atividade predefinidos
Acionadores de atividade personalizados

Acionadores de atividade predefinidos

O Agents Playground fornece acionadores de atividade predefinidos para testar as funcionalidades da sua aplicação.

Categoria	Atividade	Manipulador
Atividade de Atualização da Instalação do Acionador	Instalar aplicação Desinstalar aplicação	`onInstallationUpdate` `onInstallationUpdateAdded` `onInstallationUpdate` `onInstallationUpdateRemove`
Acionar Atividade de Atualização de Conversação	Adicionar usuário Adicionar aplicação Adicionar canal	`onMembersAdded` `onTeamsMembersAddedEvent` `onTeamsChannelRenamedEvent`
	Remover usuário Remover aplicação Remover canal Remover equipa	`onMembersRemoved` `onTeamsMembersRemovedEvent` `onMembersRemoved` `onTeamsMembersRemovedEvent` `onTeamsChannelDeletedEvent` `onTeamsTeamDeletedEvent`
	Mudar o nome do canal Mudar o nome da equipa	`onTeamsChannelRenamedEvent` `onTeamsTeamRenamedEvent`

Observação

Todos os tipos de atividades não estão disponíveis em todos os âmbitos. Por exemplo, não pode adicionar ou remover um canal numa conversa pessoal ou numa conversa de grupo.

Os acionadores de atividade predefinidos estão disponíveis no menu Simular uma Atividade no Ambiente de Trabalho dos Agentes.

Para simular uma atividade Adicionar utilizador , siga estes passos:

No Ambiente de Trabalho dos Agentes, aceda a Simular uma Atividade e selecione Adicionar utilizador.

É apresentada uma janela de pop-up para pré-visualizar o processador de atividades.
Selecione Enviar atividade.

A aplicação envia uma resposta.

Acionadores de atividade personalizados

Pode utilizar a Atividade personalizada para personalizar acionadores de atividade, como, por exemplo, reactionsAdded, para se ajustar aos requisitos da sua aplicação de bot. O Agents Playground preenche automaticamente as propriedades necessárias da atividade. Também pode modificar o tipo de atividade e adicionar mais propriedades.

Selecione Simular uma>Atividade Atividade Personalizada.

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"
}

Selecione Enviar atividade.

O bot envia um onReactionsAdded processador em resposta.

Configurar o Playground de Agentes para autenticação

Ao depurar uma aplicação que requer autenticação, pode configurar o ID de cliente Microsoft Entra e o segredo do cliente, com um ID de inquilino opcional. Se tiver criado o bot com o Serviço de Bot de IA Azure, as credenciais estão disponíveis no Serviço de Aplicativo do bot em Configuração de Definições>. Se não tiver a certeza dos valores, pode removê-los do ficheiro de configuração da aplicação em execução local e, em seguida, executar a aplicação no Ambiente de Trabalho dos Agentes. Se a aplicação não precisar que estas definições sejam executadas, não precisa de as configurar.

Variável de ambiente/Linha de comandos

Antes de iniciar o Playground dos Agentes, pode definir as seguintes variáveis de ambiente: AUTH_CLIENT_ID, AUTH_CLIENT_SECRETe AUTH_TENANT_ID. Estes valores são utilizados para a configuração de autenticação predefinida.

Ao executar o Agents Playground a partir da linha de comandos, também pode utilizar as opções: --client-id, --client-secrete --tenant-id. Estas opções substituem as definições de variáveis de ambiente predefinidas.

Interface do lado do cliente

Após o início do Agents Playground, ainda pode configurar a autenticação através da interface de cliente da seguinte forma:

Selecione Configurar Autenticação.
Preencha os campos no formulário e selecione Guardar.

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

Captura de ecrã a mostrar a mensagem do painel de registo de configuração com êxito das definições de autenticação.

Lógica de autenticação

O Agents Playground adquire um token JWT com as definições de autenticação fornecidas e inclui-o no cabeçalho Autorização ao comunicar com a aplicação. O token JWT no cabeçalho de resposta da aplicação também é validado pelo Agents Playground. Para obter mais detalhes sobre o processo de autenticação, veja Authentication with the Bot Connector API (Autenticação com a API do Conector do Bot).

Suporte de vários canais

O Teams é o canal predefinido utilizado para depurar a sua aplicação, mas também são suportados outros canais. Pode alterar o canal ao definir a DEFAULT_CHANNEL_ID variável de ambiente ou ao utilizar a opção --channel-id ao iniciar o Agents Playground a partir da linha de comandos.

Atualmente, os IDs de canal aceites são: msteams, directline, webchate emulator. Quando define um ID de canal, as propriedades das mensagens enviadas para a aplicação são alteradas em conformidade para simular um ambiente real. Para os directline canais ewebchat, é apresentado um cliente correspondente e card composição difere da do canal do Teams.

Captura de ecrã a mostrar a card resultado de composição ao utilizar um canal diferente.

Personalizar o contexto do Teams

O ficheiro de configuração na pasta raiz do projeto permite-lhe personalizar informações de contexto do Teams, como conversas, equipas e utilizadores. Fornece dados fictícios para testar as APIs do Bot Framework ou métodos do SDK do Agente ou do SDK do Teams, como TeamsInfo.getTeamMembers.

Configuração padrão

Agents Playground contém um ficheiro de configuração incorporado na pasta raiz do projeto.

# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.0/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.0"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
  id: 00000000-0000-0000-0000-00000000000011
  name: Test Bot
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

Atualizar o ficheiro de configuração

Se o código do bot utilizar AS APIs do Bot Framework, pode modificar o ficheiro de configuração para personalizar as respostas da API. Por exemplo, considere um Azure bot de notificação de DevOps instalado numa equipa que obtém erros inativos do Azure DevOps. Identifica os proprietários dos erros inativos, obtém os respetivos endereços de e-mail e envia notificações diárias para as respetivas conversas pessoais.

Para testar de forma abrangente este bot no Agents Playground, certifique-se de que atualiza o ficheiro de configuração com os endereços de e-mail corretos dos proprietários de erros inativos.

Aceda ao .m365agentsplayground.yml ficheiro na pasta raiz do projeto.

Aceda à users secção e atualize o name, userPrincipleNamee email do utilizador 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

Guarde o ficheiro e selecione F5 para depurar no Ambiente de Trabalho dos Agentes.

Observação

Quando edita o ficheiro de configuração no Visual Studio Code, o Intellisense atualiza automaticamente os nomes das propriedades e avisa-o se introduzir valores inválidos.

É importante compreender que a atualização do ficheiro de configuração tem três impactos importantes:

Afeta as respostas devolvidas pelas APIs do Conector do Bot Framework. Por exemplo, TeamsInfo.getPagedMembers().
Modifica os detalhes no payload da atividade. Por exemplo, activity.recipient.
Influencia a interface de utilizador no Agents Playground. Por exemplo, nomes de chat de grupo.

Limitações

As funcionalidades do bot ou do agente ativadas através do manifesto da aplicação Teams não estão disponíveis, uma vez que o Agents Playground não o processa.
O Agents Playground não suporta todos os tipos de cartões, exceto Cartões Ajustáveis.
O Agents Playground não suporta as seguintes funcionalidades de Cartão Ajustável:
O Agents Playground não suporta as seguintes experiências:
- Dispositivo móvel
- Reunião

O Agents Playground pode emular as seguintes experiências:

Recursos	Depuração no Playground de Agentes	Depurar seu aplicativo localmente
Envio/receção básicos de mensagens	Disponível	Disponível
APIs do Bot Framework (TeamsInfo.getPagedMembers()...)	Disponível (responder com dados fictícios)	Disponível
Enviar eventos do Teams	Disponível (atividade fictícia)	Disponível
Indicador de escrita	Não disponível	Disponível
Separador, Extensão de mensagem, Caixas de Diálogo (referidas como módulos de tarefas no TeamsJS v1.x), Início de sessão único (SSO) e Cartões Não Adaptáveis	Não disponível	Disponível

Depurar uma aplicação existente com o Agents Playground

Certifique-se de que tem uma aplicação existente criada com o Toolkit de Agentes. Para depurar a sua aplicação com o Agents Playground, siga estes passos:

Abra a pasta de projeto do bot existente no Toolkit de Agentes.
Aceda a EXPLORER.vscode>.

Selecione launch.json e adicione o seguinte código no final do ficheiro:

// .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 
        }, 
    ] 
}

Aceda a tasks.json e adicione o seguinte código no final do ficheiro:

    { 
      "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" 
      } 
    }, 
  ],
}

Em EXPLORADOR, crie um ficheiro .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

Aceda a EXPLORADOR>env.

Crie um ficheiro .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

Se tiver variáveis de ambiente personalizadas, defina os respetivos valores em .env.playground ou .env.playground.user.

Adicione uma chave OpenAI ou Azure chave OpenAI e ponto final 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/>

Aceda a package.json e adicione o seguinte código na 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", 
    ... 
},

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

O Agents Playground depura com êxito o seu bot existente.

Detetei um problema

Desativar a recolha de dados

Se decidir que não quer permitir que os Agentes Playground recolham dados de utilização, pode desativar facilmente a recolha de dados ao adicionar a opção --disable-telemetry quando iniciar o Ambiente de Trabalho dos Agentes através da linha de comandos.

Perguntas frequentes

Como posso testar a minha aplicação se o Agents Playground não suportar as funcionalidades?

Pode sempre utilizar o cliente do Teams para testar as funcionalidades que o Agents Playground não suporta. Selecione a opção Depurar no Teams (Edge) ou Depurar no Teams (Chrome) para testar a sua aplicação no cliente do Teams.

Como saberia se o Agents Playground não suporta funcionalidades na minha aplicação?

Agents Playground mostra uma mensagem de aviso na conversação e no painel de registo quando deteta funcionalidades não suportadas.

Captura de ecrã a mostrar a mensagem de aviso de uma funcionalidade não suportada.

A Microsoft recomenda a utilização apenas do Agents Playground para testar aplicações?

Não. Recomendamos sempre que os utilizadores testem as respetivas aplicações no cliente do Teams antes de moverem a aplicação para o ambiente de produção.

Exemplo de código

Nome do exemplo	Descrição	Node.js
Aplicação de Exemplo do Playground de Agentes	Uma aplicação de exemplo para explorar o Agents Playground.	View

Guias passo a passo

Siga o guia passo a passo para depurar um chatbot de IA com o Agents Playground.

Confira também

Feedback

Esta página foi útil?

Last updated on 2025-06-02

Partilhar via

Ambiente de Trabalho dos Agentes do Microsoft 365

Pré-requisitos

Compreender o Playground de Agentes

Agents Playground experience in Agents Toolkit

Acionadores de atividade

Acionadores de atividade predefinidos

Acionadores de atividade personalizados

Configurar o Playground de Agentes para autenticação

Variável de ambiente/Linha de comandos

Interface do lado do cliente

Lógica de autenticação

Suporte de vários canais

Personalizar o contexto do Teams

Configuração padrão

Atualizar o ficheiro de configuração

Limitações

Depurar uma aplicação existente com o Agents Playground

Desativar a recolha de dados

Perguntas frequentes

Exemplo de código

Guias passo a passo

Confira também

Feedback

Recursos adicionais