What Are Declarative Agents for Microsoft 365 Copilot?

If you’ve heard the term declarative agent floating around the Microsoft 365 Copilot ecosystem and wondered what it actually means: this is the post for you. Declarative agents are the fastest way to build purpose-built AI assistants on top of Copilot, and you don’t need to write a single line of runtime code to ship one.

What Is a Declarative Agent?

A declarative agent is an AI assistant you describe, not one you code. Instead of writing conversation logic, prompt orchestration, or model-calling code, you author a JSON manifest that tells Microsoft 365 Copilot what the agent should do: its name, instructions, knowledge sources, and actions. Copilot handles the how: reasoning, response generation, grounding, and safety.

Think of it this way: you’re writing a job description, not building a robot. You define the role, the tools the agent can use, and the boundaries it should respect. The foundation model (GPT) handles the rest.

How the Architecture Works

Declarative agents don’t run independently. They plug into the Microsoft 365 Copilot orchestrator, which coordinates every interaction between the user, the foundation model, and your agent’s configuration.

Here’s the data flow:

1. User sends a message: in Teams, Outlook, Word, the Microsoft 365 Copilot app, or any Copilot surface.
2. Copilot orchestrator receives the message and loads your agent’s manifest.
3. Instructions shape the model’s behavior: defining what the agent should do, how it should respond, and what it should avoid.
4. Capabilities ground the response in real data: SharePoint files, emails, Graph Connectors, Dataverse records, or anything that suits your grounding needs.
5. Actions let the agent do things: call REST APIs via API plugins or invoke tools through MCP servers.
6. The foundation model (GPT) reasons over everything and generates a response.
7. Microsoft 365 enforces security, compliance, and permissions at every step. Users only see data they already have access to.

The orchestrator is the critical piece. It handles prompt composition, retrieval-augmented generation (RAG), action execution, and safety filtering. Your manifest is the configuration layer on top of all that infrastructure.

Declarative vs Custom Engine Agents

Not every scenario fits a declarative agent. Microsoft 365 Copilot extensibility offers two agent models: here’s how to pick.

	Declarative Agent	Custom Engine Agent
Model	Copilot’s foundation model (GPT)	Your own model (Azure OpenAI, Claude, xAI, Mistral, etc.)
Hosting	None, runs inside Copilot	You host the bot service
Auth & Compliance	Inherited from Microsoft 365	You manage it
Build Time	Minutes to hours	Days to weeks
Conversation Control	Orchestrator-managed	Full control (state machines, multi-turn)
Best For	Knowledge assistants, grounded Q&A, task automation	Cross-platform bots, custom models, complex dialog flows

My guidance: declarative agents are the right choice roughly 90% of the time. Start here unless you need one of these:

• A custom or fine-tuned model: your own LLM or a specialized model for a domain.
• Complex multi-turn state machines: branching dialog flows with conditional logic you control step by step.
• External reach: you need the assistant to work outside the Microsoft 365 ecosystem entirely, reaching users on external websites, third-party platforms, or other chat clients.
• Full conversation ownership: you want to control every token in the response.

If your scenario is “help people find answers using company data and take actions through APIs,” a declarative agent will get you there faster and with less operational burden.

What Can a Declarative Agent Do?

Declarative agents combine knowledge grounding, actions, and built-in capabilities to deliver useful responses. Here’s the full capability set:

Knowledge & Grounding

Capability	What It Does
OneDriveAndSharePoint	Grounds responses in files from SharePoint sites and OneDrive
GraphConnectors	Surfaces data from Graph Connector sources (ServiceNow, SAP, etc.)
Email	Searches the user’s Exchange mailbox or group mailboxes for relevant context
People	Provides org chart and profile data from Microsoft Entra ID
TeamsMessages	Searches Teams chat and channel messages
Dataverse	Queries Dataverse tables for business data
WebSearch	Grounds responses using Bing web search results
ScenarioModels	Uses Microsoft-curated AI models optimized for specific scenarios
Meetings	Searches Teams meetings and transcripts for relevant context
EmbeddedKnowledge	Grounds responses in files packaged locally within the app itself

Actions

Type	What It Does
API Plugins	Calls REST APIs described with an OpenAPI spec, CRUD operations, workflows, data lookups
MCP Servers	Invokes tools exposed via the Model Context Protocol, the open standard for agent tooling

Built-in Capabilities

Capability	What It Does
CodeInterpreter	Executes Python code for data analysis, calculations, and chart generation
GraphicArt	Generates images using image models through Copilot

Where Declarative Agents Run

One of the strongest advantages of declarative agents is surface portability. The same agent manifest works across every Microsoft 365 Copilot surface:

• Microsoft Teams: as a chat-based assistant
• Microsoft Outlook: inline in email composition and reading
• Microsoft Word, PowerPoint, Excel: contextual help while working in documents
• Microsoft 365 Copilot in the browser: the web experience at microsoft365.com/copilot
• Microsoft 365 Copilot on desktop: the Copilot experience on Windows and Mac

You define the agent once. Copilot handles rendering and interaction patterns for each surface. No per-platform code, no separate deployments.

The Manifest at a Glance

A declarative agent is defined by two files: the app manifest (manifest.json) and the agent configuration (declarativeAgent.json). Here’s a minimal example.

manifest.json: the Teams/M365 app manifest (schema v1.24):

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json",
  "manifestVersion": "1.24",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "1.0.0",
  "name": {
    "short": "My Agent",
    "full": "My Declarative Agent"
  },
  "description": {
    "short": "A declarative agent for Microsoft 365 Copilot",
    "full": "A declarative agent that helps users find answers and take actions."
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}

declarativeAgent.json: the agent configuration:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "My Agent",
  "description": "A declarative agent that helps users find answers and take actions.",
  "instructions": "You are a helpful assistant. Answer questions accurately and concisely. If you don't know the answer, say so and suggest where the user might find more information.",
  "capabilities": [
    { "name": "OneDriveAndSharePoint" },
    { "name": "People" }
  ],
  "actions": [
    {
      "id": "myPlugin",
      "file": "my-plugin.json"
    }
  ]
}

That’s it. Two JSON files, and you have a working agent definition. The instructions shape behavior, the capabilities connect to data, and the actions let the agent call external systems.

What’s Next

Now that you understand what declarative agents are and how they fit into the Microsoft 365 Copilot architecture, the best next step is to try building one. The official Microsoft Learn documentation has everything you need to get started:

• Build your first declarative agent for a hands-on walkthrough
• Declarative agent manifest reference to explore all available properties and capabilities
• Microsoft 365 Agents Toolkit to scaffold and deploy your agent with minimal setup

Resources

• Overview of Declarative Agents
• Declarative Agent Manifest Reference
• Declarative Agent Architecture
• Build Declarative Agents
• Declarative Agent Best Practices