Script Runner Tool

Introduction

The Script Runner tool executes a JavaScript snippet in the user's browser when the agent calls it, letting the agent trigger client-side UI actions such as filtering a list, opening a panel, or updating page elements.

What it does

The Script Runner bridges the gap between an agent's text response and live browser-side behaviour. When the LLM determines that a UI action is needed, it calls this tool. Joget then executes the configured JavaScript in the page context, where your script can manipulate the DOM, trigger Joget events, or interact with other page elements.

• Predefined Script: You write the JavaScript at design time. The LLM supplies argument values that your script receives as the args object. The LLM cannot change the script itself, only the inputs.
• LLM Generated Script: The LLM writes the JavaScript at runtime and passes it as a parameter. This mode is intended only for controlled, trusted environments.

The tool operates in two modes selected at configuration time:

You also control what message, if any, appears in the agent's chat when the tool fires, using the Message Mode setting.

When to use it

Use the Script Runner when both of the following are true:

• You need the agent to trigger a browser-side action in response to a user request.
• The action is something a JavaScript snippet can accomplish: DOM updates, filtering, panel toggles, or Joget jQuery events.

Typical scenarios include the following:

• CRM Datalist Filter: The agent filters a customer list to show only overdue accounts by updating a datalist filter field and triggering a search, without a page reload.
• Procurement Dashboard: The agent highlights specific rows in a purchase-order table or scrolls to a particular section of the page in response to the user's query.
• HR Portal: The agent opens an approval panel or switches the page to a specific tab when the user asks to review a pending leave request.

Get started

How to use it

To use the Script Runner Tool:

1. Open the agent in the AI Agent Builder.
2. Select the task that should trigger the client-side action.
3. Add the Script Runner to that task from the Tools palette.
4. Set the Mode to Predefined Script (recommended) or LLM Generated Script.
5. Fill in the Function Name and Function Description.
6. In Predefined Script mode: add rows to the Function Arguments grid and write the script in the JavaScript field.
7. Set the Message Mode and, if needed, a Custom Message.
8. Save the agent.

Configure Tool Properties

To properly integrate and configure the Script Runner, set the following fields:

Predefined Script mode fields

These fields appear only when Mode is set to Predefined Script. Always Visible Fields

• Function Name: The name the LLM uses to call this tool. A short, unique name using letters, numbers, hyphens, and underscores only. For example, filter_datalist. This is a required field.
• Function Description: What the LLM reads to decide when to call this tool. A plain-language description of the UI action this script performs and when the agent should trigger it. This is a required field.
• Mode: Whether the script is written at design time or generated by the LLM at runtime. Predefined Script (recommended) or LLM Generated Script.
• Message Mode: What appears in the agent's chat when the tool fires. LLM Generated (the LLM provides a message), Custom Message (a fixed message you write), or No Message (nothing is shown).

Predefined Script Mode Fields

These fields appear only when Mode is set to Predefined Script:

• Function Arguments: The inputs the LLM can pass to the script at runtime. Use the grid to add rows. Each row specifies the argument name, data type, description, and whether it is required.
• JavaScript: The script that runs in the browser when the tool is called. Write valid JavaScript. Access LLM-supplied argument values via the args object using the argument name you declared. For example, args.status.

Custom Message Mode Field

This field appears only when Message Mode is set to Custom Message:

• Custom Message: The fixed text shown in the agent's chat when the tool fires. Any plain-text message. For example, "Filtering the list now."

Samples

A Predefined Script that filters a datalist:

// Argument declared: status (string, required)
// This script filters a Joget datalist by the status the LLM provides.
jQuery("#datalist-filter-status").val(args.status).trigger("change");
jQuery("#datalist-search-btn").click();

Best Practices

• Use Predefined Script mode for production. Predefined scripts are safe, auditable, and predictable. LLM Generated mode is only for internal or developer tools.
• The script has no server access. console.log() outputs to the browser console but produces nothing visible in the agent chat. Use DOM operations, alert(), or Joget jQuery calls for effects the user can see.
• Write specific Function Descriptions. The LLM decides when to call this tool based on the description alone. Vague descriptions cause the tool to be called at the wrong time or not at all.
• Each argument name you declare appears in the script as args.yourName. The tool handles the mapping automatically; you do not need to reference a prefix.