UI Registry (Assistant.js)

Basic Tool Registration

Use registry.addTool() to create tools that the AI assistant can invoke to interact with your UI:

1
import { registry } from "./Assistant.js"
2
3
registry.addTool({
4
  toolName: "toolName",
5
  description: "Description of what the tool does",
6
  parameters: {
7
    type: "object",
8
    properties: {
9
      paramName: {
10
        type: "string",
11
        description: "Parameter description"
12
      }
13
    },
14
    required: ["paramName"]
15
  },
16
  execute: async (args) => {
17
    // Tool implementation
18
    return { success: true, result: "Tool executed" }
19
  }
20
})

Tool Configuration Options

Each tool requires the following configuration:

• toolName (string, required): Unique identifier for the tool
• description (string, required): Clear description of the tool’s purpose and functionality
• parameters (object, required): JSON Schema defining the tool’s input parameters
  • Use type: "object" with properties to define parameter structure
  • Include required array for mandatory parameters
  • Use appropriate types: "string", "number", "boolean", "array", "object"
  • Add enum arrays for restricted value sets
• execute (function, required): Async function that implements the tool logic
  • Receives the parameters as the first argument
  • Should return an object with results or error information
  • Can interact with DOM elements, make API calls, or perform other operations

Dynamic Instructions with addInstruction

In addition to tools, the registry supports adding dynamically updatable instructions to the model context using addInstruction. Use this to stream concise, structured state into the assistant’s system prompt.

1
import { registry } from "./Assistant.js";
2
3
// Create an instruction with an initial value; JSON strings are recommended
4
const bmiInstruction = registry.addInstruction("{}");
5
6
function computeBMI(height, weight) {
7
  if (!Number.isFinite(height) || !Number.isFinite(weight) || height <= 0 || weight <= 0) return NaN;
8
  return weight / (height * height);
9
}
10
11
function updateBMI({ height, weight }) {
12
  const bmi = computeBMI(height, weight);
13
  const payload = {
14
    height,
15
    weight,
16
    bmi: Number.isFinite(bmi) ? Number(bmi.toFixed(4)) : null
17
  };
18
  bmiInstruction.update(JSON.stringify(payload));
19
}
20
21
// Later, when no longer needed:
22
// bmiInstruction.remove();

Best Practices for Instructions

• Prefer compact JSON strings so the model can easily parse state
• Update only when underlying state changes to avoid noise
• Use one instruction per cohesive state domain (e.g., BMI widget state)
• Keep tool descriptions short; let instructions carry dynamic state that tools manipulate

Example: Form Field Updater Tool

1
registry.addTool({
2
  toolName: "updateTicketField",
3
  description: "Update a field in the ticket creation form.",
4
  parameters: {
5
    type: "object",
6
    properties: {
7
      field: {
8
        type: "string",
9
        description: "Field to update",
10
        enum: ["priority", "sender", "email", "category", "subject", "body"]
11
      },
12
      value: {
13
        type: "string",
14
        description: "Value to set"
15
      }
16
    },
17
    required: ["field", "value"]
18
  },
19
  execute: async ({ field, value }) => {
20
    const elem = document.getElementById(field)
21
    if (elem) {
22
      elem.value = value
23
      return { success: true }
24
    } else {
25
      return { success: false, error: "Field not found" }
26
    }
27
  }
28
})

Example: Form Submission Tool

1
registry.addTool({
2
  toolName: "submitTicket",
3
  description: "Submit the ticket creation form and return all form values.",
4
  parameters: {
5
    type: "object",
6
    properties: {},
7
    additionalProperties: false
8
  },
9
  execute: async () => {
10
    const fields = ["priority", "sender", "email", "category", "subject", "body"]
11
    const data = {}
12
    fields.forEach(f => {
13
      const elem = document.getElementById(f)
14
      data[f] = elem ? elem.value : null
15
    })
16
17
    // Show success message
18
    document.getElementById("resultMsg").style.display = ""
19
    setTimeout(() => {
20
      document.getElementById("resultMsg").style.display = "none"
21
    }, 2400)
22
23
    return { success: true, data }
24
  }
25
})

Tool Design Best Practices

1. Clear Tool Names: Use descriptive, action-oriented names (e.g., "updateField", "submitForm", "toggleVisibility")
2. Comprehensive Descriptions: Explain what the tool does and when to use it
3. Proper Parameter Validation: Use JSON Schema to define clear parameter requirements
4. Error Handling: Return meaningful error messages when operations fail
5. Consistent Return Format: Always return objects with success/error indicators
6. DOM Safety: Check for element existence before manipulation
7. User Feedback: Provide visual feedback for user actions when appropriate

Return Format Guidelines

Tools should return objects that indicate success or failure:

• Success: { success: true, result: data } or { success: true, data: formData }
• Error: { success: false, error: "Error message" }
• Include relevant data in the response that the AI assistant can use

Form-Based Interface Guidelines

When creating form-based interfaces:

• Use semantic HTML with proper id attributes for form elements
• Create tools for both individual field updates and form submission
• Provide validation and user feedback mechanisms
• Consider accessibility and user experience in tool design