What Changed in the Declarative Agent Manifest Version 1.5 and Why It Matters

If you have built a declarative agent for Microsoft 365 Copilot, you have spent time in the manifest. It is the JSON file that tells Copilot what your agent is, how it should behave, what knowledge it can reach, and what actions it can take. It is deceptively important. The manifest is where a lot of an agent's personality and guardrails actually live, and each new schema version quietly changes what you can express.

Version 1.5 is one of the more useful jumps. It gives you more control over how the agent grounds itself in data, what capabilities it can pull in, and how tightly you can shape its behaviour. That is genuinely good. It also means more surface area, more options to get wrong, and more temptation to overbuild. So this is a practical look at what the newer schema gives you and how we actually use it when building agents for Australian businesses, rather than a field-by-field recital of the spec.

Microsoft keeps the authoritative reference in its declarative agent manifest 1.5 documentation. Read that for the exact schema. Read this for the judgement about which bits earn their place.

What a declarative agent manifest actually does

Before the changes, it helps to be clear about what this file is for, because people new to the platform often overrate the code and underrate the manifest.

A declarative agent is not a custom-built model. It is Copilot itself, the same underlying orchestration and language model, pointed at a specific job with specific instructions and specific data. You are not training anything. You are declaring, in structured form, three things: who the agent is and how it should behave (the instructions), what knowledge it is allowed to draw on (the capabilities and data sources), and what it can do out in the world (the actions). The manifest is that declaration. Get it right and Copilot does the heavy lifting. Get it vague and you have a helpful-sounding agent with no edges.

The reason schema versions matter is that each one expands what you can declare. A newer version is not just tidier JSON. It is new levers on the agent's behaviour, and if you are still authoring against an old schema you are leaving capability on the table.

The instructions are where most of the value hides

The single most underused part of any manifest is the instructions block. This is the natural-language brief that shapes how the agent thinks and responds, and it is far more powerful than most people treat it.

I have reviewed a lot of client agents where the instructions amounted to two vague sentences, and the team then wondered why the agent was inconsistent, went off-topic, or answered questions it had no business answering. The instructions are your chance to give the agent a real character and real boundaries. Tell it what it is for. Tell it what it should refuse. Tell it the tone, the audience, the things it must never do. An agent for a mortgage broker should know it does not give financial advice, it summarises and points to a human. That belongs in the instructions, spelled out, not left to chance.

The newer schema gives you room to be more precise here, and my strong advice is to use it. Spend real time on the instructions. Test them against the awkward questions, not the easy ones. The difference between a flaky agent and a trustworthy one is very often just a well-written brief, and it is the cheapest quality improvement available to you. This is the sort of unglamorous craft our AI agent builders spend a surprising amount of time on, because it is what separates a demo from something a business will actually rely on.

Capabilities and grounding: more control, more responsibility

The bigger structural gains in the newer manifest are around capabilities, which is how you tell the agent what knowledge it can draw on. This is where an agent stops being a generic chatbot and starts being your agent, grounded in your data.

You can scope the agent to specific SharePoint sites, specific files, specific connectors, web content, and other sources. The refinement in the schema lets you be tighter about exactly what is in scope. That precision is the whole game. An agent grounded in the right three document libraries gives sharp, relevant, trustworthy answers. The same agent pointed at "everything the user can access" gives mushy answers, leaks context it shouldn't, and occasionally surfaces something embarrassing. Narrow beats broad almost every time.

Here is the honest tension though. More grounding options make it easier to over-scope out of laziness. It is tempting to give the agent access to a wide pile of content "so it has everything it might need". Resist that. Every source you add is a source the agent can misread, and a wider scope makes the agent slower and less focused. We consistently get better results by starting narrow, with the smallest set of sources that answers the real questions, and widening only when a genuine gap shows up. Treat scope as a budget you spend reluctantly, not a default you max out.

The other thing to watch is that grounding scope is also a data-governance decision. What the agent can see is what the agent can surface. In regulated industries that is not a technical footnote, it is a compliance question, and the manifest is where it gets decided. We work through exactly this with clients before publishing, because the right scope protects both the answer quality and the organisation. If your agent touches sensitive data, the manifest scoping is part of your control story, and our Copilot Studio consultants treat it that way.

Actions turn an assistant into an agent

The other capability worth calling out is actions. Instructions and grounding give you an agent that knows things. Actions give you an agent that does things, by calling out to APIs, whether Microsoft's own or your systems.

This is the line between a smart search box and a genuine agent. An agent that can look up a customer, raise a ticket, check stock, or book a slot is doing work, not just talking about it. The manifest is where you wire those actions in and, just as importantly, where you constrain them. And constraint matters more here than anywhere, because an action has consequences. A grounding source that gives a slightly off answer is a nuisance. An action that submits the wrong thing is a problem.

So when we add actions, we are deliberate about what the agent can trigger, what confirmation the user sees first, and how failures are handled. An agent that silently takes an action the user did not clearly intend is how you lose trust in one interaction. Build the actions so the human stays in the loop for anything consequential. The schema gives you the structure to do this cleanly. Whether you use it well is a design choice.

The honest assessment

A few candid thoughts after building plenty of these.

The declarative approach is genuinely the right starting point for most agents. You get Copilot's quality and safety work for free, you avoid running your own model and infrastructure, and the manifest-driven model keeps things maintainable. For the majority of internal-agent use cases, this is where you should begin, and only reach for a fully custom build when you hit a real wall. Most teams reach for custom too early and regret the maintenance burden.

The JSON authoring experience is fine but not delightful. As the schema grows, the manifest grows, and a complex agent's manifest is not a small file. The tooling helps, and you should use the schema validation, but expect to spend time getting it clean. This is not a criticism so much as a heads-up: budget for the fiddly bits.

And keep an eye on schema versions over time. Newer versions bring real capability, but they also mean your older agents are authored against older schemas, and at some point you will want to bring them forward to pick up the newer behaviour and grounding controls. Treat the manifest as living configuration, not a write-once artefact. The agents that stay good are the ones whose owners revisit the manifest as the platform moves.

Where to start

If you are building a declarative agent, spend your first real effort on two things: the instructions and the grounding scope. Write instructions that actually constrain and shape the agent, tested against hard questions. Scope the grounding as narrowly as the job allows. Those two decisions determine most of the agent's quality, long before you get anywhere near actions or the more advanced parts of the schema.

If you want help building Copilot agents that are precise, well-governed and genuinely useful rather than vaguely helpful, that is core work for us. Take a look at our wider Microsoft AI consulting, and if you have an agent you want to get right from the manifest up, get in touch.