Introduction

Microsoft 365 Copilot Agents extend the value generative AI for organizations by enabling ‘focused experiences’. That is, agents that provide actions and knowledge around a specific topic. For example, an HR Helpdesk agent that provides answers related to HR related questions and creates tickets with full user context when a question cannot be answered. Agents can range from simple prompt-and-response agents to more advanced, fully autonomous agents.

From the maker/developers point of view, the integration of agents into Microsoft 365 is facilitated by the Teams app infrastructure. That is, the Microsoft Teams app manifest has been extended to support the deployment of agents for use in Microsoft Teams, M365 Copilot, and Microsoft Chat. We will use this extension to convert a simple Teams bot into a Copilot agent.

Calling an external Agent from Copilot

In the last couple of years, during this generative AI tsunami, many developers have built agents on various generative AI platforms, including Microsoft’s Azure AI. Customers using these agents have expressed a need to call these agents from M365 Copilot. A simple way to do this is via a simple bot that acts as a relay between Copilot and the external agent.

Relay bot with an Azure AI Agent

The relay bot, called from Copilot, passes through the prompt, unchanged to the target agent via an API exposed by the agent. The API returns the response from the target agent back to Copilot. We’re using Azure AI here, but the concepts should apply to any agent platform.

This architecture requires that the agent is deployed to a service that supports API interactions, such as Azure OpenAI Service, Azure Functions, or any other custom-hosted solution. In my case, I’m using the Azure OpenAI Service.

Once we have an exposed an API to our target agent that can take a prompt as input and return the results, we’re ready for integration with M365 Copilot.

Relay Bot integration with M365 Copilot

One of the latest updates to the Microsoft Teams app manifest schema (version 1.20) introduces significant enhancements. This update introduces a new object “copilotAgents”, which supports both declarative and custom engine agents. Additionally, “bots”, “commandlists,” and “commands” have been extended to support starter prompts, paving the way for converting a Teams bot into a Copilot agent.

Understanding the ‘copilotAgents’ object

The ‘copilotAgents’ object can include either the ‘declarativeAgents’ or ‘customEngineAgents’ properties. ‘declarativeAgents’ brings in the Copilot orchestrator, which we don’t need. We will use ‘customEngineAgents’ here. ‘customEngineAgents’ assumes we will provide our own orchestrator and LLM. As since this is a relay bot, will will not be using the an orchestrator. Our target agent is taking care of that for us. The ‘customEngineAgents’ object is an array of objects, each representing a custom engine agent. Each object in the array has two properties: id and type. The id property is the Microsoft App ID of the bot registered with the Bot Framework, and the type property is set to “bot”.

Note the value of the id in ‘customEngineAgents’ matches the id of the bot – the relay bot in our case. Also note that scope of the bot is required to be ‘personal’.

Starter Prompts and bots.commandLists.commands

Note below how the commands in the commandList specify the sample prompts that are displayed when the bot is invoked from Copilot.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json",
  "manifestVersion": "1.20",
  "version": "1.0.0",
  "id": "%MICROSOFT-APP-ID%",
  "name": {
    "short": "IT Support Agent",
    "full": "IT Support and Assistance Agent"
  },
  "description": {
    "short": "Your go-to IT support bot",
    "full": "A comprehensive IT support bot to assist with common IT issues and tasks"
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "bots": [
    {
      "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
      "scopes": [
        "personal"
      ],
      "commandLists": [
        {
          "scopes": [
            "personal"
          ],
          "commands": [
            {
              "title": "Password Reset",
              "description": "Guide me through resetting my password"
            },
            {
              "title": "Software Installation",
              "description": "Help me install new software"
            },
            {
              "title": "Network Issues",
              "description": "Troubleshoot network connectivity problems"
            },
            {
              "title": "Hardware Support",
              "description": "Assist with hardware-related issues"
            },
            {
              "title": "IT Policies",
              "description": "Provide information on IT policies and best practices"
            }
          ]
        }
      ]
    }
  ],
  "copilotAgents": {
    "customEngineAgents": [
      {
        "id": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
        "type": "bot"
      }
    ]
  }
}

Creating the Relay bot

To create the Relay bot, we start with the Teams Toolkit in Visual Studio 2022 and created a C# EchoBot. C# is just a personal preference, many languages are supported including python and JavaScript.

In EchoBot.cs, in the OnMessageActivityAsync method, we call by API exposed by the Azure AI agent:

1
2
3
4
5
6
7
8

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  string messageText = turnContext.Activity.RemoveRecipientMention()?.Trim();
  CallSentimentAgent callSentimentAgent = CallSentimentAgent.Instance;
  var replyText = await callSentimentAgent.CallAgent(messageText);
  //var replyText = $"Echo: {messageText}";
  await turnContext.SendActivityAsync(MessageFactory.Text(replyText), cancellationToken);
}

Sample Project

A sample project with this implemented can be found here: https://github.com/mjfusa/Copilot-Custom-Engine-Agent-Relay-to-Azure-Agent

Conclusion

The relay bot architecture provides a simple way to integrate external AI agents with M365 Copilot. By using the Teams app manifest and the new ‘copilotAgents’ object, we can easily convert a Teams bot into a Copilot agent. This allows us to leverage the capabilities of our existing agents while providing a seamless experience for users in Microsoft 365 applications.