Creating AI agent workflows in AI Agent Studio - Support and Troubleshooting

Creating AI agent workflows in AI Agent Studio Summary .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Use these general guidelines to create effective AI agents and agentic workflows in AI Agent Studio. This article covers how to write clear agent instructions, how to design tools and agent teams, how AI agent execution works, and answers to common questions.

General guidelines for creating AI agents Write clear agentic workflow names and descriptions Clearly describe and define the agentic workflow name and description, because these drive skill discovery based on the user's request.

Instead of this : Name: License Processing Description: Software License Allocation is used to allocate a software license. Use this : Name: Software License Allocation Description: The Software License Allocation process involves verifying the details of the requesting user and checking the availability of the requested software license. If the user meets the eligibility criteria, the system proceeds with assigning the license, ensuring seamless access to the required software. Write instructions in clear, correct English Poor language quality can lead to misunderstandings or execution errors.

Instead of this : Run toolA and then show result, dont do confusions Use this : Run Tool A to fetch the required data and then display the result to the user. Structure instructions as a logical workflow Structure your use case instructions using sections and subsections to create a logical workflow. This helps the reader understand and navigate the expected flow.

Instead of this : Get the user and license details. Allocate license if the user is eligible. Use this : Fetch the details of the user who opened the incident. Find out the details of the requested software license. Verify if the user is eligible to get access to the requested software license. If the user is eligible, allocate the software license. If the user is not eligible, inform the user that they are not eligible. Align instructions with agent names and descriptions Use terminology similar to the agent name and description so the expected agent is chosen correctly.

Context : Agent name: Notification Agent Agent description: This agent can send notifications to the provided list of users. Instead of this : Tell user that something went wrong. (This can confuse the orchestrator, and it might pick a Communicator Agent rather than the Notification Agent.) Use this : Send a notification to the user that something went wrong. (This helps the orchestrator understand that it should choose the Notification Agent.) Limit each instruction to one action Each instruction should focus on a single action. Combining multiple actions in one instruction can lead to skipped steps during execution, because the agent may complete one action and overlook the others. Split bundled actions into separate, ordered instructions.

Instead of this : Summarize the record and show it to user, then update the record notes with the same data. Use this : Summarize the record details. Display the summarized record details to the user. Update the record with the record summary. Avoid internal system terms in instructions Do not include internal system terms (for example, short_term_memory, scratchpad, or variables in XML tags) in the instructions. These do not add value and can confuse the agent.

Instead of this : Get the user account lock status and store the information in your memory for processing it later. Use this : Get the user account lock status. If the user account is locked, unlock the user account. (Directly refer to the data; it is available in the agent's memory.)

Instead of this : Store the user account status in variable . Use this : If the user account is locked, unlock the user account. Address the human consistently as the user When an instruction involves communicating with the person, refer to them as "the user" rather than ambiguous terms like "agent" or "entity talking to you."

To show something to the user: Instead of this : Show the list of missing users to the agent. Use this : Show the list of missing users to the user. To ask something from the user: Instead of this : Find the record number. Use this : Ask the user for the record number. Order steps and define each branch Write instructions as ordered steps, and spell out what should happen in each conditional branch. Vague references, undefined tools, and unclear branching cause execution errors and loops.

Instead of this : A step sequence that does not specify how to check for a license ID, sends guest users into a loop, references an undefined "appropriate tool," and uses vague directions like "do something else," "move forward," and "figure out what's wrong." Use this : To verify the eligibility criteria and allocate a software license, follow these instructions step-by-step: Step 1: Verify if the License ID is available. If the License ID is missing, ask the user to provide it. Step 2: Fetch the user details to determine the user type. Step 3: If the user type is 'manager', follow these steps: Check if the requested software license is available. If available, allocate it to the user. Once the license is successfully allocated, inform the user. If the licenses are not available, inform the user that the requested licenses are not available. Step 4: If the user type is 'regular employee', follow these steps: Create a license allotment task for the user. Once the task is created, inform the user that the license allotment task has been created and is waiting for their manager's approval. The license allocation is processed based on their manager's approval. Step 5: If the user type is 'guest', follow these steps: Verify the roles of the guest user. Retrieve the list of roles that are eligible for the requested software license. Compare the guest user's roles with the software license eligibility roles to determine if the guest user is eligible for the requested license. If the guest user is eligible, create a temporary license allocation task. Inform the user that the temporary license allocation task has been created for the guest user. If the guest user is not eligible, inform the user that the guest user is not qualified to access the requested software license due to missing roles. Do not restate tool information in instructions Avoid redundant tool information. Do not add instructions like "You are given these tools" or "You are provided with the below tools," because the tools and their descriptions mapped to the agent are already available to it.

Instead of this : You are provided with tool X, which has ABC functionality. Use this : Use tool X to extract data. Fetch the XYZ details. Give agents and tools unique names and descriptions Unique names and clear descriptions help the orchestrator pick the right agent for each task, and help each agent pick the right tool. Apply this to both agents and tools.

For agents:

Instead of this : Multiple agents named "Analyzer" with similar descriptions. Agent 1: Data Analyzer Agent—Description: This agent analyzes data. Agent 2: Content Analyzer Agent—Description: This agent analyzes content. Use this : Agent 1: Data Analyzer Agent—Description: Responsible for extracting and analyzing transaction data, showing the results, and taking feedback from the user. Agent 2: Log Analyzer Agent—Description: Responsible for reviewing system logs, flagging anomalies, and communicating them to the user. For tools:

Instead of this : Two tools with different purposes named similarly, with descriptions that are not clearly defined. Agent 1: Incident Analyzer — Tool: Get user details — Description: gets user details Agent 2: User Analyzer — Tool: Get user details — Description: gets user details Use this : The tools' names and descriptions clearly depict their functionality. Agent 1: Incident Analyzer — Tool: Get user status — Description: Checks whether the user account is active. Agent 2: User Analyzer — Tool: Get user details — Description: Fetches user details like the name, department, manager, and other personal and team information. Name tool inputs distinctly across agents Use unique inputs for tools across multiple agents in the team to prevent confusion.

Instead of this : Naming both tool inputs as sys_id. Agent 1: Incident Analyzer Agent — Tool: Get incident details — Input: sys_id Agent 2: User Analyzer — Tool: Get user details — Input: sys_id Use this : Provide meaningful names to differentiate the tools' inputs. Agent 1: Incident Analyzer Agent — Tool: Get incident details — Input: incident_sys_id Agent 2: User Analyzer — Tool: Get user details — Input: user_sys_id Describe tool inputs clearly Always describe the inputs clearly when designing the tool to ensure a consistent execution pattern.

Instead of this : Input name: user_id — Description: The ID of the user. Use this : Input name: user_id — Description: The 32-character alphanumeric unique identifier of the user. Explanation : A user_id could be a sys_id, full name, user name, or email. It is important to clearly help the LLM understand what type of input to choose to run the tool. Mark required tool inputs as mandatory If a tool requires a particular input to always be present, mark it as mandatory if that feature is available in the tool (flow actions, subflow, and so on). If not, mention it in the tool input description.

Instead of this : Tool name: Get incident details — Input: incident_number — Description: incident number Use this: Tool name: Get incident details — Input: incident_number — Description: The unique identifier of the incident record. This is a mandatory input. The incident number follows the pattern INCXXXXXX. Use an output transformation for large outputs Select an appropriate transformation strategy to process large outputs. For example, an output transformation like "Summary for search results" helps filter and retain only relevant information, especially when using RAG as a tool.

Instead of this : Directly pass the complete search results to the agent. Use this : Use the output transformation "Summary for search results" to filter and pass only the contextual information needed for execution. Example : When fetching similar incidents, the RAG tool retrieves all incidents that are semantically similar to the search query. Applying the "Summary for search results" transformation strategy ensures only the most relevant contextual information is selected and passed forward. Process tool outputs to stay within token limits Any tool output exceeding the model's token limit is truncated. Verify that your tool code includes post-processing logic to process or summarize data appropriately and prevent data loss.

Instead of this : Generating a large amount of data from the tool and passing it to the agent without considering the token limit. Use this : Fetch only necessary and meaningful data, and summarize it if needed. Example : Fetching all incidents assigned to a team may generate excessive data. The ideal approach is to retrieve the incidents, extract only the required attributes from the incident record, and summarize the data if necessary. Use actionable statements to transfer the flow between agents Use an actionable statement to transfer the execution flow to another agent in the team without using the agent's name or the name of a tool mapped to the other agent.

Instead of this : Call "Get incident details" from "Incident analyzer agent" with value incident_number as INCxxxxxx. Use this : Fetch incident details with the retrieved incident number. Fetch user details for the assigned user from the retrieved incident details. Use a dedicated Skill tool for complex tasks Using a custom Skill tool for complex tasks ensures the agent's behavior is predictable, reusable, and maintainable. For agent workflows that involve processing large datasets, generating structured content under specific constraints, or performing multi-step logic with deterministic outcomes, implement a dedicated Skill tool instead of relying on built-in tools like organize_general_knowledge or math.

The built-in tools support lightweight, in-memory operations, offering temporary reasoning space to the agent without persisting output to memory or enabling inter-agent sharing. They are best suited for quick data structuring and basic reasoning tasks. For use cases where precise control over output (content, format, or structure) is necessary, custom Skill tools provide greater flexibility and reliability. Example 1: Next Best Action Agent. When generating plans, a Skill tool ensures consistency in formatting, styling, and structure—something not easily achievable with built-in tools, where output cannot be explicitly guided or preserved. Example 2: Tasks like generating HTML responses, producing itemized lists with specific rules, or verifying large documents against detailed criteria are better handled by Skill tools. Otherwise, the complexity of the instructions required in the agent may increase significantly, potentially leading to ambiguity or overlooked steps during execution.

How AI agent execution works When an AI agent or agentic workflow runs, it records each execution so you can review what the agent did and why. You can review these execution records on the Activity page in AI Agent Studio, which lists both agentic workflow and AI agent executions and lets you troubleshoot them. To review a single run in detail, use the decision logs available when you test an agent manually on the Testing page.

Decision logs show how the LLM analyzes the instructions in your use case, agent, and tool details. They include the following:

Orchestrator log : Generated based on the instructions defined in the use case. This log describes the subtasks generated and the agents the orchestrator delegates to. Refine your use case instructions to adjust this behavior. Agent log : Generated based on the instructions defined in the agent. Each agent log includes the following: Thought describes what has happened so far in the execution flow and the next action to execute. The agent instructions are responsible for generating this Thought and controlling the flow. Refine your instructions accordingly. Action Reasoning describes why the agent chose to run the tool and its inputs. If the wrong tool is chosen, check your tool details such as name, description, inputs, and input descriptions. Action Inputs shows the data chosen to run the tool. This data is chosen from the agent's memory. If an incorrect input is chosen, refine the input description to align with the input details stored in memory. Output of the Action helps you understand whether the tool ran successfully and what output the tool returned. All data generated in the current conversation, including tool execution outputs, is stored in memory and persisted in the sn_aia_message table (the Message column).

AI agent workflow FAQs Why is my skill not discovered? Check if skill discovery is working on the instance. If it is not, reach out to the respective team for help. If skill discovery is working but the use case or agent is not discovered, check your use case name and description, and your agent name and description.

Why does execution end immediately with a problem message? When execution ends immediately with Sorry, there was a problem on my side trying to complete this request. Try asking again later. :

Go to the sys_generative_ai_log table and verify whether the LLM calls are successful on your instance. If there is an error, check the Generative AI Controller setup on your instance. If the Planner and ReAct LLM calls are successful, a suitable agent could not be picked for the task. Check whether the technical terms in the task align with the agent's name, description, role, instructions, and proficiency. Why is the incorrect agent chosen during execution? Check the uniqueness of the agents' names and descriptions in the team. Multiple agents with overlapping context can confuse the orchestrator about which agent is most suitable for the task.

How do I write instructions to reference the memory? No specific terms are needed to refer to the agent's memory. Write the instruction directly, for example: Show a message to the user about the extracted incident details.

How do I write instructions to hand over to another agent? Never mention the name of another agent or the name of a tool mapped to another agent to hand over the execution flow. This confuses the current agent, which is not aware of the tools or names of other agents in the team. Use an actionable statement that explains the task instead.

Example 1: Fetch the incident details. (Here, "Get incident details" is a tool in another agent.) Example 2: Fetch user information with the assigned user from the details of the incident. (Here, "Get user details" is a tool mapped to another agent.) How do I write instructions to ask the user or display something to the user? The instruction should not reference the agent. For example, "Ask agent to provide incident number" is incorrect. Address the statement to the user, for example: Ask the user to provide the incident number. To show something without seeking input, address the user with terms like "show" or "display," for example: Inform the user that the incident details could not be fetched.

How do I share memory across multiple agents? Do not use terms like "store the value from the tool into " or "store in memory." The agent cannot interpret this, because there is no concept of saving something to memory for an agent. Memory is maintained internally: all tool outputs and information conveyed to the user are saved and shared across all agents. To refer to any data in the instructions, use actionable statements aligned with the terminology returned from the tool output, so the context of the referenced data is clear to the agent. For example: Fetch user details with the assigned user from the retrieved incident details.

How do I write instructions to end the agent execution? Do not use statements like "end the conversation," "stop execution," "end the flow," or "terminate the execution." No specific instructions are required. Once the agent fulfills the action items per the instructions, it comes to completion.

Related Links .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Advanced AI Agent Instructions Guide: ServiceNow Edition