Declarative agent schema 1.2 for Microsoft 365 Copilot

This article describes the 1.2 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 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.0.

• The sites property is added to the web search object. This allows the web search capability to be limited to allowed sites.
• The graphic art capability was added. This capability allows the declarative agent to generate images and art based on user input.

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.

Example of declarative agent manifest object

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
• Microsoft Graph Connectors object
• Graphic art object

Example of capabilities

{
  "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"
    }
  ]
}

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.

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.

Microsoft Graph connectors object

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

The Microsoft Graph connectors object contains the following properties.

Connection object

Identifies a Microsoft Graph connector.

The connection 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.

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"
    }
  ]
}

Declarative agent manifest example

Here's an example of 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.2/schema.json",
  "version": "v1.2",
  "name": "Teams Toolkit declarative copilot",
  "description": "Declarative copilot created with Teams Toolkit",
  "instructions": "You are a repairs expert copilot. 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.",
  "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"
    }
  ]
}

Related content

• Write effective instructions for declarative agents