Microsoft 365 Roadmap Agent

Overview

The Microsoft 365 roadmap provides estimated release dates and descriptions for commercial features. The M365 Roadmap Agent allows you to search the Microsoft 365 Roadmap updates with Copilot chat using natural language prompts.

M365 Roadmap Agent Use Cases

Not only can users search for roadmap updates, but you can also use the power of generative AI to summarize them and draft internal communications. Here are some examples of what you can do:

• Search for updates: Find specific updates in the Microsoft 365 roadmap. Search by keywords, date ranges, and status types. Search is case-insensitive. Search by roadmap item title (default) or description.
• Summarize updates: Get a summary of the latest updates in the M365 Roadmap.
• Draft internal communications: Generate draft emails or updates to share information about roadmap items with your team.
• Get insights: Gain insights regarding impact of roadmap updates for your organization.
• Get suggested actions: Get suggested actions for roadmap items that require your attention.

Deployment Guide	Modification Guide

Deployment Guide

This guide provides step-by-step instructions to deploy the M365 Roadmap Agent using the Microsoft 365 Agents Toolkit (ATK) CLI. In this guide you will create an Entra application registration, register it with the Teams Developer Portal (provision the agent), and upload it for private testing or submit it your Teams administrator for distribution to your entire organization. After provisioning, the agent will be available in the Copilot chat interface for you to use.

Prerequisites

1. See the Required Roles section below for the roles required to deploy the agent.
2. Custom App Uploading must be enabled in your Microsoft 365 tenant via the Teams Admin Center. See section Enable Custom App Uploading below for more information on enabling custom app uploading.

Steps to deploy the M365 Roadmap Agent using the Microsoft 365 Agents Toolkit (ATK) CLI:

1. Clone this repository or download the source code as a ZIP file and extract it to a local folder on your machine.

2. Install the Microsoft 365 Agents Toolkit CLI and NodeJS using the PowerShell script provided in the prereqs folder.

   1. Open a PowerShell terminal

   2. Set the Script Execution Policy to allow running scripts. You can do this by running the following command:

      Set-ExecutionPolicy Unrestricted -Scope CurrentUser

      This command allows you to run scripts in your current user context. You may need to confirm the change by typing 'Y' and pressing Enter.

   3. Change to the prereqs folder and run InstallNodeAtk.ps1. The output should be similar to this:

Microsoft 365 Tenant Requirements

To deploy the M365 Roadmap Agent, you need the following requirements in your Microsoft 365 tenant:

• Microsoft 365 Tenant with a M365 Copilot license and admin access. See 'Required roles' below. You can use a test tenant available in your organization, if available. Alternatively, you can use a Microsoft 365 sandbox subscription with a Copilot license. See here for information on obtaining a Microsoft 365 developer sandbox subscription with a Copilot license.

• Custom app uploading must be enabled in your Microsoft 365 tenant via the Teams Admin Center. This is required for the M365 Agents Toolkit to sideload the agent to M365 Copilot. See here for more information on enabling custom app uploading.

Provisioning the Agent for testing and demos

You're now ready to deploy the M365 Roadmap Agent using the Microsoft 365 Agents Toolkit (ATK) CLI.

1. Start a new PowerShell terminal and change to the root folder of the cloned repository.

2. In the root folder of the repository, run the following command to deploy the agent:

   atk provision --env production

   You may be prompted for the Client Id if additional OAuth2 configuration is needed. The --env production flag indicates that you are deploying the agent to production.

   Type 'Y' when the script pauses to inform you: 'Microsoft 365 Agents Toolkit uploads the client id/secret for OAuth Registration to Developer Portal' (if applicable). This will provision the agent in your Microsoft 365 tenant and register it with the Teams Developer Portal. The output should be similar to this:

Test the Agent

Test the agent by starting Copilot in the web or app and selecting the M365 Roadmap Agent. Note that the agent is private to you for testing purposes. Select one of the starter prompts to interact with the agent.

See the Publish step below to submit the agent to the Teams admin for distribution to the organization.

Publish the Agent (Optional)

If you want to make the agent available to your entire organization, you can publish it to the Copilot agents store. This step is optional and is only needed if you want to share the agent with others in your organization.

To publish the agent to your organization, you can submit it to your Teams administrator for distribution by running the following command:

atk publish --env production

This will upload the agent to your Microsoft 365 tenant and make it available in the Copilot agents store after the Teams administrator approves it.

Modification Guide

If you want to modify the M365 Roadmap Agent, you can do so by following the steps in this section.

Prerequisites

1. See the Required Roles section below for the roles required to deploy the agent.

2. See the Microsoft 365 Tenant Requirements section above for the requirements in your Microsoft 365 tenant.

3. Install the Microsoft 365 Agents Toolkit extension for Visual Studio Code.

4. Compile and validate the OpenAPI specification using TypeSpec. See the TypeSpec Development section below for more information.

The OpenAPI specification (appPackage/apiSpecificationFile/roadmap-openapi.json) is generated from TypeSpec source files located in the tsp/ directory.

To regenerate the OpenAPI specification after making changes:

npm run tsp:compile

To validate the generated specification:

npm test

Provision the Agent using the Microsoft 365 Agents Toolkit

The M365 Agents Toolkit for Visual Studio Code streamlines app registration and deployment to Microsoft Teams. It automates OAuth2.0 setup, securely manages client credentials, and eliminates the need to handle infrastructure, letting you focus on app development.

1. Rename the file .env.production.sample to .env.production in the env folder of the project. This file will be populated with environment variables for the project for production release.
2. Using the M365 Agents Toolkit, in the LIFECYCLE section, select 'Provision'.
3. Provide the client id if prompted for additional OAuth2 configuration. Note that the M365 Agents Toolkit will register the app in the Teams Developer Portal and update any necessary variables in your .env file.

Use the M365 Roadmap Agent in Copilot

The 'Provision' step deploys the agent privately to you for testing purposes. Start Copilot chat in the app or web and select 'M365 Roadmap Agent'.

Publish the Agent (Optional)

If you want to make the agent available to your entire organization, you can publish it to the Copilot agents store. This step is optional and is only needed if you want to share the agent with others in your organization.

1. Using the M365 Agents Toolkit, in the LIFECYCLE section, select 'Publish to Organization'.

Architecture

Zero Code

The declarative agent is built using the Microsoft M365 Agents Toolkit for Visual Studio Code. It leverages the Microsoft 365 Roadmap API to interact with the Microsoft 365 Admin Center and retrieve updates. The declarative agent is a zero-code solution, meaning you don't need to write any code to set it up or use it. The agent is designed to be easy to setup and requires no coding experience.

Prompting Guide

See the Prompting Guide for the M365 Roadmap Agent for details on how to effectively prompt the agent to get the best results.

Example Output

Output from the M365 Roadmap Agent displaying roadmap items details with an option to open the item directly in the Microsoft 365 Roadmap site.

Here we are drafting an email to inform the team about upcoming changes coming to M365 Copilot in the next 90 days. (Only one update is shown in the screenshot for brevity.)

Key Files

The following files are key to the implementation of the declarative agent:

• roadmap-openapi.json: This file contains the OpenAPI specification for calling the Roadmap V2 API https://www.microsoft.com/releasecommunications/api/v2 that the declarative agent will use to search and retrieve updates from the Microsoft 365 Roadmap. This file is now generated from TypeSpec - see the TypeSpec Development section below for more information. Note that the Roadmap V2 API is a public API and does not require any authentication. Additionally the API supports OData query parameters to filter and sort the results. Copilot leverages the descriptions in the OpenAPI specification to understand how to interact with the API and create the needed odata queries based on user prompts.
• declarativeAgent.json: This file contains the declarative agent configuration that defines the behavior and capabilities of the agent.
• manifest.json: This file contains the Teams application manifest that defines metadata for the declarative agent. This is what is displayed in the Copilot agents store.
• m365agents.yml: This file contains the M365 Agents Toolkit project configuration and other settings.
• .env.production: This file contains environment variables for the project for production release.

TypeSpec Development

This project uses TypeSpec to define the API specification. TypeSpec provides a type-safe, maintainable way to define APIs that automatically generates OpenAPI specifications.

Why TypeSpec?

• Type Safety: Catch errors at compile time with strong typing
• Maintainability: Single source of truth for API definitions
• Reusability: Share models, parameters, and components across endpoints
• Better Organization: Modular structure with clear separation of concerns
• Automatic Generation: Generate OpenAPI, JSON Schema, and other formats from TypeSpec

For detailed information on modifying the API specification, see the TypeSpec Development Guide.

TypeSpec Project Structure

tsp/
├── main.tsp              # Service configuration and entry point
├── models/               # Data models (RoadmapItem, responses, errors)
├── routes/               # API endpoints (GET /m365)
└── parameters/           # Reusable parameters (OData query params)

For a complete guide on working with TypeSpec, including how to add fields, modify parameters, and add examples, see docs/TYPESPEC_GUIDE.md.

Build Scripts

This project includes several build scripts that automate the compilation and packaging process:

• npm run tsp:compile: Compiles TypeSpec to OpenAPI and runs post-processing scripts
• npm run inject-versions: Injects current version numbers from JSON files into agent instructions
• npm run build: Full build including TypeSpec compilation and version injection
• npm test: Validates the generated OpenAPI specification
• npm run test:integration: Runs integration tests against the API

Version Injection: The troubleshooting information in the agent automatically displays current version numbers from manifest.json, declarativeAgent.json, and ai-plugin.json. This is handled by the version injection system during build. See docs/VERSION_INJECTION.md for details.

Required Roles

Required Roles - Agent Provisioning

The roles required to manage the Teams app (Agent) in Microsoft 365 and deploy it to the organization are:

• Teams Administrator: Required to manage and deploy Teams apps within the organization via the Teams Admin Center.
• Global Administrator: Can also manage and deploy Teams apps, but has broader permissions beyond Teams management.

The recommended least-privileged role specifically for managing and deploying Teams apps is Teams Administrator.

Required Roles - Teams Developer Portal

Note that this step is done via the M365 Agents Toolkit's 'Provision' feature. To register your app in the Teams Developer Portal, you must have one of the following roles:

• Teams Administrator: Required to manage and deploy Teams apps within the organization via the Teams Admin Center.
• Global Administrator: Can also manage and deploy Teams apps, but has broader permissions beyond Teams management.

The recommended least-privileged role specifically for managing and deploying Teams apps is Teams Administrator. Note: This role is required when using the M365 Agents Toolkit to provision the app registration and deploy the app.

Required Roles - Agent Usage

The M365 Roadmap Agent accesses public roadmap information and does not require any special admin roles for usage. Any user with access to Microsoft 365 Copilot can use this agent.

Troubleshooting

If you encounter issues during deployment or usage of the M365 Roadmap Agent, consider the following troubleshooting steps:

1. Display the underlying API call: Note that you can inspect the OData URL generated by the agent with the prompt 'Show me the URL for this query' to help with troubleshooting. This displays the OData API query. The output will look something like this:
   This information should help you identify any issues with the query parameters or filters being used and assist in refining your prompts.

2. For version information use the prompt: 'Show version'. You should see output similar to this:
   

3. If a prompt is not returning expected results, try refining the prompt or breaking it down into smaller parts to isolate the issue.

4. Check Permissions: Ensure that the app registration has the necessary API permissions granted and admin consented.

5. Review Logs: Check the logs in the M365 Agents Toolkit for any error messages that can provide insights into the issue.

6. Validate Environment Variables: Ensure that the environment variables in the .env.production file are correctly set, including the client ID and secret.

7. Consult Documentation: Refer to the official Microsoft documentation for the M365 Agents Toolkit.

8. Open an issue in this repository for further assistance.

More Agents

For an agent that searches Message Center messages along with related M365 Roadmap items. See the https://github.com/mjfusa/Message-Center-Agent (authentication and admin roles required).