Building API Plugins with a New API for Microsoft 365 Copilot

Most organisations that come to us about Microsoft 365 Copilot have the same question: "How do we make it actually talk to our systems?" Fair enough. Out of the box, Copilot knows about your Microsoft 365 data - emails, documents, calendar. But your internal APIs, your line-of-business applications, your custom databases? Copilot has no idea those exist unless you build a bridge.

That bridge is an API plugin. And Microsoft has made the process of building one from scratch surprisingly straightforward with the Agents Toolkit.

I've walked a few Australian enterprise teams through this recently, and the reaction is usually the same. Initial scepticism ("this feels like it'll be complicated"), followed by genuine surprise at how quickly you can get a working prototype. The whole process can take less than an hour to go from nothing to a deployed, authenticated API plugin.

What API Plugins Actually Are

Let me be direct about what we're building here. An API plugin connects a REST API to a Copilot declarative agent. It's not a standalone Copilot skill - plugins only work inside declarative agents. This is a distinction that trips people up. You create a declarative agent, and then your API plugin becomes an action that agent can take.

The plugin is described by an OpenAPI specification that tells Copilot what endpoints are available, what parameters they accept, and what they return. When a user asks the agent something, Copilot reads this specification, figures out which API call to make, and presents the results back to the user in natural language.

It's a clean pattern. Your API doesn't need to know anything about Copilot. Copilot doesn't need to know anything about your implementation. The OpenAPI spec is the contract between them.

Prerequisites - What You Need Before Starting

Before you write a line of code, you need a few things sorted:

Microsoft 365 Copilot licence with extensibility enabled. Your tenant admin needs to have this switched on. I've seen teams spend a week building a plugin only to discover their tenant doesn't support sideloading custom apps. Check first.

Visual Studio Code with the Microsoft 365 Agents Toolkit. The Agents Toolkit (previously called Teams Toolkit) handles the scaffolding, packaging, and deployment. It's a VS Code extension - install it from the marketplace. Make sure you're running version 6.0 or later, as the earlier pre-release versions had a different UI for several of the steps.

Node.js 20 or 22. The generated project uses Node.js for the API runtime. TypeScript is the default and what I'd recommend.

An Azure subscription for deployment. You can test locally without Azure, but production deployment uses Azure Functions. Your organisation likely already has an Azure tenant if you're using Microsoft 365.

Creating the Plugin - The Actual Process

Open VS Code, click the Agents Toolkit icon in the sidebar, and select "Create a New Agent/App." From there:

1. Select Declarative Agent
2. Choose Add an Action, then Start with a New API
3. For authentication, select OAuth (we'll come back to why)
4. Pick TypeScript as your language
5. Choose a project directory
6. Give your project a name

The toolkit generates everything. Your REST API, the OpenAPI specification, the declarative agent manifest, the plugin definition. Open the README in the generated project - it's actually well-written and covers the project structure clearly.

What you get out of the box is a sample "Repairs" API with endpoints for listing, creating, and updating repair records. It's not production code, but it's a proper working example that shows all the patterns you need.

Running Locally - Where the Speed Comes From

This is the part that impressed me. Local development is fast.

Click the Agents Toolkit icon, sign in to your Microsoft 365 account under "Accounts." Check that you see "Custom App Upload Enabled" and "Copilot Access Enabled" under your account. If either is missing, talk to your tenant admin before going further.

Then hit F5 (or go to Run and Debug, select either Edge or Chrome for Copilot debugging). The toolkit builds the project, packages the plugin, and sideloads it to your account. A browser opens to Microsoft Teams.

In Teams, open Copilot, find your agent in the agents list (it'll have "local" appended to the name), and start chatting. Try something like "Which repairs are assigned to Karin?" and watch the agent call your local API and return results.

The whole cycle from code change to testing is seconds, not minutes. For developers used to the traditional Teams app development experience, this is a big improvement.

One thing to know: at this stage, the plugin is running without authentication. Your API is exposed locally and the agent connects to it directly. This is fine for development but obviously not for production.

Adding Authentication and Deploying to Azure

Authentication is where I see teams get stuck, and honestly, it's the step that separates a demo from something you can actually put in front of users.

When you chose OAuth during project creation, the toolkit set up the scaffolding for OAuth authentication. To actually enable it, you need to deploy to Azure:

1. In the Agents Toolkit sidebar, go to the Lifecycle section
2. Click Provision - this creates the Azure resources (resource group, function app, app registration)
3. Accept or customise the resource group name, pick a region (Australia East for most of our clients)
4. Wait for provisioning to complete
5. Click Deploy to push your code to the Azure Function

Once deployed, you have a properly authenticated API plugin. The Copilot agent now goes through OAuth to call your API, which means you get proper identity tokens, can enforce authorisation rules, and have audit trails.

The deployed version appears in the agents list with "dev" instead of "local" in the name. Test it the same way - open Copilot, select the dev agent, ask about repairs.

Replacing the Sample API with Your Own

The sample Repairs API is there to show you the pattern. The real work starts when you replace it with your actual API. Here's how I approach this with clients:

Start with a single read endpoint. Don't try to expose your entire API on day one. Pick one endpoint that returns useful information - maybe a customer lookup, an order status check, or a project list. Get that working end-to-end first.

Write clear operation descriptions in your OpenAPI spec. This is something I keep hammering home with teams. The description fields in your OpenAPI spec are how Copilot decides which endpoint to call. Vague descriptions like "Gets data" lead to the agent making wrong calls or not calling your API at all. Be specific: "Returns a list of active customer support tickets assigned to the specified team member, including ticket ID, priority, and creation date."

Handle errors gracefully. When your API returns an error, the agent will try to explain it to the user. If your error responses are cryptic developer messages, the user experience suffers. Return human-readable error descriptions.

Add Adaptive Card templates for response formatting. By default, Copilot renders API responses as plain text. Adaptive Cards give you control over how the data appears - tables, formatted fields, action buttons. The effort is small and the improvement in usability is significant.

What I'd Watch Out For

Manifest validation is stricter than you'd expect. During provisioning, the teamsApp/validateAppPackage step checks your plugin manifest and OpenAPI spec for issues. Certain parameter types - nested objects, properties with minimum/maximum constraints, default values - can cause validation failures. If you hit these, simplify your schema. Copilot doesn't need your full internal API schema; it needs the subset relevant to the user interaction.

Rate limiting and performance. Your API plugin is called synchronously during the Copilot response generation. If your API takes 8 seconds to respond, the user stares at a spinner for 8 seconds. Aim for sub-second response times on your endpoints. Cache where you can. If you're calling downstream services that are slow, consider returning partial results rather than waiting for everything.

Scope your plugins narrowly. I've seen teams try to create one mega-plugin that exposes 40 endpoints across their entire API surface. This doesn't work well. Copilot gets confused about which endpoint to call when there are too many options. Better to have multiple focused agents, each with a small number of well-described endpoints.

Test with real users early. Developers testing their own plugin will ask well-structured questions that match the API parameters. Real users will ask messy, ambiguous questions. You need to see how Copilot handles "what's the status of that thing Bob mentioned yesterday?" before you call it done.

When This Approach Makes Sense

Building an API plugin from scratch makes sense when you either don't have an existing API or when your existing API isn't well-suited for Copilot integration. Maybe the existing endpoints return too much data, require complex authentication flows, or have schemas that don't validate against Copilot's requirements.

If you already have a well-documented REST API with a clean OpenAPI spec, you might be better off using the "Start with an Existing API" path in the Agents Toolkit instead. Same plugin concept, but you skip the API scaffolding step.

For organisations that have existing APIs but want a Copilot-optimised facade, building a new API specifically for the plugin is often the right call. You create a thin API layer that calls your internal services but presents a simplified interface tailored for conversational interactions.

Getting Help

We've been building Copilot extensions for Australian organisations across financial services, professional services, and manufacturing. If you're looking at extending Microsoft 365 Copilot with your own APIs, our Microsoft AI consulting team can help you scope the project and get a working prototype quickly.

For broader AI agent strategies beyond Copilot, including multi-channel deployments and custom agent frameworks, have a look at our AI agent development services. We also offer specific guidance on Copilot Studio and extensibility for organisations that want hands-on support.

The full Microsoft documentation for this workflow is available at Build API plugins with a new API.