Customising Declarative Agent Behavior in Microsoft 365 Copilot - A Practical Guide

Most organisations that deploy Microsoft 365 Copilot hit the same realisation after a few weeks. The base product is fine for generic tasks, but it doesn't know anything about how your business actually works. It doesn't know your processes, your terminology, your quirks. So people stop using it, or worse, they keep using it and just accept mediocre answers.

Declarative agents fix this. You build a scoped version of Copilot that behaves the way you need it to. But here's the thing - the difference between a declarative agent that people actually use and one that gathers dust comes down to how well you customise its behaviour. Not the knowledge sources, not the API plugins. The instructions you write and the conversation starters you set up. That's what determines whether users trust the agent and come back to it.

We've built a fair number of these for Australian organisations at this point, and the behaviour customisation is where I see the most variation in quality. So let me walk through what works.

The Manifest Is Your Control Centre

Everything about a declarative agent's behaviour lives in the declarativeAgent.json file inside your app package. This is the file where you define what your agent does, how it talks, what it knows, and what actions it can take. If you've built Teams apps before, you'll recognise the structure - it's a JSON manifest with a well-defined schema.

The Microsoft documentation on customising declarative agent behaviour covers the full schema. What I want to focus on here are the two properties that have the most impact on user experience: instructions and conversation starters.

The current manifest schema (v1.4 and above) added a behavior_overrides property that gives you finer control over how the agent responds. But the core elements - instructions and conversation starters - have been there from the start and remain the most important things to get right.

Writing Instructions That Actually Work

Instructions control how your agent responds to users. They go in appPackage/instructions.txt, a plain text file that the manifest references. You can think of them as a detailed brief you'd give a new team member on their first day, except this team member has perfect recall and zero common sense.

That last bit is the key insight. The agent will follow your instructions literally. If you leave gaps, it will fill them with generic Copilot behaviour, which is rarely what you want for a business-specific agent.

Here's what I've seen work across deployments:

Start with identity, then scope. The first few lines should tell the agent who it is and what it does. Not in vague terms - be specific. "You are the IT support agent for [Company Name]. You help employees with technical issues related to laptops, VPN access, email configuration, and software installation. You do not handle HR questions, facilities requests, or anything outside IT support."

Define the boundaries explicitly. This matters more than people think. Without clear boundaries, agents try to be helpful by answering questions they shouldn't. We built a procurement agent for a client that kept answering general business strategy questions because the instructions only said what it should do, not what it shouldn't. Adding a clear "if the question is about X, Y, or Z, politely redirect the user to [specific resource]" section fixed it immediately.

Include examples of real queries. Don't just describe what the agent handles in abstract terms. Give it concrete examples. "When a user asks 'how do I connect to the VPN from home,' refer to the Remote Access Guide in the IT Knowledge Base. When a user asks about software licences, check the Software Catalogue spreadsheet first." The more real examples you provide, the better the agent handles variations of those queries.

Specify tone and format. Do you want responses in dot points or paragraphs? Should the agent be formal or conversational? Should it include links to source documents? These seem like small details but they have a bigger effect than you'd expect on whether users feel comfortable with the agent. For one financial services client, we explicitly instructed the agent to always cite the specific policy document and section number when answering compliance questions. That single instruction made the difference between the compliance team trusting the agent and dismissing it.

Keep it under control. I've seen instruction files that run to thousands of words, trying to anticipate every possible scenario. They don't work better. The agent gets confused when instructions are contradictory or overly complex. A clear, well-structured instruction file of 300-500 words typically outperforms a rambling 2,000-word one. If you find yourself writing extensive instructions, that's a signal you might need two separate agents instead of one.

One mistake I see teams make repeatedly: writing instructions like they're writing documentation for a human colleague. The agent doesn't need motivation or context about why the company exists. It needs clear rules about what to do when specific things happen. Save the storytelling for the agent's description field.

Conversation Starters - Your Agent's First Impression

Conversation starters are the suggested prompts that appear when a user first opens your agent. They're configured as a JSON array in declarativeAgent.json, and you can have up to 12 of them. Each one has a title (the short text displayed on the button) and text (the full prompt that gets sent when the user clicks it).

Here's what the configuration looks like:

"conversation_starters": [
  {
    "title": "Check VPN status",
    "text": "What's the current status of the company VPN? Are there any known outages?"
  },
  {
    "title": "Request software",
    "text": "I need to request access to a new software application. What's the process?"
  },
  {
    "title": "Reset my password",
    "text": "How do I reset my network password?"
  }
]

Sounds straightforward, and it is technically. But the strategic choices about which starters to include make a real difference to adoption.

Use them to show range. If your agent handles five different types of queries, include at least one starter for each type. Users will assume the agent can only do what the starters suggest. If all your starters are about password resets, people won't think to ask about software licences.

Write the text field as a real user would. Not as a formal prompt, not as a search query. Write it the way someone would actually type it into a chat box. "How do I set up my laptop for working from home?" beats "Provide instructions for remote workstation configuration." Users model their own language on what they see, so natural-sounding starters lead to natural-sounding queries, which the agent handles better.

Put the most common use case first. The first two or three starters get the most clicks by a wide margin. Don't waste those slots on edge cases. Use your support ticket data or FAQ analytics to figure out what people actually ask about most, and put those at the top.

Keep titles short. The title field is what people scan. Five words or fewer. The full prompt goes in the text field where there's room for a complete sentence.

I'll be honest - conversation starters feel like a minor feature when you're first building an agent. But after watching real users interact with agents we've deployed, I've changed my mind. They're doing two jobs at once: onboarding the user (showing them what the agent can do) and generating a good first interaction (which means the user comes back). An agent with no conversation starters, or with poorly written ones, often gets one try and then gets abandoned.

Provisioning and Iterating

You push changes to your declarative agent using the Microsoft 365 Agents Toolkit (formerly Teams Toolkit) in VS Code. The workflow is: edit your manifest and instructions, provision to your dev environment, test, refine, deploy to production.

The iteration cycle matters. Nobody gets the instructions right on the first try. Here's the process we follow with our Copilot Studio consulting clients:

1. Write a first draft of instructions based on the use case and existing documentation.
2. Define 8-10 conversation starters based on the most common real queries.
3. Deploy to a test group of 5-10 actual users (not developers, actual users).
4. Collect feedback for two weeks. What questions did the agent handle well? Where did it struggle? What did users try to ask that wasn't covered?
5. Revise instructions and starters based on that feedback.
6. Expand the rollout.

The testing phase is where the real value comes from. Instructions that look perfect on paper often miss obvious scenarios that real users encounter. One of our clients discovered that half their staff were asking their IT agent about printing issues - something the instructions didn't mention at all because the team building it assumed everyone knew how to print. Three sentences added to the instructions fixed a major gap.

The behavior_overrides Property

The v1.4 schema introduced behavior_overrides, which gives you control over specific aspects of how the agent formats and delivers responses. This is where you can fine-tune things like whether the agent should always include citations, how it should handle ambiguous queries, and similar response-level settings.

It's useful, but I'd classify it as a second-pass optimisation. Get your instructions and conversation starters right first. Those have a much bigger impact on the user experience than tweaking response formatting rules.

What Still Needs Work

I want to be straight about the limitations because I think the Microsoft documentation undersells them.

Instruction length limits are real. There's a practical ceiling on how detailed your instructions can be. For agents with complex business logic, you'll sometimes need to simplify or prioritise which rules make the cut. This is frustrating when you're trying to cover a large domain.

Testing is still too manual. While the Agents Toolkit gives you a way to test locally, there's no good automated testing story for declarative agent behaviour. You can't write unit tests for "does the agent respond correctly to this query." You're relying on manual testing and user feedback, which is slow. Microsoft has started adding evaluation tools in Copilot Studio, but they're early days.

Versioning instructions is awkward. The instructions live in a plain text file, which is fine for source control. But there's no built-in way to A/B test different instruction sets or gradually roll out instruction changes. You're doing a full swap every time.

These are solvable problems and I expect Microsoft will address them over time. For now, plan for more manual testing effort than you'd like.

Bringing It Together

The pattern we follow for most Microsoft AI consulting engagements is: start with clear instructions, add thoughtful conversation starters, deploy to a small group, iterate quickly based on real usage, then expand. The technology underneath is solid. The quality of the agent comes down to the quality of the configuration.

If you're building agentic automations on the Microsoft 365 platform, declarative agents with well-crafted behaviour settings are the foundation. They're not the flashiest part of the stack - API plugins and custom connectors get more attention in demos - but they're what determines whether users trust the agent enough to rely on it daily.

Get the instructions right. Get the conversation starters right. Everything else builds on that foundation.