Troubleshooting Microsoft Graph Plugin Issues in Copilot Agents Built with Microsoft 365 Agents Toolkit

Introduction

When building a Copilot agent using Microsoft 365 Agents Toolkit (previously known as Teams Toolkit), you may encounter certain errors that can hinder your progress. This blog post highlights common issues and provides solutions to help you resolve them effectively.

Common Issues and Fixes

1. name_for_human Exceeds 20 Characters

Issue:

You may encounter the following error when the name_for_human field in the ai-plugin.json file exceeds 20 characters:

name_for_human in PluginManifestDocument has characters beyond the length 20 that MAY be ignored.

Example:

name_for_human

The name_for_human field in the ai-plugin.json file might look like this:

"name_for_human": "ThisIsAVeryLongNameThatExceeds20Characters"

name_for_human in PluginManifestDocument has characters beyond the length 20 that MAY be ignored.

name_for_human issue

Solution

To fix this issue:

  1. Open the ai-plugin.json
  2. Update the name_for_human field to a shorter, meaningful name (e.g., ToDoAgent).
  3. Update the description_for_human and description_for_model fields to provide concise and relevant descriptions.

name_for_human fix

2. OpenAPI Document Size Exceeds the Limit

Issue:

You may encounter the following error when the OpenAPI document size exceeds the allowed limit of 102400 KB:

(×) Error: Invalid Declarative Copilot Document: declarativeAgent.json. Problems discovered: OpenApi document size exceeds the limit of 102400 KB.

Example:

OpenApi document size

Cause:

This issue occurs when the OpenAPI specification file includes too many endpoints or functions, making the file size too large.

Solution:

To resolve this issue:

  1. Reduce the size of the OpenAPI specification by removing unnecessary endpoints or functions.
  2. Focus on specific functionality. For example, if your plugin is for managing tasks, remove unrelated functions like SendMail from the OpenAPI spec.

Example Fix:

If the OpenAPI spec includes both SendMail and ToDo functions, remove the SendMail function to focus solely on ToDo functionality.

3. No Actions Loaded After Provisioning

Issue:

After provisioning the plugin, you may notice that no actions are loaded, and the plugin does not function as expected.

Example:

No actions loaded after provisioning

Solution:

  1. Verify that the OpenAPI specification file is correctly configured and does not exceed the size limit.
  2. Ensure that the ai-plugin.json file and the declarative agent manifest are properly linked to the OpenAPI spec.
  3. Reprovision the plugin and test again.

Conclusion

Building a Copilot agent using Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) can be a seamless process if common issues are addressed effectively. By ensuring fields like name_for_human adhere to character limits, optimizing the OpenAPI specification file, and verifying plugin configurations, you can avoid errors and streamline your development process.

If you encounter additional issues, feel free to share them in the comments or reach out for support. Happy coding!

References