<style> .chartjs-size-monitor { display: none !important; height: 0 !important; overflow: hidden !important; }p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
.chartjs-size-monitor {
display: none !important; height: 0 !important; overflow: hidden !important;
}
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><p><strong>In this guide we will cover:</strong></p><p data-pasted="true"><strong>- What are Conversation Agents?</strong></p><p><strong>- Available System Functions</strong></p><p><strong>- Custom Functions</strong></p><p><strong>- Customise System Functions </strong></p><p><strong>- Restricting Function Access </strong></p><p><strong>- Custom Functions in Chat Profiles</strong></p><p><strong>- Worked Example - Custom Function Use Case - Have a Conversational Agent trigger a Runbook to complete a password reset </strong></p><p data-pasted="true"> </p><p><br></p><p>This guide follows on from our guide on <a href="https://www.usehalo.com/guides/2336" target="_blank" rel="noopener noreferrer">Conversational Agents,</a> we recommend reading <a href="https://www.usehalo.com/guides/2336" target="_blank" rel="noopener noreferrer">this </a>guide first. </p><p><br></p><p data-pasted="true" style="box-sizing: inherit; margin: 0px; line-height: 1.4285em; color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><strong><span style="font-size: 14pt;">What are Conversation Agents?</span></strong></p><p data-pasted="true">Conversational Agents are a type of AI Agent. They leverage AI to converse with a user or agent, returning information and carrying out actions based on the user's/agent's input. Conversation Agents are primarily used in conjunction with the Chat Bot, a conversational agent can be plugged into a chat profile to process/direct the chat, making chat profiles much easier/quicker to set up as the Agent uses AI to dynamically determine what information the user would like based on their input, rather than having to create pre-configured steps.</p><p><br></p><p>Two subtypes of conversation agents are available, Operations Agents and Virtual Agents. </p><ul><li>Operations Agents - Used by agents. </li><li>Virtual Agents - Used by users. </li></ul><p><br></p><p>There are various functions conversational agents can carry out, beneficial for both agents and users, in this guide we will go through what these functions are, the benefits and how to set up the conversation agent to use these. </p><p><br></p><p><strong><span style="font-size: 12pt;">What are Functions?</span></strong></p><p>Functions are the backbone of Conversational Agents, these allow the Agents to take action/interact with your instance to support both agents and users, including updating tickets, information from the database and triggering automations. Functions inform what the conversational agent can do in your Halo instance, allowing the Agent to complete a request based on the prompt users/agents give in the chatbot. Different system functions are available for operations agents over virtual agents as users will not need access to the same functions as your agents. </p><p><br></p><p>In this guide we will outline how to configure both system and custom functions for conversational agents. </p><p><br></p><p><strong><span style="font-size: 14pt;">Available System Functions</span></strong></p><p>The system functions available for a conversational agent will differ for operations and virtual agents.</p><p><br></p><p data-pasted="true"><strong>Functions for Virtual agents (Users)</strong></p><p>The following functions can be carried out by a virtual agent, these are tailored to end users:</p><ul><li id="isPasted"><strong>Knowledge search (get_knowledge):</strong> The virtual agent will complete a search of the knowledge base based on the user's input, using AI Search. It will formulate a response based on the results returned, suggesting relevant articles for the user to read. (Additional setup is required for this functionality, covered in more detail below). </li><li><strong>Service search (log_service_request):</strong> The virtual agent will search services using AI Search, and receive the names and links to any matched services, and direct the user to the relevant service where appropriate. (Additional setup is required for this functionality, covered in more detail below). </li><li><strong>Log an incident (log_incident):</strong> The virtual agent will log a ticket for the user once it knows the user's information and details of an issue.</li><li><strong>Check my tickets (get_my_tickets):</strong> The virtual agent will provide the user information about their open tickets when requested, or a specific open ticket.</li><li><strong>Update a ticket (update_ticket):</strong> The virtual agent will add an update to one of the user's tickets when requested. This will update the ticket as if the end user has updated the ticket.</li><li><strong>Speak to an agent (transfer_to_agent):</strong> The virtual agent can transfer the user to a human agent, beginning live chat. </li><li><strong>End chat (end_chat):</strong> The virtual agent can end the chat. </li><li><strong>Get User info (get_user_info):</strong> The virtual agent can provide the user information held about the user in Halo. </li><li><strong>Upload attachments (allow_attachment_upload):</strong> The user can upload attachments to the chat, the virtual agent will then upload these attachments to the ticket logged from the chat. To use this functionality 'Allow image and attachment upload' must be enabled under Configuration > Chat. This functionality is available as a system function but we recommend making additions to the virtual agent instruction to re-enforce when this function should be used, this will increase reliability and accuracy. We outline how to configure this in the section 'Upload attachments to tickets via virtual agents' in this guide.</li><li><strong>Doing an action with fields (use_specific_action): </strong>Available from v2.238+. The virtual agent can add any action available to users on a ticket's workflow to a ticket, including populating any fields on this action. The action must be available to use on the ticket, and the virtual agent must have access to a function that allows it to check the workflow step of the ticket (such as get_one_ticket). Only available when using a virtual agent that uses the Responses API. </li><li><strong>Custom functions:</strong> Custom functions can be configured and made available at each step of the chat flow. See the custom functions section of this guide for more information. </li></ul><p><span style="color: rgb(0, 0, 0);"><br></span></p><p><span style="color: rgb(0, 0, 0);">If you would like any of this functionality to be restricted e.g. not allow live chat to be started from the virtual agent, you can instruct the virtual agent not to do this using the 'Instructions' prompt. For example, if you would not like users to be able to log a new ticket through the virtual agent you could add the following to the instructions field "If you determine that a user would like to log a ticket return the following "I'm sorry, you cannot use this service to log a new ticket". More concrete function restrictions can be enforced by disabling some functions, more information on this later in the guide. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);"><strong><span style="font-size: 12pt;">Functions for Agents</span></strong></span></p><p data-pasted="true">The following functions can be carried out by an Operations Agent, these are tailored to agents:</p><ul><li><strong>Searching the Knowledge base (using AI search)</strong><strong>: </strong>The operations agent will search the knowledge base based in the input from the agent. It can return resolution suggestions based on the relevant articles it finds, it can also suggest articles for the agent to read. </li><li><strong>Getting details of a specific article (get_one_article):</strong> The operations agent can summarise or extract details from a specific KB article and return these to the agent. </li><li><strong>Listing the agents assigned tickets (get_assigned_tickets):</strong> The operations can return a list of tickets that are assigned to the agent. </li><li><strong>Searching tickets (using AI search) (search_tickets):</strong> The operations agent can search ticket content based on a prompt from the agent. Allowing it to effectively summarise and suggest replies or resolutions to tickets based on this info.</li><li><strong>Getting details of a specific ticket (get_one_ticket):</strong> The operations agent can return details of a specific ticket, allowing agents to complete quick comparisons between tickets. On versions prior to v2.250 this will only return core system fields, it not return custom or other system fields. On v2.250+ this function can return custom field values, provided the function is added as a custom function. When it is added as a custom function you will have the option to "Include custom fields" when this this function is used. To add this function as a custom function simply deselect "Include all system functions" and add a function to the table, this function will now be available to choose as a 'Use'. Keep in mind if custom fields are included this does not respect any dynamic field visibility, all fields can be returned. </li><li><strong>Adding a private note to a ticket (add_note_to_ticket):</strong> The operations agent can add a private note to a ticket on behalf of the agent, allowing agents to update tickets from the chat bot. </li><li><strong>Doing a "Quick action" on a ticket (action_ticket):</strong> The operations agent can add any action that is configured to be a 'quick action' to a ticket on behalf of the agent, allowing agents to update tickets from the chat bot. On versions v2.238+ this function has been re-named to 'use a quick action', to more accurately reflect what the function does, the use of the function has not changed. </li><li><strong>Refreshing AI matches for a ticket (get_matches):</strong> The operations agent can re-run AI ticket matching for a specific ticket. Beneficial when the ticket has been open for some time, in which closer matches may exist. This allows the agent to ensure the matched tickets are the most up to date matches in the database. </li><li><strong>Applying AI suggestions on a ticket (apply_suggestion):</strong> The operations agent can apply AI suggestions to a ticket, rather than the agent having to do this from within a ticket. </li><li><strong>Assigning a ticket to the logged-in agent (assign_to_me):</strong> The operations agent can re-assign a ticket from one agent to the agent logged in (using the chat). </li><li><strong>Creating a new ticket (create_ticket):</strong> The operations agent can log a new ticket of a specified type with specified details. </li><li><strong>Logging time (using the quick time feature):</strong> The operations agent can a log a quick time entry for the agent.</li><li><strong>Doing an action with fields (use_specific_action):</strong> Available from v2.238+. The operations agent can add any action available on a ticket's workflow to a ticket, including populating any fields on this action. The action must be available to use on the ticket, and the operations agent must have access to a function that allows it to check the workflow step of the ticket (such as get_one_ticket). Only available when using a virtual agent that uses the Responses API.</li></ul><p>All the above functionalities come pre-configured out-of-the-box, excluding the knowledge base search functionality, this will need to be set up.</p><p><br></p><p><span style="color: rgb(0, 0, 0);"><strong><span style="font-size: 12pt;">Using the AI knowledge Search Function</span></strong></span></p><p><span style="color: rgb(0, 0, 0);">AI search can be used to search the knowledge base for answers to agent's and user's questions. Upon entering a prompt the Conversation Agent can return answers based on articles content, or suggest articles for the user/agent to read. It can also be used to search the service catalogue, returning information on services to the agent/user or directing the user to log a service request. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);">Conversation Agent search (for KB articles, tickets and services) can be used without AI search but there will be limitations in the results returned. In order to use the AI search functionality you will need to set this up and connect to Azure open AI or AWS OpenSearch, in Configuration > AI > General Settings. </span></p><p><span style="color: rgb(0, 0, 0);"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFiMmQxM2YwLWVhOTEtNDQ0ZC04YTY2LTY3MTVmNmEyYjJiZiJ9.RmTxDFFp5Xp7GksrytX1Et2d91a8CESKbLEhh0oQwFA" class="fr-fic fr-fil fr-dib" width="874" style="width: 876px; height: 629.905px;" height="630"></span></p><p><strong><span style="font-size: 10pt;">Fig 1. Setting up AI knowledge search</span></strong></p><p><br></p><p>For more information on how to set up the connection for AI knowledge base searching, see <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2125/" id="isPasted" target="_blank" rel="noopener noreferrer">Improve Search Using AI</a>.</p><p><br></p><p><strong><span style="font-size: 12pt;">Transfer to Agent Chat Function</span></strong></p><p>One of the functions of virtual agents, allows them to transfer the user to a Live Chat with a real agent should the user request this. </p><p><br></p><p>Once the Virtual Agent detects the user requires live chat, or the user specifically requests this, they will be transferred. This is dependent on <a href="https://usehalo.com/haloitsm/guides/2509/" target="_blank" rel="noopener noreferrer">Live Cha</a>t already being configured. </p><p><br></p><p>You can prevent Virtual Agents from transferring the user to a Live Chat if no agents are available to chat. This enabled under Configuration > Chat > "Check if any Agents are available before virtual agents can attempt to transfer to an Agent". </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEwNWRmMjdiLTczNWEtNGY5Ny04MzFkLWIyMDQ4NjgzYjRiMCJ9.1KwZ9-rxzUOZX9JGDc_e86dUKQCFZOMQfwupVdbvyUg" class="fr-fic fr-fil fr-dib" width="557" height="192"></p><p><strong><span style="font-size: 10pt;">Fig 2. Setting to prevent users being transferred to Live Chat if no agents are available</span></strong></p><p><br></p><p>When this is enabled, if a user requests to speak to an agent but no one is available, the Virtual Agent will return a message advising the user no one is currently available. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk1YTk2NzlmLTJhZTctNGJkZS1hZTMwLWQ4ZGRjZjQyYWEzMyJ9.zxR74GGOWCnCOcQ-vOYbgBmmj4rYbjeDwUuIQa88aZ4" class="fr-fic fr-fil fr-dib" width="328" style="width: 330px; height: 571.083px;" height="571"></p><p><strong><span style="font-size: 10pt;">Fig 3. Chat message when no agents available</span></strong></p><p><br></p><p data-pasted="true"><strong><span style="font-size: 12pt;">Upload Attachment Function</span></strong></p><p>Attachments can be given to the Conversation Agent chat and uploaded to a ticket, either a ticket of choice or a ticket logged from this chat. </p><p><br></p><p><strong><em>Note: Conversation Agents cannot read attachments, only upload given attachments to tickets. </em></strong></p><p><br></p><p>You must detail when to execute this function in your Conversation Agent's instructions in order to use this functionality. This is because attachment uploads are not available at any point in the chat conversation, the Conversation Agent will need to make attachment upload available for the user before attachments can be uploaded. The Conversation Agent's instructions will control when the Conversation Agent makes attachment upload available.</p><p><br></p><p>The instructions should tell the Conversation Agent to execute 'allow_attachment_upload' before asking the user for attachments. This function will give the user an option to upload attachments, so if it has not be executed they will not have the 'upload attachment button' available to them. An example instruction is given below but you will need to adjust this in line with when you would like users to be able to upload attachments/when you would like the Sgent to ask for attachments. </p><p><br></p><p style="margin-left: 20px;" data-pasted="true"><em>'You must invoke allow_attachment_upload before you ask the user to provide attachments/files such as images, screenshots, documents, or logs.'</em></p><p style="margin-left: 20px;"><br></p><p>You will also need to ensure attachment uploads are enabled for the chatbot, enabled under Configuration > Chat > "Allow image and attachment upload". </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM0YjZkODZjLTExMTEtNGFhNC1hNGQ4LWM5YmUwMWY2MTI4MCJ9.Oc6IIkV1fFNSaIPzlp6oJSR7sn3BRNIKUles5e04Nd4" class="fr-fic fr-fil fr-dib" width="841" style="width: 843px; height: 291.348px;" height="291"></p><p><strong><span style="font-size: 10pt;">Fig 4. Allow image and attachment upload</span></strong></p><p><br></p><p>Now, when a user asks to upload an attachment, the option to upload will be made available and the virtual agent will add this attachment to the associated ticket. </p><p><br></p><p><strong><span style="font-size: 14pt;">Custom Functions</span></strong></p><p>Custom functions can be configured against a Conversational Agent, to allow the user/agent to complete the following from a conversation agent chat: </p><ul><li>Log a ticket of a certain type or template</li><li>Trigger a chosen automation runbook</li><li>Obtain information based on Report data</li><li>Search for tickets </li><li>Execute an <a href="https://www.usehalo.com/guides/2776" target="_blank" rel="noopener noreferrer">AI Ability</a></li><li>Use a specific ticket action</li></ul><p>This increases the number of automations that can be carried out using the chatbot as well as the ease of executing these automations. Automations can be triggered based on user requests in the chat, leveraging AI to execute the correct automation based on the user's input. </p><p><br></p><p><strong><em>Note: Function customisation is not available on out of the box Conversation Agents, but new Agents can be created using either your own, or Halo's AI connection. For information on configuring an AI connection see our guide <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2385" id="isPasted" target="_blank" rel="noopener noreferrer">Connecting AI to Halo</a>.</em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Adding Custom Functions</span></strong></p><p>Custom Functions can be added to an Conversation Agent by adding an entry to the Functions table. </p><p><strong><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ3MDA3ZjkzLTg2ZDYtNDU5Zi1iNjdhLWU0M2MxYTAxNTU5NiJ9.jFC2tD9IT_nVPCNO_lgOQ2atWyVHkjO3rUCFOB9-9Do" class="fr-fic fr-fil fr-dib" width="1575" style="width: 1577px; height: 729.261px;" height="729"></strong></p><p><strong>Fig 5. Add a Custom Function</strong></p><p><strong><br></strong></p><p data-pasted="true">When adding a function you will see the pop-up shown in Figure 6. </p><p><strong><br></strong></p><p><strong><em>Note: The "Description" field here has a character limit of 1000.</em></strong></p><p><strong><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBiMTJhMjlhLThiMTktNDRjZS04ZTI1LWViNWZjZjQxZDEzMSJ9.BkNXtC6_8dL6YuJXIbO2OOW6JWCn3tMvKP2H_Sr2KG8" class="fr-fic fr-fil fr-dib" width="539" style="width: 541px; height: 789.588px;" height="790"></strong></p><p><strong>Fig 6. New Custom Function</strong></p><p><strong><br></strong></p><p data-pasted="true"><strong>Name - </strong>Here, enter the name of the function. This string/command can be entered into the chat in order to execute the function. </p><p><strong>Description -</strong> Here, enter what the function is used for i.e. what it is doing and when the virtual agent should execute the function. As well as the conditions that need to be met before the function can be executed. This will determine when the Conversation Agent executes this function. </p><p><strong>Use - </strong>Here select what you would like this function to do. You will notice some system functions are available to select here, selecting these just allows you configure access to this function. </p><p><br></p><p data-pasted="true"><strong><span style="font-size: 12pt;">Custom Function to log a ticket </span></strong></p><p>Custom functions can be configured against a Conversation Agent to have a ticket of a set type, or using a set template be logged. This is similar to the system function 'Log an incident', but a custom function allow you to configure multiple functions where each can create a ticket with a different type or template. They can also be used to log a ticket which executes an asynchronous runbook. </p><p><br></p><p>To set this up add a function with the use 'Create New ticket', then you can choose which ticket type or template this function will log. </p><p><br></p><p>In the Figure 20 example the Agent will log a ticket with type 'Other Hardware' when the user expresses an interest in having some new hardware, excluding laptops and monitors. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM1ZjIwN2FmLTZiZTQtNDM2OS1iMDliLTdjMDUwMDdmNDZhNSJ9.EhbE990u2plczsQ4oQUXg6Xxfqx6Sjyxr0iXZJLNsyE" class="fr-fic fr-fil fr-dib" width="483" style="width: 485px; height: 494.459px;" height="494"></p><p><strong><span style="font-size: 10pt;">Fig 7. Function to log specified ticket type</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Custom Function to obtain report data</span></strong></p><p>Custom functions can be can be configured against an Conversational Agent to have the Agent get data from a chosen report. Once the Agent has this data they can then return data to the user based on this report. For example, if a user/agent would like to ask about historical ticket data, or ticket statistics, the Conversational Agent will need to get data from a report that has this data, once it has this data it can then answer questions on this. </p><p><br></p><p>To do set this up add a new custom function to your Conversation Agent with the use 'Get Report Data. You can then choose which report to run. From v2.251+, when this is selected, you will have the option to "enable pagination", this will allow you to specify a page size to improve performance for reports with a large number of results. </p><p><br></p><p>In the Figure 8 example, a custom function has been added to have the Conversational Agent get the data from the report 'Feedback from tickets' when users/agents express an interest in wanting to see the feedback for a given ticket or agent. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZlZGJiOTliLTMzNDItNGQ5ZC1iZWZhLTY5OTcxYzRkZTQzOCJ9.chT-UgI1AQsj56iUPxe9UI9ZXOD7kpuWKJq8dwriErI" class="fr-fic fr-fil fr-dib" width="546" style="width: 548px; height: 711.197px;" height="711"></p><p><strong><span style="font-size: 10pt;">Fig 8. Custom Function to obtain ticket feedback data</span></strong></p><p><br></p><p>Now, when an agent/user uses this virtual agent, they will be able to ask it about data contained in this report (ticket feedback). In the below example, an agent has asked the virtual agent for the feedback that was left on a specified ticket. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM5OWQxNjEwLWE0NzYtNGU3Zi1hMTA4LTBiOTUzZGE5MTM1MyJ9.V3egDPIhivax6ijfkeUlmPkDhEbYw8y49-ZcjZkC4ik" class="fr-fic fr-fil fr-dib" width="348" style="width: 350px; height: 507.124px;" height="507"></p><p><strong><span style="font-size: 10pt;">Fig 9. Virtual agent using report data in response </span></strong></p><p><br></p><p><strong><span style="color: rgb(226, 80, 65);">Important: Reporting permissions will be ignored when running this function, even if the agent/user does not have access to the report, they will still be able to ask the virtual agent questions about it. </span></strong></p><p><br></p><p>Variables can also be used in the reports the virtual agents obtains data from, such as $-userid and $-agentid. This allows you to filter the dataset the report returns based on the user/customer/agent logged in. </p><p><br></p><p><strong><span style="font-size: 12pt;">Custom Function to Execute an Automation Runbook</span></strong></p><p id="isPasted">Custom functions can be configured against a Conversational Agent to trigger a <a href="https://www.usehalo.com/guides/1630" target="_blank" rel="noopener noreferrer">runbook</a>. Allowing you to execute automations from within a chat profile. When doing this you can choose the runbook that gets executed and define the parameters for the function which the Conversational Agent will fill in based on the conversation with the user/agent. The function parameters will be accessible inside the runbook using the <<request>> runbook variable. </p><p><br></p><p>To set this up add a new custom function to your conversation agent with the use 'Execute a Runbook'. You can then choose which runbook to execute. </p><p><br></p><p>In the Figure 10 example a custom function has been added to allow users to complete a password re-set. When a user tells the chat bot they would like or need to complete a password re-set, the virtual agent will be able make use of the custom function configured, and execute the runbook 'User Password Reset' which carries out the password re-set procedure. </p><p><strong><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzMzkxMmNmLTM2NWQtNDVmZi1iMWU3LWI3MDVkNDhkNTdjZCJ9.cWD2GCyDkqdC6pZxPm46KZ5ayaZ5jInu8YdAaaUkgdQ" class="fr-fic fr-fil fr-dib" width="508" style="width: 510px; height: 639.936px;" height="640"></strong><br></p><p><strong><span style="font-size: 10pt;">Fig 10. Custom function to execute a runbook</span></strong></p><p><br></p><p>Now, you will need to set parameters against the custom function. </p><p><br></p><p>Parameters will need to be defined to allow information within the chat to be used within the runbook (within the request of the runbook). </p><p><br></p><p><strong>Defining Parameters </strong></p><p>Parameters allow you to use information given to the chat within the automation runbook. All parameters for the function will be stored within the runbook level variable <<Request>>, but more on this later. </p><p><br></p><p>You must define a parameter for each piece of data you require for the runbook automation. For example, if your automation allows users/agents to make updates to tickets, you will need to have a parameter for the ticket ID, this parameter will need to be called upon within the automation runbook to ensure the automation is carried out on the correct ticket. </p><p><br></p><p>When defining a parameter you must give it a name, data type and description. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAzOWIxODIzLTVhNmMtNDU5Mi04OGExLTg5YTMzNTlhZDY1NSJ9.7FUzg-mWCxxuWYq5_R-PK1qCTvsfZWMqiwXNj1AgGec" class="fr-fic fr-fil fr-dib" width="553" style="width: 555px; height: 471.88px;" height="472"></p><p><strong><span style="font-size: 10pt;">Fig 11. Define Parameter</span></strong></p><p><br></p><p><strong>Name </strong>- This must contain the JSON parameter name. In other words, the JSON name for the value that is being stored here. If I would like the given ticket ID to be stored in this parameter, this would need to be named 'id' as this is the JSON name for the ticket ID field within the API. </p><p><strong>Data Type</strong> - Here set what type of data is being stored in this parameter. If my parameter is storing a ticket ID for example this would need to be 'number'. </p><p><strong>Description </strong>- Here enter a description of what data (from the chat) should be stored in this parameter. The AI model will use this description to determine what information to take from the chat and store against this parameter. </p><p><strong>Mandatory?</strong> - Check this if this parameter is required in order to execute the runbook. The runbook will not execute until the Virtual agent has the information required for this parameter. </p><p><br></p><p>In the Figure 12 example I have defined the parameter 'emailaddress'. This parameter will store the email address that the user would like the password re-set sent to. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImVkMTUxZjAxLTc5MDItNDM2Zi05OGI4LWFiOTZlYWVmNDkxNiJ9.a9QtQZlkEM0g-_74xgqfm_Em3vVognASkaybRnR5Ykc" class="fr-fic fr-fil fr-dib" width="566" style="width: 568px; height: 482.667px;" height="483"></p><p><strong><span style="font-size: 10pt;">Fig 12. Parameter to store email address</span></strong></p><p><br></p><p>Now this parameter is defined I can use it within my runbook. </p><p><br></p><p><strong>Runbook configuration - Using parameters within runbooks </strong></p><p>Now the custom function and parameters are configured you can use the values against the parameters within your runbook. </p><p><br></p><p>To call on these parameters use the variable <<Request>> </p><p><br></p><p>This variable will return all the parameters against the custom function as a JSON object, not just the value. For example, if I have defined two parameters, ticket ID (where ID=2186) and status ID (where ID=9), when the variable <<request>> is called, it will return the below: </p><p id="isPasted"><em>[</em></p><p><em> {</em></p><p><em> "id": 2186,</em></p><p><em> "status_id": 9</em></p><p><em> }</em></p><p><em>]</em></p><p><br></p><p>This is useful if you need to use all parameters within the post. However, these can be split out. </p><p><br></p><p>To be able to call specific parameters, or only parameter values, you will need to create some new runbook level variables. This is done under the 'Details' tab of the runbook. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM4MjU5ZDVmLTdiMjQtNDVmZS1iMTgxLTJmOTU1NjlhNjllNSJ9.6V4vYcRrFJaEil-MvwXP6O2IBiXSrd60JJBAwotsFBA" class="fr-fic fr-fil fr-dib" width="1476" style="width: 1478px; height: 458.497px;" height="458"></p><p><strong><span style="font-size: 10pt;">Fig 13. Set runbook level variables</span></strong></p><p><br></p><p>Here, we are essentially creating a new variable that we can use within the runbook, based on values within the <<request>> variable.</p><p><br></p><p>When adding a new runbook-level variable you will need to give it a name, this will be used to call the variable. Select the data type, and the value, the value will control what data this variable pulls. </p><p><br></p><p>To call a specific parameter within the <<request>> variable you will need to set the value as shown: <<request^PARAMETER NAME!>> (The ! is used to remove " from the parameter). </p><p><br></p><p>In the Figure 14 example I have created a new variable called 'email address' which will return the value of the emailaddress parameter, a ! has been appended to remove " from the end of the value. </p><p><br></p><p>Now the runbook level variable has been created I can call on this at any step of my runbook. </p><p><br></p><p data-pasted="true"><strong><span style="font-size: 11pt;">Execute Asynchronous Runbook</span></strong></p><p>For tasks/automations that you would like to run in the background while the chat continues, you can run an asynchronous runbook. </p><p><br></p><p>To do this you will need to configure a custom function that logs a ticket of a chosen type/template, a runbook can then be set to trigger when this ticket type/template is logged. This is recommended for longer running tasks.</p><p><br></p><p><strong><em>Note: When executing an asynchronous runbook the <<request>> variable will not contain chat data, as the runbook is triggered by a ticket, not the chat, the <<request>> variable will contain the ticket data. If you need data from the chat to be used within the runbook you will need to ensure chat data is being pulled into the ticket that triggers the runbook.</em></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Customise System Functions </span></strong></p><p>System functions can be added to a Conversational Agent as custom functions to allow you to customise when/how the system function is used. To do this you will need to disable all system functions for the Agent then add in each one back in as a custom function.</p><p><br></p><p>Disable system functions by unchecking 'Include all system functions' against the Agent. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJhNWJkYzNiLWI4NzctNDE5Ni04ZDgzLWExYzI5MTRlODIxMiJ9.ZXaI3SoIlQyR6w5V8DI2al6WV6yB1jFjLhBE_JHCwa0" class="fr-fic fr-fil fr-dib" width="860" style="width: 862px; height: 707.89px;" height="708"></p><p><strong><span style="font-size: 10pt;">Fig 14. Disable use of system functions</span></strong></p><p><br></p><p>Then you will need to add in the system functions that you would like agents/users to be able to use by adding the function as a custom function. </p><p><br></p><p>When adding a new custom function, the 'Use' field will now contain options for all the available system functions. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAzNjk1MWNjLTA2YWQtNGExNS1iNWFhLTc0OGFhNjhlMzEwNiJ9.3mM6E-mtP0sW7gYbhInC3obBnOmJSqfqHc6kFSnfyp8" class="fr-fic fr-fil fr-dib" width="525" style="width: 527px; height: 556.534px;" height="557"></p><p><strong><span style="font-size: 10pt;">Fig 15. System functions</span></strong></p><p><br></p><p>The name, description and access of the system function can be customised, allowing you to control when this function is executed. But other elements of the function cannot be customised. </p><p><br></p><p><strong>Description -</strong> Enter the prompt to be given to AI to instruct it when to use this function. </p><p><br></p><p data-pasted="true">From v2.244+ the search functions "Search Tickets" and "Search Knowledge Base", also allow you to filter which tickets and knowledge base articles can be returned by the search. This allows you to ensure only the tickets/articles relevant to the Conversation Agent's use are returned, for example for an Agent used in your portal chatbot you can restrict the Search Knowledge Base function to only return articles on user facing FAQ lists.</p><ul><li data-pasted="true">The 'Search Knowledge Base' Function can filter articles based on their FAQ list. </li><li data-pasted="true">The 'Search Tickets' function can filter tickets based on their Ticket Type, ITIL Type or Ticket Type Group.</li></ul><p>Now, only functions that have been added to the Conversation Agent as 'Custom Functions' will be able to be used by agents/users. </p><p><br></p><p data-pasted="true"><strong><span style="font-size: 14pt;">Restricting Function Access </span></strong></p><p>Access conditions can be configured for custom functions, allowing you to prevent the function from being used until prior conditions are met and control who can trigger the function. </p><p><br></p><p>Access conditions are set when configuring a custom function. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFlMTdmMDE5LWZkNGQtNGQ2OC05ZWUzLTk4NTVhNzYzYmUyMyJ9.FZ3ZpbXkbPvqUUaZzr8IvOyAB37-9fq6oNccgLQvwDU" class="fr-fic fr-fil fr-dib" width="546" style="width: 548px; height: 721.98px;" height="722"></p><p><strong><span style="font-size: 10pt;">Fig 16. Function Acccess</span></strong></p><p><br></p><p><strong>Allow anonymous Users to use this function -</strong> When enabled anonymous users (not logged into the portal) will be able to use this function. </p><p><strong>Allow authenticated Users to use this function -</strong> When enabled authenticated users (logged into the portal) will be able to use this function.</p><p><strong>Allow Agents to use this function - </strong>When enabled, agents can use this function. </p><p><br></p><p data-pasted="true">Access conditions are based on various fields in Halo, therefore you can restrict access to the function based on the value in a chosen field. </p><p><br></p><p>If a user/agent requests to execute a function that they do not have access to the conversational agent will run all evaluations for the function, then advise the user/agent that they cannot complete the request. </p><p><br></p><p><strong><span style="font-size: 14pt;">Custom Functions in Chat Profiles</span></strong></p><p>Custom functions can be added to a chat flow step to move the chat to another step or carry out an action on the step then move back to the conversational agent. This allows actions to be carried out in the chat that cannot be completed by the virtual agent, by having the agent move the chat to a step that carries out the required action, then returns to the conversational agent. </p><p><br></p><p>To set this up, add a custom function to the 'Custom Functions' table (found within a chat step). Here, you will need to give the function a name and set which step the chat will move to when this function is used. In order to use the custom function the function will need to be specified in the virtual agent instructions, this can either be under the instructions for the agent or the instructions at this chat flow step. We will work through an example on how to do this below. </p><p><br></p><p>In the below example I would like to add in the custom function to have the virtual agent walk me through logging a software request ticket. First I will add a new custom function to the step, I have called this 'new_software_request', when this function is used the chat flow will go to Step 2. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ2NGJiYjI2LTMwY2ItNDg5MC04OTM5LTgzZTA0M2ZhZTI2OCJ9.eIPELFOAjVCxFvHKkPYnSMRLmbmTrh1mfvtQvp1Xso4" class="fr-fic fr-fil fr-dib" width="541" style="width: 543px; height: 280.17px;" height="280"></p><p><strong><span style="font-size: 10pt;">Fig 18. Example add custom function to step</span></strong></p><p><br></p><p>Now I will specify when this function can be called in the 'Additional instructions', here I have instructed the conversational agent to use the function when it determines that the user wants some new software. However, you can provide it with more specific criteria. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ3Zjc5NTE2LWI5ZTYtNGYyZi1hNGNkLTdlMjI5MWQzM2YzMiJ9.yuJzdbFBFlQrOLL-vM24Qoj8fufu7qauWzS4Jwyb7Z8" class="fr-fic fr-fil fr-dib" width="747" height="368"></p><p><strong><span style="font-size: 10pt;">Fig 19. Example additional instructions for calling the custom function</span></strong></p><p><br></p><p>Now I will configure Step 2, this will determine what actually happens when the function is called. The step will complete a walkthrough of logging the ticket type 'Software request'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE5YWE2NmRmLTZkZjgtNDZiZi1iYjVkLWRjNjk3ZjNmMDBkOSJ9.TJ9hTa4J6w2GdgF-q8vWGC_W3LGwK-H6amdd9B_n5js" class="fr-fic fr-fil fr-dib" width="744" height="556"></p><p><strong><span style="font-size: 10pt;">Fig 20. Example step to complete ticket logging walkthrough</span></strong></p><p><br></p><p>I will then set the flow to send a message once the ticket is logged, then move back to the virtual agent chat. This allows the chat to continue without me having to configure more steps manually. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJmNmZmNmRjLThkNzctNDQ5NC1hNjFiLTAyN2ZmZDMxNmFlOSJ9.-V-10Sv0u5_JVb1kd7QjMk95y2DWcvw2lTLh-TS0XtE" class="fr-fic fr-fil fr-dib" width="881" height="675"></p><p><strong><span style="font-size: 10pt;">Fig 21. Example flow using virtual agent with custom function to log a ticket</span></strong></p><p><br></p><p>You can also use custom functions to have the bot flow move to another step if the AI service that the virtual agent uses errors. For example, you could move it to another step and have an agent manually complete a live chat as a backup option, or it could log a ticket so the agent can get back to the customer.</p><p><br></p><p>To do this set the "Step to move to if AI service is unavailable/errors" field when editing the step that uses the "Virtual Agent Conversation" action type, this single select dropdown will appear.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU5M2QxNWEyLWMwNTgtNDQ2OC1iMjY4LTMzMmUxMTA4MzhlMyJ9.nAhwPWcfsJqpWdHReTka73olowMQl1_H5t-xxAWAXrg" class="fr-fic fr-fil fr-dib" width="309" height="69"></p><p><strong><span style="font-size: 10pt;">Fig 22. Step to move to if AI service is unavailable/errors</span></strong></p><p><br></p><p><span style="font-size: 11pt;">For more information on configuring chat bot flows in general and the actions available, see our guide <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2335/" id="isPasted" target="_blank" rel="noopener noreferrer"><strong>here</strong></a>.</span></p><p><br></p><p><strong><span style="font-size: 14pt;">Worked Example - Custom Function Use Case - Have a Conversational Agent trigger a Runbook to complete a password reset </span></strong></p><p>In this example the conversational agent has been configured to allow a password reset to be executed automatically when users request a password reset from the a chat with a conversational agent. All the user will need to do is request a password reset and give the Agent their email address. </p><p><br></p><p><strong>Step 1 - Add Custom Function to Conversational Agent </strong></p><p>Navigate to Configuration > AI > AI Agents > Operations/Virtual Agents > select the Agent profile being used by the chatbot. Here, add a new custom function.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI5ZmM1M2EwLTU4YjgtNDQ2OC1hYTBkLWY2NGE4OTIwNGU1NSJ9.VfHjYVF9roTXhNqAiuYIPJPU6Kznei48KTcGQ8U6ekI" class="fr-fic fr-fil fr-dib" width="1243" style="width: 1245px; height: 713.883px;" height="714"></p><p><strong><span style="font-size: 10pt;">Fig 23. Add custom function</span></strong></p><p><br></p><p>Call the custom function something to represent the function being carried out, in this case re-setting the user's password. </p><p><br></p><p>In the description field enter instructions for the AI model, telling the model what this function is used for, when it should be executed, along with any conditions that need to be met for the runbook/function to run. </p><p><br></p><p>Set the use to be 'Execute a runbook'. Then select the runbook you have setup in your instance that completes the password re-set. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIxMmM3OWFkLTZjN2ItNGIyMy1iNjY3LWYzNmFhYTJmYjZiNCJ9._VkXeyha2tuCpKjLGy9wQW_nX5q0OJViW5MPV9lq1Bg" class="fr-fic fr-fil fr-dib" width="633" height="558"></p><p><strong><span style="font-size: 10pt;">Fig 24. Custom function configuration example</span></strong></p><p><br></p><p>In order for the password reset to be completed for the correct user, the user will need to give the Conversation Agent their email address, this can then be used when executing the runbook. Therefore a parameter for the user's email will need to be set. </p><p><br></p><p>Add a parameter to the custom function using the configuration shown in Figure 25. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQxNTI1OWMyLWY4OGEtNDM0NS04M2VkLTE0MzNiYTZlZTM2ZiJ9.nFYhedIaS-QSd1AFl48PpWd2kIt7nYa4J0dT5gc0o40" class="fr-fic fr-fil fr-dib" width="578" style="width: 580px; height: 491.541px;" height="492"></p><p><strong><span style="font-size: 10pt;">Fig 25. emailadress parameter against custom function</span></strong></p><p><br></p><p>The parameter has been called 'emailaddress' as this is the JSON name of the email address field in the API. </p><p><br></p><p>Save the custom function and the virtual agent. Now you can configure the runbook.</p><p><br></p><p><strong>Step 2- Runbook configuration </strong></p><p>Now navigate to the runbook you are executing in your Halo instance. </p><p><br></p><p>The first step of my runbook executes a sql query on my database to obtain the ID of the user based on the email address they provide. The variable <<request>> will contain the email address address data the user gives in the chat, however, this will return the whole JSON object. In order to use the given email address in my sql query I need the JSON value only. Therefore, I will create a new runbook level variable that obtains the JSON value only from the emailaddress parameter within the <<Request>> variable. </p><p><br></p><p>Add a new runbook level variable to the runbook. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM5YzUzNThiLTdiYzktNDM2NS05OTNmLTJkZjNmNjU1Zjg5OSJ9.7SbYW4pEwvjI-ckNavDTxqGmYaR3RnODo9DLfzCUFiA" class="fr-fic fr-fil fr-dib" width="1263" style="width: 1265px; height: 606.724px;" height="607"></p><p><strong><span style="font-size: 10pt;">Fig 26. Add new runbook level variable</span></strong></p><p><br></p><p>Add the variable as shown in Figure 27. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE2NjkyNDc3LTFiYmYtNGZlYS1hNzE0LWE0OTQ2YjZhNzMyNiJ9.4LpdAXIull1YlXIszgClhhT9ICFYhg_4GD3OGgo7NJo" class="fr-fic fr-fil fr-dib" width="1505" style="width: 1507px; height: 289.883px;" height="290"></p><p><strong><span style="font-size: 10pt;">Fig 27. email address variable</span></strong></p><p><br></p><p>Here, I have called the variable email address, therefore I will need to use <<email address>> to call the variable. </p><p><br></p><p>The value of the variable will be <<request^emailadress!>> as I want this to be the emailadress parameter that is stored within the <<request>> variable. An ! has been appended to the parameter to prevent ", if the variable value returns " this will interfere with my sql query. </p><p><br></p><p>Now I have defined a new variable I can use this in the method of my runbook. </p><p><br></p><p>I will add this variable to my sql query, this will populate a new variable (user_id) with the ID of the user based on the email address given. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijc4NWM0MTE5LWYwNjQtNGFkYy04M2RiLTI5Mjk4M2JkNTZiNiJ9.FWlbfm066SuoOv9iY_3yjwedKyQ0BwXbxvvBu7wJFPk" class="fr-fic fr-fil fr-dib" width="1223" style="width: 1225px; height: 748.699px;" height="749"></p><p><strong><span style="font-size: 10pt;">Fig 28. Runbook step to obtain user ID based on given email</span></strong></p><p><br></p><p>In the next step of the runbook I can use the variable user_id to execute the password reset against the correct user. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhlNGZkYzhiLTM5YjctNGQzMS1hMTg5LTllZDQ0NGE5MTdlNyJ9.osHr0JcDaIb-kOLmqTrmJdZosb8dnNE8hrpThdoe5xk" class="fr-fic fr-fil fr-dib" width="1275" style="width: 1277px; height: 642.244px;" height="642"></p><p><strong><span style="font-size: 10pt;">Fig 29. Execute password reset</span></strong></p><p><br></p><p><strong>Step 3 - Trigger custom function</strong></p><p>Now configuration is complete a user can trigger this custom function from a chat with a Conversation Agent. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZiZDRkMmUzLWJjYTAtNDBjMS05ZWUyLTBlN2QwYTAyM2RkYSJ9.__WkhblbN2nkQKTsGCDIlwrKtGOYZdngKAjs13pZGjU" class="fr-fic fr-fil fr-dib" width="337" height="569"></p><p><strong><span style="font-size: 10pt;">Fig 30. User triggering automated password reset from chat</span></strong></p>
