Edit

Share via


Build high-quality plugins for Microsoft 365 Copilot

When you build a plugin, you enable your users to interact with your web service using natural language via Microsoft 365 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
  • Performing actions across apps

Important

  • API plugins are currently only supported as actions within declarative agents. They aren't enabled in Microsoft 365 Copilot. For an example that shows how to add an API plugin to a declarative agent, see Add an API plugin as a custom action to the agent.
  • 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 more information, see Manage Agents in Integrated Apps.

Qualities of a good plugin

A clear and concise description of your plugin 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.

Image representing 'Robust search'

Support search

Anticipate and support the most common searches users will perform.

Image representing 'Deep content retrieval'

Retrieve deep content

Make sure that the search matches with the surrounding paragraph. Provide an Adaptive Card response with additional information.

Image representing 'Actionable'

Present actionable results

Include a way for the user to take action, such as a deep link to your website, or a modal dialog.

Image representing 'Provide a preview'

Provide a preview

Guide your user through content previews.

Plugin best practices

This section describes best practices for building high-quality plugins.

Build for safety and responsible AI

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

Support multi-parameter search queries

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.

Make sure that 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 doesn't do. While it's tempting to add extra information to try to boost the likelihood that Copilot uses a plugin, this can result in the following undesirable consequences:

  • 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 won't surface plugins that have high error rates, which can erode user trust.

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. As a best practice, 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 vary depending on the scenario. As a best practice, 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. Make sure that your Adaptive Card responses provide rich information, and include at least one action button and two additional pieces of information (in addition to your app logo, title, thumbnail, and title of the information). It can be useful to provide the most frequently searched attributes, such as status, date, or assigned to fields.