Converting a Declarative Agent to a Custom Engine Agent - When and How

There is a moment in a lot of Microsoft 365 Copilot projects that goes like this. A team builds a declarative agent, ships it, and it works. People use it. Then a request comes in that the declarative agent simply cannot do, and someone asks whether they need to throw the whole thing out and start again as a full custom build. The answer, more often than people expect, is no. Microsoft provides a documented path to convert a declarative agent into a custom engine agent, and it keeps a fair bit of your work intact. Microsoft's page is Convert to custom engine agent, and it is worth reading. This post is the consulting view: when the conversion is the right move, what it actually gives you, and the parts nobody warns you about.

A quick reminder of the two things

You cannot make sense of the conversion without being clear on what you are converting from and to, so here is the short version.

A declarative agent is the lightweight option. You describe the agent with instructions, point it at knowledge sources, wire in some actions, and it runs entirely on Copilot's own orchestrator and Copilot's own model. You do not host anything. You do not choose the model. It is fast to build and cheaper than most people assume, and for a huge number of "answer questions about our stuff" use cases it is exactly right.

A custom engine agent is the pro-code option. You bring your own orchestration, your own code, and your own choice of model, hosted on infrastructure you control. It still appears inside Teams and Microsoft 365 Copilot like any other agent, but everything behind the chat window belongs to you. More power, more responsibility, more cost.

The conversion is the bridge between them. It exists because Microsoft recognises that plenty of agents start life as the simple thing and then outgrow it, and forcing a full rebuild every time would be daft.

What the conversion actually does

Here is the honest framing, because the word "convert" oversells it slightly. The conversion does not magically turn your declarative configuration into a running custom application. What it does is give you a scaffolded starting point that carries across the things worth carrying: the agent's instructions, its manifest and app registration details, and the overall shape of what you already built. You end up with a project you can open in the Agents Toolkit and run as a custom engine agent, pre-populated with the identity and intent of the declarative agent you started from.

That matters because those are exactly the fiddly bits people dread redoing. App registration, the manifest, the packaging, the identity that admin already approved in your tenant: keeping that continuity means the converted agent can slot into the same place your declarative one occupied, rather than arriving as a stranger that needs fresh admin consent and a new approval conversation. If you have ever been through a tenant admin approval cycle, you understand why not repeating it is a genuine win.

What the conversion gives you, in plain terms, is a head start, not a finished product. You get the boilerplate and the identity. You still have to build the actual engine.

What it very much does not do

This is the part I make sure clients hear clearly. Converting to a custom engine agent hands you the keys and an empty vehicle. Everything that Copilot was doing for you automatically, you now own.

The orchestration is yours. In a declarative agent, Copilot decides how to interpret the user, when to call your actions, and how to weave in your knowledge sources. The moment you convert, that reasoning loop is your code to write. The model call, the tool calling, the handling of multi-turn conversation, the deciding what to do when the model asks for something that fails: all of it becomes your responsibility. This is the whole point of converting, but people underestimate how much invisible work Copilot's orchestrator was doing until they have to reproduce it.

The model is yours to choose and yours to pay for. A declarative agent runs on Copilot's model at no separate inference cost to you. A custom engine agent runs on whatever you wire up, which for most of our enterprise clients means Azure OpenAI or another model hosted in their own Azure subscription, and that carries its own consumption bill. The economics change. Sometimes they change in your favour, because a custom engine agent can serve users who do not hold a Copilot licence, and for a large organisation that trade can work out well. But it is a real calculation, not a footnote, and it is worth running properly before you commit. This is exactly the kind of sizing our Microsoft AI consultants run with clients before a conversion, because the answer genuinely swings both ways depending on headcount and usage.

The knowledge grounding changes shape too. Declarative agents lean on Copilot's built-in retrieval over your Microsoft 365 content. Once you are running your own engine, you are responsible for how the agent retrieves and grounds its answers. If you were relying on Copilot quietly doing good retrieval over SharePoint for you, you now have to build that retrieval pipeline yourself, and doing it well is not trivial.

How to tell you have actually hit the ceiling

The mistake I see most is converting too early, because the custom path looks more capable and engineers find it more interesting. So before anyone touches the conversion, I push clients to check whether they have genuinely exhausted the declarative option. A few honest triggers usually settle it.

You need a specific model, in a specific region, or the ability to swap models as the market moves. Declarative agents do not offer that. If regulatory or data-residency requirements dictate the model and where it runs, that is a legitimate reason to convert.

Your logic is genuinely code-shaped. Multi-step workflows with real branching, half a dozen internal systems to orchestrate with proper error handling, business rules that would be misery to express as declarative instructions. If the whiteboard sketch of your agent looks like software architecture, it should be software.

You need to reach people who do not have a Copilot licence. This is the one that quietly tips a lot of decisions. A custom engine agent runs in Teams for the whole tenant without every user needing a Microsoft 365 Copilot seat. For an organisation where only a slice of staff have Copilot licences but everyone needs the agent, the sums can favour a custom build even before you consider the extra capability.

If none of those apply, the honest advice is to stay declarative and push the simpler tool further than you think it can go. We spend a real portion of our Copilot Studio and Copilot work talking teams out of conversions they would enjoy but the business does not need, because the rebuild is not the expensive part. Operating a custom agent for the next three years is.

The honest assessment

What works well: the conversion is a sensible piece of tooling and it saves you the tedious re-registration and manifest work. Microsoft has clearly listened to the reality that agents evolve, and providing a defined path from simple to complex is the right design. The Agents Toolkit experience on the far side is decent, and if you have a team that already ships software, the converted project will feel familiar.

What is still rough: the gap between "converted" and "working well" is large, and the conversion tooling cannot close it for you. You inherit a scaffold, then face the actual engineering of orchestration, retrieval, evaluation, and guardrails. Microsoft's agent tooling has also been reorganising itself for a couple of years, so pin your versions and expect the occasional tutorial that no longer matches the current toolkit. And budget for the first production deployment being slower than anyone plans, because custom engine agents bring the full weight of app registration, hosting, monitoring, and someone on call when it misbehaves.

The deeper point is the one I close every one of these conversations with. Converting is not a shortcut to a better agent. It is a decision to take on ownership of everything Copilot was doing for you invisibly, in exchange for control you may or may not need. When the need is real, it is the right call and the conversion path makes it markedly less painful than a rebuild. When the need is imagined, you have just signed up to operate software you did not have to. Working out which situation you are in is most of the value, and it is precisely the conversation our AI agent development team has with clients before a line of the converted project gets written.

If you think you are at the ceiling, do the cheap checks first. Write down which of the three triggers actually apply to you. Run the conversion in a test tenant and have a developer spend a day with the scaffold to feel the shape of what you are taking on. And map who owns the thing in production, because a custom engine agent without an owner becomes an Azure bill with no one watching it. Convert because you hit the wall, not because the wall looked more fun from the other side.