Transition conversations from bot to human
APPLIES TO: SDK v4
Regardless of how much artificial intelligence a bot possesses, there may still be times when it needs to hand off the conversation to a human being. This can be necessary either because the bot does not understand the user (because of an AI limitation), or if the request cannot be automated and requires a human action. In such cases the bot should recognize when it needs to hand off and provide the user with a smooth transition.
Microsoft Bot Framework is an open platform that allows developers to integrate with a variety of agent engagement platforms.
Handoff integration models
Microsoft Bot Framework supports two models for integration with agent engagement platforms. The handoff protocol is identical for both models, however the onboarding details differ between the models and the agent engagement platforms.
The goal is not to offer a universal solution for integration with any customer's system, but rather to provide a common language and best practices for bot developers and system integrators building conversational AI systems with human in the loop.
Bot as an agent
In the first model, known as "Bot as an agent", the bot joins the ranks of the live agents connected to the agent hub and responds to user requests as if the requests came from any other Bot Framework channel. The conversation between the user and the bot can be escalated to a human agent, at which point the bot disengages from the active conversation.
The main advantage of this mode is in its simplicity – an existing bot can be onboarded to the agent hub with minimal effort, with all of the complexity of message routing taken care of by the agent hub.
Bot as a proxy
The second model is known as "Bot as a proxy". The user talks directly to the bot, until the bot decides that it needs help from a human agent. The message router component in the bot redirects the conversation to the agent hub, which dispatches it to the appropriate agent. The bot stays in the loop and can collect the transcript of the conversation, filter messages, or provide additional content to both the agent and the user.
Flexibility and control are the main advantages of this model. The bot can support a variety of channels and have control over how the conversations are escalated and routed between the user, the bot, and the agent hub.
Handoff protocol
The protocol is centered around events for initiation, sent by the bot to the channel, and status update, sent by the channel to the bot.
Handoff initiation
The Handoff Initiation event is created by the bot to initiate handoff.
The event contains two components:
- The context of the handoff request that is necessary to route the conversation to the right agent.
- The transcript of the conversation. The agent can read the conversation that took place between the customer and the bot before the handoff was initiated.
The following are the handoff initiation event fields:
Name - The
name
is a required field that is set to"handoff.initiate"
.Value - The
value
field is an object containing agent hub-specific JSON content, such as required agent skill and so on. This field is optional.{ "Skill" : "credit cards" }
Attachments - The
attachments
is an optional field containing the list ofAttachment
objects. Bot Framework defines the "Transcript" attachment type that is used to send conversation transcript to the agent hub if required. Attachments can be sent either inline (subject to a size limit) or offline by providingContentUrl
.handoffEvent.Attachments = new List<Attachment> { new Attachment { Content = transcript, ContentType = "application/json", Name = "Transcript", }};
Note
Agent hubs must ignore attachment types they don't understand.
Conversation - The
conversation
is a required field of typeConversationAccount
describing the conversation being handed over. Critically, it MUST include the conversationId
that can be used for correlation with the other events.
When a bot detects the need to hand the conversation off to an agent, it signals its intent by sending a handoff initiation event.
In C# an higher level API CreateHandoffInitiation
method can be used as demonstrated in the code snippet below.
var activities = GetRecentActivities();
var handoffContext = new { Skill = "credit cards" };
var handoffEvent =
EventFactory.CreateHandoffInitiation(
turnContext, handoffContext, new Transcript(activities));
await turnContext.SendActivityAsync(handoffEvent);
Handoff status
The Handoff Status event is sent to the bot by the agent hub. The event informs the bot about the status of the initiated handoff operation.
Note
Bots are not required to handle the event, however they must not reject it.
The following are the handoff status event fields:
Name - The
name
is a required field that is set to"handoff.status"
.Value - The
value
is a required field describing the current status of the handoff operation. It is a JSON object containing the required fieldstate
and an optional fieldmessage
, as defined below.
The state
has one of the following values:
accepted
- An agent has accepted the request and taken control of the conversation.failed
- Handoff request has failed. Themessage
might contain additional information relevant to the failure.completed
- Handoff request has completed.
The format and possible value of the message
field are unspecified.
Successful handoff completion:
{ "state" : "completed" }
Handoff operation failed due to a timeout:
{ "state" : "failed", "message" : "Cannot find agent with requested skill" }
Conversation -
Conversation
is a required field of typeConversationAccount
describing the conversation that has been accepted or rejected. TheId
of the conversation MUST be the same as in the HandoffInitiation that initiated the handoff.
Handoff library
The Handoff Library has been created to complement the Bot Framework v4 SDK in supporting handoff; specifically:
- Implements the additions to the Bot Framework SDK to support handoff to an agent (also known as escalation.
- Contains definitions of three event types for signaling handoff operations.
Note
Integrations with specific agent hubs are not part of the library.
Additional resources
Feedback
Submit and view feedback for