<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><span style="font-size: 11pt;"><strong>In this guide we will cover:</strong></span></p><p><span style="font-size: 11pt;"><strong>- Overview</strong></span></p><p><span style="font-size: 11pt;"><strong>- Setup Process For Halo MCP AI Agent</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>- Data Sources report</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>- AI Run Report Runbook</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>- AI Agent</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>- Run Chat Agent Runbook</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>- HaloAI Agent Chat Profile</strong></span></p><p><span style="font-size: 11pt;"><strong>- The ChatBot In Action</strong></span></p><p><span style="font-size: 11pt;"><strong>- What Can The Agent Achieve & Return?</strong></span></p><p><span style="font-size: 11pt;"><strong><br></strong></span></p><p><span style="font-size: 11pt;"><strong>Related Guides:</strong></span></p><ul><li style="font-size: 11pt; font-weight: bold;"><strong><a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer" style="font-weight: bold; font-size: 11pt;">AI Agents</a></strong></li><li style="font-size: 11pt; font-weight: bold;"><strong><a href="https://www.usehalo.com/guides/1630" target="_blank" rel="noopener noreferrer" style="font-weight: bold; font-size: 11pt;">Custom Integrations/Runbooks</a></strong></li><li style="font-size: 11pt; font-weight: bold;"><a href="https://www.usehalo.com/guides/2335" target="_blank" rel="noopener noreferrer" style="font-weight: bold; font-size: 11pt;"><strong>Chat Bot and Chat Profiles</strong></a></li></ul><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 14pt;"><strong>Overview</strong></span></p><p data-pasted="true"><span style="font-size: 11pt;">When using the ChatBot, Halo's MCP server can be leveraged by AI Agents in order to evaluate your data and carry out actions within your Halo environment. As an example, this can be useful for obtaining quick data on your team and checking in on your profit and loss figures, or quickly checking off action points without having to leave your current page. </span></p><p><span style="font-size: 11pt;"><br style="box-sizing: inherit;"></span></p><p><span style="font-size: 11pt;"><strong>This guide is a walk-through for setting up this chat functionality from scratch in environments deployed <u>before</u> July 1st 2026.</strong> If your Halo environment was deployed on July 1st 2026 or later, then this functionality is largely pre-configured in your environment and you should instead use the following guide for the small amount of setup required: <a href="https://www.usehalo.com/guides/2875" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">Using the Halo MCP AI Agent Chat</a>.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">As this functionality utilises the <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">AI Agent</a> functionality, you do not need to plug in your own AI connection for it to function and you can use the default Halo connection if you wish to do so. </span></p><p><span style="font-size: 11pt;"><br style="box-sizing: inherit;"></span></p><p><span style="font-size: 11pt;"><strong>How does it work?</strong></span></p><p><span style="font-size: 11pt;">Within the "HaloAI Agent" chat profile, there is a step to execute the "Run Chat Agent" runbook. When this runbook is triggered, a pre-configured <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">AI Agent</a> is prompted to get data or suggest actions relevant to the Agent's request. </span></p><p><span style="font-size: 11pt;"><br style="box-sizing: inherit;"></span></p><p><span style="font-size: 11pt;">In the event that the chat user requests any information regarding Tickets, the AI Agent will trigger an additional runbook called "AI Run Report". This allows it to efficiently query the database, using a payload chosen by the AI Agent, and return accurate Ticketing data to the chat user. </span></p><p><span style="font-size: 11pt;"><br style="box-sizing: inherit;"></span></p><p><span style="font-size: 11pt;"><strong><em>Note: When utilising the MCP endpoint in Halo, it is advisable to enable the logs for this by navigating to Configuration > AI > Halo MCP Server and turning on the setting "enable MCP request logging". This will aid with any necessary troubleshooting.</em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 14pt;"><strong>Setup Process For Halo MCP AI Agent</strong></span></p><p><span style="font-size: 12pt;"><strong>Data Sources Report</strong></span></p><p><span style="font-size: 11pt;">A function that you will see the AI Agent perform is getting and returning Ticket data to the chat - this is now achieved by the AI Agent utilising the reporting endpoint. </span></p><p><span style="font-size: 11pt;">To facilitate this, the AI Agent needs access to the 'Data Sources' report to gather all relevant data sources for ticketing and decide which is the correct one. This report needs to be downloaded to your Halo environment from the reporting online repository. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">To do this, click into the reporting area in the navigation menu and select 'Online Repository'. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBkZDAyNjhiLWFmYmEtNDQ2OC1hYzc3LTI2NGVjOGQ4ZTg2ZCJ9.IzkXWF0VDdXwtxR_YBRnFMYkUoKcQ_sry4l_WBZWdY4" class="fr-fic fr-fil fr-dib" width="1021" style="width: 1023px; height: 640.751px;" height="641"></span></p><p><span style="font-size: 10pt;"><strong>Fig 1. Navigating to the reporting online repository</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Search for and select the "Data Sources" report, then select the option to "add this report to my library". </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAyZDEwZmEyLTdiOGMtNGRkZS1iY2E1LWMxYzZlNTZkNGUyZSJ9.8LGEeUOtudKI6oWzmjX6tQVuGlSiTPOXySjHtlUbJgc" class="fr-fic fr-fil fr-dib" width="1008" style="width: 1010px; height: 634.908px;" height="635"></span></p><p><span style="font-size: 10pt;"><strong>Fig 2. Downloading the data sources report to your local Halo environment</strong></span></p><p><br></p><p><span style="font-size: 11pt;"><span style="font-size: 11pt;" data-pasted="true">Once your data sources report has been downloaded into your Halo, you then need to download the runbook which the AI Agent triggers once it has used its chosen data source to construct its report for the chat user.</span></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 12pt;"><strong>AI Run Report Runbook</strong></span></p><p><span style="font-size: 11pt;"><strong>Import The Runbook</strong></span></p><p><span style="font-size: 11pt;">To do this, we have attached the JSON for the runbook. Download the "AI Run Report Runbook JSON" attached file </span><span style="font-size: 11pt;"><a href="https://support.haloservicedesk.com/portal/kb?btn=46&id=2876" target="_blank" rel="noopener noreferrer">from this article on our Porta</a></span><span style="font-size: 11pt;">l, and copy all of the JSON contained within the file.</span></p><p><span style="font-size: 11pt;">Go to the runbooks area in your Halo by navigating to Configuration > Integrations > Custom Integrations > Integration Runbooks and select the "Import from JSON" button in the top right corner. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU2MDJlMGU2LTZjMDQtNDQ2NC04NjAxLTJjZGI3MTQ1ODc0YiJ9.419YYRpiywk4bEDBwlRgYK1iCi5PDm_n4lyJAEkH3D8" class="fr-fic fr-fil fr-dib" width="954" style="width: 956px; height: 765.061px;" height="765"></span></p><p><span style="font-size: 10pt;"><strong>Fig 3. The Import from JSON button to import a new runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Selecting this button will bring up a modal screen into which you can paste the JSON that you copied. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhODY3YjBiLWQ0ODItNDU5MS05YWY2LWJhMjA0YTU2ZThhMSJ9.Ob4AO4O4-VTXIZesePbKkJ64d-IBL0JypgD5hIqgvcw" class="fr-fic fr-fil fr-dib" width="798" style="width: 800px; height: 471.194px;" height="471"></span></p><p><span style="font-size: 10pt;"><strong>Fig 4. Importing the JSON for the AI Run Report runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Paste the entire JSON body into the field and save, the runbook will then automatically appear in the list of runbooks in your Halo. </span></p><p><br></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImEzM2Q4ODhkLTQ1MDMtNDQwMC04MjZhLTNkYjQ4NjliMGZhMyJ9.MyT3cHCll__JKrWkBokT1QV0bEL3B1qJgrwck-Zfkaw" class="fr-fic fr-fil fr-dib" width="684" style="width: 686px; height: 450.252px;" height="450"></span></p><p><br></p><p><strong>Fig 5. The AI Run Report runbook will appear once successfully imported</strong></p><p><br></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><strong>Create The Method</strong></span></p><p><span style="font-size: 11pt;">Once your runbook has been imported, you then need to create the the method for this runbook.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">To do this, click into the runbook, press edit at the top left, click into the 'flow chart' tab and then click the icon in the top right of the first step of the runbook's flow chart to edit that step. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM0MTY2ZjdiLTA3OTUtNDZmMi05YjQ1LTJjYjVkZmExNGQwOSJ9.4K96jSsXj_SGukNFJaSPRrpMrfho6mrCiRydmbloxus" class="fr-fic fr-fil fr-dib" width="702" style="width: 704px; height: 514.065px;" height="514"></span></p><p><span style="font-size: 10pt;"><strong>Fig 6. Editing the first step of the runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Select the "New Method" button below the method field, and create your new method using the example in Figure 7 as reference. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg4MTczNTAxLWQwZDEtNDE3OC1iMTA0LTk3Njg4NzM4MDhlOCJ9.6zZznPAR4yIAj2ym6mj9JGV9aAwkE8Rxi5D1Rw_bFMs" class="fr-fic fr-fil fr-dib" width="874" style="width: 876px; height: 567.254px;" height="567"></span></p><p><span style="font-size: 10pt;"><strong>Fig 7. Creating a new method for the runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save the method, the step, and then the runbook, and then we can create it's authentication - to do this, we need to create a custom integration and an API application for that custom integration.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Navigate to Configuration > Integrations > HaloPSA API, and then select the "View Applications" button in the applications section of the page. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM5MzEwZDE2LWMzMDQtNDEzZS04MTcyLWQyODc4ODBiNTM3OCJ9.QUSVczjYFOZ_vltzOKgcCx4E7C6vOGIxBVvzqkEvbp8" class="fr-fic fr-fil fr-dib" width="867" style="width: 869px; height: 652.746px;" height="653"></span></p><p><span style="font-size: 10pt;"><strong>Fig 8. Navigating to the API applications area of Halo</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once in this area, select the "+ New" button in the top right corner to create a new API application. </span></p><p><span style="font-size: 11pt;">Create the application according to Figures 9a and 9b, ensuring that you set the authentication method to "Halo Automation Identity" and the permissions to "all:standard". </span></p><p><span style="font-size: 11pt;">Ensure you choose an Agent to login as that has the correct permissions for what you will want the Agent to be able to do and access, you can use an </span><span style="font-size: 11pt;"><a href="https://www.usehalo.com/guides/1670" target="_blank" rel="noopener noreferrer">API only Agent</a></span><span style="font-size: 11pt;"> here, or </span><span style="font-size: 11pt;"><a href="https://www.usehalo.com/guides/1823" target="_blank" rel="noopener noreferrer">Halo automaton identity</a></span><span style="font-size: 11pt;">. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQwN2RmODYzLWI3MjQtNGRmOS04NDQwLWM4YTE3MDdlYmZhZCJ9.5tB9cLzHXcxrdrTD9lERgPSj2eoPyzPZFUBXuqNOF10" class="fr-fic fr-fil fr-dib" width="814" style="width: 816px; height: 530.282px;" height="530"></span></p><p><span style="font-size: 10pt;"><strong>Fig 9a. Set the authentication method for the application to Halo Automation Identity</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjExNjUwZmU0LTBmMzAtNGZhYi1hZjFlLTc1NDdlM2Y2Y2Q4OSJ9.WipbYlhbaHKa8IS3q6Ok7t0Z20XAWsavWVby8kORWD0" class="fr-fic fr-fil fr-dib" width="818" style="width: 820px; height: 482.572px;" height="483"></span></p><p><span style="font-size: 10pt;"><strong>Fig 9b. Set the permissions for the application to all:standard</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save the application and then navigate to Configuration > Integrations > Custom Integrations > Custom Integrations and select "+ New" in the top right corner to create a new custom integration. </span></p><p><span style="font-size: 11pt;">Create the new custom integration according to Figure 10, ensuring that you keep the system integration as "None", set the connection to "Connect to your Halo", and set the "Run-as Application" to your newly created API application. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY5NDM2OTBlLTNkYTctNGRlNC05YjI3LWU2OTNmY2FhNjhmYyJ9.49lh_DpwzvuO2irCxV7SE-TK0QjSUudBoQEvmFYQF5s" class="fr-fic fr-fil fr-dib" width="877" style="width: 879px; height: 712.805px;" height="713"></span></p><p><span style="font-size: 10pt;"><strong>Fig 10. Creating a new custom integration</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save your custom integration, and then navigate back to your AI Run Report runbook via Configuration > Integrations > Custom Integrations > Integration Runbooks. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Edit your runbook and edit the same step as before where we created the new method. Select the "Edit Method" button underneath the method field on the step. </span></p><p><span style="font-size: 11pt;">In the integration field of your method, set your newly created custom integration, see Figure 11 for reference.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhhNWMxZjViLTgxMjktNGRhNC1hY2Q4LTMxYWNhOWMyYzY3YSJ9.5rJp2MyNK_WFbc1VApPSaCr3FGrQkCH_u_qafl9Bnpo" class="fr-fic fr-fil fr-dib" width="913" style="width: 915px; height: 528.977px;" height="529"></span></p><p><span style="font-size: 10pt;"><strong>Fig 11. Setting the new custom integration for the AI Run Report runbook method</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save the method, save the step, and then save the runbook. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 12pt;"><strong>AI Agent</strong></span></p><p><span style="font-size: 11pt;">Your next step is to create the <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">AI Agent</a> that will be used for your Agent chat.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">To do this, navigate to Configuration > AI > AI Agents and select the "AI Agents" button. Select the "+ New" button in the top right corner to create a new AI Agent. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Give your Agent a name, set the connection to </span><span style="font-size: 11pt;"><a href="https://www.usehalo.com/guides/2385" target="_blank" rel="noopener noreferrer">the connection method of your choice</a></span><span style="font-size: 11pt;">, and then set the API application you created earlier as the "Halo application to authorise as". </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNhNmIyYzU2LTk1YmItNGNiMi1hZThmLTVmZTI5OTFiYWUzNSJ9.k45QUNECL_4-hw-MjslJLxkLhEwqGTGhLjr_giWI9HI" class="fr-fic fr-fil fr-dib" width="895" style="width: 897px; height: 603.013px;" height="603"></span></p><p><span style="font-size: 10pt;"><strong>Fig 12. Configuring the connection for your AI Agent</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><strong><em>Note: To use the default Halo AI connection, you should choose the "Built-in OpenAI" option.</em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><a href="https://support.haloservicedesk.com/portal/kb?btn=46&id=2876" target="_blank" rel="noopener noreferrer">Download the "Instructions" attached file </a></span><span style="font-size: 11pt;"><a href="https://support.haloservicedesk.com/portal/kb?btn=46&id=2876" target="_blank" rel="noopener noreferrer">from this article on our Portal</a></span><span style="font-size: 11pt;"> and copy all the content within the file. Paste this content into the instructions field on the AI Agent, and then turn on the "Force JSON response" checkbox setting. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">In the input variables section you will need to <strong>create three input variables</strong> using the "+ Add" button:</span></p><ul><li style="font-size: 11pt;">user_prompt (string, not mandatory)</li><li style="font-size: 11pt;">report_payload (string, not mandatory)</li><li style="font-size: 11pt;">halo_url (string, not mandatory)</li></ul><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImMzOWY2N2U0LWY2NWUtNDJjMi1iZmEwLWI5ZjRiNTUzMDBiNCJ9.U7o-9On1uAJOXEFDw9t00F8m1IGBue-VaRFgf138xNw" class="fr-fic fr-fil fr-dib" width="916" style="width: 918px; height: 808.677px;" height="809"></span></p><p><span style="font-size: 10pt;"><strong>Fig 13. The assistant fields and the input variables for the AI Agent</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">In the functions section, ensure all system functions are included, and then create two new functions using the "+ Add" button:</span></p><ul><li style="font-size: 11pt;">get_data_sources <ul style="font-size: initial;"><li style="font-size: 11pt;">Use: Get Report Data</li><li style="font-size: 11pt;">Report: Data Sources</li></ul></li><li style="font-size: 11pt;">run_report<ul style="font-size: initial;"><li style="font-size: 11pt;">Use: Execute a Runbook</li><li style="font-size: 11pt;">Runbook: AI Run Report</li><li style="font-size: 11pt;">Runbook execution mode: Execute and await completion</li><li style="font-size: 11pt;">Parameters: report_payload (string, not mandatory)<br><br></li></ul></li></ul><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUwYmRjY2M0LTY5N2YtNGFhNy1iMDE5LTliNTMwZmI2MDIyZSJ9.TrV8MwO5amKRQmiRwjda51nb1KcrutVKRDFqglmVimA" class="fr-fic fr-fil fr-dib" width="818" style="width: 820px; height: 675.859px;" height="676"></span></p><p><span style="font-size: 10pt;"><strong>Fig 14a. The AI Agent function for running the data sources report</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ2NWIxYThiLWUwZjYtNGRlZi1iZjZmLWQ5OTM0YmUzMmFhMCJ9.l71Tx7jtxSgEPCflijWbJvYqh-Ww7J0R-jUJUo_5CcU" class="fr-fic fr-fil fr-dib" width="710" style="width: 712px; height: 735.113px;" height="735"></span></p><p><span style="font-size: 10pt;"><strong>Fig 14b. The AI Agent function for running the AI Run Report runbook</strong></span></p><p><br></p><p><span style="font-size: 11pt;"><strong><em>Note: The "CF_" is prepended to the function name by the system, you do not need to include it when writing the function's name.</em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once your functions are created, save the AI Agent. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 12pt;"><strong>Run Chat Agent Runbook</strong></span></p><p><span style="font-size: 11pt;">Now that you have your AI Agent and its functions configured, you need to set up the runbook that will trigger the AI Agent. This is because you cannot currently trigger AI Agents from a chat. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">To do this you first need to import a second runbook using the same method as the creation for the AI Run Report runbook. </span><span style="font-size: 11pt;"><a href="https://support.haloservicedesk.com/portal/kb?btn=46&id=2876" target="_blank" rel="noopener noreferrer">Download the the "Run Chat Agent Runbook JSON" attached file from this article on our Portal</a></span><span style="font-size: 11pt;"> and copy all JSON contained in it. </span></p><p><span style="font-size: 11pt;">Navigate to Configuration > Integrations > Custom Integrations > Integration Runbooks and select the "Import from JSON" button in the top right corner. </span></p><p><span style="font-size: 11pt;">Paste the copied JSON and save to create the runbook. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once the runbook is saved and visible in your list of runbooks, click into it, edit it, and navigate to the flow chart. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Edit the first step of the runbook using the icon in the top right of the step.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM1MWE3NzVlLWEwZWEtNGMxYS1hNjIzLTIxMWM4NmI1ZTU1OSJ9.OGNd5dmwuNfl42VQ8jZ2vGoGTENRweckkoACrvSPLUE" class="fr-fic fr-fil fr-dib" width="799" style="width: 801px; height: 542.077px;" height="542"></span></p><p><span style="font-size: 10pt;"><strong>Fig 15. Editing the start step of the run chat agent runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">In the AI Agent field of this step, select the AI Agent you made earlier, you will see the instructions automatically populate. </span></p><p><span style="font-size: 11pt;">After setting the agent, you can save the step and save the runbook. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijc5YWFiZGUzLTUwMTctNGQ2Yy04OWQyLTQxZGE4YTQ1ODcyYSJ9.W06mMwNnsEjOdeFgbfNRU2Cc4V-PcgKYrbVde4H70lA" class="fr-fic fr-fil fr-dib" width="937" style="width: 939px; height: 610.791px;" height="611"></span></p><p><span style="font-size: 10pt;"><strong>Fig 16. Set your new AI Agent in the first step of the run chat agent runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 12pt;"><strong>HaloAI Agent Chat Profile</strong></span></p><p><span style="font-size: 11pt;">Once your runbook has been saved, you now need to set this as the runbook that the ChatBot will trigger - this is set within the <a href="https://www.usehalo.com/guides/2335" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">chat profile</a>. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">To do this, create a new chat profile by navigating to Configuration > Chat > Chat Profiles and select the "+ New" button in the top right corner, give your new chat profile a name and then save it. </span></p><p><span style="font-size: 11pt;">Download the "Chat Profile JSON" attached file from this article and copy the JSON it contains. </span></p><p><span style="font-size: 11pt;">Select the "Import from JSON" button at the top of your chat profile. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBmMzVhOTZiLThlODMtNGY0Yi1hMDRlLWQ0NjkyODdiODFlYSJ9.FXQQgJ7xqnWoNF2x6aSnhhTFVMUGk6ChWLfTe4eToyM" class="fr-fic fr-fil fr-dib" width="903" style="width: 905px; height: 620.571px;" height="621"></span></p><p><span style="font-size: 10pt;"><strong>Fig 17. Importing a new Chat Profile using JSON</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">This will bring up the same modal screen that you have seen previously for importing runbook JSON. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYwYzg5NzE5LTE4ODMtNGRlNC1hNzU1LTc0ZDE3ZWIyYjY1YyJ9.pNNH_VZIaH4yGoLYGQgAEcOirscu9YFfY0yHUYDLYjQ" class="fr-fic fr-fil fr-dib" width="532" style="width: 534px; height: 280.738px;" height="281"></span></p><p><span style="font-size: 10pt;"><strong>Fig 18. The modal window for posting JSON for a chat profile</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once your new chat profile has saved, you should edit the profile, navigate to the Bot Flow tab, and edit the second step of the flow labelled "Execute MCP Request". </span></p><p><span style="font-size: 11pt;">Set the runbook in the 'runbook' field to be the "Run Chat Agent" runbook that you created earlier, then save the step and the chat profile. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBjZmU0OTJkLWYxNjEtNDZjOS04NmE3LTFiN2JjMGRiYTVlMSJ9.krmI80h0kvgelJ4BZuK6WQ1oogUKp1qSQ19437K38H0" class="fr-fic fr-fil fr-dib" width="895" style="width: 897px; height: 552.086px;" height="552"></span></p><p><span style="font-size: 10pt;"><strong>Fig 19. Set the new 'run chat agent' runbook to be the runbook triggered in the chat profile</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">You can edit the settings in the details tab of the chat profile accordingly, for example you may want to make it available to certain agents or change its colour. This is available to administrators only by default as it grants high level access to your </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><strong>Important: </strong>As this is a chat setup meant for the Agent-side application only, it is not advisable to change the 'access' field. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><strong><em>Note: If you have an existing MCP Agent chat profile, you should repurpose this chat profile instead of creating a new one from scratch. All you will need to do in this case is edit the second step of the profile and switch the runbook being triggered to your new "Run Chat Agent" runbook. </em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Your chat setup is now complete.</span></p><p><br></p><p data-pasted="true"><strong><span style="font-size: 14pt;">The ChatBot In Action</span></strong></p><p>The HaloAI Agent chat profile has a simple flow, that starts with a greeting and then flows immediately into executing the AI Agent via the 'Run Chat Agent' runbook.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk2NDk4NzA1LTI1OWYtNGJmNS04MzU4LWZkNDU2NDU2NTY3NCJ9.3ZB7eVa-EBR11KNAW0wDjIJMrisZHEY_1J8v-2nUNA8" alt="" data-pasted="true" width="910" style="width: 912px; height: 609.369px;" height="609" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 20. The flow for the Halo AI agent chat profile for the agent application</span></strong></p><p><br></p><p>As shown in Figures 21a and 21b respectively, to start a chat with the MCP ChatBot in the agent application you can either select the circular chat symbol in the lower right corner of your screen, or you can enter the chat area in your navigation menu and select the "+ HaloMCP (Beta)" button in the top right corner. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY3MTBlYjM4LWIyZWYtNGNlZC1iMmU5LTM1NWRiMjJiYWI4OSJ9.cQwQGJ6m54hEHGogrZGogunF8MGs6vwBcv5C_NBtn5c" width="833" style="width: 835px; height: 637.146px;" height="637" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 21a. Starting a HaloMCP chat via the floating chat icon</span></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNhZmQ0NDkyLTc4MjMtNDc4Zi1iMjYzLTRkZGEzNzBmODVlMyJ9.1QDC1tYVa1LblL7DAFUqj1HPj7XIoOwdDaVEyBzmDG8" width="960" style="width: 962px; height: 604.403px;" height="604" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 21b. Starting a HaloMCP chat via the chat area in Halo</span></strong></p><p><br></p><p>As dictated by the chat profile, when you first start a chat you will be greeted by the ChatBot who will ask how it can help. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNhMDZhZTc3LWViYzUtNDcwZC1iNWI3LWIwYjAxOGU0Y2UyYiJ9.0EbX7E1ulA_cSVvPDU8AeSrqIG0eNE6WErWaQNHNQ_E" width="892" style="width: 894px; height: 552.064px;" height="552" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 22. The AI Agent will greet you as soon as you begin the chat with the MCP ChatBot</span></strong></p><p><br></p><p>Once you submit your question or request, the AI Agent is prompted to query the MCP endpoint and return relevant data according to your request. </p><p><br></p><p>As an example, in Figure 23 you can see that I have asked for a list of current open tickets on the service desk. The AI Agent has returned a table of all the relevant Tickets and their information, including a hyperlinked ID for each one that will take me to the ticket itself in Halo.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRjNzU5YzJhLTc1YzYtNDljMS05NmUzLWUxNmMyNzJiNmZkMSJ9.FItn9wnk6uYAZHyXz4_618ccjK5xMTSQvZoO1M5S63A" width="760" style="width: 762px; height: 608.962px;" height="609" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 23. Querying the MCP endpoint via the agent ChatBot</span></strong></p><p><br></p><p>In Figure 24, I then tell the agent to add a note to one of the tickets stating that the issue has now been resolved. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjcyNzU4MWE4LTYzOGItNDA1OC1iMmY4LThmM2Y2NGVlZDFlNiJ9.RpQsxeffO0Pc_JMPKVbbWvYVfuvLBiFGkkRWPoqDHk0" width="768" style="width: 770px; height: 616px;" height="616" class="fr-fic fr-dii"></p><p><span style="font-size: 10pt;"><strong>Fig 24. Instructing the AI Agent to add a note to a ticket</strong></span></p><p><br></p><p>The AI Agent carried out this task for me by using the tools it has access to via the MCP endpoint, demonstrating that I can action my tickets without even having to leave the chat or the page that I am on.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk3MDEzY2ZiLWQ5ZTktNGVhYi1iOGQzLTY5ZTU3NmE1NTI2YSJ9.JTGvazS25HmVHc5oeN0SVpksqbrKHXZ17-4WXf9TLws" width="814" style="width: 816px; height: 569.897px;" height="570" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 25. A note added to a Ticket by the AI chat agent</span></strong></p><p><br></p><p>If you wish to view or modify the prompt for the AI Agent, you can do so by navigating to the AI Agent in Configuration > AI > AI Agents.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQzNjVmMThmLWQ4OWQtNGUzMi1hZGRhLTFkNTI0MGFiZGE3NSJ9.AtwJsblzQ0q7rgqd1DZpBkvwGvZAMld9ZE2xBdZ346s" width="941" style="width: 943px; height: 664.373px;" height="664" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 26a. The AI Agents section within the AI configuration module of Halo</span></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjNDM2N2IwLTdmY2UtNDc5ZS05M2FkLTI1MjllYzMwMDFjOSJ9.9nnBNaeJiw8tcbAKQzABAq-KxwqK7x_8i8XZPMsBwl4" width="863" style="width: 865px; height: 414.91px;" height="415" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 26b. Selecting the AI Agent being used for the chat</span></strong></p><p><br></p><p>As you saw when setting up the process, within the 'Assistant Fields' section of the agent you can view and edit the 'instructions' being fed into OpenAI in order to customise your agent's behaviour to your liking. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE3ZTI0MmUzLTZhODUtNGE1Mi04MGFlLTBlYjhkOTgyMjZlOSJ9.QToFOrM5X_w-6rgvigLTt3xz_lUWvx0YCxrenvKdeuQ" width="887" style="width: 889px; height: 592.504px;" height="593" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 27. The instructions/prompt for the ChatBot's AI Agent</span></strong></p><p><br></p><p><em><strong>Note: It is not advisable to change, add or remove any input variables for this Agent unless you are familiar with how AI Agents work and how the variables are handled/edited. For information on this, please do refer to the guide: <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer">AI Agents</a>.</strong></em></p><p><br></p><p><br></p><p data-pasted="true"><strong><span style="font-size: 14pt;">What Can The Agent Achieve & Return?</span></strong></p><p>The functions available to the AI Agent, and the data that it is able to return, are partly dependent on the tools made available to the Agent via the MCP server, and partly dependent on the prompt fed through to OpenAI via the AI Agent's instructions.</p><p><br></p><p>The Chat Agent has all system functions enabled (Figure 28).</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkxOTYxMjA3LWE3NGMtNDg0Yy04MWY4LTIyYzIwOTExZDc2ZCJ9._TOYaJF6ZAoSikB3UgAX7mf8peaHhTDw4ahSGhXiV-0" width="631" style="width: 633px; height: 435.885px;" height="436" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 28. Enabling all system functions on an AI Agent</span></strong></p><p><br></p><p data-pasted="true">Although these functions are not listed, you can find details of the functions included in this guide: <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer">AI Agents</a>. </p><p>In the Functions table beneath this checkbox, you can create new functions or, if you have deselected "include all system functions", you can choose the functions available to the Agent. Please do refer to the <a href="https://www.usehalo.com/guides/2783" target="_blank" rel="noopener noreferrer">AI Agents</a> guide for details on system and custom functions.</p><p><br></p><p><strong><em>Note: You do not need to have the MCP endpoint enabled/exposed to be able to use AI Agents. Although they use the Halo MCP server, they have their own unique endpoint and their own set of available tools/functions. </em></strong></p><p><br></p><p>In terms of retrieving ticketing data, although there are functions providing access to ticket data, the AI Agent is instructed to ignore these and follow the flow dictated in the instructions. This involves running the "Data Sources" report and selecting the most appropriate data source for the agent's request or question, it then uses this data source and the user's request to construct a report to run. Once the report is ready it executes the 'AI Run Report' runbook to query the reporting endpoint and return relevant, formatted data to the chat. Performing this function rather than the system improves accuracy of the data returned to the chat by exposing the Agent to a greater number of data sources.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRiNjg5OTMwLWEzZmItNGNhMi1hNWI3LWI1ZGU0YTJmYjE5ZCJ9.pi6EdXOUpW2_f8gxGi74sVtnwjFRFlYLSfdL8usjcJI" width="937" style="width: 939px; height: 687.637px;" height="688" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 29. Instructions to the AI Agent to use custom functions instead of MCP tools for retrieving ticketing data</span></strong></p><p><br></p><p>As mentioned in the previous section, you can change these instructions if you wish to, including the JSON for constructing the report.</p>
