diff --git a/docs/assets/images/Copilot_orchestrator_sequence_v2.png b/docs/assets/images/Copilot_orchestrator_sequence_v2.png new file mode 100644 index 0000000..ecbde0e Binary files /dev/null and b/docs/assets/images/Copilot_orchestrator_sequence_v2.png differ diff --git a/docs/assets/images/connectors-gallery.png b/docs/assets/images/connectors-gallery.png new file mode 100644 index 0000000..cb756e9 Binary files /dev/null and b/docs/assets/images/connectors-gallery.png differ diff --git a/docs/data-privacy-security.md b/docs/data-privacy-security.md index 7ad2ae2..6e60fdf 100644 --- a/docs/data-privacy-security.md +++ b/docs/data-privacy-security.md @@ -4,12 +4,12 @@ description: Learn how to protect your customer's data when you extend Microsoft author: erikadoyle ms.author: edoyle ms.topic: overview -ms.date: 11/15/2023 +ms.date: 06/26/2024 --- # Data, Privacy, and Security considerations of extending Copilot for Microsoft 365 -When you extend Copilot's repertoire of skills with a plugin, queries based on your prompts, conversation history, and Microsoft 365 data can be shared with the plugin to generate a response or complete a command. When you extend Copilot with a Microsoft Graph connector, your external data is ingested into Microsoft Graph and remains in your tenant. This article will outline data privacy and security considerations for developing different Copilot extensibility solutions, both in-house and as a commercial developer. +When you extend Copilot's repertoire of skills with a plugin, queries based on your prompts, conversation history, and Microsoft 365 data can be shared with the plugin to generate a response or complete a command. When you extend Copilot with a Microsoft Graph connector, your external data is ingested into Microsoft Graph and remains in your tenant. This article outlines data privacy and security considerations for developing different Copilot extensibility solutions, both in-house and as a commercial developer. :::image type="content" source="assets/images/validation-principles.png" alt-text="Diagram key considerations for developing Copilot extensibility: Enterprise security and trust, Responsible AI, High-quality user experience, High-value functionality" border="false"::: @@ -23,13 +23,13 @@ Prompts, responses, and data accessed through Microsoft Graph aren't used to tra ## Plugins -Similar to traditional [Teams apps](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#privacy-policy) and [Power Platform connectors](/connectors/custom-connectors/certification-submission#step-4b-product-or-end-service-metadata), plugins for Microsoft Copilot are individually governed by their terms of use and privacy policies. As a plugin developer, you are responsible for securing your customer's data within the bounds of your service and providing information on your policies regarding users' personal information. Admins and users can then view your [privacy policy](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#privacy-policy) and [terms of use](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#terms-of-use) in the app store before choosing to add or use your plugin as a Copilot data source. +Similar to traditional [Teams apps](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#privacy-policy) and [Power Platform connectors](/connectors/custom-connectors/certification-submission#step-4b-product-or-end-service-metadata), plugins for Microsoft Copilot are individually governed by their terms of use and privacy policies. As a plugin developer, you're responsible for securing your customer's data within the bounds of your service and providing information on your policies regarding users' personal information. Admins and users can then view your [privacy policy](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#privacy-policy) and [terms of use](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#terms-of-use) in the app store before choosing to add or use your plugin as a Copilot data source. When you plug in your app to Copilot as a plugin, your external data stays within your app; it *does not* flow into Microsoft Graph or is used to train Microsoft Copilot LLMs. Copilot does, however, generate a search query to send to your plugin on the user's behalf based on their prompt and conversation history with Copilot, and data the user has access to in Microsoft 365. Message extension plugins use the same [authentication process for Teams message extensions](/microsoftteams/platform/bots/how-to/authentication/bot-sso-overview). -Power Platform plugins use the same [authentication process for custom connectors](/connectors/custom-connectors/azure-active-directory-authentication). +Power Platform connector plugins use the same [authentication process for custom connectors](/connectors/custom-connectors/azure-active-directory-authentication). ## Considerations for line-of-business developers @@ -44,11 +44,11 @@ Copilot for Microsoft 365 only shares data with and searches in plugins or conne ## Considerations for independent software vendors -Message extension plugins are packaged and distributed in the same way as Microsoft Teams apps that are integrated to run across the Microsoft 365 ecosystem. Microsoft Graph connectors can also be packaged and distributed in the same way as Teams apps. +Power Platform connectors as Copilot plugins are [certified](/connectors/custom-connectors/certification-submission) and [packaged](/connectors/custom-connectors/certification-submission#connector-and-plugin-packaging-guide) in the same way as regular [Power Platform Connectors](/connectors/custom-connectors/certification-submission). They can then be submitted to [Microsoft Partner Center](https://partner.microsoft.com) through the **Microsoft 365 and Copilot program** as a **Power Platform Connector**. -Power Platform plugins are certified and distributed in the same way as Power Platform connectors, by first publishing your connector to the [Power Platform Connectors](https://github.com/microsoft/PowerPlatformConnectors) open source repository, and then submitting its information to Microsoft. +Message extension plugins are packaged and distributed in the same way as [Teams apps](/microsoftteams/platform/concepts/build-and-test/apps-package) that are [integrated to run across the Microsoft 365 ecosystem](/microsoftteams/platform/m365-apps/overview). Microsoft Graph connectors can also be packaged and distributed in the same way as Teams apps. -Submission of your app package to the Microsoft Partner Center *Microsoft 365 and Copilot* program requires meeting [certification policies](./publish.md#microsoft-365-and-copilot-program) for acceptance to Microsoft 365 in-product stores. Microsoft Commercial Marketplace certification policies and Teams Store validation guidelines regarding privacy, security, and responsible AI include: +Submission of your app package to the Microsoft Partner Center *Microsoft 365 and Copilot* program requires meeting [certification policies](./publish.md#microsoft-365-and-copilot-program) for acceptance to Microsoft 365 in-product stores. Microsoft Commercial Marketplace certification policies and applicable Teams Store validation guidelines regarding privacy, security, and responsible AI include: | Commercial marketplace certification policy | Teams store guidelines | |----------|-----------| @@ -62,10 +62,12 @@ Submission of your app package to the Microsoft Partner Center *Microsoft 365 an | [1140.4.1 General](/legal/marketplace/certification-policies#1-apps-with-artificial-intelligenceai-generated-content-must-meet-below-requirements) | [Responsible AI checks](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines?branch=pr-en-us-9402#teams-apps-extensible-as-microsoft-365-chat-plugin) | | [1140.9 Teams apps extensible as plugins for Microsoft Copilot for Microsoft 365](/legal/marketplace/certification-policies#11409-teams-apps-extensible-as-microsoft-365-copilot-plugin) | [Teams apps extensible as plugins for Microsoft Copilot](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines#teams-apps-extensible-as-microsoft-365-chat-plugin) | -Submission to the Microsoft 365 and Copilot program is currently limited to [verified publishers](/entra/identity-platform/publisher-verification-overview). This provides end-users and organizational admins assurance that the publisher of an app has been verified as authentic by Microsoft. +For Microsoft Graph connectors (packaged as Teams apps), submission to the Microsoft 365 and Copilot program is currently limited to [verified publishers](/entra/identity-platform/publisher-verification-overview). This provides end-users and organizational admins assurance that the publisher of an app has been verified as authentic by Microsoft. ## See also +[Data, Privacy, and Security for Microsoft Copilot (Microsoft 365 admin)](/copilot/microsoft-365/microsoft-365-copilot-privacy) + [Publish plugins and connectors for Microsoft Copilot for Microsoft 365](publish.md) [Microsoft commitment to responsible AI](https://www.microsoft.com/ai/responsible-ai) diff --git a/docs/ecosystem.md b/docs/ecosystem.md index 345d2ca..4071161 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -33,7 +33,7 @@ This article will walk you through the resources of the Microsoft 365 ecosystem ## Plugins and connectors work across Microsoft 365 experiences -There are over 350 million daily active users across applications in the Microsoft 365 ecosystem, including Teams, Outlook, Word, Excel, Power Point, and the Microsoft 365 app. When you write a plugin or connector, it can reach all the places Copilot runs across Microsoft 365. +There are over 350 million daily active users across applications in the Microsoft 365 ecosystem, including Teams, Outlook, Word, Excel, Power Point, and the Microsoft 365 app. When you write a plugin or connector, it can reach all the places Copilot extensibility is supported across Microsoft 365. . . . but that's not all! Depending on the [way you extend Copilot](./decision-guide.md), your plugin or connector also runs outside of Copilot experiences. The following table lists alternate ways the skills and knowledge from your plugins and connectors are available to end-users within an organization: diff --git a/docs/feedback.md b/docs/feedback.md index 9cfa775..ebdb854 100644 --- a/docs/feedback.md +++ b/docs/feedback.md @@ -13,12 +13,12 @@ In this doc you will find help and resources needed for Copilot for Microsoft 36 ## Developer support channels -To inquire about general questions related to Copilot and Copilot samples use the following community groups. Use the [Microsoft 365 Admin Center](https://admin.microsoft.com/Adminportal/Home#/homepage) for any business-critical issues that need SLA(service level agreement) based support and [Microsoft Q&A](/answers/tags/465/copilot-m365.html) for general questions. +To inquire about general questions related to Copilot and Copilot samples use the following community groups. Use the [Microsoft 365 Admin Center](https://admin.microsoft.com/Adminportal/Home#/homepage) for any business-critical issues that need SLA(service level agreement) based support and [Microsoft Q&A](/answers/tags/466/copilot-m365-development) for general questions. | **Support channel category** | **Channel** | |:------------|:------------| | Microsoft Copilot for Microsoft 365 service issues, development issues, and limited advisory support. | If you have a Premier/Unified support agreement for Microsoft 365, visit the [Microsoft 365 Admin Center](https://admin.microsoft.com/Adminportal/Home#/homepage) and use the Support menu to open a service request. | -| General questions about Microsoft Copilot for Microsoft 365 | If you have general questions on Microsoft Copilot for Microsoft 365, submit your questions on [Microsoft Q&A](/answers/tags/465/copilot-m365.html). | +| General questions about Microsoft Copilot for Microsoft 365 | If you have general questions on Microsoft Copilot for Microsoft 365, submit your questions on [Microsoft Q&A](/answers/tags/466/copilot-m365-development). | | Developer community help | [Microsoft Q&A](/answers/) exists as the home of technical questions and answers for Microsoft products. Use the [Microsoft Copilot for Microsoft 365 Development](/answers/tags/466/copilot-m365-development.html) tag to post questions, connect with other developers, and submit answers. | | Extensibility samples | Submit issues and ask general questions related to samples using the respective Microsoft Copilot for Microsoft 365 [extensibility samples](samples.md) GitHub repositories. | diff --git a/docs/includes/preview-disclaimer.md b/docs/includes/preview-disclaimer.md index d9a120f..4c6d3ad 100644 --- a/docs/includes/preview-disclaimer.md +++ b/docs/includes/preview-disclaimer.md @@ -7,5 +7,5 @@ ms.topic: include > [!IMPORTANT] > -> - Plugins for Microsoft Copilot for Microsoft 365 are in public preview and only work in Microsoft 365 Chat in Microsoft Teams. +> - Plugins for Microsoft Copilot for Microsoft 365 are in public preview and only work in Copilot chat in Microsoft Teams. > - The capability is enabled by default in all Microsoft 365 Copilot licensed tenants. Admins can disable this functionality on a user and group basis and control how individual plugins are approved for use, and which plugins are enabled. For details see: [Manage Plugins for Copilot in Integrated Apps](/microsoft-365/admin/manage/manage-plugins-for-copilot-in-integrated-apps?context=/microsoft-365-copilot/extensibility/context). diff --git a/docs/openapi-document-guidance.md b/docs/openapi-document-guidance.md index ee6142e..1a6b76e 100644 --- a/docs/openapi-document-guidance.md +++ b/docs/openapi-document-guidance.md @@ -3,7 +3,7 @@ title: How to make an OpenAPI document effective in extending Copilot capabiliti description: Learn what makes an OpenAPI description most effective for extending Copilot skills author: njaci1 ms.author: kelvinnjaci -ms.topic: openapi +ms.topic: how-to ms.date: 05/21/2024 --- @@ -11,13 +11,13 @@ ms.date: 05/21/2024 Plugins let Microsoft Copilot work with web services and get real-time information. Copilot uses this information to extend its skills. With a plugin, a user can bring real-time data from their line of business (LOB) system on to the Copilot. -A plugin is comprised of a web service, its OpenAPI description, and a manifest file. The plugin manifest informs Copilot about the plugin's capabilities. The plugin manifest includes an OpenAPI description for the web service. The OpenAPI description is particularly important because it describes to Copilot how to connect to the web service. For optimal plugin performance with Copilot, provide a clear and meaningful OpenAPI description. This document will explain the elements that make an OpenAPI description effective for a plugin that extends Copilot. +A plugin is comprised of a web service, its OpenAPI description, and a manifest file. The plugin manifest informs Copilot about the plugin's capabilities. The plugin manifest includes an OpenAPI description for the web service. The OpenAPI description is important because it describes to Copilot how to connect to the web service. For optimal plugin performance with Copilot, provide a clear and meaningful OpenAPI description. This document explains the elements that make an OpenAPI description effective for a plugin that extends Copilot. Here, we presume that you have a web service and an OpenAPI description for the web service. **OpenAPI Validation**: A good first step is to verify that your OpenAPI description follows the rules of the [OpenAPI Specification](https://swagger.io/resources/open-api/). You can use [Hidi](https://github.com/microsoft/OpenAPI.NET/blob/vnext/src/Microsoft.OpenApi.Hidi/readme.md), a command line tool that can validate OpenAPI descriptions among other use cases, or any other tool of choice. A valid OpenAPI description not only works well with Copilot but also makes sure that your OpenAPI description can work with other tools. -**The info section**: The description field is optional in the OpenAPI specification, but it is essential for an OpenAPI description that is meant to extend Copilot skills. Copilot needs the description field to know what the API does and when to use the plugin. Always have a description field and make it brief but clear. For example, here is an info section of a repairs shop web service OpenAPI description. +**The info section**: The description field is optional in the OpenAPI specification, but it's essential for an OpenAPI description that is meant to extend Copilot skills. Copilot needs the description field to know what the API does and when to use the plugin. Always have a description field and make it brief but clear. For example, here's an info section of a repairs shop web service OpenAPI description. ```yaml info: @@ -30,7 +30,7 @@ info: Additionally add a meaningful description of each operation supported by your API. After Copilot chooses to use a plugin based on the user's prompt and the plugin description, it searches through the descriptions of the paths to determine the endpoint to use to satisfy the user's request. -Operation IDs are shown during debugging as functions to indicate which operations Copilot is attempting to execute. Here is a sample of an openAPI document and a sample of the corresponding debugger output: +Operation IDs are shown during debugging as functions to indicate which operations Copilot is attempting to execute. Here's a sample of an openAPI document and a sample of the corresponding debugger output: ```yaml paths: @@ -47,7 +47,7 @@ Debugger output: **Parameters:** If an operation supported by your API takes in parameters, include the parameters in the OpenAPI description. Include a description field for each parameter to briefly describe it, and where necessary, give an example of the parameter's usage. Parameters are use by Copilot to get all the required information from a user's prompt for making a request to the API. -Here is an example: +Here's an example: ```yaml parameters: diff --git a/docs/orchestrator.md b/docs/orchestrator.md index 497f98d..d29c411 100644 --- a/docs/orchestrator.md +++ b/docs/orchestrator.md @@ -8,15 +8,16 @@ ms.date: 06/25/2024 --- + # How Copilot for Microsoft 365 decides which plugin to use Microsoft Copilot for Microsoft 365 is your personal assistant for work. It helps with various general **tasks**, such as writing, summarizing, researching, and more. Copilot has different **skills** that correspond to these different types of tasks. For example, Copilot can summarize action items from a meeting, suggest edits to a file, or track down resources and experts on a given topic within your organization. Each skill has its own parameters and outputs that are tailored to the specific task. -Like any copilot, Copilot for Microsoft 365 is trained with data at a point in time. To retrieve and process new and real-time information, especially data that's specific to your organization and workflows, Copilot requires *plugins*. **Plugins** extend Copilot for Microsoft 365's skills and utility for end users, enabling it to choose the right skill from thousands. +Like any copilot, Copilot for Microsoft 365 is trained with data at a point in time. To retrieve and process new and real-time information, especially data that's specific to your organization and workflows, Copilot requires _plugins_. **Plugins** extend Copilot for Microsoft 365's skills and utility for end users, enabling it to choose the right skill from its repertoire. But how does Copilot know which skill to use when you ask for help? How does it interpret your request and match it to the best skill available? That's the job of the Copilot for Microsoft 365 **orchestrator**. -This article will explain the logic behind Copilot's skill selection process and how you can ensure Copilot employs your plugin at every opportunity it can benefit your users. +This article will explain the logic behind Copilot's skill selection process and how you can ensure Copilot employs your plugin at every opportunity to benefit your users. [!INCLUDE [preview-disclaimer](includes/preview-disclaimer.md)] @@ -28,56 +29,66 @@ The orchestration layer represents the interface between foundation LLMs and the :::image type="content" source="assets/images/copilot-stack.png" alt-text="Diagram of the Microsoft Copilot technology stack. From bottom to top: Microsoft Cloud, AI infrastructure, Your data, Foundation models, AI orchestration, Microsoft Copilots | Your copilots, Teams AI Library, Graph connectors, Plugin extensibility"::: -The following chart illustrates how the Copilot for Microsoft 365 orchestrator selects the right plugin, with the right skill, at the right time, even when there are thousands of options to choose from. +The following chart illustrates how the Copilot for Microsoft 365 orchestrator selects the right plugin, with the right skill, at the right time, even when there are multiple options to choose from. -:::image type="content" source="assets/images/orchestrator-sequence.png" alt-text="Visual illustration of the sequential steps in the text following this image."::: +:::image type="content" source="assets/images/copilot_orchestrator_sequence_v2.png" alt-text="Visual illustration of the sequential steps in the text following this image." lightbox="assets/images/copilot_orchestrator_sequence_v2.png"::: 1. **Natural language input** - The user types a prompt to Copilot through Microsoft 365 chat. +The user submits a query to Copilot, such as "What tickets are assigned to me right now?" -2. **Search for relevant tools** +2. **Preliminary checks** - The Copilot orchestrator searches its tool catalog of installed and enabled plugins for an initial list of relevant skills. +Copilot conducts several checks on the query, including responsible AI checks and security measures to ensure it doesn’t pose any risks. If the query fails any of these checks, Copilot will terminate the interaction. 3. **Reasoning** - Copilot draws upon the combined knowledge of its LLM and your organizational data from Microsoft Graph to analyze the request and determine the context of the user. It then breaks down the user's prompt into intents, or goals. Each goal is then broken into tasks. +The Copilot orchestrator formulates a plan comprising of multiple actions that it will perform in an attempt to respond to the user's prompt. + +3a. **Context and Tool Selection:** + +The orchestrator retrieves the user's conversation context from the context store and integrates data from Microsoft Graph to refine the context. It then adjusts the initial query based on this updated context and forwards it to the LLM (large language model) to guide the next steps. +The LLM may proceed to generating a response using Copilot’s built-in capabilities, or it may determine that additional data is necessary. +If further information is needed, the orchestrator does a search for the plugins(tools) with the right skill for the task from the user's enabled plugins based on the plugins descriptions and their functions descriptions. -4. **Mapping user's intent to slots** +3b. **Function Matching and Parameter Determination:** - The orchestrator maps the user's tasks to plugin skills and/or built-in Copilot skill functions, mapping implicit constraints from the user's prompt to the slots (parameter values) required to execute each of the identified skills. +The orchestrator formulates a new prompt incorporating the user’s initial query, the updated context, and the selected plugins, and presents it to the LLM. The LLM evaluates the input and specifies the optimal plugin and function within that plugin to address the task. It then provides the orchestrator with the necessary function details and parameters required to gather the needed information. -5. **Execute tool** +3c. **Tool execution:** - Copilot and its plugins are called to execute their selected skills. +The orchestrator uses the response from the LLM to construct an API request and send the request to the tool executor, which securely retrieves the requested information located outside of Copilot's infrastructure. It executes the request and sends the results back to the orchestrator for further processing. -6. **Generate summary** +3d. **Result Analysis and Response Formulation:** - Copilot merges, filters, or ranks the responses from different assistants, and generates a single response for the user. +The orchestrator integrates the API response into the ongoing context and consults the LLM in a continuous reasoning loop until the LLM deems it appropriate to generate a final response. -7. **Natural language output** +4. **Responding** - Finally, Copilot delivers the response to the user and updates the conversation state. Copilot is ready for its next prompt. +The orchestrator compiles all the information gathered during the reasoning process and submits it to the LLM to create a final response. After ensuring the response complies with Responsible AI guidelines, it sends the response back to the orchestrator, which logs it in the context store and delivers it to the user via the Copilot UI. -If you imagine a user's prompt to Copilot like a construction project, then the Copilot orchestrator is the *general contractor*, who coordinates and organizes the work of the specialist *subcontractors*, your plugins. Similar to a general contractor, the orchestrator is responsible for ensuring the project is "completed" according to specifications implied by the user's input (in other words, that Copilot's response satisfies the user's intent in their request). +5. **Natural language output** -However, its the responsibility of each plugin to provide Copilot with an accurate description of its skills and to execute its skills effectively. This will instill a sense of trust in your users and ensure Copilot will call your plugin each time its skills are needed. The next section provides more details on how to optimize your plugin for the orchestrator to find and use. +Finally, the orchestrator delivers the response to the user and updates the conversation state. Copilot is ready for its next prompt. -## Plugin search optimization +If you imagine a user's prompt to Copilot like a construction project, then the Copilot orchestrator is the _general contractor_, who coordinates and organizes the work of the specialist _subcontractors_, your plugins. Similar to a general contractor, the orchestrator is responsible for ensuring the project is "completed" according to specifications implied by the user's input (in other words, that Copilot's response satisfies the user's intent in their request). -Copilot for Microsoft 365 can uniquely choose the right skill from thousands. But how can you make sure Copilot will choose *your plugin* to provide the right skill? +However, its the responsibility of each plugin to provide Copilot with an accurate description of its skills and to execute its skills effectively. This will instill a sense of trust in your users and ensure Copilot will call your plugin each time its skills are needed. The next section provides more details on how to optimize your plugin and your OpenAPI documents for the orchestrator to find and use. + +## Plugin optimization + +Copilot for Microsoft 365 can uniquely choose the right skill from the many in its repertoire. But how can you make sure Copilot will choose _your plugin_ to provide the right skill? The answer lies in how you describe your plugin, its skills, and the parameters for skill execution. Specifying concise and accurate descriptions in your plugin manifest is critical to ensuring the Copilot orchestrator knows when and how to invoke your plugin. ### Matching mechanisms -When a user submits a query to Copilot, the orchestrator searches its full catalog of skills (*functions*) from installed plugins to identify up to five skills which best match the query. The orchestrator first tries to match on exact words (**lexical match**) and expands its search scope as needed to include matches on descriptive meanings (**semantic match**), working from specific function names to general plugin descriptions, until all five function candidate slots are filled. Specifically, here is the hierarchy of matching mechanisms for Copilot plugin function selection: +When a user submits a query to Copilot, the orchestrator searches its full catalog of skills (_functions_) from installed plugins to identify up to five skills which best match the query. The orchestrator first tries to match on exact words (**lexical match**) and expands its search scope as needed to include matches on descriptive meanings (**semantic match**), working from specific function names to general plugin descriptions, until all five function candidate slots are filled. Specifically, here is the hierarchy of matching mechanisms for Copilot plugin function selection: 1. Lexical match on function name. -1. Semantic match on function description. -1. Lexical match on plugin name (adds all plugin functions to candidate list). *This step is currently in private preview.* -1. Semantic match on plugin name (adds all plugin functions to candidate list). +2. Semantic match on function description. +3. Lexical match on plugin name (adds all plugin functions to candidate list). **This step is currently in private preview.** +4. Semantic match on plugin name (adds all plugin functions to candidate list). The orchestrator works through the above list until all five function candidate slots are filled. @@ -162,7 +173,7 @@ The following table lists the short description examples for various plugin scen #### [General](#tab/general) -**Description**: Search and share stock quotes. +**Description**: Search and share stock quotes. **App description example:** @@ -441,7 +452,6 @@ Advanced search: Find top 10 stocks in NASDAQ with P/E less than 30 and P/B less --- - ## Next step Learn best practices for optimizing plugin discoverability and usefulness in Copilot for Microsoft 365. diff --git a/docs/overview-graph-connector.md b/docs/overview-graph-connector.md index 43f4328..4726f5c 100644 --- a/docs/overview-graph-connector.md +++ b/docs/overview-graph-connector.md @@ -33,6 +33,18 @@ If users desire to dive deeper into the referenced content, they can click on on ![A screenshot of Graph connectors reference list in Copilot for Microsoft 365](assets/images/connectors-copilot-logo.png) +## Microsoft Graph connectors gallery + +The [Microsoft Graph connectors gallery](https://www.microsoft.com/microsoft-search/connectors) includes a brief description of each of the connectors created by Microsoft and our partners, and a link to each partner's website. + +With more than 100 connectors currently available, you can connect to popular Microsoft and non-Microsoft services such as Azure services, Box, Confluence, Google services, MediaWiki, Salesforce, ServiceNow, and many more. + +Visit the connectors gallery to find all the information you need to get started using connectors. + +
+ +![Image showing the new connectors gallery.](assets/images/connectors-gallery.png) + ## Create your own custom Microsoft Graph connection You can use the [Microsoft Graph connectors APIs](/graph/connecting-external-content-connectors-api-overview?context=microsoft-365-copilot/extensibility/context) to build custom Microsoft Graph connections that index content from line-of-business data sources into Microsoft Graph. You can use the Microsoft Graph connectors APIs to create and manage external Microsoft Graph connections, define and register the schema of external data types, ingest external data items into Microsoft Graph, and sync external groups. diff --git a/docs/plugin-guidelines.md b/docs/plugin-guidelines.md index 70e1271..a347b68 100644 --- a/docs/plugin-guidelines.md +++ b/docs/plugin-guidelines.md @@ -4,14 +4,14 @@ description: Here are best practices for building plugins for Microsoft Copilot author: erikadoyle ms.author: edoyle ms.topic: best-practice -ms.date: 11/15/2023 +ms.date: 6/26/2024 --- # Build high quality plugins for Microsoft Copilot [!INCLUDE [preview-disclaimer](includes/preview-disclaimer.md)] -When you build a plugin, you enable your users to interact with your web service using natural language with Microsoft Copilot. Plugins expand Copilot's skills to accomplish tasks on behalf of your users. They are especially good at: +When you build a plugin, you enable your users to interact with your web service using natural language with Microsoft Copilot. Plugins expand Copilot's skills to accomplish tasks on behalf of your users. They're especially good at: - Accessing real-time information, - Retrieving relational data, and @@ -19,7 +19,7 @@ When you build a plugin, you enable your users to interact with your web service ## Qualities of a good plugin -A clear and concise [description of your plugin](orchestrator.md#plugin-search-optimization) is essential for Copilot to recognize its capabilities and match it with the appropriate user tasks. You can ensure your plugin provides the best possible user experience at runtime by designing your plugin with the following characteristics. +A clear and concise [description of your plugin](orchestrator.md#plugin-optimization) is essential for Copilot to recognize its capabilities and match it with the appropriate user tasks. You can ensure your plugin provides the best possible user experience at runtime by designing your plugin with the following characteristics. :::row::: @@ -59,7 +59,7 @@ A clear and concise [description of your plugin](orchestrator.md#plugin-search-o ## Plugin best practices -The remainder of this article will cover best practices for building high quality plugins. +The remainder of this article covers best practices for building high quality plugins. ### Build for safety and responsible AI @@ -69,20 +69,32 @@ The remainder of this article will cover best practices for building high qualit ### Support multi-parameter search queries -To support complex prompts, expand the scope of your search support to handle two or more search query `parameters` simultaneously by enabling multi-parameter support in your plugin [app manifest](/microsoftteams/platform/resources/schema/manifest-schema#composeextensionscommands). +To support complex prompts, expand the scope of your search support to handle three or more search query `parameters` simultaneously by enabling multi-parameter support in your plugin [app manifest](/microsoftteams/platform/resources/schema/manifest-schema#composeextensionscommands). + +Ensure search parameters have good descriptions and explicit input types and output formats. ### Avoid generic descriptions of your plugin, its skills, and parameters -Be precise in the description of what the plugin does and does not do. While it's tempting to add extra information to try and boost the likelihood of a plugin being used by Copilot, this can result in the following critical issues: +Be precise in the description of what the plugin does and doesn't do. While it's tempting to add extra information to try to boost the likelihood of a plugin being used by Copilot, this can result in the following critical issues: -- A generic plugin description can prevent the appropriate plugin for the job from getting picked up and if this happens frequently the user might disable the plugin. +- A generic plugin description prevents the appropriate plugin for the job from getting picked up and if this happens frequently the user might disable the plugin. -- When selected incorrectly, failures in plugin execution or response are likely outcomes. Copilot will not surface plugins that have high error rates, and user trust in the plugin could erode. +- When selected incorrectly, failures in plugin execution or response are likely outcomes. Copilot won't surface plugins that have high error rates, and user trust in the plugin could erode. -### Do not assume Copilot can guess required inputs +### Don't assume Copilot can guess required inputs Only in limited scenarios is Copilot able to guess an input to a user prompt. Most of the time, required inputs to plugin queries need to be stated explicitly in the user's prompt to Copilot. Best practice is to test your plugin with different prompts to Copilot to anticipate expected behavior. ### Validate operations Copilot can perform in terms of reasoning over the plugin response -While Copilot provides basic capabilities in reasoning over the output of a plugin response, results will vary depending on the scenario. Best practice is to test your plugin with different prompts that require post-processing to anticipate expected behavior. +While Copilot provides basic capabilities in reasoning over the output of a plugin response, results vary depending on the scenario. Best practice is to test your plugin with different prompts that require post-processing to anticipate expected behavior. + +### Provide visually rich responses to user queries + +Respond to user input with structured, actionable, and visually rich [Adaptive Cards](/microsoftteams/platform/messaging-extensions/high-quality-message-extension?context=/microsoft-365-copilot/extensibility/context#adaptive-card-response). Ensure your Adaptive Card responses are informationally dense, and provide at least one action button and two additional pieces of information (in addition to your app logo, title, thumbnail, and title of the information). As additional information, it's useful to provide the most frequently searched attributes, such as *status*, *date*, or *assigned to* fields. + +## See also + +[Guidelines to create or upgrade Copilot extensions](/microsoftteams/platform/messaging-extensions/high-quality-message-extension?context=/microsoft-365-copilot/extensibility/context) + +[Publish plugins and Graph connectors for Copilot](./publish.md) diff --git a/docs/publish.md b/docs/publish.md index 65cc605..061ec54 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -70,7 +70,7 @@ In order to use the connector as a plugin, the *M365 Copilot* setting must first ### Distribute a Power Platform connector plugin through Microsoft Partner Center (preview) -Ensure your app meets certification criteria for [Power Platform Connectors](/connectors/custom-connectors/certification-submission), then submit your [app package](/connectors/custom-connectors/certification-submission) to [Microsoft Partner Center](https://partner.microsoft.com) through the **Microsoft 365 and Copilot program** as a **Power Platform Connector**. +Ensure your app meets certification criteria for [Power Platform Connectors](/connectors/custom-connectors/certification-submission), then submit your [app package](/connectors/custom-connectors/certification-submission#connector-and-plugin-packaging-guide) to [Microsoft Partner Center](https://partner.microsoft.com) through the **Microsoft 365 and Copilot program** as a **Power Platform Connector**. Once certified and published by Microsoft, your connector is available on Power Automate, Power Apps, and Logic Apps and your plugin is ready for IT enablement in the Microsoft Admin Center. The Copilot plugin will then appear as an installed plugin in Copilot for Microsoft 365.