Building a Copilot Agent with Microsoft 365 Agents Toolkit and Microsoft Graph Plugin to list my ToDo Tasks

Introduction

This guide walks you through creating a Copilot agent using Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) and Microsoft Graph API. By leveraging OpenAPI specifications, Kiota, and Microsoft 365 Agents Toolkit, you can build a plugin to interact with Microsoft Graph endpoints. I used the blog post Copilot Graph API QnA Plugin by Franck Cornu as inspiration with some variation to apply it to get my ToDo tasks.

Plugins for Copilot agents rely on OpenAPI specifications. While the complete Microsoft Graph OpenAPI specification exists, it is a massive file (34MB) and not practical for performance reasons. Instead, we can use kiota to pick then endpoints required.

Steps to Build the Plugin

1. Generate the Copilot plugin information

To generate the plugin information required by the Copilot agent, we use the Kiota tool. If not installed already, install the Kiota extension for Visual Studio Code.

Why use Kiota instead of the built-in Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) plugin generation?
The default Microsoft 365 Agents Toolkit plugin generation may struggle with complex property types like arrays or nested objects. Kiota ensures the plugin information is generated correctly.

Install Kiota and Download the OpenAPI Specification

  1. Download the Microsoft Graph OpenAPI specification:
   Invoke-WebRequest -Uri "https://aka.ms/graph/v1.0/openapi.yaml" -OutFile "openapi.yaml"
  1. Install Kiota Visual Code Extension

Follow the instructions from Install the Visual Studio Code extension to install the VS Code extension.

Generate the Plugin Information

  1. Open Kiota and add a new API description.
  2. Select “Browse path” and choose the openapi.yml file generated earlier.
  3. Kiota will load all available endpoints from the file. Add the desired endpoint (click the + sign on the POST line) and click “Generate”.

Generate Plugin

Import the Plugin into Microsoft 365 Agents Toolkit (previously known as Teams Toolkit)

  1. Open Visual Studio and navigate to the Microsoft 365 Agents Toolkit options.
  2. Use the “Add Plugin” option and select Import an existing plugin.
  3. Provide the following files:
    • plugin-apiplugin.json (manifest file).
    • plugin-openapi.yml (OpenAPI specification).
    • Declarative agent manifest file.

Once imported, you should see the ai-plugin.json and plugin-openapi.yml files under the appPackage folder.

Generate Plugin

The project structure will look like

AI Plugin

Add OAuth2 Authentication

To enable authentication, update the plugin-openapi.yml file with the following securitySchemes configuration (replace tenantid with your Azure tenant ID):

components:
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/tenantid/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/tenantid/oauth2/v2.0/token
          scopes:
            User.Read: 'Read user profile'
            User.ReadWrite: 'Read and write user profile'
            Directory.Read.All: 'Read directory data'
            Directory.ReadWrite.All: 'Read and write directory data'
security:
  - azureaadv2: [ ]

Add OAuth2 Authentication

Create an App Registration in Azure

  1. Register an Entra ID application in Azure.
  2. Add the following API permissions:
    • Mail.Send
    • offline_access
    • openid
    • Tasks.ReadWrite
    • User.Read
    • Directory.Read.All
  3. Add the redirect URL https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect for the web platform in the Authentication settings.

Create App Registration

  1. Grant admin consent for the permissions.

API Permissions

OAuth Client Registration in Teams Developer Portal

  1. In the Teams Developer Portal, add a new OAuth client registration with the following details:

  2. OAuth Settings:

Replace tenantid with your tenantid which is a GUID.

OAuth Client Registration

Update the ai-plugin.json File

  1. Open the ai-plugin.json file.
  2. Replace the auth property with the following configuration:
"runtimes": [
        {
            "type": "OpenApi",
            "auth": {
                "type": "OAuthPluginVault",
                "reference_id": "MzlmMGUxNDktNmNlMC00ODNlLThhY2YtYjZmYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="
            },
            "spec": {
                "url": "todoaction-openapi.yml"
            },
            "run_for_functions": [
                "me_todo_ListTasks"
            ]
        }
    ]

AI Plugin Vault

Issues

While building the plugin, I encountered a few challenges that required additional troubleshooting. For detailed solutions and workarounds, refer to my post: Troubleshooting Microsoft Graph Plugin Issues in Copilot Agents Built with Microsoft 365 Agents Toolkit.

Testing the Plugin

To test the plugin:

  1. Update the instruction.txt and parameters within the declarativeAgent.json file.
  2. Deploy the declarative agent and test it within M365 Copilot.

Testing the Plugin

Solution

To try out the solution, you can download the project from my GitHub repository:
Use the Microsoft Graph API as a Copilot plugin for a declarative agent to get ToDo tasks.

This project demonstrates how to integrate the Microsoft Graph API as a plugin for a declarative agent to retrieve ToDo tasks.

Conclusion

Integrating Microsoft Graph as a plugin for Copilot agents is a powerful way to extend functionality. While I successfully tested the GET tasks endpoint, I faced issues with the POST tasks endpoint, as the function failed to load.

No Actions Loaded

After investigating on the above issues, I wrote two articles about alternatives to generate OpenAPI spec, Refer to those.

Creating an OpenAPI Specification for Microsoft 365 Copilot Declarative Agents to Interact with SharePoint Lists

Limitations of OpenAPI Spec with Complex Objects in Copilot Declarative Agents

Also, I faced issues just to get a particular task using id using Ms Graph, hence could not get the patch, delete and get details for a task work.

Get Task failed

If anyone has insights or solutions for this issue, feel free to reach out—I’d love to collaborate and resolve it together!

References