Declarative agent schema 1.4 for Microsoft 365 Copilot

This article describes the 1.4 schema used by the declarative agent manifest. The manifest is a machine-readable document that provides a Large Language Model (LLM) with the necessary instructions, knowledge, and actions to specialize in addressing a select set of user problems. Declarative agent manifests are referenced by the Microsoft 365 app manifest inside an app package. For details, see the Microsoft 365 app manifest reference.

Declarative agents are valuable in understanding and generating human-like text, making them versatile for tasks like writing and answering questions. This specification is focused on the declarative agent manifest that acts as a structured framework to specialize and enhance functionalities a specific user needs.

Changes from previous version

This schema version introduces the following changes from version 1.3:

• Added the sensitivity_label, disclaimer, and behavior_overrides properties to the declarative agent manifest object.
• Added the part_type and part_id properties to the items by SharePoint IDs object.
• Added additional properties to the Connection object, allowing scoping of Copilot connector content.
• Added the scenario models capability to the list of capabilities, which allows agents to use task-specific models.

JSON schema

The schema described in this document can be found in JSON Schema format here.

Conventions

Relative references in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references. Relative references in the manifest document are relative the ___location of the manifest document.

String length

Unless specified otherwise, all string properties SHOULD be limited to 4K characters. This string length doesn't confer any acceptable size for the entire document. Implementations are free to impose their own practical limits on manifest length.

Unrecognized properties

JSON objects defined in this document support only the described properties. Unrecognized or extraneous properties in any JSON object SHOULD make the entire document invalid.

String localization

Localizable strings can use a localization key instead of a literal value. The syntax is [[key_name]], where key_name is the key name in the localizationKeys property in your localization files. For details on localization, see Localize your agent.

Declarative agent manifest object

The root of the manifest document is a JSON object that covers required fields, capabilities, conversation starters, and actions.

The declarative agent manifest object contains the following properties.

Declarative agent manifest object example

The following JSON is an example of required fields within a declarative agent manifest.

{
  "name" : "Repairs agent",
  "description": "This declarative agent is meant to help track any tickets and repairs",
  "instructions": "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
}

Capabilities object

The capabilities object is the base type of objects in the capabilities property in the declarative agent manifest object. The possible object types are:

• Web search object
• OneDrive and SharePoint object
• Copilot connectors object
• Graphic art object
• Code interpreter object
• Dataverse object
• Teams messages object
• Email object
• People object
• Scenario models object

Capabilities object example

{
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_sharepoint_ids": [
        {
          "site_id": "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd",
          "web_id": "a5377427-f041-49b5-a2e9-0d58f4343939",
          "list_id": "78A4158C-D2E0-4708-A07D-EE751111E462",
          "unique_id": "304fcfdf-8842-434d-a56f-44a1e54fbed2"
        }
      ],
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "jiraTickets"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    }
  ]
}

Web search object

Indicates that the declarative agent can search the web for grounding information.

The web search object contains the following properties.

Site object

Indicates a site that a declarative agent can search for content.

The site object contains the following properties.

OneDrive and SharePoint object

Indicates that the declarative agent can search a user's SharePoint and OneDrive for grounding information.

The OneDrive and SharePoint object contains the following properties.

For information about how to optimize SharePoint content for Copilot, see Optimize SharePoint content retrieval.

Items by SharePoint IDs object

The items by SharePoint IDs object contains the following properties.

Items by URL object

The items by URL object contains the following properties.

Copilot connectors object

Indicates that the declarative agent can search selected Copilot connectors for grounding information.

The Copilot connectors object contains the following properties.

Connection object

Identifies a Copilot connector.

The connection object contains the following properties.

Item identifier object

Identifies an external item by it's ID.

The item identifier object contains the following properties.

Path object

Identifies an external item by it's path.

The path object contains the following properties.

Container name object

Identifies a container by it's name.

The container name object contains the following properties.

Container URL object

Identifies a container by it's URL.

The container URL object contains the following properties.

Graphic art object

Indicates that the declarative agent can create images and art based on the text input from the user. For more information, see Image generator.

The graphic art object contains the following properties.

Code interpreter object

Indicates that the declarative agent can generate and execute Python code to solve complex math problems, analyze data, generate visualizations, and more. For more information, see Code interpreter.

The code interpreter object contains the following properties.

Dataverse object

Indicates that the declarative agent can search through data from tables in Microsoft Dataverse.

The Dataverse object contains the following properties.

Knowledge sources object

Contains information about the Dataverse instances to include as knowledge.

The knowledge sources object contains the following properties.

Tables object

Contains the tables to scope the agent's knowledge.

The tables object contains the following property.

Teams messages object

Indicates that the declarative agent can search through Teams channels, teams, meetings, 1:1 chats, and group chats.

The Teams messages object contains the following properties.

Teams URL object

Identifies a Teams channel, team, or meeting chat.

The Teams URL object contains the following properties.

Email object

Indicates that the declarative agent can search through email messages in the mailboxes that the user has access to.

The email object contains the following properties.

Folders object

Contains the folders to scope the agent's knowledge.

The folders object contains the following property.

People object

Indicates that the declarative agent can search for information about people in the organization.

The people object contains the following property.

Scenario models object

Indicates that the declarative agent can use task-specific models.

The scenario models object contains the following properties.

Model object

Identifies a task-specific model.

The model object contains the following property.

Conversation starters object

The conversation starters object is optional in the manifest. It contains hints that are displayed to the user to demonstrate how they can get started using the declarative agent.

The conversation starter object contains the following properties:

Conversation starters object example

{
  "conversation_starters": [
    {
      "title": "My Open Repairs",
      "text": "What open repairs are assigned to me?"
    }
  ]
}

Actions object

Actions are an optional JSON object in the manifest. It acts as a developer input and can be considered as plugins.

The action object contains the following properties.

Actions object example

{
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "plugin.json"
    }
  ]
}

Sensitivity label object

A sensitivity label is an optional JSON object in the manifest that assigns a Microsoft Purview sensitivity label to the declarative agent. This label should be at least as restrictive as the most restrictive label on any knowledge files included in the agent. For more information about sensitivity labels, see Learn about sensitivity labels.

The sensitivity label object contains the following property.

Disclaimer object

A disclaimer is an optional JSON object in the manifest that specifies disclaimer text that is displayed to the user at the start of a conversation.

The disclaimer object contains the following property.

Behavior overrides object

An optional JSON object that contains configuration settings that override the agent's behavior.

The behavior overrides object contains the following property.

Suggestions object

An optional JSON object that contains configuration settings for the suggestions feature.

The suggestions object contains the following property.

Declarative agent manifest example

The following example shows a declarative agent manifest file that uses most of the manifest properties described in this article.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Teams Toolkit declarative agent",
  "description": "Declarative agent created with Teams Toolkit",
  "instructions": "You are a repairs expert agent. With the response from the listRepairs function, you **must** create a poem out of the repairs listed and always include their title and the assigned person. The poem **must** not use the quote markdown and use regular text. If the user is asking to create a new repair, use the createRepair function and do not add poems.",
  "sensitivity_label": {
    "id": "c7d25882-b276-4ad8-851b-f84cb0146605"
  },
  "disclaimer": {
    "text": "This declarative agent is a fictional example. You should not take it seriously."
  },
  "conversation_starters": [
    {
      "title": "Getting Started",
      "text": "How can I get started with Teams Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Teams Toolkit?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com/projects/mark-8"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "foodStore"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "Email",
      "shared_mailbox": "sample@service.microsoft.com",
      "folders": [
        {
         "folder_id": "inbox"
        }
      ]
    },
    {
      "name": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    }
  ]
}

Related content

• Write effective instructions for declarative agents
• Microsoft 365 app manifest reference