The Declarative Agent Manifest Version 1.0 - What It Is and Why the Version Number Matters

Most people building their first agent on Microsoft 365 Copilot never look at the manifest. They use the visual builder, they get something working, and the JSON that sits underneath is invisible to them. That is fine right up until it isn't. The moment you need to do something the builder does not expose, or you hit a strange behaviour and someone asks "what version is your manifest", you discover there is a spec underneath all of this, it has versions, and the version you are on decides what your agent can and cannot do.

The declarative agent manifest version 1.0 is where that story starts. It is the original schema for describing a declarative agent: the file that tells Copilot what your agent is called, what it is for, what instructions it follows, and what knowledge it can reach. Microsoft has moved well past 1.0 now, but understanding the 1.0 manifest is still worth doing, because it is the foundation the later versions build on, and because knowing how versioning works here saves you from a specific kind of pain later. Microsoft's version 1.0 manifest documentation is the reference. Here is the consultant's read.

What a declarative agent actually is

Worth being clear about the term, because "agent" is doing a lot of overloaded work in the market right now. A declarative agent is not a from-scratch AI system. It is Microsoft 365 Copilot, the same underlying model and orchestration, pointed at a specific job with specific instructions and specific knowledge. You are not building the intelligence. You are declaring how you want the existing intelligence to behave for your use case. Hence "declarative".

The manifest is how you declare it. It is a JSON file that says: here is the name, here is the description, here are the instructions that shape how this agent responds, and here are the knowledge sources it is allowed to draw on. That last part is where a lot of the value lives, because an agent grounded in your SharePoint sites, your documents, or a connected data source behaves very differently from generic Copilot. It answers from your material rather than from the whole world.

Version 1.0 gave you the core of that. The identity fields, the instructions, and the ability to attach knowledge. It was deliberately simple, which is both its strength and the reason it did not stay the only version for long.

Why the version number is not a detail

Here is the thing people underestimate. The manifest has a schema version, and that version is not cosmetic. It determines which fields are valid, which capabilities you can express, and how Copilot interprets the file. An agent written against 1.0 has a smaller vocabulary of things it can say about itself than one written against a later version. If you need a capability that arrived in a newer schema, being on 1.0 means you simply cannot express it, no matter how you word the JSON.

This trips people up in both directions. Some teams pin to 1.0 because that is what an old sample used, then wonder why a feature they read about does not work. Others copy a newer manifest into an environment that expects an older schema and get validation errors they cannot explain. The version is a contract between your file and the platform. Get the contract wrong and things fail in ways that look mysterious until you realise the mismatch.

My honest advice: know which version you are targeting, write it down, and treat a version bump as a real change rather than a find-and-replace. When we build custom AI agents for clients, the manifest version is something we track deliberately, because a change there can quietly alter behaviour or unlock a feature we have been waiting for. It is infrastructure, and you treat it like infrastructure.

Where 1.0 fits now

Let me be straight about this. You probably should not start a new agent on version 1.0 today. The schema has moved on, later versions added meaningful capabilities, and there is no prize for beginning on the oldest available spec. If you are starting fresh, start on a current version and get the newer features for free.

So why care about 1.0 at all? Two reasons. First, understanding it teaches you the shape of the whole thing. Every later version is 1.0 plus more, so the mental model you build from the original carries forward. The identity, the instructions, the knowledge sources: those core ideas did not go anywhere, they just got richer. Learn the base and the rest reads easily.

Second, you will meet 1.0 in the wild. Older agents, older samples, older internal builds that someone stood up eighteen months ago and never touched again. When you inherit one of those, knowing what 1.0 could and could not do tells you immediately what you are working with and what upgrading would buy you. A lot of our Microsoft AI consulting work is exactly this: someone has an agent that works but nobody remembers how it was built, and the first job is reading the manifest to understand what we are actually dealing with.

The instructions field is where the real work is

If there is one part of the manifest, at 1.0 or any version, that decides whether your agent is good or mediocre, it is the instructions. This is the plain-language brief you give the agent about how to behave, what tone to take, what to prioritise, and what to avoid. It reads like prose, and it is tempting to dash it off in five minutes. Do not.

The gap between a vague instruction and a precise one is the gap between an agent that guesses and an agent that helps. "You help users with HR questions" is nearly useless. Something that spells out which policies to lean on, how to handle a question it cannot answer, when to point someone to a human, and what not to speculate about produces a completely different agent. The model is capable. The instructions are how you aim it.

We spend real time on this with clients, and it is some of the highest-return work in the whole build. It is also work that does not require a developer, which surprises people. A subject matter expert who understands the job the agent is doing can often write far better instructions than an engineer who does not know the domain. The manifest just holds the text. Getting the text right is a thinking exercise, not a coding one.

The honest bits, what to watch out for

A few things worth saying plainly.

First, do not confuse a valid manifest with a good agent. The schema will happily accept a technically correct file that produces a useless agent. Passing validation means the JSON is well-formed, not that the agent is helpful. The quality comes from the instructions and the knowledge sources, and neither of those is something the validator checks. Test with real questions from real users, because that is the only feedback that matters.

Second, knowledge sources are a governance question, not just a technical one. The moment you point an agent at a SharePoint site or a document library, you are deciding what information it can surface and to whom. An agent that reaches content a user should not see is a data exposure incident wearing a friendly interface. Be deliberate about what you connect, and make sure the permissions underneath are right before you make that content easy to ask for. This belongs in a broader AI strategy conversation, not a quiet decision made by whoever built the agent.

Third, the platform moves quickly. Version 1.0 is proof of that on its own: it exists as a historical marker because the schema kept advancing. What is current today will be superseded. Build with that in mind, keep an eye on the changelog, and do not treat any version as permanent. The teams that stay current get the new capabilities; the teams that set and forget end up on an old schema wondering why the world moved on without them.

Fourth, the visual builder hides the manifest for a reason, and that reason is mostly good. For simple agents, you may never need to touch the JSON directly. But the moment your needs get specific, understanding the manifest is what lets you do things the builder does not expose. Knowing the file is there, and roughly what lives in it, is the difference between being stuck at the builder's ceiling and being able to go further when you need to.

Who should care about this

If you are an Australian organisation building agents on Microsoft 365 Copilot with any seriousness, someone on your side should understand the manifest and its versioning. Not everyone, but someone. It is the layer where capability and behaviour are actually defined, and treating it as invisible works until the day it doesn't.

If you are just getting started and the visual builder does everything you need, you do not have to become a manifest expert overnight. Build, test, learn what jobs are worth doing. The manifest matters most when you outgrow the builder or inherit something you need to understand, and both of those are good problems to have because they mean you are actually using this stuff.

Most of the organisations we work with want agents that do a real job and keep doing it as the platform evolves underneath them. That takes understanding the layers, including the boring ones like the manifest version. If you want a partner who tracks that detail so you do not have to, that is what we do. Have a look at how we work as Microsoft AI consultants, or get in touch and we will give you a straight read on where to start.

For the schema itself and the current state of the spec, Microsoft's version 1.0 manifest documentation is the place to keep bookmarked.