Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Copilot Studio provides a set of nodes that you can use for activities that aren't messages: the Event activity node, the Invoke activity node, and other activity-related nodes that the activity protocol supports.
What is the activity protocol?
The activity protocol is a core transport concept in Copilot Studio. The activity protocol allows seamless communication between users and agents. It defines a standardized structure for all interactions, categorizing them into various activity types.
Event activities and message activities are two distinct types within the activity protocol, each serving unique purposes in communication workflows.
Message activities represent the foundational communication units between users and agents, primarily carrying textual, media, or adaptive card content. They're designed for direct interactions, where a user makes a query or statement, and the agent responds accordingly.
Event activities, on the other hand, are typically used to signify nonverbal actions or system-generated updates. They allow for asynchronous communication, triggering specific functionalities or workflows without requiring direct user interaction. For instance, an event activity can notify an agent about a user joining a conversation or changes in surrounding context.
Sending events
The Event activity node is designed for sending event activities. Event activities are sent from the agent and can be intercepted and used by the channel, which decides if and how to use the activities. When you send an event, you give it a name and then you can set a value for the event. This value can be in any format:
- A primitive literal value
- A variable reference
- A Power Fx formula.
The value gets serialized as a JSON literal and added to the outgoing activity.
Uses of this node include:
- Configure a custom Web Chat control to handle events sent from the agent. For example, you could look for an event coming back from the agent and take an action on the page. The
04.api/c.incoming-activity-eventsample in the Microsoft Bot Framework Web Chat samples repository on GitHub demonstrates how event handling could work. - Use event activities to control AudioCodes recording services—for example, to start or stop call recording. For more information, see Recording calls.
Using client tools
During orchestration, we provide the language model with a set of tools. Most people think about tools as calling into external systems.
However, we can also use event activities to execute tools from the client.
When the orchestrator decides to execute a client tool, the agent sends out an event activity to the client, including the inputs defined in the tool.
The agent sends out the activity, then waits for the client to perform the action and return a result. When the client is done, it sends an event activity containing the response to the agent. The agent takes this response as the tool response and continues orchestration.
Sample payloads for client tools
Suppose we have a client tool that retrieves the text on a PowerPoint slide.
The inputs are the page number, and the output is the text on the slide.
The agent could send a payload like:
{
"type": "event",
"timestamp": 1738709828,
"from": {
"id": "d9c0dcf9-4045-8062-535b-73fb4dfee954",
"role": 0
},
"name": "getSlideContent",
"replyToId": "f617c120-7b36-496a-a096-ac692efdad04",
"value": {
"page": 5
}
}
After the operation finishes, the client sends the agent something a payload like:
{
"type": "event",
"timestamp": 1738709828,
"name": "getSlideContent",
"replyToId": "f617c120-7b36-496a-a096-ac692efdad04",
"value": {
"content": "QA slide. Next steps"
}
}
Setting up client tools
There are two ways to register client tools.
As part of your agent topic content, you can register a dedicated client task action on your agent, using the code editor.
For example:
description: this tool retrieves the content of a powerpoint slide
schemaName: GetSlideContent
dialog:
kind: TaskDialog
action:
kind: InvokeClientTaskAction
clientActionInputSchema:
kind: Record
properties:
page:
displayName: Page Number
description: The number of the slide
isRequired: true
type: Number
clientActionResponseSchema:
kind: Record
properties:
content:
displayName: Slide Content
description: The content of the slide
type: String
Sometimes, the available tools are dynamic, based on the context of the hosting client. To allow more flexibility, makers can set a system variable to dynamically set other client tools that can be used for this session.
- kind: SetVariable
id: setVariable_76NZWK
variable: System.ClientPluginActions
value: |-
=[
{
Description: "this tool retrieves the content of a powerpoint slide",
Identifier: "GetSlideContent",
Name: "GetSlideContent",
Response: {mode: "Generated"},
Inputs: [
{
Description: "The name of the menu for the form to launch",
IsAutomatic: true,
IsRequired: true,
Name: "Page Number",
PropertyName: "page",
Type: {
'$kind': "Number"
}
}
],
Outputs: [
{
Description: "The content of the slide",
Name: "Slide Content",
PropertyName: "content",
Type: {
'$kind': "String"
}
}
]
}
]
Sending other activity types
In addition to event activities, you can send activities of other types using the Invoke activity node. The types of activities you can send are a subset of the ones offered in the Bot Framework Schema - ActivityTypes Class. When using this node, you choose the type of the activity and then optionally set a name or value.
Common types are:
- Typing sends a typing activity, which the channel can choose to pick up and show a typing indicator on the client.
- Invoke and Invoke response are used for Microsoft Teams. You create a topic with an invoke trigger to intercept an incoming Invoke from Teams, and use an Invoke response activity node to send an appropriate response back to Teams.
- Handoff sends a handoff activity with explicit control over the value. A handoff is used for external channels, such as AudioCodes.