<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 data-pasted="true"><strong>In this guide we will cover:</strong></p><p><br></p><p data-pasted="true"><strong>- What are AI Agents?<br></strong></p><p data-pasted="true"><strong>- API Application</strong></p><p data-pasted="true"><strong>- Creating AI Agents</strong></p><p><strong>- AI Agents in Runbooks</strong></p><p><br></p><p data-pasted="true"><strong>Admin Guides:</strong></p><ul><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2328/" target="_blank" rel="noopener noreferrer"><strong>AI</strong></a></li></ul><p><strong>Related Guides:</strong></p><ul><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2385/" target="_blank" rel="noopener noreferrer"><strong>Connecting AI to Halo</strong></a></li><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2137/" target="_blank" rel="noopener noreferrer"><strong>Leveraging AI in Halo</strong></a></li><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/1630/" target="_blank" rel="noopener noreferrer"><strong>Custom Integrations/Runbooks</strong></a></li><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2776" target="_blank" rel="noopener noreferrer"><strong>AI Abilities </strong></a></li></ul><p><br></p><p><br></p><p data-pasted="true"><strong><span style="font-size: 14pt;">What are AI Agents?<br></span></strong></p><p>Available from v2.234.1+, an AI Agent is a custom set of instructions that can be sent to an AI model to generate a response and perform certain tasks. The AI Agent can execute requests in your own instance via the API. Using AI Agents makes the creation of Runbooks easier, as you do not need to create your own integration method with a JSON body, instead you can just give AI instructions on what you want to do at a given step of a Runbook and it will execute the request via the API for you.</p><p><br></p><p>AI Agents currently only support OpenAI connections. The Halo default Connection and Azure OpenAI will be available for this feature from v2.236+. </p><p><br></p><p>From v2.236+, tickets, actions, and Knowledge Base Articles created by an AI Agent will be "flagged" as AI in reporting under the columns: faicreated, aacreated, and kbaicreated. The ID of the AI 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 data-pasted="true">For more information on setting your OpenAI connection see our guide on <a href="https://usehalo.com/haloitsm/guides/2385/" target="_blank" rel="noopener noreferrer">connecting AI to Halo</a>.</p><p><br></p><p data-pasted="true"><span style="font-size: 14pt;"><strong>API Application</strong></span></p><p>Before you can set up an AI Agent you will need to create an API application with the Authentication Method "Halo Automation Identity". To do this head to Configuration > Integrations > Halo API, click the "View Applications" button, click "New" to create a new application. </p><p><br></p><p>Give this application a sensible name and set the Authentication Method to "Halo Automation Identity". </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ1OWZjN2ZhLThjMWQtNDA0YS04MWE1LTcwMzc2ZmFkMTQ0MSJ9.QhmFlwqJrjKmqNvrg7NKX75W3-jJx-QuD8oeVgvxTyU" class="fr-fic fr-fil fr-dib" width="1090" style="width: 1092px; height: 573.922px;" height="574"></p><p><span style="font-size: 10pt;"><strong>Fig 1. Creating an API application </strong></span></p><p><br></p><p>Once selected, you will need to specify an identity for the application. This informs the base level of access granted to the application. The option "Application identity" is recommended here, as you can use roles to control the base level of permission rather than having to pick a specific agent. When this option is selected the "Identity Roles" field can be used to determine which roles to use as the base level permissions.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM3ZGY3MGI3LTIyYTYtNGZjYy1iYjVhLTJiN2NlNTljNTNkMyJ9.xSE7vIcxZGFVUPNaB8oT6DrJNSw_fXVv576TJuV14AQ" class="fr-fic fr-fil fr-dib" width="1108" style="width: 1110px; height: 233.121px;" height="233"></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 2. API application login </strong></span></p><p><br></p><p>Under the "Permissions" tab set which specific features (scopes) you would like to allow the application to have access to.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM0ZTNlNWRiLTVlNjYtNGE1ZS04MWUxLTBiZjIyZWI3NmE1YSJ9.VVejvcps4i97p6dIGDmlUV5IIzHVKQeDUyiGRUHuDZw" class="fr-fic fr-fil fr-dib" width="1070" height="865"><span style="font-size: 10pt;"><strong>Fig 3. API application permissions</strong></span></p><p><span style="font-size: 10pt;"><strong> </strong></span></p><p>For more information on API applications see our guide linked <a href="https://usehalo.com/haloitsm/guides/1823" target="_blank" rel="noopener noreferrer">here</a>.</p><p><br></p><p><span style="font-size: 14pt;"><strong>Creating AI Agents</strong></span></p><p>Once your application has been created you can create an AI Agent. To do this head to Configuration > AI, and click the "AI Agents" button.</p><p><br></p><p><span style="font-size: 14pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM2MDU1Nzg3LTNjMDQtNDk4Mi1hM2ZiLTVhNzZhMmY3NDNhMiJ9.ClGZr_6T5NkCPzAyeLy8S9XUZgTbGAgbQ4Mq2Fhemos" class="fr-fic fr-fil fr-dib" width="1200" style="width: 1202px; height: 328px;" height="328"></span></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 4. AI Agents button</strong></span></p><p><br></p><p data-pasted="true">When you create a new AI Agent you will need to set a name, connection, and model for your AI Agent to use. You will need to set the "Halo Application to authorise as" to your newly created application.</p><p><br></p><p data-pasted="true">For more information on setting your OpenAI connection see our guide on <a href="https://usehalo.com/haloitsm/guides/2385/" target="_blank" rel="noopener noreferrer">connecting AI to Halo</a>. </p><p><br></p><p><span style="font-size: 14pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZjNDUzOWY1LWJlM2QtNDM2NC05NzQ4LTM2YzQ1MWFmOGNkYiJ9.Gk5y4_LwNFFP4E5yIBA_S99OVmADXRIhUs84IDxQ13w" class="fr-fic fr-fil fr-dib" width="1203" style="width: 1205px; height: 492px;" height="492"></span></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 5. Creating an AI Agent </strong></span><span style="font-size: 10pt;"><strong> </strong></span></p><p><br></p><p>Next you can set the instructions for your AI Agent to follow. The instructions you set here control the request that is sent to the API. You must state exactly what you want the AI Agent to do here.</p><p>These instructions can include input variables in the format <<variable_name>>, which will need to be specified in the table below. These variables let you change the instructions dynamically based on the event that triggered, or information obtained by the Runbook.</p><p><br></p><p data-pasted="true">If you are using your AI Agent to extract output variables for a Runbook you will want to select "Force JSON response". This will make sure the response provided is in JSON format, allowing successful variable declared in the Runbook. If you force a JSON response you will also need to include the word 'JSON' in the instructions.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjlhMGEwMGMzLWY2NTctNGM5Yi04YWI0LWE2ZTI2MDc4N2UxYSJ9.wlTS9qAEquw3K9p-KvRecpruhkX6yt8gir7bn_aQz4U" class="fr-fic fr-fil fr-dib" width="1196" style="width: 1198px; height: 396.346px;" height="396"></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 6. AI Agent instructions </strong></span></p><p><br></p><p data-pasted="true">Any input variables you are including in your instructions need to be added to the Input Variables table. These variables will be mapped to the variables used in the runbook later. Click "Add" to set the name and data type for your variable. Here you will also have the option to set the variable as mandatory, and set a description for the parameter. </p><p><br></p><p>Finally, you can set any functions that are available to this AI Agent. Deselecting "Include all system functions" will remove system functions, allowing you to add specific system and custom functions to the Functions Table. Leaving this checkbox selected will include all system functions and allow you to add additional custom functions using the table. </p><p><br></p><p data-pasted="true">The available system functions are as follows:</p><p><br></p><ul><li><strong>Action a Ticket –</strong> Allows you to add any action that is configured to be a 'quick action' to a ticket on behalf of the agent, allowing agents to update tickets. </li><li><strong>Add Note to Ticket –</strong> Allows you to add a private note to a ticket on behalf of the agent, allowing agents to update tickets.</li><li><strong>Apply AI Suggestion –</strong> Applies AI suggestions to a ticket, rather than the agent having to do this from within a ticket. </li><li><strong>Assign to me –</strong> Re-assigns a ticket from one agent to the agent logged in.</li><li><strong>Get Assigned Tickets –</strong> Returns a list of tickets that are assigned to the agent. </li><li><strong>Search Knowledge Base –</strong> Searches 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>Get matching Articles and Tickets for a Ticket –</strong> Re-runs AI ticket and article 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 and articles are the most up to date matches in the database. </li><li><strong>Get One Article –</strong> Can summarise or extract details from a specific KB article and return these to the agent. </li><li><strong>Get One Ticket –</strong> Return a list of tickets that are assigned to the agent. </li><li><strong>Get User Info –</strong> Returns the information held about the user in Halo. </li><li><strong>Search Service Catalogue –</strong> 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. </li><li><strong>Log Time –</strong> Logs a quick time entry for the agent.</li><li><strong>Search Tickets –</strong> Searches 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 data-pasted="true"><strong>Search Assets (v2.236+) –</strong> Searches assets based on a prompt from the agent.</li><li data-pasted="true"><strong>Get One Asset (v2.236+) – </strong>Can summarise or extract details from a specific assets and return these to the agent. </li><li><strong>Search Users (v2.236+) –</strong> Searches users based on a prompt from the agent. (Only available to agents)</li><li><strong>Get One User</strong><strong data-pasted="true"> (v2.236+) –</strong> Can summarise or extract details from a specific user and return these to the agent (only available to agents). </li><li><strong>Use specific action (v2.238+) - </strong>Can add an action to a ticket, including populating any fields on this action. The action must be available to use on the ticket's current workflow step, and the AI Agent must also have access to a function that allows it to check the workflow step of the ticket (such as get one ticket). <p><br></p></li></ul><p data-pasted="true">Custom Tools can be created with the following uses: </p><p><br></p><ul><li><strong>Use an AI Ability – </strong>Allows you to use/trigger an AI ability. See our guide on AI Abilities for information on this.</li><li><strong>Log a ticket of a certain type or template –</strong> Logs a new ticket of a specified type or template. From v2.232+ you can also use the option "Any Ticket Type the user has access to" to allow users/agents to log any ticket type they have access to, provided they provide the ticket type name. From v2.238+, you can set the fields to use a as parameters. This allows you to choose between including the ticket type's field list as parameters for the AI to populate, or or using the Summary and Details. </li><li><strong>Get Report Data –</strong> Returns the data from a specified report. </li><li><strong>Execute a Runbook –</strong> Executes a runbook of choice.</li></ul><p><br></p><p><strong><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAzZDMzZGZkLWNlMTgtNDg3NS05ODNiLTkyOWUyYjc3NzA4YyJ9.gKRgVo41c9LvI8SyxivYqyF5XfkwZXO5g7hcYVRxKK8" class="fr-fic fr-fil fr-dib" width="1206" style="width: 1208px; height: 525.39px;" height="525"></strong><br></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 7. AI Agent variables and functions </strong></span></p><p><br></p><p data-pasted="true">Now you have created your AI Agent click "Save". This AI Agent can now be used in a Runbook. </p><p><br></p><p><span style="font-size: 14pt;"><strong>AI Agents in Runbooks</strong></span></p><p data-pasted="true">To add an AI Agent to a Runbook, head to Configuration > Integrations > Custom Integrations, select the "Integration Runbooks" button. Click a Runbook to edit, or create a new one using the "Add" button.</p><p> </p><p data-pasted="true">Against your Runbook flow you can add or edit a step of type "Action". When the action type is set to "AI Agent" an additional dropdown will show, allowing you to select which AI Agent to use. Selecting this will automatically populate the variable table. You will need to set the value for this to use by typing or selecting a default Runbook-level variable from the "Available Variables" list, using the dropdown to select the relevant entity to filter by. For more information on Runbook-level variables, see our guide linked <a href="https://usehalo.com/haloitsm/guides/1630/" target="_blank" rel="noopener noreferrer">here</a>. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI4NWJjYjc5LTM2OGYtNDRjOS05ZjViLWJhZTlhMzM4YWZjMSJ9.fALlb7vMiO8JkNKvb3i-9TAme-qNTpeVnAIf-HImna8" class="fr-fic fr-fil fr-dib" width="1192" style="width: 1194px; height: 516.692px;" height="517"></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 8. Using an AI Agent in a Runbook</strong></span></p><p><br></p><p>In the Figure 8 example, when the Runbook is triggered the Ticket ID populates the <<ticket^id>> variable. This is set as the value for the <<InputTicketID>> variable, which informs the AI Agents what Ticket to action. </p><p><br></p><p data-pasted="true">This tells the AI Agent to perform the instructions in response to the input variable, in this case adding a note and providing a recommended resolution and Knowledge Base article. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk4YTcyYWZkLTdmYmEtNGUwNy1hNGVhLWRhODZhNjczYTIyZSJ9.JujTNx3AkpNWdKIO8h1FIraFxkLjOSa9Ryne3BkYofA" class="fr-fic fr-fil fr-dib" width="1180" style="width: 1182px; height: 729.24px;" height="729"></p><p data-pasted="true"><span style="font-size: 10pt;"><strong>Fig 9. AI Agent performing a task </strong></span></p>
