AssistantTool#

Assistant Tool is a system extension mechanism within the Scripting application that enhances the capabilities of an intelligent assistant (Assistant). By defining and implementing an Assistant Tool, developers can provide the Assistant with auxiliary functionalities such as device capability access, file reading/writing, and data analysis. This improves both the intelligence and practicality of the Assistant.

This document uses an example tool, "Request Current Location", to illustrate the full implementation process, including tool creation, configuration file explanation, execution logic, and detailed descriptions of various functions.

1. Tool Creation Process#

1. Open any scripting project and click the “Add Assistant Tool” button in the file manager interface.
2. Fill in the relevant information about the Assistant Tool in the configuration popup window.
3. After clicking “Save,” the system will automatically generate two files in the script:

• assistant_tool.json: Describes the tool’s metadata and parameter information.
• assistant_tool.tsx: Implements the tool’s execution logic.

2. Configuration File: assistant_tool.json#

This file declares the basic information and behavior settings of the tool. Below is a sample content and explanation of each field:

1{
2  "displayName": "Request Current Location",
3  "id": "request_current_location",
4  "description": "This tool allows you to request the one-time delivery of the latitude and longitude of the user’s current location.",
5  "icon": "location.fill",
6  "color": "systemBlue",
7  "parameters": [],
8  "requireApproval": true,
9  "autoApprove": true,
10  "scriptEditorOnly": false
11}

Field Descriptions:#

3. Execution Logic Example: assistant_tool.tsx#

1type RequestCurrentLocationParams = {}
2
3const locationApprovalRequest: AssistantToolApprovalRequestFn<RequestCurrentLocationParams> = async (
4  params,
5) => {
6  return {
7    message: "The assistant wants to request your current location.",
8    primaryButtonLabel: "Allow"
9  }
10}
11
12const requestCurrentLocation: AssistantToolExecuteWithApprovalFn<RequestCurrentLocationParams> = async (
13  params,
14  {
15    primaryConfirmed,
16    secondaryConfirmed,
17  }
18) => {
19  try {
20    const location = await Location.requestCurrent()
21    if (location) {
22      return {
23        success: true,
24        message: [
25          "The user's current location info:",
26          `<latitude>${location.latitude}</latitude>`,
27          `<longitude>${location.longitude}</longitude>`
28        ].join("\n")
29      }
30    }
31    return {
32      success: false,
33      message: "Failed to request user's current location, ask user to check the device's location permission."
34    }
35  } catch {
36    return {
37      success: false,
38      message: "Failed to request user's current location, ask user to check the device's location permission."
39    }
40  }
41}
42
43const testRequestLocationApprovalFn = AssistantTool.registerApprovalRequest(
44  locationApprovalRequest
45)
46
47const testRequestLocationExecuteFn = AssistantTool.registerExecuteToolWithApproval(
48  requestCurrentLocation
49)
50
51// Test the tool in the script editor:
52testRequestLocationApprovalFn({})
53testRequestLocationExecuteFn({}, {
54  primaryConfirmed: true,
55  secondaryConfirmed: false
56})

4. AssistantTool Registration Functions Explained#

1. registerApprovalRequest#

Registers a function to request user approval before executing the tool.

1function registerApprovalRequest<P>(
2  requestFn: AssistantToolApprovalRequestFn<P>
3): AssistantToolApprovalRequestTestFn<P>

Parameters:

• requestFn(params, scriptEditorProvider?): Returns a prompt with messages and button labels.
• params: Input parameters for the tool.
• scriptEditorProvider: Available only when scriptEditorOnly is set to true, provides file access for the script.

Return Value:

A test function for simulating approval requests in the script editor.

2. registerExecuteToolWithApproval#

Registers an execution function that requires user approval.

1function registerExecuteToolWithApproval<P>(
2  executeFn: AssistantToolExecuteWithApprovalFn<P>
3): AssistantToolExecuteWithApprovalTestFn<P>

Parameters:

• params: Input parameters for execution.
• userAction: User's choice in the approval prompt:

1type UserActionForApprovalRequest = {
2  primaryConfirmed: boolean
3  secondaryConfirmed: boolean
4}

• scriptEditorProvider: Same as above.

Return Value:

Returns an object:

1{
2  success: boolean
3  message: string
4}

• success: Whether execution succeeded.
• message: Message returned to the Assistant.

3. registerExecuteTool#

Registers a tool that does not require user approval.

1function registerExecuteTool<P>(
2  executeFn: AssistantToolExecuteFn<P>
3): AssistantToolExecuteTestFn<P>

Use Case: Suitable for non-sensitive operations or those that don’t involve device permissions.

4. Testing Functions#

Each registration function returns a test function that can be used in the script:

1testApprovalRequestFn({ ...params })
2testExecuteFn({ ...params }, {
3  primaryConfirmed: true,
4  secondaryConfirmed: false,
5})
6testExecuteToolFn({ ...params })

5. ScriptEditorProvider Interface#

When scriptEditorOnly: true is set, the system provides a ScriptEditorProvider interface that allows access to the script project’s file system and syntax info.

Capabilities include:

• File read/write (read, update, write, insert, replace)
• Diff comparison (openDiffEditor)
• Linting results (getLintErrors)
• List all files/folders in the project

Useful for tools that edit scripts, perform formatting, or batch modifications.

6. Execution and User Experience Flow#

1. The Assistant determines whether to invoke a tool during a conversation.
2. If the tool requires approval, a dialog box is displayed:
   • The prompt is provided by registerApprovalRequest.
   • Once the user clicks “Allow,” the tool logic is executed.
3. Execution results are returned to the Assistant through the message field, and shown to the user.

7. Tools That Don’t Require Approval#

If you don’t want to show an approval prompt, simply use registerExecuteTool and set requireApproval: false in assistant_tool.json.

1AssistantTool.registerExecuteTool<MyParams>(async (params) => {
2  return {
3    success: true,
4    message: "Tool executed successfully."
5  }
6})

8. Summary#

Assistant Tool is an extensible module provided by the Scripting application, supporting scenarios such as user authorization, file manipulation, and system-level access. The development process includes:

1. Creating the tool in a scripting project;
2. Configuring its metadata;
3. Implementing and registering the logic functions;
4. Testing tool behavior with test functions;
5. Triggering tool execution automatically or manually within Assistant conversations.