Início Rápido: Criar um agente e conversar com ele no Teams

Neste início rápido, você usará ferramentas de desenvolvedor de linha de comando para criar um novo agente do Teams. Ao final, você conversará com seu agente no Teams enquanto o código é executado em seu ambiente de desenvolvimento local. Você poderá usar o código e o registro do agente criados neste início rápido como base para um agente do Teams completo.

Pré-requisitos

Este guia de início rápido é dividido em duas seções. No primeiro, você executa um agente no Microsoft 365 Agents Playground para testes locais. Para esta seção, você precisará de:

Na segunda seção, em que você instala e testa seu agente no Teams, também precisará de:

  • Um locatário do Teams onde os uploads de aplicativos personalizados são permitidos e uma conta nele com permissões para instalar aplicativos personalizados (pode ser necessário habilitar isso)

Se você não tiver uma conta ou não tiver certeza sobre suas permissões, ainda poderá começar. O início rápido atenderá a esses requisitos quando eles forem necessários.

Criar código para um tempo de execução de agente e experimentá-lo no Microsoft 365 Agents Playground

  1. Instale a CLI do desenvolvedor do Teams e o Playground dos agentes do Microsoft 365.

    npm install -g @microsoft/teams.cli @microsoft/m365agentsplayground

  2. Use teams project new para criar o código de um novo tempo de execução de agente a partir de um modelo e, em seguida, abra-o no Visual Studio Code.

    teams project new typescript echo-bot
cd echo-bot
code .

  3. No Visual Studio Code, abra src/index.ts. Encontre a linha que diz const app = new App(); e modifique-a para ler:

    const app = new App({ skipAuth: true });

    Esta é uma modificação temporária para permitir que ele se comunique com o Microsoft 365 Agents Playground.

  4. Inicie o tempo de execução do agente. Quando estiver em execução, você verá uma confirmação de que ele está disponível na porta 3978.

    npm install
npm run dev

  5. Em uma nova janela de console, inicie o Microsoft 365 Agents Playground.

    agentsplayground

    Isso conectará o Agents Playground ao tempo de execução do seu agente e abrirá a interface em uma nova guia do navegador.

  6. Use a caixa de composição para enviar uma mensagem ao seu agente e vê-lo responder no chat. Seu agente está funcionando localmente!

    Captura de tela de uma breve interação do agente no Microsoft 365 Agents Playground.

  7. Feche a guia Agents Playground no navegador e use Ctrl+C nas duas janelas do console para interromper o Agents Playground e o tempo de execução do agente. Deixe aberta a janela do console usada para criar o código de tempo de execução do agente, você precisará dele novamente em breve.

  8. No Visual Studio Code, desfaça a modificação feita na etapa 3. Isso garantirá uma conexão segura com o Teams nas próximas etapas.

    const app = new App();

Faça logon e confirme as permissões

Importante

A próxima parte deste início rápido requer o Teams, conectado a uma conta corporativa ou de estudante do Microsoft 365 com permissões para instalar aplicativos personalizados do Teams. Esta etapa marcará essa permissão.

Se você não tiver uma conta do Microsoft 365, poderá prosseguir para Próximas etapas para continuar trabalhando em seu código e concluir o restante deste início rápido mais tarde. Consulte Programa para Desenvolvedores do Microsoft 365 para obter informações sobre como obter uma assinatura da área restrita para desenvolvedores que você pode usar para experimentar seu aplicativo no Teams.

Faça login na sua conta corporativa ou de estudante do Microsoft 365 a partir da CLI do desenvolvedor do Teams.

teams login

A CLI confirmará as permissões da sua conta para instalar aplicativos personalizados ("sideload") e marcará a presença de uma instalação da CLI do Azure (não necessária para este início rápido).

✔ Logged in as user@contoso.com
✔ Sideloading: enabled

Azure CLI: installed, not logged in

Para continuar com este início rápido, o sideload deve estar habilitado. Se estiver desabilitado, você precisará do administrador do Microsoft 365 da sua organização para habilitá-lo para sua conta. Consulte Permitir que os usuários carreguem aplicativos personalizados para obter instruções de administrador para habilitar essa permissão. Enquanto isso, você pode prosseguir para Próximas etapas para continuar trabalhando no código do seu agente.

Pré-requisitos

Este guia de início rápido é dividido em duas seções. No primeiro, você executa um agente no Microsoft 365 Agents Playground para testes locais. Para esta seção, você precisará de:

Na segunda seção, em que você instala e testa seu agente no Teams, também precisará de:

  • Um locatário do Teams onde os uploads de aplicativos personalizados são permitidos e uma conta nele com permissões para instalar aplicativos personalizados (pode ser necessário habilitar isso)

Se você não tiver uma conta ou não tiver certeza sobre suas permissões, ainda poderá começar. O início rápido atenderá a esses requisitos quando eles forem necessários.

Criar código para um tempo de execução de agente e experimentá-lo no Microsoft 365 Agents Playground

  1. Instale a CLI do desenvolvedor do Teams e o Playground dos agentes do Microsoft 365.

    npm install -g @microsoft/teams.cli @microsoft/m365agentsplayground

  2. Use teams project new para criar o código de um novo tempo de execução de agente a partir de um modelo e, em seguida, abra-o no Visual Studio Code.

    teams project new python echo-bot
cd echo-bot
code .

  3. No Visual Studio Code, abra src/main.py. Encontre a linha que diz app = App() e modifique-a para ler:

    app = App(skip_auth=True)

    Esta é uma modificação temporária para permitir que ele se comunique com o Microsoft 365 Agents Playground.

  4. Inicie o tempo de execução do agente. Quando ele estiver em execução, você verá uma confirmação de que ele está sendo executado na porta 3978.

    python -m venv .venv
source .venv/bin/activate
pip install -e .
python src/main.py

  5. Em uma nova janela de console, inicie o Microsoft 365 Agents Playground.

    agentsplayground

    Isso conectará o Agents Playground ao seu agente e abrirá a interface em uma nova guia do navegador.

  6. Use a caixa de composição para enviar uma mensagem ao seu agente e vê-lo responder no chat. Seu agente está funcionando localmente!

    Captura de tela de uma breve interação do agente no Microsoft 365 Agents Playground.

  7. Feche a guia Agents Playground no navegador e use Ctrl+C nas duas janelas do console para interromper o Agents Playground e o tempo de execução do agente. Deixe aberta a janela do console usada para criar o código de tempo de execução do agente, você precisará dele novamente em breve.

  8. No editor, desfaça a modificação feita na etapa 3. Isso garantirá uma conexão segura com o Teams nas próximas etapas.

    app = App()

Faça logon e confirme as permissões

Importante

A próxima parte deste início rápido requer o Teams, conectado a uma conta corporativa ou de estudante do Microsoft 365 com permissões para instalar aplicativos personalizados do Teams. Esta etapa marcará essa permissão.

Se você não tiver uma conta do Microsoft 365, poderá prosseguir para Próximas etapas para continuar trabalhando em seu código e concluir o restante deste início rápido mais tarde. Consulte Programa para Desenvolvedores do Microsoft 365 para obter informações sobre como obter uma assinatura da área restrita para desenvolvedores que você pode usar para experimentar seu aplicativo no Teams.

Faça login na sua conta corporativa ou de estudante do Microsoft 365 a partir da CLI do desenvolvedor do Teams.

teams login

A CLI confirmará as permissões da sua conta para instalar aplicativos personalizados ("sideload") e marcará a presença de uma instalação da CLI do Azure (não necessária para este início rápido).

✔ Logged in as user@contoso.com
✔ Sideloading: enabled

Azure CLI: installed, not logged in

Para continuar com este início rápido, o sideload deve estar habilitado. Se estiver desabilitado, você precisará do administrador do Microsoft 365 da sua organização para habilitá-lo para sua conta. Consulte Permitir que os usuários carreguem aplicativos personalizados para obter instruções de administrador para habilitar essa permissão. Enquanto isso, você pode prosseguir para Próximas etapas para continuar trabalhando no código do seu agente

Pré-requisitos

  • Node.js 24 ou posterior (download do instalador)
  • .NET 10 ou posterior (download do instalador)
  • Um locatário do Teams onde os uploads de aplicativos personalizados são permitidos e uma conta nele com permissões para instalar aplicativos personalizados (pode ser necessário habilitar isso)

Se você não tiver uma conta corporativa ou de estudante do Microsoft 365, consulte Programa de Desenvolvedor do Microsoft 365 para obter informações sobre como obter uma assinatura de área restrita de desenvolvedor que você pode usar para testar seu agente no Teams.

Instale ferramentas, faça login e confirme permissões

Instale a CLI do desenvolvedor do Teams e faça logon com sua conta corporativa ou de estudante do Microsoft 365.

npm install -g @microsoft/teams.cli
teams login

A CLI confirmará seu logon, as permissões da sua conta para instalar aplicativos personalizados ("sideload") e marcará a presença de uma instalação da CLI do Azure (não é necessária para este início rápido).

✔ Logged in as user@contoso.com
✔ Sideloading: enabled

Azure CLI: installed, not logged in

Para continuar com este início rápido, o sideload deve estar habilitado. Se estiver desabilitado, você precisará do administrador do Microsoft 365 da sua organização para habilitá-lo para sua conta. Consulte Permitir que os usuários carreguem aplicativos personalizados para obter instruções de administrador para habilitar essa permissão.

Criar código para um tempo de execução de agente

  1. Use teams project new para criar o código de um novo tempo de execução de agente a partir de um modelo.

    teams project new csharp EchoBot
cd EchoBot/EchoBot

  2. Inicie o tempo de execução do agente para confirmar sua execução. Quando estiver em execução, você verá uma confirmação de que ele pode ser acessado pela porta 3978.

    dotnet run

  3. Use Ctrl+C na janela do console para parar o agente. Deixe a janela do console aberta, você precisará dela novamente em breve.

Hospedar um túnel de desenvolvimento

As equipes só podem se comunicar com um tempo de execução de agente acessível pela Internet pública. Nesta etapa, use o utilitário Microsoft Dev Tunnel para criar um túnel que exporá o tempo de execução do agente à Internet enquanto ele estiver em execução no ambiente de desenvolvimento.

  1. Em uma nova janela de console, instale o dev tunnel.

    winget install Microsoft.devtunnel

  2. Faça logon devtunnel com sua conta do Microsoft 365 e hospede um novo túnel.

    devtunnel user login
devtunnel create --allow-anonymous
devtunnel port create -p 3978
devtunnel host

    Você verá resultados como os seguintes:

    Connection to host tunnel relay restored.
Hosting port: 3978
Connect via browser: https://4r9dd5xj-3978.usw2.devtunnels.ms
Inspect network activity: https://4r9dd5xj-3978-inspect.usw2.devtunnels.ms

Ready to accept connections for tunnel: joyful-dog-xgz66vp.usw2

  3. Deixe o túnel funcionando. Anote a Connect via browser URL para a próxima etapa.

Observação

O túnel de desenvolvimento precisará ser reiniciado se a conexão de rede do seu dispositivo for alterada. Se você criar um novo túnel, a URL será diferente daquela que você registrou — atualize o ponto de extremidade de mensagens do seu agente para corresponder ou o agente deixará de receber mensagens do Teams.

Registrar, instalar e conversar no Teams

  1. Na janela do console usada para criar seu projeto de tempo de execução do agente, use teams app create para registrá-lo na plataforma do Teams. Substitua <tunnel-host> pela URL completa Connect via browser da etapa anterior. Esse comando cria um arquivo de configuração que o tempo de execução do agente precisa para se comunicar com o Teams, por isso é importante executá-lo no diretório do projeto.

    teams app create --endpoint <tunnel-host>/api/messages --name echo-bot --env .env

  1. Na janela do console usada para criar seu projeto de tempo de execução do agente, use teams app create para registrá-lo na plataforma do Teams. Substitua <tunnel-host> pela URL completa Connect via browser da etapa anterior. Esse comando cria um arquivo de configuração que o tempo de execução do agente precisa para se comunicar com o Teams, por isso é importante executá-lo no diretório do projeto.

    teams app create --endpoint <tunnel-host>/api/messages --name echo-bot --env appsettings.json

  1. Quando o create comando for concluído, ele exibirá um menu. Selecione Instalar no Teams para abrir o Teams e exibir a caixa de diálogo do instalador do agente.

    Captura de tela da caixa de diálogo de instalação do aplicativo no Teams.

  1. Antes de prosseguir no Teams, volte para a janela do console e selecione Concluído no menu CLI do desenvolvedor do Teams para fechá-la. Em seguida, use a linha de comando para iniciar o tempo de execução do agente novamente. Verifique se ele está escutando na porta 3978 antes de continuar.

    npm run dev

  1. Antes de prosseguir no Teams, volte para a janela do console e selecione Concluído no menu CLI do desenvolvedor do Teams para fechá-la. Em seguida, use a linha de comando para iniciar o tempo de execução do agente novamente. Verifique se ele está escutando na porta 3978 antes de continuar.

    python src/main.py

  1. Antes de prosseguir no Teams, volte para a janela do console e selecione Concluído no menu CLI do desenvolvedor do Teams para fechá-la. Em seguida, use a linha de comando para iniciar o tempo de execução do agente novamente. Verifique se ele está escutando na porta 3978 antes de continuar.

    dotnet run

  1. Volte para o Teams e selecione Adicionar na caixa de diálogo do instalador da etapa 2 para instalar o agente. Na caixa de diálogo Como você gostaria de usar este aplicativo hoje? que aparece, selecione Abrir para abrir um chat privado com o agente.

    Captura de tela da caixa de diálogo do Teams perguntando como o usuário gostaria de usar um aplicativo recém-instalado.

  2. Chat com seu agente no Teams!

    Captura de tela de uma breve interação de chat com um agente no Teams.

Próximas etapas

Tudo o que você criou neste início rápido persistirá e poderá ser usado como base para a criação de um agente. Enquanto o código e o túnel de desenvolvimento estiverem em execução no ambiente de desenvolvimento, o agente poderá enviar e receber mensagens no Teams.

Todo o comportamento do agente está em seu código de tempo de execução: você pode modificar e reiniciar o tempo de execução para alterar seu comportamento sem registrá-lo novamente ou reinstalá-lo no Teams.

Explore a documentação para saber mais sobre os recursos e as práticas recomendadas para agentes no Teams.

  • Última atualização em