diff --git a/msteams-platform/bots/how-to/teams-conversational-ai/conversation-ai-quick-start.md b/msteams-platform/bots/how-to/teams-conversational-ai/conversation-ai-quick-start.md index 9bf74200f02..70166044039 100644 --- a/msteams-platform/bots/how-to/teams-conversational-ai/conversation-ai-quick-start.md +++ b/msteams-platform/bots/how-to/teams-conversational-ai/conversation-ai-quick-start.md @@ -12,122 +12,122 @@ ms.date: 12/11/2024 # Teams AI library quick start guide -Get started with Teams AI library using the LightBot sample, which is designed to help you through the process of creating apps that can control lights, such as turning them on and off using Teams AI library. The bot uses the gpt-3.5-turbo model to chat with Microsoft Teams users and respond in a polite and respectful manner, staying within the scope of the conversation. +This guide helps you get started with the Teams AI library using the LightBot sample. This sample demonstrates how to create apps that control lights, such as turning them on and off, while using the gpt-3.5-turbo model to interact politely with Microsoft Teams users within the conversation scope. ::: zone pivot="qs-javascript" ## Prerequisites -To get started, ensure that you have the following tools: +Ensure that you have the following tools installed and configured: | Install | For using... | | --- | --- | | [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript, TypeScript, and Python build environments. Use the latest version. | -| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.| -|[Git](https://git-scm.com/downloads)|Git is a version control system that helps you manage different versions of code within a repository. | -| [Node.js](https://nodejs.org/en) | Back-end JavaScript runtime environment. For more information, see [Node.js version compatibility table for project type](~/toolkit/build-environments.md#nodejs-version-compatibility-table-for-project-type).| -| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | To collaborate with everyone, you work with them through apps for chat, meetings, and call all in one place.| -| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal)| First create your OpenAI API key to use OpenAI's GPT. If you want to host your app or access resources in Microsoft Azure, you must create an Azure OpenAI service.| -| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | -| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with the appropriate permissions to install an app and [enable custom Teams apps and turn on custom app uploading](../../../concepts/build-and-test/prepare-your-o365-tenant.md#enable-custom-teams-apps-and-turn-on-custom-app-uploading). | +| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Microsoft Visual Studio Code extension that creates project scaffolding for your app. Use the latest version.| +| [Git](https://git-scm.com/downloads) | Version control system to manage different versions of code within a repository. | +| [Node.js](https://nodejs.org/en) | Back-end JavaScript runtime environment. For more information, refer to the "Node.js version compatibility table for project type" in the Teams Toolkit documentation. | +| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Platform to collaborate using apps for chat, meetings, and calls. | +| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal) | Create your OpenAI API key to use OpenAI's GPT. If you need to host your app or access resources in Azure, create an Azure OpenAI service. | +| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | Browser with developer tools. | +| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with permissions to install an app and enable custom Teams apps and custom app uploading. |
-If you've already run the samples before or encountered a runtime error, follow these steps to start fresh: +If you have run the samples before or encounter a runtime error, take these actions to ensure a fresh setup: -* Check all the `.env` and `env/.env.*.*` files in the sample and delete any automatically populated values to ensure that Teams Toolkit generates new resources for you. -* If you don’t want Teams Toolkit to generate the app ID and password, update the `BOT_ID` and `BOT_PASSWORD` in the `.env` file with your own values. -* Remove values or leave the values blank for **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** in the `.env` file to avoid conflicts. +* Check all the `.env` and `env/.env.*.*` files in the sample and delete any automatically populated values. This action ensures that Teams Toolkit generates new resources. +* If you prefer not to let Teams Toolkit generate the app ID and password, update the `BOT_ID` and `BOT_PASSWORD` in the `.env` file with your custom values. +* Remove any values or leave blank the **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** entries in the `.env` file to avoid conflicts. -Teams Toolkit automatically provisions `BOT_ID` and `BOT_PASSWORD` resources. If you want to use your own resources, you need to manually add them to the `.env` file. Teams Toolkit doesn't auto-generate the following resources: +Note that Teams Toolkit automatically provisions `BOT_ID` and `BOT_PASSWORD` resources. When you use your own resources, manually add them into the `.env` file. Teams Toolkit does not auto-generate the following resources: * An Azure OpenAI or OpenAI key * A database or similar storage options ## Build and run the sample app -Get started with Teams AI library using the LightBot sample. It enables your computer’s localhost to quickly execute a Teams AI library-based sample. +This section guides you through building and running the LightBot sample app, which runs on your computer’s localhost using the Teams AI library. -1. Go to the [sample](https://github.com/microsoft/teams-ai/tree/main/js/samples). +1. Navigate to the [sample](https://github.com/microsoft/teams-ai/tree/main/js/samples). -1. Run the following command to clone the repository: +2. Run the following command to clone the repository: ```cmd git clone https://github.com/microsoft/teams-ai.git ``` -1. Go to **Visual Studio Code**. +3. Open Visual Studio Code. -1. Select **File** > **Open Folder**. +4. Choose File > Open Folder. -1. Go to the location where you cloned teams-ai repo and select the **teams-ai** folder. +5. Navigate to the location where you cloned the teams-ai repository and select the teams-ai folder. -1. Select **Select Folder**. +6. Click Select Folder. - :::image type="content" source="../../../assets/images/bots/ai-library-dot-net-select-folder.png" alt-text="Screenshot shows the teams-ai folder and the Select Folder option."::: + :::image type="content" source="../../../assets/images/bots/ai-library-dot-net-select-folder.png" alt-text="Screenshot shows the teams-ai folder and the Select Folder option." ::: -1. Select **View** > **Terminal**. A terminal window opens. +7. Choose View > Terminal to open a terminal window. -1. In the terminal window, run the following command to go to the **js** folder: +8. In the terminal window, run this command to change to the js folder: ```terminal cd .\js\ ``` -1. Run the following command to install dependencies: +9. Run the following command to install the dependencies: ```terminal yarn install ``` -1. Run the following command to build dependencies: +10. Run this command to build the project: - ```terminal - yarn build - ``` + ```terminal + yarn build + ``` -1. After the dependencies are installed, select **File** > **Open Folder**. +11. After installing dependencies, choose File > Open Folder. -1. Go to **teams-ai > js > samples> 03.ai-concepts> c.actionMapping-lightBot** and select **Select Folder**. All the files for the LightBot sample are listed under the **EXPLORER** section in Visual Studio Code. +12. Navigate to teams-ai > js > samples > 03.ai-concepts > c.actionMapping-lightBot and select Select Folder. All files for the LightBot sample display under the EXPLORER section in Visual Studio Code. -1. Update the following steps based on the AI services you select. +13. Update the following settings based on your selected AI service: - # [OpenAI key](#tab/OpenAI-key) + # [OpenAI key](#tab/OpenAI-key) - 1. Go to the `env` folder and update the following code in `./env/.env.local.user` file: + 1. Open the `env` folder and update the code in the `./env/.env.local.user` file: - ```text + ```text SECRET_OPENAI_KEY= - ``` - - 1. Go to the `infra` folder and ensure that the following lines in the `azure.bicep` file are commented out: + ``` - ```bicep - // { - // name: 'AZURE_OPENAI_KEY' - // value: azureOpenAIKey - // } - // { - // name: 'AZURE_OPENAI_ENDPOINT' - // value: azureOpenAIEndpoint - // } - ``` + 2. Open the `infra` folder and comment out these lines in the `azure.bicep` file: + + ```bicep + // { + // name: 'AZURE_OPENAI_KEY' + // value: azureOpenAIKey + // } + // { + // name: 'AZURE_OPENAI_ENDPOINT' + // value: azureOpenAIEndpoint + // } + ``` - # [Azure OpenAI](#tab/Azure-OpenAI) + # [Azure OpenAI](#tab/Azure-OpenAI) - 1. Go to the `env` folder and update the following code in `./env/.env.local.user` file: + 1. Open the `env` folder and update the code in the `./env/.env.local.user` file: ```text SECRET_AZURE_OPENAI_KEY= SECRET_AZURE_OPENAI_ENDPOINT= ``` - 1. Go to the `teamsapp.local.yml` file and modify the last step to use Azure OpenAI variables: + 2. Open the `teamsapp.local.yml` file and modify the last step to use Azure OpenAI variables: ```yaml - - uses: file/createOrUpdateEnvironmentFile - with: - target: ./.env - envs: + - uses: file/createOrUpdateEnvironmentFile + with: + target: ./.env + envs: BOT_ID: ${{BOT_ID}} BOT_PASSWORD: ${{SECRET_BOT_PASSWORD}} #OPENAI_KEY: ${{SECRET_OPENAI_KEY}} @@ -135,59 +135,53 @@ Get started with Teams AI library using the LightBot sample. It enables your com AZURE_OPENAI_ENDPOINT: ${{SECRET_AZURE_OPENAI_ENDPOINT}} ``` - 1. Go to the `infra` folder and ensure that the following lines in the `azure.bicep` file are commented out: - - ```bicep - // { - // name: 'OPENAI_KEY' - // value: openAIKey - // } - ``` + 3. Open the `infra` folder and comment out these lines in the `azure.bicep` file: - 1. Go to `infra` > `azure.parameters.json` and replace the lines from [20 to 22](https://github.com/microsoft/teams-ai/blob/main/js/samples/03.ai-concepts/c.actionMapping-lightBot/infra/azure.parameters.json#L20-L22) with the following code: - - ```json - "azureOpenAIKey": { - "value": "${{SECRET_AZURE_OPENAI_KEY}}" - }, - "azureOpenAIEndpoint": { - "value": "${{SECRET_AZURE_OPENAI_ENDPOINT}}" - } - ``` - - --- + ```bicep + // { + // name: 'OPENAI_KEY' + // value: openAIKey + // } + ``` -1. From the left pane, select **Teams Toolkit**. + 4. Open `infra > azure.parameters.json` and replace the lines from [20 to 22](https://github.com/microsoft/teams-ai/blob/main/js/samples/03.ai-concepts/c.actionMapping-lightBot/infra/azure.parameters.json#L20-L22) with this code: -1. Under **ACCOUNTS**, sign-in to the following: + ```json + "azureOpenAIKey": { + "value": "${{SECRET_AZURE_OPENAI_KEY}}" + }, + "azureOpenAIEndpoint": { + "value": "${{SECRET_AZURE_OPENAI_ENDPOINT}}" + } + ``` - * **Microsoft 365 account** - * **Azure account** +14. In Visual Studio Code, select Teams Toolkit from the left pane. -1. To debug your app, select **F5**. +15. Under ACCOUNTS, sign in using the following accounts: - A browser tab opens the Teams web client to add the bot to your tenant. + * Microsoft 365 account + * Azure account -1. Select **Add**. +16. Press F5 to debug your app. - :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app."::: + A browser tab opens the Teams web client to add the bot to your tenant. - When the app is added, a dialog to select the required scope appears. +17. Click Add. -1. Select **Open** to open the app in personal scope. + :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app." ::: - Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select **Go**. + When the app adds, a dialog displays to select the required scope. - :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes."::: +18. Choose Open to launch the app in personal scope. Alternatively, search for and select the required scope or choose a channel, chat, or meeting; then, follow the dialog prompts and choose Go. - A chat window opens. + :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes." ::: -1. In the message compose area, send a message to invoke the bot. +19. In the chat window that appears, send a message to invoke the bot. - :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output." lightbox="../../../assets/images/bots/lightbot-output.png"::: + :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output." lightbox="../../../assets/images/bots/lightbot-output.png" ::: > [!NOTE] -> If you're building a bot for the first time, it's recommended to use Teams Toolkit extension for Visual Studio Code to build a bot, see [build your first bot app using JavaScript](../../../sbs-gs-bot.yml). +> When building a bot for the first time, use the Teams Toolkit extension for Visual Studio Code. For additional assistance, refer to the "build your first bot app using JavaScript" guide in the documentation. ::: zone-end @@ -195,60 +189,60 @@ Get started with Teams AI library using the LightBot sample. It enables your com ## Prerequisites -To get started, ensure that you have the following tools: +Ensure that you install and configure the following tools: | Install | For using... | | --- | --- | -| [Visual Studio](https://visualstudio.microsoft.com/downloads/) | C Sharp build environments. Use the latest version. | -| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.| -|[Git](https://git-scm.com/downloads)|Git is a version control system that helps you manage different versions of code within a repository. | -| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | To collaborate with everyone, you work with them through apps for chats, meetings, and calls all in one place.| -| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal)| First create your OpenAI API key to use OpenAI's GPT. If you want to host your app or access resources in Microsoft Azure, you must create an Azure OpenAI service.| -| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | -| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with the appropriate permissions to install an app and [enable custom Teams apps and turn on custom app uploading](../../../concepts/build-and-test/prepare-your-o365-tenant.md#enable-custom-teams-apps-and-turn-on-custom-app-uploading). | +| [Visual Studio](https://visualstudio.microsoft.com/downloads/) | C# build environments. Use the latest version. | +| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Extension that creates project scaffolding for your app. Use the latest version. | +| [Git](https://git-scm.com/downloads) | Version control system to manage code changes. | +| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Platform to collaborate through chats, meetings, and calls. | +| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal) | Create your OpenAI API key for GPT use. If you host your app in Azure, create an Azure OpenAI service. | +| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | Browser with developer tools for debugging. | +| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Permission to install apps and enable custom Teams apps and uploading in your Teams account. |
-If you've already run the samples before or encountered a runtime error, follow these steps to start fresh: +If you have executed the samples previously or experience a runtime error, perform these steps to start fresh: -* Check all the `.env` and `env/.env.*.*` files in the sample and delete any automatically populated values to ensure that Teams Toolkit generates new resources for you. -* If you don’t want Teams Toolkit to generate the app ID and password, update the `MicrosoftAppId` and `MicrosoftAppPassword` in the `.env` file with your own values. -* Remove values or leave the values blank for **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** in the `.env` file to avoid conflicts. +* Check all the `.env` and `env/.env.*.*` files in the sample and remove any automatically populated values to force Teams Toolkit to generate new resources. +* If you choose not to allow Teams Toolkit to generate the app ID and password, update the `MicrosoftAppId` and `MicrosoftAppPassword` in the `.env` file with your chosen values. +* Remove or leave blank the **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** values in the `.env` file to avoid conflicts. -Teams Toolkit automatically provisions `MicrosoftAppId` and `MicrosoftAppPassword` resources. If you want to use your own resources, you need to manually add them to the `.env` file. Teams Toolkit doesn't auto-generate the following resources: +Teams Toolkit automatically provisions `MicrosoftAppId` and `MicrosoftAppPassword` resources. Use your own resources by manually adding them in the `.env` file. Note that the following resources are not automatically generated by Teams Toolkit: * An Azure OpenAI or OpenAI key * A database or similar storage options ## Build and run the sample app -1. Go to the [sample](https://github.com/microsoft/teams-ai/tree/main/dotnet/samples). +1. Navigate to the [sample](https://github.com/microsoft/teams-ai/tree/main/dotnet/samples). -1. Clone the repository to test the sample app. +2. Clone the repository using this command: - ``` + ```cmd git clone https://github.com/microsoft/teams-ai.git ``` -1. Go to the **dotnet** folder. +3. Change directory to the dotnet folder: - ``` + ```cmd cd teams-ai/dotnet ``` -1. Go to the folder where you cloned the repository and select **04.ai.c.actionMapping.lightBot**. +4. In your file explorer, navigate to the folder where you cloned the repository and open the folder named 04.ai.c.actionMapping.lightBot. -1. Select **LightBot.sln**. The solution opens in Visual Studio. +5. Open the solution file LightBot.sln in Visual Studio. -1. In Visual Studio, update your OpenAI-related settings in the `appsettings.Development.json` file. +6. In Visual Studio, update the OpenAI-related settings in the appsettings.Development.json file with your credentials: - ```json - "Azure": { - "OpenAIApiKey": "", - "OpenAIEndpoint": "" - }, - ``` + ```json + "Azure": { + "OpenAIApiKey": "", + "OpenAIEndpoint": "" + } + ``` -1. Go to `Prompts/sequence/skprompt.txt` and update the following code in `skprompt.txt` file: +7. Open Prompts/sequence/skprompt.txt and update its contents as follows: ```skprompt.txt The following is a conversation with an AI assistant. @@ -269,53 +263,47 @@ Teams Toolkit automatically provisions `MicrosoftAppId` and `MicrosoftAppPasswor Always respond in the form of a JSON based plan. Stick with DO/SAY. ``` -1. In the debug dropdown menu, select **Dev Tunnels** > **Create a Tunnel..**. - - :::image type="content" source="../../../assets/images/bots/dotnet-ai-library-dev-tunnel.png" alt-text="Screenshot shows an example of the Dev Tunnel and Create a Tunnel option in Visual Studio."::: - -1. Select the **Account** to use to create the tunnel. Azure, Microsoft Account (MSA), and GitHub accounts are supported. Update the following options: - 1. **Name**: Enter a name for the tunnel. - 1. **Tunnel Type**: Select **Persistent** or **Temporary**. - 1. **Access**: Select **Public**. - 1. Select **OK**. Visual Studio displays a confirmation message that a tunnel is created. +8. In the debug dropdown menu, choose Dev Tunnels and then Create a Tunnel. - The tunnel you created is listed under **Dev Tunnels > (name of the tunnel)**. + :::image type="content" source="../../../assets/images/bots/dotnet-ai-library-dev-tunnel.png" alt-text="Screenshot shows an example of the Dev Tunnel and Create a Tunnel option in Visual Studio." ::: -1. Go to **Solution Explorer** and select your project. +9. Select the Account to use for creating the tunnel. Azure, Microsoft Account (MSA), and GitHub accounts are supported. Update the following tunnel options: + - Name: Enter a name for the tunnel. + - Tunnel Type: Choose either Persistent or Temporary. + - Access: Choose Public. + - Confirm by selecting OK. Visual Studio displays a confirmation message upon tunnel creation. -1. Right-click menu and select **Teams Toolkit** > **Prepare Teams App Dependencies**. +10. In Solution Explorer, select your project. - :::image type="content" source="../../../assets/images/bots/dotnet-ai-library-prepare-teams.png" alt-text="Screenshot shows an example of the Prepared Teams app Dependencies option under Teams Toolkit section in Visual Studio."::: +11. Right-click and choose Teams Toolkit > Prepare Teams App Dependencies. - If prompted, sign in to your Microsoft 365 account. You receive a message that Teams app dependencies are successfully prepared. + :::image type="content" source="../../../assets/images/bots/dotnet-ai-library-prepare-teams.png" alt-text="Screenshot shows the Prepared Teams app Dependencies option under Teams Toolkit in Visual Studio." ::: -1. Select **OK**. + If prompted, sign in to your Microsoft 365 account. A confirmation message appears indicating that Teams app dependencies prepare successfully. -1. Select **F5** or select **Debug** > **Start**. +12. Choose OK to confirm. -1. Select **Add** to add the bot to your tenant. +13. Press F5 or select Debug > Start to debug your project. - :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app."::: +14. Click Add to add the bot to your tenant. - When the app is added, a dialog to select the required scope appears. + :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app." ::: -1. Select **Open** to open the app in personal scope. + A dialog presents to select the required scope. - Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select **Go**. +15. Choose Open to launch the app in personal scope. Alternatively, search for and select the required scope or choose a channel, chat, or meeting, then follow the prompts to select Go. - :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes."::: + :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes." ::: - A chat window opens. +16. In the chat window, send a message to invoke the bot. -1. In the message compose area, send a message to invoke the bot. + :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output." ::: - :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output."::: +You can also deploy the sample to Azure using Teams Toolkit. To complete deployment: -You can also deploy the samples to Azure using Teams Toolkit. To deploy, follow these steps: - -1. In Visual Studio, go to **Solution Explorer** and select your project. -1. Right-click menu and select **Teams Toolkit** > **Provision in the Cloud**. Toolkit provisions your sample to Azure. -1. Right-click menu and select **Teams Toolkit** > **Deploy to the Cloud**. +1. In Visual Studio, open Solution Explorer and select your project. +2. Right-click and choose Teams Toolkit > Provision in the Cloud. Teams Toolkit provisions your sample in Azure. +3. Then, right-click and choose Teams Toolkit > Deploy to the Cloud. ::: zone-end @@ -323,129 +311,123 @@ You can also deploy the samples to Azure using Teams Toolkit. To deploy, follow ## Prerequisites -To get started, ensure that you have the following tools: +Ensure that the following tools are installed and configured: | Install | For using... | | --- | --- | | [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript, TypeScript, and Python build environments. Use the latest version. | -| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.| -| [Python](https://www.python.org/) | Python is an interpreted and object-oriented programming language with dynamic semantics. Use versions between 3.8 to 4.0. | -| [Poetry](https://python-poetry.org/docs/#installing-with-pipx) | Dependency management and packaging tool for Python.| -| [Python VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | Provides rich support for Python on VSCode. | -|[Git](https://git-scm.com/downloads)|Git is a version control system that helps you manage different versions of code within a repository. | -| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | To collaborate with everyone, you work with them through apps for chats, meetings, and calls all in one place.| -| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal)| First create your OpenAI API key to use OpenAI's GPT. If you want to host your app or access resources in Microsoft Azure, you must create an Azure OpenAI service.| -| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | -| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with the appropriate permissions to install an app and [enable custom Teams apps and turn on custom app uploading](../../../concepts/build-and-test/prepare-your-o365-tenant.md#enable-custom-teams-apps-and-turn-on-custom-app-uploading). | +| [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | Extension that creates project scaffolding for your app. Use the latest version. | +| [Python](https://www.python.org/) | Interpreted and object-oriented programming language. Use versions between 3.8 and 4.0. | +| [Poetry](https://python-poetry.org/docs/#installing-with-pipx) | Dependency management and packaging tool for Python. | +| [Python VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | Provides rich support for Python development in VSCode. | +| [Git](https://git-scm.com/downloads) | Version control system to manage code versions. | +| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Platform to collaborate through chats, meetings, and calls. | +| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal) | Create your OpenAI API key for GPT. For Azure hosting, create an Azure OpenAI service. | +| [Microsoft Edge](https://www.microsoft.com/edge/) (recommended) or [Google Chrome](https://www.google.com/chrome/) | Browser with developer tools for debugging purposes. | +| [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Permission to install apps in Teams and enable custom Teams app uploading. |
-If you've already run the samples before or encountered a runtime error, follow these steps to start fresh: +If you have executed the samples before or experience a runtime error, perform these steps to ensure a fresh environment: -* Check all the `.env` and `env/.env.*.*` files in the sample and delete any automatically populated values to ensure that Teams Toolkit generates new resources for you. -* If you don’t want Teams Toolkit to generate the app ID and password, update the `BOT_ID` and `BOT_PASSWORD` in the `.env` file with your own values. -* Remove values or leave the values blank for **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** in the `.env` file to avoid conflicts. +* Inspect all `.env` and `env/.env.*.*` files in the sample and remove any auto-populated values so that Teams Toolkit generates new resources. +* If you prefer not to let Teams Toolkit generate the app ID and password, update the `BOT_ID` and `BOT_PASSWORD` in the `.env` file with your custom values. +* Remove or leave blank the **SECRET_BOT_PASSWORD** and **TEAMS_APP_UPDATE_TIME** in the `.env` file to avoid conflicts. -Teams Toolkit automatically provisions `BOT_ID` and `BOT_PASSWORD` resources. If you want to use your own resources, you need to manually add them to the `.env` file. Teams Toolkit doesn't auto-generate the following resources: +Teams Toolkit automatically provisions `BOT_ID` and `BOT_PASSWORD` resources. If you use your own resources, manually add them into the `.env` file. Note that Teams Toolkit does not auto-generate the following resources: * An Azure OpenAI or OpenAI key * A database or similar storage options ## Build and run the sample app -1. Go to the [sample](https://github.com/microsoft/teams-ai/tree/main/python/samples). +1. Navigate to the [sample](https://github.com/microsoft/teams-ai/tree/main/python/samples). -1. Clone the repository to test the sample app. +2. Clone the repository using this command: - ``` + ```cmd git clone https://github.com/microsoft/teams-ai.git ``` -1. Go to the **python** folder. +3. Change directory to the python folder: - ``` + ```cmd cd teams-ai/python ``` -1. Go to the folder where you cloned the repository and select **04.ai.c.actionMapping.lightBot**. All the files for the LightBot sample are listed under the **EXPLORER** section in Visual Studio Code. +4. In your file explorer, open the folder named 04.ai.c.actionMapping.lightBot. All files for the LightBot sample appear under the EXPLORER section in Visual Studio Code. -1. Under **EXPLORER**, duplicate the **sample.env** file and update the duplicate file to **.env**. +5. Within EXPLORER, duplicate the file named sample.env and rename the duplicate to .env. # [OpenAI key](#tab/OpenAI-key2) - Go to the `env` folder and update the following code in `./env/.env.local.user` file: + Open the `env` folder and update the following code in the `./env/.env.local.user` file: - ```text - SECRET_OPENAI_KEY= - ``` + ```text + SECRET_OPENAI_KEY= + ``` # [Azure OpenAI](#tab/Azure-OpenAI2) - Go to the `env` folder and update the following code in `./env/.env.local.user` file: - - ```text - SECRET_AZURE_OPENAI_KEY= - SECRET_AZURE_OPENAI_ENDPOINT= - ``` - - --- + Open the `env` folder and update the following code in the `./env/.env.local.user` file: -1. To install the following dependencies, go to **View** > **Terminal** and run the following commands: + ```text + SECRET_AZURE_OPENAI_KEY= + SECRET_AZURE_OPENAI_ENDPOINT= + ``` - |Dependencies |Command | - | --- | --- | - | python-dotenv | pip install python-dotenv | - | load-dotenv | pip install load-dotenv | - | teams-ai | pip install teams-ai | - | botbuilder-core | pip install botbuilder-core | + --- -1. Update `config.json` and `bot.py` with your model deployment name. +6. Install the required dependencies. Open the Terminal from View > Terminal and run these commands: -1. Go to **View** > **Command Palette...** or select **Ctrl+Shift+P**. + | Dependencies | Command | + | ----------------- | --------------------------------- | + | python-dotenv | pip install python-dotenv | + | load-dotenv | pip install load-dotenv | + | teams-ai | pip install teams-ai | + | botbuilder-core | pip install botbuilder-core | -1. Enter **Python: Create Environment** to create a virtual environment. +7. Update config.json and bot.py with your model deployment name. -1. To debug your app, select **F5**. +8. Open the Command Palette using View > Command Palette... or press Ctrl+Shift+P. - A browser tab opens the Teams web client to add the bot to your tenant. +9. Initiate Python: Create Environment to set up a virtual environment. -1. Select **Add**. +10. Press F5 to debug your app. - :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app."::: + A browser tab launches the Teams web client to add the bot to your tenant. - When the app is added, a dialog to select the required scope appears. +11. Click Add. -1. Select **Open** to open the app in personal scope. + :::image type="content" source="../../../assets/images/bots/lightbot-add.png" alt-text="Screenshot of the app details dialog to add the LightBot app." ::: - Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select **Go**. + When the app adds, a dialog displays to select the required scope. - :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes."::: +12. Choose Open to launch the app in personal scope. Alternatively, search for and select the required scope or choose a channel, chat, or meeting; then, follow the prompts to select Go. - A chat window opens. + :::image type="content" source="../../../assets/images/bots/bot-add-scope.png" alt-text="Screenshot of the scope selection dialog with the list of shared scopes." ::: -1. In the message compose area, send a message to invoke the bot. +13. In the chat window, send a message to invoke the bot. - :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output."::: + :::image type="content" source="../../../assets/images/bots/lightbot-output.png" alt-text="Screenshot shows an example of the LightBot output." ::: ::: zone-end ## Additional tools -You can also use the following tools to run and set up a sample: - -1. **Teams Toolkit CLI**: You can use the Teams Toolkit CLI to create and manage Teams apps from the command line. For more information, see [Teams Toolkit CLI set up instructions](https://github.com/microsoft/teams-ai/blob/main/getting-started/OTHER/TEAMS-TOOLKIT-CLI.md). - -1. **Bot Framework Emulator**: The [Bot Framework Emulator](https://github.com/microsoft/BotFramework-Emulator) is a desktop application that allows you to test and debug your bot locally. You can connect to your bot by entering the bot’s endpoint URL and Microsoft app ID and password. You can then send messages to your bot and see its responses in real-time. For more information, see [Bot Framework Emulator set up instructions](https://github.com/microsoft/teams-ai/blob/main/getting-started/OTHER/BOTFRAMEWORK-EMULATOR.md). +This section describes additional tools you can use to run and set up a sample: -1. **Manual setup**: If you prefer to set up your resources manually, you can do so by following the instructions provided by the respective services. For more information, see [manual set up instructions](https://github.com/microsoft/teams-ai/blob/main/getting-started/OTHER/MANUAL-RESOURCE-SETUP.md). +1. **Teams Toolkit CLI**: Use the Teams Toolkit CLI to create and manage Teams apps from the command line. For more information, refer to the "Teams Toolkit CLI set up instructions" provided in the documentation. +2. **Bot Framework Emulator**: Use the [Bot Framework Emulator](https://github.com/microsoft/BotFramework-Emulator) to test and debug your bot locally. Connect to your bot by entering the bot’s endpoint URL along with the Microsoft app ID and password. This tool allows you to send messages to your bot and observe responses in real time. Consult the "Bot Framework Emulator set up instructions" for further details. +3. **Manual setup**: If you prefer setting up resources manually, follow the instructions provided by each respective service. Refer to the "manual set up instructions" in the documentation for guidance. ## Next step -Choose one of the following as a next step: +Choose one of the following actions to continue your learning journey: > [!div class="nextstepaction"] -> If you want to learn how to use Teams AI library to create an AI-powered bot, select the following:
+> To learn how to create an AI-powered bot using Teams AI library, select: > [Build with Teams AI library](how-conversation-ai-get-started.md) > > [!div class="nextstepaction"] -> If you want to build a a custom engine agent using Teams Toolkit, select the following:
-> [Build a custom engine agent](../../../Teams-AI-library-tutorial.yml) +> To build a custom engine agent using Teams Toolkit, select: +> [Build a custom engine agent](../../../Teams-AI-library-tutorial.yml) \ No newline at end of file