Copilot agents are apps for Microsoft 365

When you build a Copilot 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 Copilot agents reach the widest possible audience and appear contextually within the workflow of your users.

This article will walk you through the key parts of the Microsoft 365 app model for Copilot agent development.

App model for Microsoft 365

The Microsoft 365 ecosystem is evolving into an integrated app platform, where you can use a common app model to define and package your app. What started as a way to extend Teams apps to run in other Microsoft 365 applications has since expanded to support the distribution of Graph connectors, Outlook Add-ins, and now Copilot agents.

App package

The app package for Microsoft 365, including Copilot 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 Copilot UI and store, and
• 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.

For further design guidance on color and outline icons for the Microsoft 365 app package, App icons for Teams Store and app bar.

Color icon

The color icon represents your agent within the Microsoft Copilot UI and in-product (Teams, Outlook, Microsoft 365) app stores.

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 Copilot agents, but still required in order for the app package to pass validation.

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 it has since expanded (since version 1.13) to define apps that run across Microsoft 365 hosts, in addition to Teams.

If you're using Microsoft Copilot Studio to build a declarative agent, the app manifest will be generated for you based on the info you provide during the creation process.

Every app manifest must include the following information:

Here's an example app manifest with placeholder sections at the end for message extension and declarative agent app capabilities:

{
    "$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": {
        ...
    },
    "copilotExtensions": {
        ...
    }
}

To learn more, see the Developer preview app manifest schema reference.

copilotExtensions definitions

Declarative agents and API plugins each have their own definition schemas. The definition file for a declarative agent is referenced from the copilotExtensions object of the app manifest.

Here's an example that references a declarative agent:

    "copilotExtensions": {
        "declarativeCopilots": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

The definition of an API plugin is referenced from the declarative agent definition.

Please note the following:

• Currently only one declarative agent definition is supported per app manifest. Only one API plugin is supported per declarative agent.

• When using Copilot Studio to build Copilot agents, a unique id will be 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.

To learn more, see Declarative agent manifest schema for Microsoft 365 Copilot.

API plugin manifest

The API plugin manifest describes the plugin's capabilities, including the 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.

To learn more, see API plugin manifest schema for Microsoft 365 Copilot.

Localizing your agent

The way you localize a Copilot agent is slightly different than how you localize other capabilities (such as tabs, bots, and message extensions) in the app manifest.

You'll use the same localization file (per language) for both classic Teams app capabilities and Copilot agent. However, while all other app manifest fields are referenced using JSONPath expressions in the language file(s), Copilot agent-related fields are simply referenced using dictionary keys. Unlike classic Teams app capabilities, which use default language strings in the app manifest itself, localized Copilot agents require a language file for the default language as well as for each additional language.

Following are the steps for supporting additional languages (beyond the default) to your Copilot agents.

1. Update your Copilot agent manifest(s) with tokenized keys

Update your declarative agent and/or API plugin manifests with tokenized keys (indicated with double square brackets, for example [[PLUGIN_NAME]]) for any field values you wish to localize. Localization keys much match this regular expression: ^[a-zA-Z_][a-zA-Z0-9_]*$

Here's an example declarative agent manifest with tokenized values for its name and description:

{
    "$schema": "https://aka.ms/json-schemas/copilot-extensions/v1.0/declarative-copilot.schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. Add localizationInfo to your app manifest

Add the localizationInfo section to your app manifest, with language tags and relative paths to each supported language file within your app package.

If your Copilot agent supports more than one language, then you must specify a standalone language file for every supported language, including your default language.

Here's an example localization info section in app manifest:

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

If your Copilot agent doesn't support additional languages, the default language strings are represented within app manifest file itself. (Single language app packages don't require a separate language file for the default language.)

3. Create a localization file for each additional language

Create a localization file for each additional supported language with values for the tokenized keys, using the file names specified (for defaultLanguageFile and file properties) in app manifest from the previous step.

Here's an example language file, fr.json, with localized strings for both a Copilot agent and personal tabs:

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

Localizable fields in app manifest

For each language file, specify the following properties from the app localization schema that are required to be localized:

To learn more, see Localize your app (Microsoft Teams) and the Localization schema reference.

Localizable fields in declarative agent manifest

The following fields are localizable within the declarative agent manifest:

To learn more, see Declarative agent manifest reference.

Localizable fields in API plugin manifest

The following fields are localizable within the API plugin manifest:

To learn more, see API plugin manifest reference.

See also

• Manage extensibility for Microsoft 365 Copilot
• Publish agents for Microsoft 365 Copilot