Using Microsoft Copilot Studio agents as a chat suggestion source

Prerequisites

Before you start working through this article, make sure you meet the following requirements:

Your organization has an environment in Microsoft Copilot Studio.
You have a Microsoft account that can access your organization’s environment.
Your user account for Unblu Spark has admin privileges.

Setting up an agent as a suggestion source in Microsoft Copilot Studio

To set up an agent in Microsoft Copilot Studio that can act as a suggestion source, you must complete the following steps:

Create an agent
Add knowledge sources to the agent
Configure the agent’s topics
Publish the agent

Each of these steps is discussed in the sections below. For further information and more detailed instructions on each step, refer to the Microsoft Copilot Studio documentation.

Create an agent

To create an agent in Microsoft Copilot Studio, complete the following steps:

Select Agents in the left sidebar, then click New agent.
Give your agent a name. Optionally give it a different icon and a description.
In the Knowledge section, click Add knowledge. In the modal dialog that appears, select the sources that the agent should use to generate suggestions.

You can add knowledge sources after you create the agent, so you can skip this step for now if you prefer.
Click Create in the upper right-hand corner to complete the process.

Add knowledge sources to the agent

When Copilot Studio creates your agent, it displays the agent’s Overview page. To add knowledge sources, click Knowledge at the top of the screen. Any knowledge sources you added while creating the agent are already listed on the page.

To add a knowledge source, proceed as follows:

Click Add knowledge.
In the modal dialog that appears, select the type of source you wish to add and follow the instructions in the Microsoft Copilot Studio documentation.
Click Add to add the resource.

Repeat the steps above for all the knowledge sources you want the agent to base its suggestions on.

Once you’ve added a knowledge source, you can mark it as an official source. If you do so, the agent adds a remark to that effect at the beginning of messages based on the resource in question.

Disable general knowledge

By default, Microsoft Copilot agents use all the resources they were trained on to generate suggestions. Since you have no control over these resources, using them may result in less appropriate responses.

To ensure only the knowledge sources you selected are used to generate suggestions, disable the option Allow the AI to use its own general knowledge in the agent’s Overview tab.

Configure the agent’s topics

This section is only a brief introduction to configuring topics. For more information, refer to Create and edit topics in the Microsoft Copilot Studio documentation.

In the context of Microsoft Copilot Studio, a topic represents part of an exchange between the agent and a user. When you create an agent, Microsoft Copilot Studio automatically creates a number of predefined custom and system topics for you. Whether you need the predefined topics or not depends on your specific use case for the agent. Delete or disable any topics you don’t need.

Custom topics for chat suggestions

When you create a new topic in Microsoft Copilot Studio, you create a custom topic. Custom topics can have different types of trigger. For chat suggestions, the phrases trigger is the most relevant. Custom topics with a phrases trigger are similar to intents in the Unblu Conversational Bot (UCB).

If you want the agent to react to certain phrases in a specific way, create a custom topic and add a number of related phrases to the topic as the trigger. These phrases are used as training phrases for the agent.

When a user requests a suggestion for a phrase similar to the training phrases, the agent triggers the custom topic. The custom topic then processes the nodes you defined for it. The actions these nodes can define are outside the scope of this article.

For chat suggestions, you must ensure that the agent returns a message. When configuring the response, bear in mind the following points:

Don’t include any questions in your topics. Questions block the flow of the topic until Unblu Spark sends an answer. For agents used as suggestion sources, this never happens. As a result, the agent never returns a suggestion.
If your topic returns multiple answers, Unblu only ever uses the first answer as a chat suggestion and discards the other answers. Agents used as suggestions sources should therefore only ever send a single answer.
The message your agent returns can be supplemented by a ChatSuggestionResponse. For more information, refer to Using chat suggestion data types with Copilot agents below.

Conversational boosting for chat suggestions

One particularly interesting topic in the context of chat suggestion sources is Conversational boosting. It’s a system topic that’s triggered when the agent can’t find another topic with which to process the input it received. Conversational boosting uses generative AI to make suggestions based on the knowledge sources you added to the agent.

The trigger type for conversational boosting is "On Unknown Intent". You can’t select this trigger type in the UI, although you can use it in code representations of a topic and upload it to Microsoft Copilot Studio.

Publish the agent

To prepare your agent for publication, first set its authentication type to No authentication:

Open the agent’s settings.
In the sidebar on the left, click Security, then click Authentication in the main area.
On the next screen, select the option No authentication and click Save.

Now you’re ready to publish the agent. To do so, close the agent’s settings and click Publish.

Now you can configure Unblu Spark to use the agent as a suggestion source.

Configuring a Microsoft Copilot agent as a suggestion source in Unblu Spark

You can add a Microsoft Copilot agent to Unblu Spark as a suggestion source using the Account Configuration interface or the Unblu web API.

For information on the former, refer to Suggestion sources in the Account Configuration interface guide.
For information on the various suggestion source web API calls, refer to the /suggestionsources endpoints in the Unblu web API reference. You should also review the CopilotSuggestionSourceData schema.

Whichever option you choose, you need the following information:

The Direct Line API 3.0 endpoint that Unblu Spark uses to communicate with the agent. The endpoint is <directLineBaseURI>/v3/directline. Replace <directLineBaseURI> with the appropriate Direct Line baseURI for your Microsoft Copilot agent.

Note that the endpoint doesn’t distinguish one agent from another. That’s what the authentication token’s for, which is described in the next point.
An authentication token. This identifies a specific agent.

The authentication token comes from Microsoft Copilot Studio. To get one for your Copilot agent, open the agent’s settings, click Security in the left sidebar, then select Web channel security. You can use either of the two secrets listed as the agent’s authentication token.
The Microsoft Copilot agent ID and the Microsoft environment ID. To retrieve these, click the settings icon and select Session details. The values are listed under the heading Copilot Studio details as Copilot Id and Environment ID, respectively.

If you’re using Copilot’s generative AI abilities, make sure you set the timeout such that Copilot has enough time to generate a suggestion. In these circumstances, consider setting the timeout to at least 10000 ms.

You must also set several configuration properties in Unblu Spark:

com.unblu.copilot.activityReceptionMethod specifies how Unblu Spark is informed of activity on the Copilot agent’s part. You can configure Unblu Spark to expect responses using HTTP or WebSockets.
- If you choose HTTP, Unblu polls the agent for new activities.
- If you choose WebSockets, Unblu opens a WebSocket connection to the agent that the latter can then use to notify Unblu Spark of new activities. (Agents generate a lot of activities, not just when they’ve created a suggestion.)

Once you’ve added the Microsoft Copilot agent to Unblu Spark as a suggestion source, you can use it in conversation templates like any other suggestion source. For more information, refer to Enabling suggestions.

Using chat suggestion data types with Copilot agents

If a Microsoft Copilot agent is configured as a chat suggestion source in Unblu, Unblu Spark communicates with it using the data types for chat suggestions.

When a user requests a chat suggestion, Unblu Spark sends the Microsoft Copilot agent a message activity. The message activity has numerous attributes, but the two Unblu uses are text and value:

The text attribute contains the text of the message for which the agent should generate a suggestion.
The value attribute contains a ChatSuggestionRequest. It allows Unblu to provide the agent with more context for the suggestion request. This can be especially useful if a topic uses actions that access another of your organization’s systems to generate a suggestion.

If you allow your users to customize the prompt, the text that they entered is in the customPrompt attribute of the ChatSuggestionRequest. However, Unblu also ensures that the custom prompt is inserted in the activity’s text attribute.

When your agent responds to Unblu, it also sends a message activity. You can transmit your agent’s suggestion in one of two ways:

By default, Unblu Spark expects the text attribute to contain the chat suggestion.
If you include a value attribute in your agent’s response, Unblu Spark disregards the contents of the text attribute. Instead, it interprets the contents of the value attribute as a ChatSuggestionResponse, and attempts to read that schema’s attributes, suggestionText and suggestionComment.

To return a ChatSuggestionResponse, you must create a variable in your topic with the attributes mentioned above and assign the suggestionText attribute a value. You must also specify that the activity include the variable in its value attribute.

The contract between the Unblu Spark chat suggestion integration, on the one hand, and Microsoft Copilot Studio, on the other, isn’t enforced technically. However, if your agent doesn’t adhere to the contract, chat suggestions won’t work.