Pages Menu
TwitterRssFacebook

Posted by on Feb 4, 2025 in Microsoft 365 Copilot

Building Declarative Agents with API Plugins for Microsoft Copilot Part 2 – Prerequisites

Building Declarative Agents with API Plugins for Microsoft Copilot Part 2 – Prerequisites

This is the second in a series of 5 blog posts and videos around Declarative Agents for Copilot.

In this blog post I’m going to talk about what you need to get started building Declarative Agents, focusing specifically on agents that use the API plugin model. Part 1 of this series introduced Declarative Agents and how they fit into the rest of the Microsoft 365 Developer Platform.

In part 3 I will introduce my demo application, and walk you through it.
In part 4 I will show you how the demo application was built, walking you through the process so that you can build your own Declarative Agent with an API plugin.
In part 5 I’ll cover off the gotchas, tips & other things that I learnt along the way.

If you want to be purist about it, there actually aren’t any really hard requirements to creating a Declarative Agent (DA), apart from the ability to create and zip text files. Agents are defined in a series of (mostly JSON) manifest files that describe their abilities and the resources they use, according to a published schema.

However, unless you really like manually creating and editing hundreds of lines of manifest code, you’ll want to make use of some of the tooling that Microsoft have made available to developers to make creating DAs easier. It is this list that I’m going to go through in this blog post, because I believe that using these tools results in the quickest and easiest way to create Declarative Agents, particularly ones using an API plugin.

Visual Studio Code

Get it from: Visual Studio Code – Code Editing. Redefined

Let’s start with the basics. You probably already use this, but if not, it’s worth getting. Again, you technically don’t need to use it, but it’s the only way to make use of the next item on this list.

Teams Toolkit Extension for Visual Studio Code

Get it from: Teams Toolkit – Visual Studio Marketplace

The Teams Toolkit (TTK) has evolved from humble beginnings to become an indispensable part of developer workflow building for Microsoft 365. It’s greatest achievement is how up to date it always is, and this is true here as well. The TTK includes support for creating all sort of things, not just Microsoft Teams solutions, and there are scaffolding templates for building Declarative Agents, with and without API plugins.

Kiota Extension for Visual Studio Code

Get it from: Microsoft Kiota – Visual Studio Marketplace

Kiota helps TTK with the API plugin aspect of putting together a Declarative Agent. I don’t think that it’s strictly required but things seem more robust with it there, so it’s worth installing before you get started.

Copilot License (now optional, I think)

Until the recent announcement from Microsoft about Microsoft 365 Copilot Chat being available to everyone, you would have needed a Copilot license to be able to test out a newly created Declarative Agent. I don’t think that this is the case any more. However, as I already have a Copilot license in my test tenant, I’m not very easily able to try this out. If you don’t already have a license then don’t buy one for this: give it a go and see what happens – it’ll most likely work, and if it doesn’t then I think it’ll be obvious if the license is the issue.

Some willing APIs

As discussed in part 1, the real power of writing Declarative Agents (for me) is their ability to make calls to other APIs, either to retrieve up to date information, or to enact actions.

Whilst you may be able to use your existing APIs for this, especially if they’re simple, you might want to consider creating a new API specifically for Copilot usage, even if it calls the same business logic as your other APIs. Reasons for doing this include:

  • The API will be smaller and more simple because it’ll only be those methods that you want to expose to Copilot. This will make it easier to define.
  • You can combine calls from several different APIs together into one single API endpoint, and expose just that to Copilot. This will make defining your agent easier, and help with debugging.
  • You will be able to work around any idiosyncrasies and gaps that the API parser in Copilot might have, either by creating specific methods instead of generic ones that take parameters, or adjusting the output.
  • If your APIs don’t already have good logging and tracing, then using something like Azure API Management as your API abstraction, even if it just passes the call along to your existing APIs, will give you that visibility into what is happening.
  • Whilst you are developing and testing your Copilot plugin, you can mock the results returned from your new API without impacting other systems, enduring a consistent result. This can really help when refining the system prompts given to Copilot.

OpenAPI Specs for your APIs

For every API you want to include in a Copilot Declarative Agent you need to specify an OpenAPI spec file, which describes the API methods, their parameters and outputs. It’s how Copilot gets to know about your API and its capabilities, which helps it to know when and how to call it.

Creating an OpenAPI file to describe your API can be a bit of a pain, if you don’t already have one. However, there are tools to help you:

Declarative Agents for Copilot are still very new, and there may be some gaps between what is allowed in the OpenAPI spec and what is actually supported by the parser. In particular, I’ve found that calling a POST or PUT with an array in the body can have some issues. I expect these to be worked out soon though and may well be fixed by the time you read this.

OpenAPI also specifies any authentication that needs to be performed when using your API. Right now, OAuth, Bearer Tokens, URL parameters and custom header fields are all supported. Read more: Declarative Agent Copilot now supports APIs secured with keys passed in query params or headers.


Once you have all these prerequisites ready, and you’ve got a good idea about what you want to build, then you’re good to go.

If you’re still wondering how Declarative Agents with API plugins can help you to create compelling (and useful!) user experiences, look out for the next blog post in the series. In part 3, I’ll walk you through a demo of a sample application I’ve built to showcase this technology, and in part 4 we’ll deconstruct it and show you how to build your own.

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.
Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Post a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.