Validation guidelines for agents

This section is in line with Microsoft commercial marketplace policy number 1140.9.

Apps must be consistent with responsible AI checks.

Description

A good description offers a clear and concise summary of the agent's features. It enhances user awareness and allows Microsoft 365 Copilot to efficiently discover and execute search operations.

You must ensure to meet the following guidelines for agents:

• The Teams Store validation guidelines related to app description for Microsoft 365 apps are applicable. For more information, see app descriptions.

• Short description of agent, parameter, command description, semantic description, and operation ID mustn't include:

  • Instructional phrases, for example, 'if the user says X', 'ignore', 'delete', 'reset', 'new instructions', 'Answer in Bold', or 'Do not print anything'. [Must fix]
  • URLs, emojis, or hidden characters such as hexadecimal, binary, or unconventional symbols. [Must fix]
  • Grammar and punctuation errors. [Must fix]
  • Overly verbose, flowery, or marketing language. [Good-to-fix]
  • Superlative claims such as “#1,” “amazing,” or “best”. [Good-to-fix]

  Note

  • In case of declarative agents, the short description guidelines apply to the instructions and conversation_starters fields also.
  • For API based plugins, these guidelines apply to description_for_human, description_for_model, capabilities, conversation_starters (both the title and and text), states\reasoning\description in functions fields, if provided. [Must fix]
  • When utilizing Swagger or OpenAPI file formats, adhere to these guidelines for the path content associated with keys and the description field for GET, POST, PUT, or DELETE APIs. [Must fix]

• App long description must clearly call out that the agent works in Microsoft 365 Copilot. For example, use Contoso in Microsoft 365 Copilot to search and summarize your tasks. ​[Must fix]

  

  

• The semanticDescription property isn't a mandatory field. However, if you add semanticDescription in app manifest, the existing validation checks for short, parameter, and command descriptions are also applicable for semantic descriptions.

Back to top

Screenshots

You must ensure to meet the following guidelines for agents:

• The Teams Store validation guidelines related to screenshots for Microsoft 365 apps are applicable. For more information, see screenshots.
• Apps with agent functionality must have atleast one screenshot related to Microsoft 365 Copilot functionality. [Must fix]

Back to top

Agent name

You must ensure to meet the following guidelines for agents:

• The Teams Store validation guidelines related to app name for Microsoft 365 apps are applicable. For more information, see app name.
• For declarative agent, ensure that the following parameters are identical: [Must fix]
  • name in the app manifest
  • name in declarativeAgent1.json
  • name_for_human in plugin.json files

Back to top

Compound utterances

Agents must support atleast three unique compound utterances by handling three or more parameters.

Back to top

Prompts

You must ensure the following guidelines for sample prompts and prompt starters:

Sample prompts

The samplePrompts property provides guidance to users on utilizing the various agents in Microsoft 365 Copilot.

Sample prompts are specified using samplePrompts property in the app manifest. These prompts must meet the following requirements:

• An agent must have at least three prompts and maximum of five prompts for each command. [Must fix]
• Each prompt mustn't exceed 128 characters. [Must fix]
• Two commands within the same agent mustn't have identical prompts. [Must fix]
• All sample prompts must be functional and return responses. [Must fix]
• Prompt must be relevant to the commands. [Must fix]

Prompt starters

Prompt starters guide users on how to start using declarative agents. You must ensure the following guidelines for prompt starters:

• A declarative agent must have at least three prompts and maximum of six prompts. [Must fix]
• All prompt starters must be functional and return responses. [Must fix]

Back to top

Adaptive Card response

Agent responses provided as an Adaptive Card must meet the following requirements:

• Adaptive Card response must include Adaptive Card content and preview card information as part of the same template. [Must fix]

  

• Apart from the agent logo, title, thumbnail, and title of the information, the data in the Adaptive Card must represent at least two pieces of information. You can identify the fields from the most frequently searched attributes such as data modified, author, status, and flags. [Must fix]

  

• Adaptive Card must be well-formatted to suit the desktop, web, and mobile (iOS and Android) clients. [Must fix]

• Adaptive Cards must include a URL as part of the metadata, which allows cards to be easily copied from one hub to another. [Must fix]

Back to top

Compatibility

Agents must be fully responsive and functional on the latest versions of these clients: [Must fix]

• Microsoft Teams on desktop and web
• copilot.microsoft.com on web
• Microsoft 365 Copilot in Word

Ensure your Copilot plugins work in Teams meetings

You must implement the following:

• Adaptive Cards mustn't display a horizontal scroll. To avoid horizontal scrolls, don’t specify a fixed width: [Must fix]

  • ColumnSets

    • Don't define ColumnSets with more than three columns.
    • Don’t use explicit pixel width on more than one column in the set.
    • Ensure the column doesn't exceed one-quarter of the narrowest card width, such as in a meeting chat or Microsoft 365 Copilot.
    • Generally, an explicit width mustn't exceed 48 pixels, though some scenarios might allow for exceptions.

  • Sizing images

    • When using an image inside a ColumnSet with more than one column, specify the size of the column containing an image rather than the image itself.
    • If the image isn’t in a ColumnSet, we recommend you to set its size to auto or stretch.
    • If you want to define an explicit width in pixels, ensure that it doesn’t exceed three-fourths of the narrowest card width.
    • If you want to define explicit size in pixels, define it for the width or height. Setting explicit size for any one parameter preserves the image's aspect ratio.
    • We recommend that you set the width of the image, though some scenarios might allow for exceptions.

For more information to create plugins for teams meetings, see enable message extension as a plugin for Copilot for meetings.

Back to top

Ensure your agents work with Microsoft 365 - Word, Excel, PowerPoint, OneNote, Office, and Outlook Copilots

You must ensure to meet the following guidelines for agents:

1. If using SSO-enabled app, update Microsoft Entra app registration: [Must fix]

   Microsoft Entra single sign-on (SSO) for message extension works in the same way as it does in Teams or Outlook. If you enabled SSO for your app, add the Office app Copilot’s client application identifier to the Microsoft Entra app registration of your bot in your tenant's App registrations portal.

   1. Sign in to Azure portal with your sandbox tenant account.

   2. Open App registrations.

   3. Select the name of your application to open its app registration.

   4. From the Manage section, select Expose an API.

   5. In the Authorized client applications section, ensure that the following client ID values are listed:

      Microsoft 365 client application	Client ID
      Word, PowerPoint, Excel (web, desktop)	3068386c-7a16-4f6a-a664-043b6b232816
      Teams desktop, mobile	1fec8e78-bce4-4aaf-ab1b-5451cc387264
      Teams web	5e3ce6c0-2b1f-4285-8d4b-75ee78787346
      Microsoft 365 web	4765445b-32c6-49b0-83e6-1d93765276ca
      Microsoft 365 desktop	0ec893e0-5785-4de6-99da-4ed124e5296c
      Microsoft 365 mobile	d3590ed6-52b3-4102-aeff-aad2292ab01c
      Outlook desktop	d3590ed6-52b3-4102-aeff-aad2292ab01c
      Outlook web	bc59ab01-8403-45c6-8796-ac3ef710b3e3
      Outlook mobile	27922004-5251-4030-b22d-91ecd9a37ea4
      Bing	9ea1ad79-fdb6-4f9a-8bc3-2b70f96e34c7

      Note

      For more information about how SSO works for message extensions, see enable SSO for your app.

2. Ensure your registered bot is connected to Microsoft 365 and Microsoft Teams channel: [Must fix]

   1. Sign in to Azure portal with your sandbox tenant account.
   2. Open Bot Services.
   3. Select the name of your bot to update its channels.
   4. From the Settings section, select Channels.
   5. From Available channels, select Microsoft 365 & Microsoft Teams, and then select Apply.

3. Configure Content Security Policy headers [Must fix]

   If your agent makes use of Content Security Policy (CSP) headers, ensure that all the following frame-ancestors are included in your CSP headers:

   Microsoft 365 App	frame-ancestors permission
   All hosts (New)	*.cloud.microsoft
   Word	fa000000125.resources.office.net
   PowerPoint	fa000000129.resources.office.net
   Excel	fa000000124.resources.office.net
   OneNote	fa000000128.resources.office.net
   Microsoft 365 Copilot and Bing	edgeservices.bing.com, www.bing.com, copilot.microsoft.com
   Microsoft 365 app	*.microsoft365.com, *.office.com
   Outlook	outlook.office.com, outlook.office365.com, outlook-sdf.office.com, outlook-sdf.office365.com
   Office.com	Office.com/copilot Office.com/chat
   Microsoft365.com	Microsoft365.com/copilot Microsoft365.com/chat
   M365.cloud.microsoft	M365.cloud.microsoft/chat M365.cloud.microsoft/copilot
   Copilot.cloud.microsoft	Copilot.cloud.microsoft

4. Upgrade Teams JS version to the 2.22.0 build [Must fix]

   If you're using Teams JS version 2.22 or earlier, update it to version 2.22 or higher. 

   For more information, see Teams JS Repository @microsoft/teams-js - npm (npmjs.com).

Back to top

Technical requirements

For an agent to be validated, invoked, and to work seamlessly, ensure that it meets the following criteria: [Must fix]

Back to top

User disclosure and confirmation for action scenarios

For action scenarios, agents must share user disclosure and seek user confirmation:

• Data shown in third-party service (through dialogue) must be reflective of confirmation provided by the user. [Must fix]

• A confirmation of the completion of the action must be shared by the agent in the form of a card. [Must fix]

• Action taken by a user must be correctly reflected in third-party service. [Must fix]

• Modification requests by the user prior to confirmation of the action must be honored. [Must fix]

• Highly consequential tasks such as bulk delete mustn't be supported. [Good-to-fix]

• The declarative agent must provide confirmation prompts aligned with user-initiated actions, using clear language that explicitly seeks the user's permission. [Must fix]

  Confirmation prompt can be set by using body property in the Confirmation object in the function's Function capabilities object in the manifest. For more information, see customizing confirmation text.

  Pass example	Fail example
  For a function which searches tickets - "Do you want to allow searching in Contoso?" "Do you want to allow searching for tickets?"	Do you want to proceed?" --> Does not indicate what the function does.
  For a function which creates a new order "Do you want to proceed with creating a new order?"	Searches tickets" --> Does not seek permission
  For a function which creates a new ticket: "Do you want to proceed with creating a new ticket?"	"Creates tickets" --> Does not seek permission

• For declarative agents, any action with consequences on the external system mustn't have isConsequential flag set as ‘False’. [Must fix]

  For more details, see overriding prompt behavior.

  Operation type	Actions	Expected value for isConsequential flag
  Create	Consequential	True
  Read	Non-consequential	False or True
  Update	Consequential	True
  Delete	Consequential	True

  Command description	Consequential function?	Expected value for isConsequential flag
  Returns a list of quest recommendations based on the user's interest. If there is no quote recommendations, then create a new one.	Yes	True
  Returns a list of meditation recommendations based on the user's preferences.	No	False or True
  Returns a list of quest recommendations based on the user's interest. If there is no quote recommendations, then create a new one.	Yes	True

Back to top

Bot requirements for custom engine agents

A custom engine agent is a conversational Teams bot that must meet the following requirements:

1. A custom engine agent must always contain conversation bot based on Large Language Models (LLMs) for seamless user interaction. [Must fix]

2. The bot ID declaration as a custom engine agent node must be same as the bot ID defined in the bot node in the app manifest. [Must fix]

3. User must be able to reference custom engine agent in Microsoft 365 Copilot and handoff chat experience in Teams. [Good-to-fix]

4. Bot must include the following UX design components:

   1. An AI label that enables a user to identify that the message was generated using AI. [Must fix]

   2. A feedback button that enables a user to provide positive or negative feedback to the agent's messages. [Must fix]

   3. A citation that enables a user to refer to the source of the bot message through in-text citations and references. [Must fix]

   4. A sensitivity label that enables a user to understand the confidentiality of the bot message. [Good-to-fix]

   5. An agent must stream it’s responses to the user. [Must fix]

   6. An agent must include at least three prompt starters or a welcome message. [Must fix]

      For more information, see bot welcome messages.

   7. A bot should offer at least two context-specific suggestions or prompts to the user, rather than generic or fixed ones. [Must fix]

Back to top

Agent must have Action or knowledge source

• Your agent must have nodes defined as actions in the app manifest. All agents must have a core use case that's served through API actions. [Must fix]

• For capabilities such as Websearch, Graphic Art, or Code Interpreter, the Instruction field must include details on how to use the capabilities within the context of the agent. [Must fix]

Back to top

Graceful error handling

All agents must handle the following scenarios gracefully, that is, the agent must reject the user request and provide a way forward: [Must fix]

• For incorrect search parameters

• For misuse or inappropriate language

• For topics in which the agent doesn’t specialize

  For example, graceful error message with way forward for declarative agent:

  

Back to top

Security requirements for OpenAPI spec URL

Agents that use OpenAPI specs must ensure the following security standards:

• All API calls must use HTTPS with TLS 1.2 or higher. [Must fix]
• API calls mustn't lead to any URL redirection. Actual API calls must be served from the same domain or subdomain as the root domain verified for the developer. [Must fix]

Back to top

See also

• Teams Store validation guidelines
• Guidelines to create and upgrade agents
• Extend bot-based message extension as agent for Microsoft 365 Copilot
• Extend Microsoft 365 Copilot