When you build an agent, you're also building an app for Microsoft 365. Apps for Microsoft 365 share a common manifest schema and packaging format, and unified distribution and management processes and tools. The end result is that your apps and agents reach the widest possible audience and appear contextually within the workflow of your users.
This article describes the key parts of the Microsoft 365 app model that apply to agent development.
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 a plugin.
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.
App package
The app package for Microsoft 365, including agents, is a zip file that contains one or more configuration (manifest) files and your app icons. Your app logic and data storage are hosted elsewhere and accessed by the Microsoft 365 host application via HTTPS. You'll submit the app package to your admin to publish to your organization or to Partner Center to publish to Microsoft AppSource.
At minimum, an app package contains:
The app manifest (manifest.json), which describes app configuration, capabilities, required resources, and important attributes
A large color icon (color.png), a full-color 92x92 icon to display your agent in the Microsoft 365 Copilot UI and store
A small outline icon (outline.png), a 32x32 icon with transparent background (not currently used in Copilot, but required to pass validation)
The app package can also contain declarative agent and API plugin definitions, as well as localization files for other supported languages.
App icons
Your app package must include both a color and outline version of your app icon, as .png files. These icons have specific size requirements in order to pass store validation.
Note
Currently only the color icon is used to represent agents to users (both as its store listing and within the Microsoft 365 Copilot UI), but an outline icon is still required when you submit the app package to Microsoft AppSource.
Must sit atop a fully solid or fully transparent square background
Outline icon
The outline icon is used to represent pinned and/or active apps on the Teams app bar. It's not currently used for agents, but still required in order for the app package to pass validation.
Your outline icon:
Must be 32 x 32 pixels
Must be either white with a transparent background, or transparent with a white background
Must not contain additional padding around the symbol
App manifest
The app manifest for Microsoft 365 is a JSON file that describes the functionality and characteristics of your app. At its core, the app manifest for Microsoft 365 is the schema for building Teams apps; however, starting with version 1.13, it supports apps that run across Microsoft 365 hosts, in addition to Teams.
If you're using Copilot Studio to build a declarative agent, the app manifest is generated for you based on the information you provide during the creation process.
Every app manifest must include the following fields.
Information about the developer, including name, website, and links to privacy policy and terms of use. For apps submitted to AppSource, values must match the value provided in the Partner Center app submission form.
A color to use with and as a background for your outline icons, in RGB hex value, for example #4464ee.
Definitions for specific app capabilities
A definition for each app capability, such as personal tabs (staticTabs), message extensions (composeExtensions), or bots. Declarative agents and API plugins are defined under the copilotAgents node.
The following example shows an app manifest with placeholder sections at the end for message extension and declarative agent app capabilities.
JSON
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
"manifestVersion": "1.18",
"version": "1.0.0",
"id": "00000000-0000-0000-0000-000000000000",
"developer": {
"name": "Northwind Traders",
"websiteUrl": "https://www.example.com",
"privacyUrl": "https://www.example.com/termofuse",
"termsOfUseUrl": "https://www.example.com/privacy"
},
"icons": {
"color": "Northwind-Logo-196.png",
"outline": "Northwind-Logo-32.png"
},
"name": {
"short": "Northwind Inventory",
"full": "Northwind Inventory App"
},
"description": {
"short": "App allows you to find and update product inventory information",
"full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
},
"accentColor": "#3690E9",
"composeExtensions": {
...
},
"copilotAgents": {
...
}
}
Declarative agents and API plugins each have their own definition schemas. The definition file for a declarative agent is referenced from the copilotAgents object of the app manifest.
The following example shows how to reference a declarative agent:
The definition of an API plugin is referenced (under actions) from the declarative agent definition.
Note the following:
Currently only one declarative agent definition is supported per app manifest.
When you use Copilot Studio to build agents, a unique id is generated for each, as part of the overall app manifest generation. When building agents with Teams Toolkit or your own IDE, you assign the id yourself, according to your own conventions or friendly name.
Declarative agent manifest
The declarative agent manifest includes instructions for Copilot responses, conversation starter sample prompts, data sources used for grounding, and a list of actions (API plugin skills) the agent is able to perform.
The API plugin manifest describes the plugin's capabilities, including the APIs it supports and the operations it can perform. It also includes metadata such as name, description, version, and a reference to the OpenAPI definition of the REST APIs with which it interacts. API plugins can be referenced from a declarative agent manifest to be used within the declarative agent experience.
Extend Microsoft 365 Copilot with declarative agents is a multi-part series that teaches you basic concepts of extending Microsoft 365 Copilot using Visual Studio Code. You learn what declarative agents are, how they work, and when you should consider building them. You also learn, how to extend them with skills and knowledge to make them more powerful and useful.
Agents, plugins, and connectors run across the Microsoft 365 ecosystem. Learn how the Microsoft 365 ecosystem extends the reach of your apps, services, and data.
Learn how you can use declarative agents to meet business needs. Declarative agents customize Microsoft 365 Copilot via instructions, actions, and knowledge.
