Back to Blog

Building Declarative Agents with TypeSpec for Microsoft 365 Copilot

March 22, 2026•8 min read•Michael Ridland

Most organisations we work with are already paying for Microsoft 365 Copilot licences. The question that keeps coming up in our consulting engagements is: "How do we make Copilot actually useful for our specific business?" Generic Copilot is fine for summarising emails and drafting documents, but the real value kicks in when you tailor it to your organisation's knowledge and workflows.

That's where declarative agents come in. And with the introduction of TypeSpec support in the Microsoft 365 Agents Toolkit, building these agents has become significantly more approachable for .NET and TypeScript developers.

What Are Declarative Agents, Really?

A declarative agent is a customised version of Microsoft 365 Copilot. You're not writing inference code or managing model weights. Instead, you're declaring what the agent should know, how it should behave, and what data sources it can access. Think of it as configuration-driven AI customisation rather than traditional software development.

The official Microsoft documentation walks through the full process. I want to focus on what we've found works well in practice and where teams tend to trip up.

We've been building these for clients across professional services, finance, and manufacturing. The pattern that consistently delivers value is connecting Copilot to internal SharePoint knowledge bases - turning tribal knowledge into something any employee can query in natural language. It sounds simple, but the impact on onboarding and decision-making speed is substantial.

Getting Started with TypeSpec

TypeSpec is a language for describing APIs and, in this context, agent configurations. If you've worked with OpenAPI or Swagger, the concept feels familiar. You define your agent's properties in a .tsp file and the toolkit generates the manifest for you.

The prerequisites are straightforward:

  • Visual Studio Code
  • The Microsoft 365 Agents Toolkit extension
  • A Microsoft 365 organisation with Copilot licences

Creating the initial project is simple. Open VS Code, hit Microsoft 365 Agents Toolkit > Create a New Agent/App, select Declarative Agent, then choose Start with TypeSpec for Microsoft 365 Copilot.

The project scaffolds out with a main.tsp file that becomes your single source of truth for the agent's configuration.

Instructions - Where the Real Work Happens

The @instructions decorator is where you define your agent's personality and behaviour. This is the part that takes the most iteration to get right - and it's where most teams underinvest.

@instructions("""
  You are a declarative agent and were created with Team Toolkit.
  You are an expert at creating poems.
  Every time a user asks a question, you **must** turn the answer
  into a poem. The poem **must** not use the quote markdown
  and use regular text.
""")

That's the example from the docs. In real projects, your instructions will be much more detailed. We typically spend a full workshop with stakeholders to nail down the instruction set - what tone should the agent use? What topics are off-limits? What should it do when it doesn't know something?

One thing I've learned the hard way: be explicit about what the agent should NOT do. If you don't want it giving legal advice based on your policy documents, say so. If it should always direct users to a human for certain query types, spell that out. The model follows instructions well, but only the ones you actually write down.

Conversation Starters - Guiding Users to Value

Conversation starters are the hints shown to users when they first open the agent. They're more important than most teams realise.

@conversationStarter(#{
  title: "Getting started",
  text: "How can I get started with Agents Toolkit?"
})

@conversationStarter(#{
  title: "Getting Help",
  text: "How can I get help with Agents Toolkit?"
})

In our deployments, we treat conversation starters as a UX design problem. The starters you choose determine whether users immediately see value or bounce off confused. We recommend picking three to four starters that represent the most common real questions your users have. Pull them from actual support tickets or Slack channels - don't guess.

A financial services client of ours saw a 40% increase in agent adoption after we rewrote their conversation starters based on the top five questions from their IT helpdesk. Users opened the agent, saw their exact question listed, clicked it, and got a useful answer within seconds.

Knowledge Sources - The Power Layer

This is where declarative agents go from "neat demo" to "genuinely useful tool." You can connect several knowledge sources, and combining them is where the magic happens.

Web Search

namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com",
    },
  ]>;
}

Scoping web search to specific domains is a smart move. Without the Sites array, the agent searches all of the web - which can lead to inconsistent or irrelevant results. For enterprise use, lock it down to your documentation sites, vendor knowledge bases, and industry resources.

SharePoint and OneDrive

namespace MyAgent {
  op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
    {
      url: "https://contoso.sharepoint.com/sites/ProductSupport"
    }
  ]>;
}

This is the capability that gets the most use in our client deployments. Point the agent at your SharePoint sites and it can answer questions based on documents stored there. Policy manuals, process documentation, product specs - anything your team has already written becomes queryable.

A word of caution: the agent's usefulness is directly proportional to the quality of your SharePoint content. If your documents are outdated, poorly organised, or contradictory, the agent will reflect that. We usually recommend a content audit before launching a declarative agent. It's not glamorous work, but it makes the difference between an agent people trust and one they ignore.

Teams Messages

You can also connect Teams channels and meeting chats as knowledge sources. This is powerful for project-specific agents that need context from ongoing discussions. The setup follows the same TypeSpec pattern - just add the TeamsMessages capability with the relevant channel URLs.

Provisioning and Testing

After each change to your main.tsp file, you need to provision again through the Agents Toolkit lifecycle pane. Then refresh the Copilot page to see your changes. The feedback loop isn't instant, but it's reasonable.

Testing happens directly in the Copilot interface at https://m365.cloud.microsoft/chat. Select your agent from the conversation drawer and start asking questions.

My advice: test with people who weren't involved in building the agent. Builders have implicit knowledge about what the agent can and can't do. Fresh users will ask questions you never considered, and those edge cases are where you'll find the most important improvements.

What We've Seen Work (and What Hasn't)

Works well:

  • HR policy agents connected to SharePoint policy libraries. Employees get instant answers to "How many sick days do I have?" or "What's the parental leave policy?" without waiting for HR to respond.
  • IT helpdesk agents scoped to internal troubleshooting guides. First-line support gets faster, and repetitive tickets drop off.
  • Project-specific agents combining SharePoint docs and Teams messages. New team members get up to speed without scheduling a dozen "context download" meetings.

Still rough:

  • The provisioning cycle feels slow when you're iterating quickly on instructions. There's no hot-reload - you provision, wait, refresh, test, repeat.
  • Debugging why the agent gives a particular answer can be opaque. You know it's drawing from your knowledge sources, but tracing exactly which document influenced a response isn't always clear.
  • Multi-language support in instructions needs more testing. We've had mixed results with agents that need to respond in languages other than English.

Practical Tips from Our Deployments

  1. Start narrow, expand later. Don't try to build an everything-agent. Pick one department or one use case, get it working well, then broaden scope.

  2. Version your instructions. Keep a changelog of what you've added or modified in the @instructions decorator. When the agent starts behaving oddly, you can trace it back to a specific change.

  3. Measure adoption, not just accuracy. An agent that gives perfect answers but nobody uses is worthless. Track how many unique users interact with it weekly and what questions they're asking.

  4. Combine knowledge sources thoughtfully. Web search plus SharePoint can create conflicting answers if your internal docs disagree with public documentation. Be intentional about which sources you include and why.

Where This Is Heading

Microsoft keeps expanding what declarative agents can do. API plugins, Graph connectors, and custom actions are all available or coming soon. The TypeSpec approach makes it easier to manage these configurations as your agents grow more sophisticated.

For organisations already invested in Microsoft 365, declarative agents are the lowest-friction path to custom AI experiences. You're building on infrastructure you already have, using data sources your team already maintains. The total cost of ownership is far lower than building custom AI applications from scratch.

If you're looking at extending Microsoft 365 Copilot for your organisation, our team at Team 400 has been doing this work across a range of industries. We offer Copilot Studio consulting and broader Microsoft AI consulting to help organisations get from "we have Copilot licences" to "Copilot is actually driving productivity." We also help teams think through AI strategy so the technology investment connects to real business outcomes.

The tools are mature enough now that you can have a useful declarative agent running in a day. Getting it right - with the proper instructions, knowledge sources, and user testing - takes longer, but it's time well spent.