<style>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>
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>
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>
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><strong>- What are Virtual agents in Halo?</strong></p><p><strong>- Functions of Virtual Agents</strong></p><p><strong>- Using Virtual Agents</strong></p><p><strong>- Creating a new virtual Agent</strong></p><p><strong><span style="font-size: 11pt;">- </span></strong><span style="font-size: 11pt;"><strong>Plugging a Virtual Agent into a Chat Profile</strong></span></p><p><strong>- Custom Functions (against the chat profile)</strong></p><p id="isPasted"><strong>- Customising Virtual Agent functions </strong></p><p><strong>- Disable System functions</strong></p><p><strong>- Restrict Function Access (for virtual agent custom functions)</strong></p><p><strong>- External MCP Connection (v2.236+)</strong></p><p><br></p><p><br></p><p><br></p><p><br></p><p><strong>Related Guides:</strong></p><ul><li><strong><a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2335" id="isPasted" target="_blank" rel="noopener noreferrer">Chat Bot and Chat Profiles</a></strong></li></ul><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">What are Virtual Agents in Halo?</span></strong></p><p id="isPasted">Virtual Agents can be used in conjunction with the <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2335/" id="isPasted" target="_blank" rel="noopener noreferrer"><strong>Chat Bot</strong></a>, allowing a user to converse with a 'virtual agent' within the chat. They use AI technology to return information and carry out actions based on a user's input, making the chat profile much easier/quicker to set up as the virtual agent uses AI to determine what information the user would like based on their input, rather than having to create pre-configured steps.</p><p><br></p><p>There are various functions virtual 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 virtual agent to use these. </p><p><br></p><p>Tickets, actions, and Knowledge Base Articles created by a Virtual Agent will be "flagged" as AI in reporting under the columns: faicreated, aacreated, and kbaicreated. The ID of the Virtual Agent that was used to create the entity can also be identified using the following fields: fvirtualagentid, avirtualagentid, and kbvirtualagentid. This will correlate to the ID in the VirtualAgent table.</p><p><br></p><p><strong><span style="font-size: 14pt;">Functions of Virtual Agents</span></strong></p><p><strong><span style="font-size: 12pt;">Functions for users</span></strong></p><p>The following functions can be carried out by the virtual agent, these are beneficial for end users. </p><p><br></p><ul><li id="isPasted"><strong>Knowledge search (get_knowledge):</strong> The 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".</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><span style="color: rgb(0, 0, 0);">The following functions that can be carried out by the virtual agent are beneficial for agents, assisting them in resolving tickets. These are only available when using a virtual agent set to have 'Agent App Virtual Agent' as it's use:</span></p><p><br></p><ul><li><strong>Searching the Knowledge base (using AI search)</strong><strong>: </strong>The virtual 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 virtual 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 virtual agent can return a list of tickets that are assigned to the agent. </li><li><strong>Searching tickets (using AI search) (search_tickets):</strong> The virtual 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 virtual agent can return details of a specific ticket, allowing agents to complete quick comparisons between tickets. </li><li><strong>Adding a private note to a ticket (add_note_to_ticket):</strong> The virtual 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 virtual 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 virtual 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 virtual 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 virtual 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 virtual 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 virtual 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 virtual 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 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></ul><p>All the above functionalities come pre-configured out-of-the-box, except the knowledge base search functionality, you will need to set this up. </p><p><br></p><p><span style="color: rgb(0, 0, 0);"><strong><span style="font-size: 12pt;">Using AI knowledge search</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 virtual 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);">Virtual 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. </span></p><p><span style="color: rgb(0, 0, 0);"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJiNGE4MTE5LTgzYWItNDY1OS1hYTcyLTZlMzI1ZWYyM2E2ZCJ9.0dJ1o0flVj1OpD3fOxTCz2UMxeqj5SatYBsL-rOqzXE" class="fr-fic fr-fil fr-dib" width="806" style="width: 808px; height: 464.485px;" height="464"></span></p><p><strong><span style="font-size: 10pt;">Fig 1. Setting up Azure 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;">Have the Virtual Agent Transfer to Live Chat</span></strong></p><p>Once 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><strong><span style="font-size: 14pt;">Using Virtual Agents</span></strong></p><p><strong><span style="font-size: 12pt;">Out-of-the-box agents </span></strong></p><p>As the virtual agent functionality uses AI you will need to have the AI module enabled and a default AI connection set (and connected). The virtual agent will still work without this enabled but functionality will be limited. To set a default connection head to Configuration > AI > 'Default AI Connection'. </p><p><br></p><p>Hosted customers will have some pre-configured virtual agents in their instance already. These each have their own use cases and require minimal setup. These agents use the built in OpenAI connection (regardless of the AI connection you have configured under Configuration> AI), by using them you agree to your data being sent to Halo's OpenAI instance, nothing is trained on and the data is removed after the chat ends. If using your own connection, data will be stored out with Halo. To see the virtual agents you have available in your Halo head to Configuration > Chat > Virtual Agents. </p><p><br></p><p><strong>Halo Agent App Default Virtual Agent v1</strong>- This virtual agent is used for agent app chats, in which an agent can ask the virtual agent questions, for information and to carry out actions to assist them in resolving tickets. </p><p><br></p><p><strong>Halo Chat Default Virtual Agent v1</strong> - This virtual agent is used for end user chats, in which end users can ask the virtual agent questions, for information and to carry out actions to improve customer service and accessibility.</p><p> </p><p><strong>Halo Documentation Virtual Agent v1</strong> - This virtual agent is used for agent app chats, to guide Halo administrators in how to use Halo. Agents can ask this virtual agent questions about Halo as a platform and they will be provided with information or recommended a knowledge base article(s) to read. </p><p><br></p><p>Under the configuration for each of these agents you will see an 'Instructions' field, which contains the prompt for the AI model to use for this virtual agent. The out-of-the-box agent prompts cannot be changed, but if you would like to customise the prompt you can create your own new virtual agent. </p><p><br></p><p><strong><span style="font-size: 12pt;">Data Retention when using the default Virtual Agents</span></strong></p><p>By using the default virtual agents (outlined above) you agree to your data being sent to Halo's OpenAI instance. Whether data is retained by OpenAI will depend on if the user using the virtual agent is authenticated. </p><p><br></p><p><strong>Authenticated Users</strong></p><p>Zero data will be retained by OpenAI for authenticated users using the virtual agent. Users can be authenticated either by logging into the self service portal or using "<a href="https://usehalo.com/haloitsm/guides/1842/#enable_user_matching" target="_blank" rel="noopener noreferrer">Embeddable Chat User Matching</a>" when a chat is embedded on another site. </p><p><br></p><p><strong>Unauthenticated Users</strong></p><p>When unauthenticated users are using the virtual agent, either when users are not logged into your Halo portal, or when the chat is embedded on another site, data will be retained temporarily. OpenAI will hold this data for 30 days for usage monitoring purposes. This data will not be used to train models. This is in line with OpenAI's zero data retention policy <a href="https://developers.openai.com/api/docs/guides/your-data#data-retention-controls-for-abuse-monitoring" target="_blank" rel="noopener noreferrer">here</a>. </p><p><br></p><p><strong><em>Note: If you are creating your own virtual agent with your own connection this will not apply, data will be retained based on how your project is configured. </em></strong></p><p><br></p><p><span style="font-size: 14pt;"><strong>Creating a New Virtual Agent</strong></span></p><p>You may want to create your own virtual agent if you would like to customise the connection method or prompt the virtual agent uses. </p><p><br></p><p>To create a new virtual agent head to Configuration > Chat > Virtual Agents > New. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjMTc1Mzg1LWM4NmQtNDIxNS05N2IzLTk5ZTcyMjIwNmE1ZiJ9.m_erjJyyCE7wnqVpjNFOx91opKHPSzmiA61lQV7gKNw" class="fr-fic fr-fil fr-dib" width="984" style="width: 986px; height: 700.203px;" height="700"></p><p><strong><span style="font-size: 10pt;">Fig 4. New Virtual agent setup screen</span></strong></p><p><br></p><p>Here, give the agent a name and set the use. The 'Use' field determines where the virtual agent can be used. Setting the use to be 'End-user chat' will result in this agent only being able to be used within self-service portal chat profiles. Setting the use to be 'Agent App virtual agent' will result in the virtual agent only being able to be used within agent app chat profiles. </p><p><br></p><p>Now you will need to select a connection method from OpenAI, Azure OpenAI, or (As of v2.236+) the built in OpenAI connection. Once a connection is selected an additional button will appear to 'Configure ... connection', select this to bring up the connection page. Here, you will need to complete the details required for connection, only once this is completed successfully will the virtual agent be able to use AI functionality. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBlNmUyMzgyLTJjNWMtNDI0NC1hYTBjLTgyMjMwYzdkMzg2OCJ9.Vdd_5gOgj5ns-H0HuZZHHM3tS-lDon9IE7TVcjbpCNE" class="fr-fic fr-fil fr-dib" width="435" height="237"></p><p><strong><span style="font-size: 10pt;">Fig 5. Configure connection for virtual agent</span></strong></p><p><br></p><p><strong><em>Note: If connecting using Azure OpenAI you will need to be on version 2024-02-15 or higher. </em></strong></p><p><br></p><p>Once connected under the 'Assistant Fields' section of the setup page you will need to enter the Model/Deployment you are using within the chosen AI model. Then complete the 'Instructions' field.</p><p><br></p><p>You will also find a "Temperature" field in this section. The value given here will determine how focused the response will be. Higher values like 1 will make the output more random, using a more creative approach, while lower values like 0.2 will make it more focused and consistent. The default value is 1 which remains in line with behaviour before the update. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA5MWMxNDA2LTc0ZDAtNDdkOS1iZmVhLWRhNGQzNTc4YmRmNCJ9.3Xqe0HbUwKao8174qSW4An9MytIK3tCvuuJufhN7uG4" class="fr-fic fr-fil fr-dib" width="1320" style="width: 1322px; height: 393.713px;" height="394"></p><p><strong><span style="font-size: 10pt;">Fig 6. Assistant fields (for OpenAI connection)</span></strong></p><p><br></p><p>The 'Instructions' field should contain a prompt for the AI model to use within this virtual agent. This should include information like: what context is the model being used in, who is using this, what tasks the model is expected to carry out, the more information you provide here, the more accurate the virtual agent chat will be.<span style="color: rgb(250, 197, 28);"> </span><span style="color: rgb(0, 0, 0);">If you would like the agent to function similarly to an out-of-the-box agent, but with some amendments, you can copy and paste the instructions from an existing agent into your new agent then make the required changes. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);"><em><strong>Note: The "Instructions" field does not have any character limit in itself, but will follow any character limit from the OpenAI model you use.</strong></em></span></p><p><br></p><p data-pasted="true"><strong><span style="font-size: 12pt;">Open AI's Deprecation of the Assistants API/Responses API</span></strong></p><p>If connecting using OpenAI, you will have an additional option to choose which API to use.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQxM2VmNzE4LTg3MTQtNDU0NS04YzBmLWZhZTJkMDJkMjA2NiJ9.bLxN8mP5DiewrxmjynspkLawBbnUsPD8UyhAea7nupw" class="fr-fic fr-fil fr-dib" width="893" style="width: 895px; height: 593.806px;" height="594"></p><p><strong><span style="font-size: 10pt;">Fig 7. Connecting to OpenAI using the Responses API</span></strong></p><p><br></p><p data-pasted="true">Open AI are deprecating the Assistants API from August 2026, therefore new virtual agents should be setup using the Responses API. Existing virtual agents will be automatically migrated to use the Responses API closer to the deprecation date. </p><p><br></p><p>If connecting using the Responses API you will have an additional option to provide a prompt ID for the virtual agent.</p><p><br></p><p><strong>Prompt ID -</strong> Here, enter the ID of the prompt you would like to provide the AI model when this virtual agent is used. This will need to be the ID of a prompt saved within your OpenAI account. The instructions and model should be stored inside the prompt, therefore when this is used you do not need to populate the "Model/Deployment" and "Instructions" field. Using a prompt will reduce the size of the request sent to OpenAI which can be more cost effective. </p><p><br></p><p><strong><span style="font-size: 12pt;">Allow Functions for the Virtual Agent</span></strong></p><p>Once you have configured the connection for the virtual agent you can set which functions the agent can use. If you would like the agent to be able to use all available functions enable "Include all system functions". </p><p><br></p><p>If you would like to restrict the functions available you can either, disable this and add each allowed function as a 'custom function' (covered in the 'Customising Virtual Agent functions' section of this guide), or provide strict instructions in the prompt to not carry out specified functions. </p><p><br></p><p><span style="color: rgb(0, 0, 0);"><strong><span style="font-size: 12pt;">Upload attachments to Tickets via Virtual Agents</span></strong></span></p><p><span style="color: rgb(0, 0, 0);">If you would like users/agents to be able to upload attachments to tickets from the virtual agent chat you will need to add some additional instructions to your virtual agent. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);">Out-of-the box virtual agents (that use our built-in AI connection) cannot have their instructions edited, therefore this functionality works best when configuring your own virtual agent with your own AI connection. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);">For users/agents to be able to upload attachments from the chat the attachment button need to be made available to them (this is not available at all times). For this to become available the virtual agent will need to execute the function <em>allow_attachment_upload </em>this function must be executed before asking the user for attachments, otherwise they will not be able to upload an attachment. Once the function <em>allow_attachment_upload </em>is executed the user will be able to upload one attachment, in order for them to upload additional attachments the function must be executed again. Therefore, you must give additional instructions to your virtual agent that instruct when to execute the function <em>allow_attachment_upload </em>as this will determine when users can upload attachments from the chat. </span></p><p><br></p><p><span style="color: rgb(0, 0, 0);">The instruction you give the virtual agent will vary based on when you would like users to upload attachments, however, an example instruction is give below:</span></p><p><br></p><p style="margin-left: 20px;"><span style="color: rgb(0, 0, 0);"><em>You must invoke allow_attachment_upload before you ask for supporting attachments/files such as images, screenshots, documents, or logs. Call this proactively before asking for such details, even if the user hasn’t mentioned attachments. Also, invoke allow_attachment_upload whenever you mention attachments so that the user can actually upload an attachment. Examples include logging an incident, troubleshooting an issue, or analysing a situation where visuals or additional data could clarify the user’s input. If you identify a user wants to upload an attachment to a ticket invoke allow_attachment_upload then prompt them to upload their attachment. </em></span></p><p><br></p><p><span style="color: rgb(0, 0, 0);"><em><strong>Note: This will need to be added in addition to your existing virtual agent instruction. </strong></em></span><strong><em><br></em></strong></p><p><br></p><p>Now, when the user logs a ticket the chat will ask if they would like to upload an attachment. The user can upload their attachment to the chat, and the virtual agent will attach this to the associated ticket. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIyYTA1YzA2LWMyNjItNDJkMy1iNjFkLWExMzY2NDkyZTAyOCJ9.vKInZSzEC8w5qZ4eAsgd8mPnSYndQDOGoQume_Xiwto" class="fr-fic fr-fil fr-dib" width="344" height="539"><strong><span style="font-size: 10pt;">Fig 8. User uploading attachment to ticket via virtual agent chat</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Plugging a Virtual Agent into a Chat Profile</span></strong></p><p>Once you are happy with the virtual agent you have set up you can plug this into a chat profile for your agents/users to use. </p><p><br></p><p>To do this head to Configuration > Chat > Chat profiles > New > Bot Flow tab. Here a new step will automatically appear, set the step type to be 'Virtual Agent conversation', once selected you will be able to choose which virtual agent is used within this chat. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY2MjBiMGY5LWQzMzMtNGVhNC1iNGIwLWE1MjM3Yzk3MjJiMSJ9.oqQC8cFPToMQ_dpWSBCAZZfEHPv1IU_7BivQjTW6dgI" class="fr-fic fr-fil fr-dib" width="953" style="width: 955px; height: 505.81px;" height="506"></p><p><strong><span style="font-size: 10pt;">Fig 9. Configuring Chat step for virtual agent</span></strong></p><p><br></p><p>You will also be able to provide an additional prompt/instructions for the virtual agent at this step. This allows you to provide step, specific prompts, so you can have general virtual agents that can be more specialised per chat profile step. </p><p><br></p><p>You will also need to enter an 'AI Failure Message', this message will display to the user if the AI response fails. </p><p><br></p><p>You will need to specify what team the user will be transferred to if the virtual agent is prompted to start a live chat with a human agent. You can also specify what ticket type or template is used when the user requests to log a ticket, if the user/agent specifies a particular ticket type/template they would like to log this will override what is set here. </p><p><br></p><p><strong>Message Suggestions</strong> - Here, you can configure pre-set message suggestions for the user to use within a set context of the chat. These will give the user set options they can choose from, once selected the virtual agent will be given a set prompt. This provides your users an easy way to give the agent complex prompts. </p><p><br></p><ul><li>Context - This determines when the suggestions appear, 'viewing a ticket' will only show this suggestion when the user is viewing a ticket. 'Anywhere else' will show this suggestion at all stages of the chat. </li><li>Prompt text - This is the suggestion text that the user will see and can select</li><li>Message text - This is the text that will be posted into the chat, the virtual agent will provide a response based on this text. </li></ul><p>You can also configure criteria for message suggestions in the "Context" of "Viewing a Ticket". This allows you to filter which suggestions can be used based on properties of the ticket. If configured, all criteria will need to be met for the suggestion to appear. </p><p><br></p><p>In the <strong>Fig 10 </strong>example, when a user is viewing a ticket an option will appear on screen called 'Summarise #XXX'. When selected the virtual agent will be asked to return a summary of the ticket ($-faultid). Another option will also appear called "Suggest a resolution for this ticket", but this will only appear if set criteria is met. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImExZDg5Mzk5LTQ3YjItNGUzYy05ODdiLWJhYWFkMTc3NjUyYSJ9.KoCQeGWR1OHgvb2sdYfGkrt85-sgvGkGkxrhhIUQQp4" class="fr-fic fr-fil fr-dib" width="1507" height="327"></p><p><strong><span style="font-size: 10pt;">Fig 10. Example message suggestion </span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Custom Functions against the Chat Profile</span></strong></p><p>Custom functions can be used to move the chat to another step, carry out an action on the step then move back to the virtual agent. This allows you to complete actions that cannot be completed by the virtual 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>From v2.232+, AI abilities can be added as custom functions. For more information on how to use AI Abilities please see our guide linked <a href="https://usehalo.com/haloitsm/guides/2776" target="_blank" rel="noopener noreferrer">here</a>. </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 11. 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 virtual 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 12. 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 13. 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 14. Example flow using virtual agent with custom function to log a ticket</span></strong></p><p><br></p><p>You also 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>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 15. 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 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;">Customising Virtual Agent functions</span></strong></p><p>Custom functions can be configured against a virtual agent, to allow the user to complete the following from a virtual agent chat: </p><p><br></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></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 request. </p><p><br></p><p>This feature is available for both End-User and Agent Virtual Agents. <strong>Function customisation is only available for Virtual Agents connected to your own OpenAI or Azure OpenAI instance,</strong> so this cannot be used in built-in Virtual Agents. 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>.</p><p><br></p><p><strong><span style="font-size: 12pt;">Use custom functions to log a ticket </span></strong></p><p>Custom functions can be configured against a virtual 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 custom functions 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 head to a virtual agent (or create a new virtual agent) in your instance. Against the agent profile here you will see the 'Functions' section, here you can add new custom functions. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU1ZjNhM2EyLTliMTUtNGMyMi05MmQxLWI0MTI3YjViMmZhNCJ9.91cTDq6inN-Qs-JTGBQRAFzAOF4zyqoifE85MKY90DI" class="fr-fic fr-fil fr-dib" width="1238" style="width: 1240px; height: 664.202px;" height="664"></p><p><strong><span style="font-size: 10pt;">Fig 16. Add function to virtual agent</span></strong></p><p><br></p><p>When adding a function you will see the pop-up shown in figure 17. </p><p><br></p><p><em><strong>Note: The "Description" field here has a character limit of 1000.</strong></em></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM0YTU2OWFlLTliYWItNDkzOS1iNTY3LWU4Y2E1ZDM4MmVkYSJ9.pQN6DVi0VMYrcBVmig5MQplPzECZq5x98xhRTRRuxk4" class="fr-fic fr-fil fr-dib" width="505" style="width: 507px; height: 673.901px;" height="674"></p><p><strong><span style="font-size: 10pt;">Fig 17. Custom function configuration</span></strong></p><p><br></p><p><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. T<span style="color: rgb(0, 0, 0);">his will determine when the virtual agent executes this function. </span></p><p><strong>Use</strong>- Here enter what you would like this function to do. You will need to choose 'Create New ticket'. You can then choose which ticket type or template this function will log. </p><p><br></p><p>In the figure 16 example the virtual 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 18. Function to log specified ticket type</span></strong></p><p><br></p><p>Now when the user asks the chat for new hardware, the virtual agent will execute this function, logging a ticket for this request. </p><p><br></p><p><strong><span style="font-size: 12pt;">Use custom functions to upload attachments via the virtual agent</span></strong></p><p>Attachments can be given to the virtual 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: The virtual agent cannot read attachments, only upload given attachments to tickets. </em></strong></p><p><br></p><p>You must set up a custom function against your virtual agent to use this functionality. This is because attachment uploads are not available at any point in the chat conversation, the virtual agent will need to make attachment upload available for the user before attachments can be uploaded. The custom function will control when the virtual agent makes attachment upload available.</p><p><br></p><p>To configure this functionality head into your virtual agent and disable 'Include all system functions'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkODZlMDViLTY2ZmUtNGRhYy1iYjA0LWY2Mzg3MzVjYTk5ZiJ9._buGpGR3H1opoY37GoccuNLhBoL59acIRKKoHqBem5M" class="fr-fic fr-fil fr-dib" width="402" height="163"></p><p><strong><span style="font-size: 10pt;">Fig 19. Include all system functions</span></strong></p><p><br></p><p>This needs to be disabled in order to configure the attachment upload function. As this is disabled this means any other system functions that you would like to be available will need to added in as a custom function. System functions can be added as custom functions by choosing one of the system uses in the 'Use' field. </p><p><br></p><p>Now add a new custom function give it a name (like Add_attachment) and set the 'Use' to be 'Allow attachment upload'. Now you will need to set a description for the function. </p><p><br></p><p>The description should tell the virtual 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 description 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 virtual agent to ask for attachments. </p><p><br></p><p style="margin-left: 20px;"><em>''You must invoke allow_attachment_upload before you ask for supporting attachments/files such as images, screenshots, documents, or logs. Call this proactively before asking for such details, even if the user hasn’t mentioned attachments. Also, invoke allow_attachment_upload whenever you mention attachments so that the user can actually upload an attachment. Examples include logging an incident, troubleshooting an issue, or analyzing a situation where visuals or additional data could clarify the user’s input.'</em></p><p><br></p><p><em><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjgxMmI0NGM1LTUzMzctNGVkZi04ZDUyLWNlZTVlMTZkZmUwYiJ9.hHKQDKSGWX2SOW13U2rTkKUo1UbVWQw63j9JxZBfpPY" class="fr-fic fr-fil fr-dib" width="471" style="width: 473px; height: 668.697px;" height="669"></em></p><p><strong><span style="font-size: 10pt;">Fig 20. Custom function to allow attachment upload</span></strong></p><p><em><br></em></p><p>Then you will need to add additional instructions to the virtual agent instructions to instruct it when to execute this custom function i.e. when to allow users to upload attachments. An example instruction can be found below but again this will need to be adjusted in line with when you would like users to be able to upload attachments. </p><p><br></p><p style="margin-left: 20px;"><em>'You must invoke allow_attachment_upload before you ask the user to provide attachments/files such as images, screenshots, documents, or logs. If you identify the user would like to upload an attachment invoke CF_add_attachment.'</em></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>This is also the case for the new search function. With 'Include all system functions' disabled you will be able to set the use to 'search tickets'. Once set you will have the option to 'Use Semantic Search'. Selecting this will allow the Virtual Agent to complete a text search in Halo.</p><p><br></p><p><strong><span style="font-size: 12pt;">Use custom functions to obtain report data</span></strong></p><p>Custom functions can be can be configured against a virtual agent to have the Agent get data from a chosen report. Once the virtual agent has this data the virtual agent 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 chat 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 virtual agent. When adding a custom function you will see the pop-up shown in figure 17 </p><p><br></p><p id="isPasted"><strong>Name - </strong>Here, enter the name of the function. This string/command will be used in the prompt given to the AI model to tell it when this function should be executed.<strong> </strong></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 virtual agent executes this function. </p><p><strong>Use</strong>- Here enter what you would like this function to do. You will need to choose 'Get Report Data. You can then choose which report to run. </p><p><br></p><p>In the figure 21 example, a custom function has been added to have the virtual 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 21. 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 22. 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;">Use custom functions to execute an automation Runbook</span></strong></p><p id="isPasted">Custom functions can be configured against a virtual agent to trigger a runbook. 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 Virtual agent will fill in based on the conversation with the user. 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 virtual agent (shown in figure 16). </p><p><br></p><p>When adding a function you will see the pop-up shown in figure 22. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM0YTU2OWFlLTliYWItNDkzOS1iNTY3LWU4Y2E1ZDM4MmVkYSJ9.pQN6DVi0VMYrcBVmig5MQplPzECZq5x98xhRTRRuxk4" class="fr-fic fr-fil fr-dib" width="505" style="width: 507px; height: 673.901px;" height="674"></p><p><strong><span style="font-size: 10pt;">Fig 23. Custom function configuration</span></strong></p><p><br></p><p><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. T<span style="color: rgb(0, 0, 0);">his will determine when the virtual agent executes this function. </span></p><p><strong>Use</strong>- Here enter what you would like this function to do. You will need to choose 'Execute a Runbook'. You can then choose which runbook to execute. </p><p><br></p><p>In the figure 24 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 24. 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 25. 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 26 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 26. 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 27. 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 27 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><strong><span style="font-size: 12pt;">Worked Example - Have virtual agent trigger a runbook to complete a password reset </span></strong></p><p>In this example the virtual agent has been configured to allow a password reset to be executed automatically when users request a password reset from the virtual agent chat. All the user will need to do is request a password reset and give the chat their email address. </p><p><br></p><p><strong>Step 1 - Add Custom Function to virtual Agent </strong></p><p>Navigate to configuration > chat > virtual agents > select the virtual agent profile. 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 28. 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 29. 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 chat/virtual 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 27. </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 30. 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 31. Add new runbook level variable</span></strong></p><p><br></p><p>Add the variable as shown in figure 32. </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 32. 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 33. 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 34. 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 virtual 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 35. User triggering automated password reset from chat</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">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;">Disable System functions</span></strong></p><p>The system functions that the virtual agent can execute are outlined in the 'Functions of Virtual Agents' section of this guide. These will be available to all agents/users by default but they can be disabled per virtual agent. </p><p><br></p><p>Disable system functions by unchecking 'Include all system functions' against the Virtual 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 36. 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 be populated with all 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 37. System functions</span></strong></p><p><br></p><p>The name and description 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>Now, only functions that have been added to the virtual agent as 'Custom Functions' will be able to be used by agents/users. </p><p><br></p><p><strong><span style="font-size: 14pt;">Restrict Function Access (for virtual agent custom functions)</span></strong></p><p id="isPasted">You can control which users/agents can use a function by configuring the "Function Access" within the Function. This allows you to prevent access to a runbook or logging a ticket with a specific type based on the user. </p><p><br></p><p>The options available here allow you to disable anonymous users, authenticated users, or agents from accessing the function, and allow you to add a set of conditions. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBlZTI4MzVhLWE2MDUtNGI1MC04MDM4LTkyMGY1NTQzNzg4OSJ9.ZbP05nmdrIF1LLO1N4tthS_IKGDUlWYlKeZ1rkW_-Vg" class="fr-fic fr-fil fr-dib" width="575" height="413"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 38. Function access settings against custom function</span></strong></p><p><br></p><p>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 virtual agent will run all evaluations for the function, then advise the user/agent that they cannot complete the request. </p><p><br></p><p data-pasted="true"><span style="font-size: 14pt;"><strong>External MCP Connection (v2.236+)</strong></span></p><p>Virtual Agents using the API type "responses" can connect to third-party MCP servers. This allows the AI to call external tools for other applications. For information on setting up the connection, see the guide linked <a href="https://usehalo.com/haloitsm/guides/2597" target="_blank" rel="noopener noreferrer">here</a>. </p><p>Once you have configured your connection you will be able to add it to your Virtual Agent using the "External MCP Servers dropdown.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA0M2YzNzQ4LTk3NjAtNDI2MS1hM2M0LTY4MDU1NzAyZmE3MSJ9.fXBXSD_MyN7OkklisFlTS-ixgOiTkT9PoSRUDTfhWDw" class="fr-fic fr-fil fr-dib" width="833" style="width: 835px; height: 97.3313px;" height="97"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 39. External MCP connection</span></strong></p><p><br></p>
