A developer finishes a declarative agent in Copilot Studio’s Agent Builder, publishes it to the tenant catalog, and then watches every one of the intended users fail to open it — because a declarative agent requires each user to hold a Microsoft 365 Copilot license, and most of that team does not. In a parallel project, a developer told to build the more involved custom engine agent braces for a heavier licensing bill, and instead ships an agent that any user can reach in Copilot Chat with no Copilot license at all. The relationship between how much of the agent you build and what your users must be licensed for runs backwards from the assumption most developers bring to this decision — and before you choose between the two agent types, two architectural facts decide the rest: who provides the orchestrator, and who pays for what as a result.

After reading this post, you will be able to:

✅ Explain the declarative-versus-custom-engine split in terms of who runs the reasoning loop, and what that means for hosting, compliance, and proactive messaging

✅ Read a Microsoft 365 app manifest to tell whether an agent is declarative (copilotAgents.declarativeAgents) or custom engine (the bots array)

✅ Apply the verified decision framework — including three binary differentiators that often settle the choice on their own — to pick a path for a given scenario

✅ Position Copilot Studio correctly: Agent Builder always produces declarative agents, while the full Copilot Studio platform can produce either type

The Architectural Divide: Who Writes the Reasoning Loop, You or Microsoft

The word “declarative” is the whole distinction, and it is a statement about who runs the AI. In a declarative agent you declare the agent’s behavior in a configuration file — its instructions, its knowledge sources, and its actions — and Microsoft’s Copilot orchestrator and foundation models do all the reasoning, the model calls, and the response generation. You write no orchestration code and no reasoning loop. You provide three things and nothing more: custom instructions that scope how Copilot responds, custom knowledge that points at data sources (SharePoint, OneDrive, Copilot connectors, uploaded files, Teams messages), and custom actions that call external REST APIs.

A custom engine agent inverts that. You supply the orchestration layer — the reasoning loop, the model calls, the workflow logic — and the AI model or models themselves. Microsoft provides the distribution surface (Teams, Outlook, Microsoft 365 Copilot Chat), but every reasoning decision is delegated to your engine. Microsoft’s official framing is that custom engine agents “give developers the flexibility to bring their own orchestration and AI services,” with full control over workflows, models, and integrations.

That single split — whose orchestrator runs — drives two consequences that matter before you write a line of anything. The first is compliance. Because declarative agents run on Copilot’s own infrastructure, they inherit Microsoft 365’s security, compliance, and Responsible AI posture automatically; your team implements none of it. Custom engine agents must ensure their own compliance, Responsible AI practices, and security measures, because the reasoning happens on infrastructure you own. The second consequence is hosting. Declarative agents require no additional hosting — Microsoft 365 Copilot hosts them. Custom engine agents run outside Microsoft 365 on infrastructure you pay for, typically Azure App Service, Azure AI Foundry, Bot Service, or a Copilot Studio plan.

That architectural split is not abstract. It is visible in the app package, because each type registers under a different top-level manifest property.

What this means for you: decide who you want running the reasoning loop first — that one choice determines your compliance obligations and your hosting bill before any feature requirement enters the conversation.

What the Manifest Reveals: How to Identify Agent Type From the Package

Both agent types ship as the same kind of artifact: a Microsoft 365 app package, a zip file containing a manifest.json app manifest, the required color and outline icons, and any type-specific files. What differs is the capability the manifest declares.

A declarative agent is registered under the copilotAgents.declarativeAgents array in manifest.json, and points at a separate declarativeAgent.json file that carries the instructions, conversation starters, knowledge sources, and action references:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
  "manifestVersion": "1.18",
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "agent1",
        "file": "declarativeAgent.json"
      }
    ]
  }
}

Note: The property is copilotAgents.declarativeAgents — camelCase, no hyphen. An older copilot-extensions property name appears in some earlier material (including an earlier working note in this series). It is obsolete. If you are copying from a source that uses copilot-extensions, you are looking at a stale reference and current tooling will not recognize it.

The referenced declarativeAgent.json is the declarative agent manifest, a separate schema from the app manifest. Its skeleton is small — the instructions field is the equivalent of a system prompt:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json",
  "version": "v1.8",
  "name": "My Agent",
  "description": "Helps with X",
  "instructions": "You are a helpful assistant that..."
}

The declarative agent manifest schema is version 1.8 as of July 2026, which added EmailActions and MeetingActions capability declarations. A custom engine agent, by contrast, is registered under the manifest’s bots array — the standard bot registration pattern — not under copilotAgents. That is the fastest way to read an unfamiliar package: copilotAgents.declarativeAgents means declarative; a bots entry means custom engine.

Note: App manifest schema versions increment. The examples here show app manifest 1.18 for declarative agents, and custom engine agents require app manifest version 1.21 or later — but treat these as the versions shown in the current official examples, not as permanent constraints. Confirm the current production version at the Microsoft 365 app manifest schema reference before you author a manifest.

Distribution is identical for both types and offers the same two paths: submit the app package to a tenant admin for the organizational catalog (Microsoft 365 admin center → Settings → Integrated Apps), or submit to Microsoft Partner Center for the AppSource commercial store. There is no separate approval track by agent type.

What this means for you: you can classify any agent package in seconds by reading one manifest property — and if a teammate’s manifest still says copilot-extensions, treat it as out of date before you debug anything else.

The Licensing Asymmetry That Reverses Most Developers’ First Assumption

Here is the inversion stated plainly. Declarative agents are the more accessible path to build — low-code tooling, no orchestration code, Microsoft-hosted — and they demand the most from your users at runtime: every user needs a Microsoft 365 Copilot license. Custom engine agents require you to build and host an orchestration engine — and they demand nothing extra from your users at runtime: no Copilot license is required to reach them in Copilot Chat.

The last row is the one that catches teams late. An agent of either type that only uses its instructions and public web content incurs no extra usage charges. But once an agent grounds answers on shared tenant data — SharePoint content, Copilot connector data — usage-based charges measured in Copilot Credits can apply, billed through Copilot Studio. Rates change and are outside the scope of this post; confirm the current model on Microsoft’s licensing and cost considerations page before you budget. For custom engine agents built in Copilot Studio specifically, users who already hold a Microsoft 365 Copilot add-on license are covered at no extra charge, while users without one may need a Copilot Studio license or a Power Platform plan.

💡 Insight: The inversion has a clean logical explanation. A declarative agent runs on Microsoft’s licensed Copilot service, so every user consuming that service needs the entitlement — but you pay no hosting because Microsoft runs it. A custom engine agent consumes no Microsoft 365 Copilot service entitlement for reasoning, so users need no Copilot license — but you pay for the infrastructure that does the reasoning instead. You are always paying for the orchestrator. The only question is whether you pay Microsoft in licenses or pay your cloud provider in hosting.

What this means for you: price the licensing before you pick the path — a declarative agent for a 5,000-person tenant is a 5,000-seat Copilot commitment, while a custom engine agent for the same audience is a hosting line item and zero seat requirement.

Why Copilot Studio Shows Up on Both Sides of This Comparison

Most readers meeting Copilot Studio for the first time assume it produces one kind of agent. It produces both, and conflating the two is the single most common taxonomy error in this space. The clarifying move is to separate the tool from the platform.

Agent Builder — the no-code tool embedded directly in Microsoft 365 Copilot — always produces a declarative agent. It uses Microsoft 365 Copilot’s orchestrator, inherits Microsoft 365 compliance, needs no external hosting, and therefore requires a Copilot license for its users. This is the default path for makers who encounter agent building through the Copilot chat surface, and it is where the licensing surprise in this post’s opening comes from.

The full Copilot Studio platform can produce either type. Used one way, it builds a declarative agent that runs on Microsoft 365 Copilot’s orchestrator — the same output as Agent Builder, through the fuller product. Used another way, Copilot Studio acts as the orchestration platform itself: the agent runs on Copilot Studio’s own managed orchestrator (not Microsoft 365 Copilot’s), connects to Power Platform connectors, Dataverse, and HTTP actions, and is therefore architecturally a custom engine agent — one where the “engine” is Copilot Studio’s managed service rather than code you host. That agent requires no Microsoft 365 Copilot license for its users but does require Copilot Studio licensing for the platform.

Copilot Studio’s full build surface — its knowledge, actions, tools, and MCP support — is the subject of Post 12. This post fixes only the taxonomy: which build path yields which agent type, and what that means for licensing.

What this means for you: never let “we built it in Copilot Studio” stand as an answer to “what agent type is this?” — ask which build path was used, because the answer changes your users’ license requirements.

Three Binary Differentiators That Often Make the Choice Without the Full Decision Table

Before you reach for a full comparison, three yes/no questions settle a large share of real scenarios on their own. Each one, answered “yes,” rules declarative agents out entirely.

Proactive interactions is the sharpest of the three. Declarative agents are user-initiated: a user must send a message for anything to happen. Custom engine agents can be programmatically triggered — they can alert on a threshold, notify on an event, or start a workflow on a schedule with no user in the loop. If your scenario needs the agent to reach out first, that alone is the decision.

Group collaboration follows the same logic. Declarative agents are designed for individual use. Custom engine agents support multiple users interacting with one agent in a Teams channel or meeting — a loan approval thread a manager and an analyst both work in, for example.

External channels is the widest. Declarative agents run only inside Microsoft 365 applications — Teams, Word, Excel, Outlook. Custom engine agents can also run on external websites, mobile apps, and partner platforms. If any intended user lives outside Microsoft 365, custom engine is the only option.

✅ Quick win: Answer these three before you write your first line of manifest or open Copilot Studio. If any one is “yes,” you are building a custom engine agent — the manifest uses the bots array, your users need no Copilot license, and you own the hosting. If all three are “no,” declarative is on the table and usually the faster route.

What this means for you: run the three-question gate first — a single “yes” here saves you from designing against a declarative agent that can never meet the requirement.

The Full Decision Framework: Build Declarative When, Build Custom Engine When

When the three gates do not settle it, Microsoft’s own decision criteria do. The lists below come directly from the official agents-overview comparison, updated 2026-08-11.

Build a declarative agent when:

• The agent should work within Copilot’s existing orchestration and language models, for security and compliance consistency with Microsoft 365.
• You want faster implementation — anywhere from low-code tools (Agent Builder, Copilot Studio) to a streamlined pro-code experience (Agents Toolkit in VS Code).
• The user’s workflow lives inside Microsoft 365 apps — SharePoint, OneDrive, Teams.
• Inheriting Microsoft 365’s compliance and Responsible AI posture is sufficient for the scenario.

Microsoft’s anchor examples are an IT helpdesk agent that responds to @mentions in Teams and a document-summarization agent scoped to SharePoint content — both individual, both inside Microsoft 365, both fine on Copilot’s orchestrator.

Build a custom engine agent when:

• The workflow requires custom orchestration, specific business logic, or integration across multiple systems.
• You need a fine-tuned, domain-specific, or non-Microsoft AI model.
• You need group productivity — multiple users collaborating with the agent in a Teams channel.
• You are integrating an existing conversational assistant that already lives outside Copilot.
• The agent must operate outside Microsoft 365.
• You need proactive messaging.

Microsoft’s anchor example is a financial loan approval agent with specific business rules and multiple external credit-check integrations — custom orchestration, external systems, and a collaborative workflow all in one.

The boundary is crossable. Microsoft documents a conversion path from a declarative agent to a custom engine agent, so a wrong first guess is recoverable if requirements grow — but the conversion is an architectural change, not a setting, so it is far cheaper to answer the gates correctly up front.

What this means for you: map your scenario against both lists before committing — if it lands cleanly in the declarative column, take the faster path, and only reach for custom engine when a real requirement forces it.

Cleaning Up the Terminology: “Plugin,” “Action,” “API Plugin,” and Where the SDKs Fit

Two terminology tangles trip up readers who move between older and current docs.

The first is “plugin.” Action is the current term for a capability a declarative agent can perform — one of the three configuration elements alongside instructions and knowledge. API plugin is the current term for the artifact that implements an action: a separate manifest JSON file carrying an OpenAPI reference, pointed at from the declarative agent manifest’s actions. The bare word “plugin” is being superseded and still lingers in some current pages, but “action” (the capability) and “API plugin” (the artifact) are the authoritative terms. One scoping constraint matters: API plugins are currently supported only as actions inside declarative agents — they are not enabled in standalone Microsoft 365 Copilot.

The second tangle is treating the SDKs as agent types. They are not. Microsoft 365 Agents SDK, Teams AI Library (the Teams SDK), and Microsoft Foundry are implementation tools for building custom engine agents. Whichever one you use, the result is a custom engine agent — the SDK does not create a new category.

Note: The table shows Copilot Studio agents as organization-publish only — they cannot currently target the AppSource commercial store. Only agents built with the Teams SDK, Agents SDK, or Foundry (via the Agents Toolkit) can be published to AppSource. This feature area has been evolving, so confirm the current Copilot Studio publishing scope on the custom engine agent overview before you plan a commercial distribution.

One preview item is worth naming so you can set it aside: Work IQ Dev Tools (wiqd) is a preview command-line tool for the declarative agent lifecycle. It is not required for production use and is out of scope here. The implementation detail behind this table belongs to Posts 12 and 13.

What this means for you: when a doc or a colleague says “plugin,” translate it to “action” or “API plugin” before you act on it — and never let a choice of SDK stand in for a choice of agent type, because every one of these tools produces the same custom engine category.

Eight Questions to Answer Before You Commit to Either Path

Run this as a pre-decision checklist. Any “yes” on the capability questions (1, 2, 3, 5) or a “no” on question 4 excludes declarative agents and points you to custom engine.

• Proactive messaging — Does the scenario need the agent to trigger actions or messages with no user input? A “yes” means custom engine only.
• Group collaboration — Will multiple users interact with the agent in a shared Teams channel or meeting? A “yes” means custom engine only.
• External channels — Must the agent run outside Microsoft 365 applications? A “yes” means custom engine only.
• User licensing — Do all intended users hold a Microsoft 365 Copilot license, or can you require them to get one? A “no” excludes declarative agents.
• Custom AI models — Does the scenario need a fine-tuned, domain-specific, or non-Microsoft model? A “yes” means custom engine only.
• Compliance ownership — Is the team ready to build and maintain its own compliance and Responsible AI layer? This is required for custom engine and inherited for declarative.
• Hosting budget — Is there Azure or Copilot Studio infrastructure cost in the project budget? This is required for custom engine and not required for declarative.
• AppSource publishing — Must the agent reach the AppSource commercial store? Not available for Copilot Studio–built agents; available for Agents Toolkit, Teams SDK, and Foundry-built agents.

If questions 1, 2, 3, or 5 are “yes,” or question 4 is “no,” you are building a custom engine agent. If none of those exclusions fire, a declarative agent is the likely faster path.

What this means for you: walk this list before the first design meeting — it turns a vague “which agent should we build” into a short set of answers your architecture, budget, and licensing all fall out of.

Now What? Your Next Three Steps

1. Run the three-question gate — Check proactive interactions, group collaboration, and external channels against your scenario. If any one is required, you are building a custom engine agent; your next stop is Microsoft’s custom engine agent overview.

2. Check your Copilot licensing before touching a manifest — If you are heading toward a declarative agent, confirm that every user who needs it holds a Microsoft 365 Copilot add-on or an eligible Copilot Chat license. This is a design-time commitment, not a runtime detail.

3. Choose your starting tool — Start in Agent Builder for the fastest declarative path with no manifest authoring, or in the Agents Toolkit in VS Code for full manifest control and store publishing. Read Post 12 before you commit to Copilot Studio’s full platform, because that is where a build path can quietly change your agent type.

How to Navigate This Series

This series runs 13 posts across 3 phases, moving from API landscape and governance foundations through the core Copilot API surfaces into agent architecture and extensibility.

• Phase 1 — Foundations and Governance (Posts 01–04): API landscape (Post 01), auth and permissions (Post 02), rate limits and national cloud readiness (Post 03), and usage reporting (Post 04).
• Phase 2 — Building with Core APIs (Posts 05–09): Package Management API (Post 05), Retrieval API (Post 06), Chat API (Post 07), Meeting AI Insights (Post 08), and AI Interactions Change Notifications (Post 09).
• Phase 3 — Agents and Extensibility (Posts 10–13): Copilot connectors (Post 10), this post on declarative versus custom engine agents (Post 11), building agents in Copilot Studio (Post 12), and SPFx and enterprise integration patterns (Post 13).

By role:

• Architects choosing an extensibility path: → Post 01 → Post 10 → Post 11 → Post 12
• Developers building an agent: → Post 02 → Post 07 → Post 11 → Post 13
• Low-code makers evaluating Copilot Studio: → Post 11 → Post 12

This post sits in the middle of Phase 3 and settles the agent taxonomy that the rest of the phase builds on. The knowledge sources a declarative agent consumes are the Copilot connectors set up in Post 10; the Copilot Chat surface where both agent types appear is the subject of Post 07; and the series’ overall landscape is Post 01.

The immediate next post is Post 12 — Building Agents in Microsoft Copilot Studio: Knowledge, Actions, Tools, and MCP, which opens up the full Copilot Studio build surface for readers whose scenario landed on the declarative or Copilot Studio path. Developers building pro-code integrations for either agent type will find those patterns in Post 13.

References

All claims in this post trace to the following official Microsoft documentation:

• 1. Agents for Microsoft 365 Copilot — taxonomy overview, decision table, “build when” guidance, declarative-versus-custom-engine comparison (updated 2026-08-11) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/agents-overview
• 2. Declarative agents for Microsoft 365 Copilot — definition, build tools, national cloud support, Agent Builder output, no-additional-hosting characteristic (updated 2026-07-02) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/overview-declarative-agent
• 3. Custom engine agents for Microsoft 365 — definition, development approaches, tool comparison table, hosting and compliance requirements (updated 2026-08-11) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/overview-custom-engine-agent
• 4. Microsoft 365 app model for agents (agents are apps) — app package structure, the copilotAgents.declarativeAgents property, icon requirements, distribution paths, API plugin scoping (updated 2026-07-21) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/agents-are-apps
• 5. Licensing and cost considerations for Copilot extensibility — declarative-versus-custom-engine licensing table, Copilot Credits model, hosting cost breakdown (updated 2026-07-02) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/cost-considerations
• 6. What’s new for Microsoft 365 Copilot developers — taxonomy stability, declarative agent manifest v1.8 release (July 2026) (updated 2026-07-29) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/whats-new
• 7. Declarative agent manifest schema version 1.8 — current schema version, EmailActions and MeetingActions additions — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/declarative-agent-manifest-1.8
• 8. Microsoft 365 Agents SDK — custom engine agent deployment to Microsoft 365 Copilot and Teams; multi-channel agent framework — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/create-deploy-agents-sdk
• 9. Convert your declarative agent to a custom engine agent — confirms the architectural boundary is crossable — https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/convert-declarative-agent
• 10. Extend Microsoft 365 Copilot (extensibility landing page) — the two extensibility approaches — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/
• 11. Microsoft 365 Copilot extensibility FAQ — additional taxonomy clarifications — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/faq