Skip to content

Latest commit

 

History

History
 
 

04.ai.a.teamsChefBot

README.md

Microsoft Teams Conversational Bot with AI: Teams Chef

Please note: this sample is still being tweaked and therefore not setup with Teams Toolkit yet. We'll get it updated ASAP!

Summary

This is a conversational bot for Microsoft Teams that thinks it's a Chef to help you cook Teams apps. The bot uses the text-davinci-003 model to chat with Teams users and respond in a polite and respectful manner, staying within the scope of the conversation.

This sample illustrates basic conversational bot behavior in Microsoft Teams. The bot is built to allow GPT to facilitate the conversation on its behalf, using only a natural language prompt file to guide it.

It shows Teams AI SDK capabilities like:

Conversational bot scaffolding

 Throughout the 'index.ts' file you'll see the scaffolding created to run a simple conversational bot, like storage, authentication, and conversation state.

Open the panel below to learn fine-tuned details on how this sample works.

Natural language modelling

 Notice that outside of one '\history' command, the 'index.ts' file relies on GPT for all its natural language modelling - no code is specifically written to handle language processing. Rather, a 'predictionEngine' is defined to handle this for you: 
// Create prediction engine
const predictionEngine = new OpenAIPredictionEngine({
    configuration: {
        apiKey: process.env.OPENAI_API_KEY
    },
    prompt: path.join(__dirname, '../src/prompt.txt'),
    promptConfig: {
        model: 'text-davinci-003',
        temperature: 0.4,
        max_tokens: 2048,
        top_p: 1,
        frequency_penalty: 0,
        presence_penalty: 0.6,
        stop: [' Human:', ' AI:']
    },
    logRequests: true
});

Prompt engineering

 Inside the 'predictionEngine', a prompt file is defined: 
prompt: path.join(__dirname, '../src/prompt.txt'),

Open the 'prompt.txt' file to find descriptive prompt engineering that, in plain language and with minor training, instructs GPT how the bot should conduct itself and facilitate conversation:

prompts/chat/skprompt.txt

The following is a conversation with an AI assistant, its name is Teams Chef.
Teams Chef is an expert in Microsoft Teams apps development and the Human is junior developer learning Microsoft Teams development for the first time.
Teams Chef should always reply by explaining new concepts in simple terms using cooking as parallel concepts.
Teams Chef should always greet the human, ask them their name, and then guide the junior developer in his journey to build new apps for Microsoft Teams.

{{$history}}
Human: {{$input}}
AI:

Conversational session history

 Because this sample leaves the conversation to GPT, the bot simply facilitates user conversation as-is. But because it includes the 'prompt.txt' file to guide it, GPT will store and leverage session history appropriately. From the 'prompt.txt' file: 
Conversation history:
{{conversation.history}}

For example, let's say the user's name is "Dave". The bot might carry on the following conversation:

AI: Hi there! My name is Teams Chef. It's nice to meet you. What's your name?
DAVE: My name is Dave.
AI:Hi Dave! It's great to meet you. Let me help you get started with Microsoft Teams app development. Have you ever cooked before?
DAVE: No, not yet, why?
AI:Cooking is a great way to learn how to develop apps for Microsoft Teams. Just like cooking, developing apps requires you to have the right ingredients and tools, and to follow a set of instructions. It also requires creativity and problem-solving skills. So, let's get started! What would you like to learn first?
DAVE: Which kind of apps can I build for Microsoft Teams?
AI: Great question! You can build a variety of apps for Microsoft Teams, including bots, messaging extensions, tabs, and connectors. Bots are like the main course of your app - they provide the core functionality. Messaging extensions are like side dishes - they add extra features to your app. Tabs are like garnishes - they provide additional information or visuals. And connectors are like spices - they allow you to integrate with other services.

Notice that the bot remembered Dave's first message when responding to the second.

Localization across languages

 Because this sample leverages GPT for all its natural language modelling, the user can talk to an AI bot in any language of their choosing. The bot will understand and respond appropriately with no additional code required.

Prerequisites

Setting up the sample

  1. Clone the repository

    git clone https://github.com/Microsoft/teams-ai.git

  2. In the root JavaScript folder, install and build all dependencies

    cd teams-ai/js
yarn install
yarn build

  3. In a terminal, navigate to the sample root.

    cd teams-ai/js/samples/04.ai.a.teamsChefBot/

Multiple ways to test

The easiest and fastest way to get up and running is with Teams Toolkit as your development guide. To use Teams Toolkit to continue setup and debugging, please continue below.

Otherwise, if you only want to run the bot locally and build manually, please jump to the BotFramework Emulator section.

Using Teams Toolkit for Visual Studio Code

The simplest way to run this sample in Teams is to use Teams Toolkit for Visual Studio Code.

  1. Ensure you have downloaded and installed Visual Studio Code
  2. Install the Teams Toolkit extension
  3. Select File > Open Folder in VS Code and choose this sample's directory from the repo
  4. Using the extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps
  5. Select Debug > Start Debugging or F5 to run the app in a Teams web client.
  6. In the browser that launches, select the Add button to install the app to Teams.

If you do not have permission to upload custom apps (sideloading), Teams Toolkit will recommend creating and using a Microsoft 365 Developer Program account - a free program to get your own dev environment sandbox that includes Teams.

Using Teams Toolkit CLI

You can also use the Teams Toolkit CLI to run this sample.

  1. Install the CLI

    npm install -g @microsoft/teamsfx-cli

  2. Open a second shell instance and run ngrok tunneling service - point to port 3978

    ngrok http --host-header=rewrite 3978

  3. Copy the ngrok URL and put the URL and domain in the /env/env.local file

    BOT_ENDPOINT=https://{ngrok-url}.ngrok.io
BOT_DOMAIN={ngrok-url}.ngrok.io

  4. In the repository directory, run the Teams Toolkit CLI commands to automate the setup needed for the app

    cd teams-ai/js/samples/04.ai.a.teamsChefBot/
teamsfx provision --env local

  5. Next, use the CLI to validate and create an app package

    teamsfx deploy --env local

  6. Finally, use the CLI to preview the app in Teams

    teamsfx preview --env local

Manually upload the app to a Teams desktop client

If you used Teams Toolkit in the above steps, you can upload a custom app to a desktop client using the /appPackage/appPackage.local.zip file created by the tools and skip to step 6.

  1. In a terminal, navigate to teams-ai/js/samples/04.ai.a.teamsChefBot/

    cd teams-ai/js/samples/04.ai.a.teamsChefBot/

  2. Run ngrok tunneling service - point to port 3978

    ngrok http --host-header=rewrite 3978

  3. Create Bot Framework registration resource in Azure

    • Use the current https URL you were given by running ngrok. Append with the path /api/messages used by this sample.
    • Ensure that you've enabled the Teams Channel

  4. Update the .env configuration for the bot to use the Microsoft App Id and App Password from the Bot Framework registration. (Note the App Password is referred to as the "client secret" in the Azure Portal and you can always create a new client secret anytime.)

  5. This step is specific to Teams.

    • Edit the manifest.json contained in the appPackage folder to replace your Microsoft App Id (that was created when you registered your bot earlier) everywhere you see the place holder string ${{TEAMS_APP_ID}} (depending on the scenario the Microsoft App Id may occur multiple times in the manifest.json). If you haven't created an Azure app service yet, you can use your bot id for the above. You're bot id should be pasted in where you see ${{BOT_ID}}. Replace everywhere you see ${{BOT_DOMAIN}} with the domain part of the URL created by your tunneling solution.
    • Zip up the contents of the appPackage folder to create a manifest.zip

  6. Run your app from the command line:

    yarn start

  7. Upload the app file (manifest.zip created in the previous step) in Teams.

Testing in BotFramework Emulator

Bot Framework Emulator Allows testing bots independently from Channels when developing your bot. If you do not wish to use Teams Toolkit, please follow the steps below to test your bot in Emulator.

Directions

  1. Download and install Bot Framework Emulator
  2. Launch Bot Framework Emulator
  3. Run the app you are in the directory for.
yarn start
  1. Add your app's messaging endpoint to the "Open a Bot" dialog. The endpoint your localhost endpoint with the path /api/messages appended. It should look something like this: http://localhost:3978/api/messages.

Bot Framework setup menu with a localhost url endpoint added under Bot URL

  • In order to test remote apps, you will need to use a tunneling service like ngrok along with an Microsoft App Id and password pasted into the dialog shown above.
  • Channel-specific features (For example, Teams Message Extensions) are not supported in Emulator and therefore not fully-testable.
  • If you are building, testing and publishing your app manually to Azure, you will need to put your credentials in the .env file.

Interacting with the bot

Interacting with the bot is simple - talk to it! You can invoke it by using @ mention and talk to it in plain language.

The bot uses the text-davinci-003 model to chat with Teams users and respond in a polite and respectful manner, staying within the scope of the conversation. This is possible due to the skprompts.txt file's contents.

Deploy the bot to Azure

To learn more about deploying a bot to Azure, see Deploy your bot to Azure for a complete list of deployment instructions or use the Teams Toolkit to help you: Deploy a Microsoft Teams app to Azure by using Teams Toolkit for Visual Studio Code

Further reading