Extend Microsoft 365 Copilot using a message extension

Completed

When you build a message extension for Microsoft Teams, you can also use it as a plugin for Microsoft 365 Copilot. In this unit, you learn how to build a message extension that is suitable for use as a plugin for Copilot.

Note

At the time of publishing this module, Plugins for Microsoft 365 Copilot are in preview and only work in Microsoft 365 Chat in Microsoft Teams.

Extending Microsoft 365 Copilot

Microsoft 365 Copilot is a powerful productivity tool that uses a combination of Microsoft 365 apps, Microsoft Graph, and large language models (LLMs) to help users complete tasks.

Copilot uses the apps and data within the Microsoft 365 ecosystem, but can be extended to use the functionality of external data, apps, and services. You can extend Copilot with plugins, Graph connectors, and agents.

Plugins for Microsoft 365 Copilot

When you build a plugin for Copilot, you extend the set of skills available to Copilot, enabling real-time use of your external data, app, or service to respond to user prompts.

For example, Copilot can use plugins to:

• Retrieve real-time information. For example, the # of work items assigned to an employee.
• Retrieve knowledge-based information. For example, the team’s design files in Figma.
• Perform actions on behalf of the user. For example, creating a Jira ticket.

Your users can do so much more than just getting search results. Since Copilot is powered by Generative AI, it can understand, summarize, predict, and generate content across a multitude of Microsoft 365 applications. Users can ask all sorts of follow-up questions and complete additional tasks using the results of the interaction with your plugin.

For example, suppose you are a developer at Northwind Traders and you built an inventory tool with a message extension. The tool works in Teams and Copilot. In Teams, the search command is invoked from the Compose message area, allowing a user to search the Northwind inventory for the stock of carrot soup cans. In Microsoft 365 Copilot, users can interact by asking a question using natural language, asking how much stock left for carrot soup cans.

Microsoft Graph connectors

Similarly to plugins, Graph connectors expand the capabilities of Copilot by connecting external data to Microsoft Graph. This grounds Copilot with your data, providing semantic understanding of your content and relationships and delivering highly personalized results to users.

Graph connectors are not limited to Microsoft 365 Copilot. Other Microsoft 365 intelligent experiences, including Microsoft Search, Context IQ, and the Microsoft 365 app, also use Graph connector content.

How to build plugins

If you have an existing search-based message extension for Microsoft Teams, it can be used as a plugin for Copilot. Copilot knows how to interact with message extensions and translate user requests in natural language into actions that your message extension can fulfill. Copilot recognizes the search commands that you implement as skills and will invoke your plugin when appropriate.

Note

At the time of publishing, Teams message extension plugin support is limited to search commands. Support for action commands is coming soon.

Guidelines and best practices

Review the following guidance to ensure your message extension works optimally as a plugin for Microsoft 365 Copilot:

Write clear, concise, and accurate descriptions

Copilot uses your app manifest to determine when to use your plugin, what parameters are required, and what to expect from responses. Specifying concise and accurate descriptions in your app manifest is critical to ensuring Copilot knows when and how to invoke your extension as a plugin. Accurate descriptions increase the chances of Copilot selecting your plugin to perform the appropriate skill.

App descriptions are used by Copilot to determine when it's appropriate to use your plugin. Your app's long description must clearly describe the functionality of the app. The short description must briefly describe the app's functionality in a natural language.

Keep in mind the following guidelines for app descriptions:

• Anti-Compete: Avoid using the name of any other plugin in both short and long descriptions.
• Responsible AI: Avoid using inappropriate or offensive keywords.
• Prompt injections: Ensure that the text doesn't lead to prompt injections. Additionally, the description must not contain symbols or text that indicate that it can be used as code for prompt injection. Avoid using phrases, functions, and code that call an app recurrently.

Here's an example of the app descriptions in the app manifest for a task tracking app:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "version": "1.0.0",
  "manifestVersion": "1.16",
  "id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
  "name": {
    "short": "Tasks",
    "full": "Contoso Tasks"
  },
  "description": {
    "short": "Create, search, view tickets, bugs, and projects",
    "full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
  },

Command descriptions for your message extension commands help identify the skills your app enables for Copilot. These descriptions are used to interpret the user's prompt into an intent and then map that to the most relevant skill available to Copilot.

Search command descriptions should:

• Focus on what and how the command searches (detailed list) in natural language.
• Include verbs and synonyms, if applicable.
• Focus on keywords that are likely to be used in the search function of your native apps.

Here's an example of a command description in the app manifest for a task tracking app:

"commands": [
        {
          "id": "Search",
          "type": "query",
          "title": "Tasks",
          "description": "Search for high priority tasks related to Northwind that are due tomorrow.",
          "initialRun": true,
          "fetchTask": false,
          "context": [
            "commandBox",
            "compose",
            "message"
          ],

Parameter descriptions help Copilot understand the parameters required for your extension/plugin. Describe the expected input for each parameter, including format or type.

In Teams, message extension commands can only support queries with one parameter at a time. When used as a plugin, message extension search commands support up to five parameters.

Here's an example of search command parameters defined in the app manifest for a task tracking app:

"parameters": [
    {
        "name": "Name",
        "title": "Project or Task Name",
        "description": "Project name or task name as keyword",
        "inputType": "text"
    },
    {
        "name": "Time",
        "title": "Time",
        "description": "Date or number of days for which to find tasks. Output: Number",
        "inputType": "text"
    },
    {
        "name": "Priority",
        "title": "Priority",
        "description": "Priority of tasks. Acceptable values: high, medium, low, NA ",
        "inputType": "text"
    }]

Note

For Copilot, a search-based message extension must support compound utterances to perform deep retrieval of accurate information. To enable compound utterances, we recommend that you expand the scope of search to handle two or more search parameters simultaneously by enabling multi-parameter support in app manifest (previously called Teams app manifest).

Follow guidelines for the adaptive card response

The adaptive cards your message extensions respond to users with must function effectively, appear rich, and meet specific requirements. Learn more about the adaptive card requirements for plugins here.

More tips

Follow these best practices to improve the user experience for your plugin:

• Test your plugin. - AI can produce unexpected results. Be sure to test your plugin with Copilot to ensure it produces expected results and identify opportunities to improve the clarity of your descriptions.
• Use an API manager. Using an API manager, you can
  • Set policies to govern plugin usage
  • Prevent unintended API usage spikes by setting up rate limiting policies
  • Monitor API logs and metrics with Azure Application Insights