Note

Access to this page requires authorization. You can try signing in or .

Access to this page requires authorization. You can try .

root.copilotAgents object

Defines one or more agents to Microsoft 365 Copilot, selectable as Agents from the Microsoft 365 Copilot navigation panel. Declarative agents are customizations of Microsoft 365 Copilot that run on the same orchestrator and foundation models. Custom engine agents use custom AI language models and orchestration.

Note

Custom engine agents support in Microsoft 365 Copilot is currently in public preview.

Properties that reference this object type:

root.copilotAgents

Syntax

{
 "declarativeAgents": [
 {
 "id": "{string}",
 "file": "{string}"
 }
 ],
 "customEngineAgents": [
 {
 "id": "{string}",
 "type": "bot",
 "disclaimer": {
 disclaimer object
 },
 "functionsAs": "agentOnly | agenticUserOnly",
 "agenticUserTemplateId": "{string}"
 }
 ]
}

{
 "type": "object",
 "properties": {
 "declarativeAgents": {
 "type": "array",
 "description": "An array of declarative agent elements references. Currently, only one declarative agent per application is supported.",
 "items": {
 "$ref": "#/definitions/declarativeAgentRef"
 },
 "minItems": 1,
 "maxItems": 1
 },
 "customEngineAgents": {
 "type": "array",
 "description": "An array of Custom Engine Agents. Currently only one Custom Engine Agent per application is supported.",
 "items": {
 "type": "object",
 "properties": {
 "id": {
 "$ref": "#/definitions/guid",
 "description": "The id of the Custom Engine Agent. If it is of type bot, the id must match the id specified in a bot in the bots node and the referenced bot must have personal scope. The app short name and short description must also be defined."
 },
 "type": {
 "type": "string",
 "enum": [
 "bot"
 ],
 "description": "The type of the Custom Engine Agent. Currently only type bot is supported."
 },
 "disclaimer": {
 "type": "object",
 "properties": {
 "text": {
 "type": "string",
 "description": "The message shown to users before they interact with this application. ",
 "maxLength": 500
 }
 },
 "required": [
 "text"
 ]
 },
 "functionsAs": {
 "type": "string",
 "enum": [
 "agentOnly",
 "agenticUserOnly"
 ],
 "default": "agentOnly",
 "description": "Possible values: \u0027agenticUserOnly\u0027, \u0027agentOnly\u0027. \u0027agenticUserOnly\u0027 means the customEngineAgent must be hired and cannot be installed as a regular agent. \u0027agentOnly\u0027 means it supports being installed as a regular agent only (default)."
 },
 "agenticUserTemplateId": {
 "type": "string",
 "description": "Unique identifier for the agentic user template. This id must match the id specified in an agentic user template in the agenticUserTemplates node"
 }
 },
 "required": [
 "id",
 "type"
 ],
 "additionalProperties": false
 },
 "minItems": 1,
 "maxItems": 1
 }
 },
 "additionalProperties": false,
 "oneOf": [
 {
 "required": [
 "declarativeAgents"
 ]
 },
 {
 "required": [
 "customEngineAgents"
 ]
 }
 ]
}

{
 "declarativeAgents": [
 {
 "id": "{string}",
 "file": "{string}"
 }
 ],
 "customEngineAgents": [
 {
 "id": "{string}",
 "type": "bot",
 "disclaimer": {
 disclaimer object
 }
 }
 ]
}

{
 "type": "object",
 "properties": {
 "declarativeAgents": {
 "type": "array",
 "description": "An array of declarative agent elements references. Currently, only one declarative agent per application is supported.",
 "items": {
 "$ref": "#/definitions/declarativeAgentRef"
 },
 "minItems": 1,
 "maxItems": 1
 },
 "customEngineAgents": {
 "type": "array",
 "description": "An array of Custom Engine Agents. Currently only one Custom Engine Agent per application is supported. Support is currently in public preview.",
 "items": {
 "type": "object",
 "properties": {
 "id": {
 "$ref": "#/definitions/guid",
 "description": "The id of the Custom Engine Agent. If it is of type bot, the id must match the id specified in a bot in the bots node and the referenced bot must have personal scope. The app short name and short description must also be defined."
 },
 "type": {
 "type": "string",
 "enum": [
 "bot"
 ],
 "description": "The type of the Custom Engine Agent. Currently only type bot is supported."
 },
 "disclaimer": {
 "type": "object",
 "properties": {
 "text": {
 "type": "string",
 "description": "The message shown to users before they interact with this application. ",
 "maxLength": 500
 }
 },
 "required": [
 "text"
 ]
 }
 },
 "required": [
 "id",
 "type"
 ],
 "additionalProperties": false
 },
 "minItems": 1,
 "maxItems": 1
 }
 },
 "additionalProperties": false,
 "anyOf": []
}

{
 "declarativeAgents": [
 {
 "id": "{string}",
 "file": "{string}"
 }
 ],
 "customEngineAgents": [
 {
 "id": "{string}",
 "type": "bot",
 "disclaimer": {
 disclaimer object
 }
 }
 ]
}

{
 "type": "object",
 "properties": {
 "declarativeAgents": {
 "type": "array",
 "description": "An array of declarative agent elements references. Currently, only one declarative agent per application is supported.",
 "items": {
 "$ref": "#/definitions/declarativeAgentRef"
 },
 "minItems": 1,
 "maxItems": 1
 },
 "customEngineAgents": {
 "type": "array",
 "description": "An array of Custom Engine Agents. Currently only one Custom Engine Agent per application is supported. Support is currently in public preview.",
 "items": {
 "type": "object",
 "properties": {
 "id": {
 "$ref": "#/definitions/guid",
 "description": "The id of the Custom Engine Agent. If it is of type bot, the id must match the id specified in a bot in the bots node and the referenced bot must have personal scope. The app short name and short description must also be defined."
 },
 "type": {
 "type": "string",
 "enum": [
 "bot"
 ],
 "description": "The type of the Custom Engine Agent. Currently only type bot is supported."
 },
 "disclaimer": {
 "type": "object",
 "properties": {
 "text": {
 "type": "string",
 "description": "The message shown to users before they interact with this application. ",
 "maxLength": 500
 }
 },
 "required": [
 "text"
 ]
 }
 },
 "required": [
 "id",
 "type"
 ],
 "additionalProperties": false
 },
 "minItems": 1,
 "maxItems": 1
 }
 },
 "additionalProperties": false,
 "oneOf": [
 {
 "required": [
 "declarativeAgents"
 ]
 },
 {
 "required": [
 "customEngineAgents"
 ]
 }
 ]
}

{
 "declarativeAgents": [
 {
 "id": "{string}",
 "file": "{string}"
 }
 ],
 "customEngineAgents": [
 {
 "id": "{string}",
 "type": "bot"
 }
 ]
}

{
 "type": "object",
 "properties": {
 "declarativeAgents": {
 "type": "array",
 "description": "An array of declarative agent elements references. Currently, only one declarative agent per application is supported.",
 "items": {
 "$ref": "#/definitions/declarativeAgentRef"
 },
 "minItems": 1,
 "maxItems": 1
 },
 "customEngineAgents": {
 "type": "array",
 "description": "An array of Custom Engine Agents. Currently only one Custom Engine Agent per application is supported. Support is currently in public preview.",
 "items": {
 "type": "object",
 "properties": {
 "id": {
 "$ref": "#/definitions/guid",
 "description": "The id of the Custom Engine Agent. If it is of type bot, the id must match the id specified in a bot in the bots node and the referenced bot must have personal scope. The app short name and short description must also be defined."
 },
 "type": {
 "type": "string",
 "enum": [
 "bot"
 ],
 "description": "The type of the Custom Engine Agent. Currently only type bot is supported."
 }
 },
 "required": [
 "id",
 "type"
 ],
 "additionalProperties": false
 },
 "minItems": 1,
 "maxItems": 1
 }
 },
 "additionalProperties": false,
 "oneOf": [
 {
 "required": [
 "declarativeAgents"
 ]
 },
 {
 "required": [
 "customEngineAgents"
 ]
 }
 ]
}

{
 "declarativeAgents": [
 {
 "id": "{string}",
 "file": "{string}"
 }
 ]
}

{
 "type": "object",
 "properties": {
 "declarativeAgents": {
 "type": "array",
 "description": "An array of declarative agent elements references. Currently, only one declarative agent per application is supported.",
 "items": {
 "$ref": "#/definitions/declarativeAgentRef"
 },
 "minItems": 1,
 "maxItems": 1
 }
 },
 "additionalProperties": false,
 "required": [
 "declarativeAgents"
 ]
}

Properties

declarativeAgents

Array of objects that each define a declarative agent.

The declarativeAgents property is required if customEngineAgents is not specified.

Type
Array of declarativeAgentRef

Required
—

Constraints
Minimum array items: 1. Maximum array items: 1.

Supported values

declarativeAgents

Array of objects that each define a declarative agent.

Type
Array of declarativeAgentRef

Required
✅

Constraints
Minimum array items: 1. Maximum array items: 1.

Supported values

customEngineAgents

Array of objects that each define a custom engine agent.

The customEngineAgents property is required if declarativeAgents is not specified.

Type
Array of customEngineAgents

Required
—

Constraints
Minimum array items: 1. Maximum array items: 1.

Supported values

Remarks

Note

Custom engine agents support in Microsoft 365 Copilot is currently in limited private preview and not all developers have access during the staged rollout.

Examples

{
 "copilotAgents": {
 "declarativeAgents": [
 {
 "id": "agent1",
 "file": "declarativeAgent1.json"
 }
 ]
 }
}

Feedback

Was this page helpful?

Additional resources

Last updated on

URL: https://learn.microsoft.com/en-us/microsoft-365/extensibility/schema/root-copilot-agents?view=m365-app-1.28