Custom plugins and tools

I. Core Concepts

• Plugin : A collection of tools used to standardize the description of capabilities and authorization methods, making them easy to reuse in intelligent agents.
• Tool : A specific capability unit within a plugin, corresponding to an API call. It defines the request method, URL, input parameters, output parameters, etc.

Target audience

Product, R&D, and operations staff can all use it; it is recommended that members with basic interface knowledge complete the tool configuration and integration testing.

II. Creating Plugins

1. Go to HelpKnow AI employee configuration , click Manage Plugins , and enter the plugin page.
2. Select "Custom Plugin ," click "Create New Plugin" on the right, and fill in the following information in the pop-up window:
   • Plugin Name : Use standardized naming conventions to distinguish the purpose, such as "helpknow platform related plugins".
   • Plugin Description : This section describes which tools the plugin includes and in what scenarios they are used, facilitating subsequent identification and reuse.
   • Authorization method : Choose based on whether the interface has unified authentication. After configuring unified authentication at the plugin level, all tools below will use the same authentication.
3. Click " Create" to enter the plugin details page.

Recommendation: Group tools related to the same platform under one plugin to unify the management of authentication and common headers.

III. Creating a new tool within the plugin

1. On the plugin details page, click "Create New Tool" and fill in the basic information:
   • Tool name : Describe it using "verb + noun", such as "Get list of agents".
   • Tool ID : A unique identifier that supports letters, numbers, and underscores, such as GET_BOT_LIST.
   • Tool Description : Explains the use cases and functions to help large models understand when to call it.
2. Configure the request address and method :
   • Methods : GET/POST/PUT/DELETE.
   • URL : You can enter a complete address or a relative path based on the plugin's base URL. Example: https://api.helpbots.ai/api/chats/agent-list

IV. Input Parameter Configuration

Input parameters constrain what large models must provide when calling the tool, and are divided into four categories: Header, Path, Query, and Body . Multiple parameters can be added to each category.

General Field Description

1) Header

Place authentication and general request headers, such as Authorization: Bearer and Content-Type: application/json.

2) Path

Used for placeholders in RESTful paths, such as order_id in /orders/{order_id}. This parameter is configured to include it in the path if needed; refer to the example for the format using {}.

3) Query

URL query string parameters, such as ?page=1&page_size=20. Common uses include: pagination, sorting, filtering conditions, time windows, etc. This type of parameter does not need to be specified in the path.

4) Body

Request body parameters (commonly used in POST/PUT). Supports nested structures of objects and arrays . Sub-items can be added to define hierarchical fields.

Naming recommendations: Focus on business needs and model readability, and avoid excessive abbreviations; if necessary, supplement the description with enumeration values and format requirements (such as timestamp/ISO8601).

V. Output Parameter Configuration

Extract the fields that are meaningful to the model from the original response; meaningless IDs and error codes can be discarded.

Common configuration methods

• Top-level object : such as data.
• List fields : such as list (type: Array).
• Sub-item fields : Continue adding to ArrayItem, such as add_time (creation time, string) and model (question-answer model, string).

Example: Output structure definition

 {
  "data": {
    "list": [
      {
        "add_time": "2024-12-01 10:00:00",
        "model": "gpt-4o-mini
      }
    ]
  }
}

The above is just a structural example. Please set the fields according to the actual interface return fields, and try to retain the key fields that can directly answer the user's question to reduce the secondary understanding cost of the model.

VI. Debugging (Self-test before adding to AI employees)

1. Click "Debug" in the upper right corner of the Tools page.
2. Complete the values for each type of input parameter (Header / Path / Query / Body) on the Input tab.
3. Click Run , and check the Output tab to see if the response and mapping match expectations:

• If the original response is normal but the output is empty, check whether the hierarchy and field names of the output parameters are consistent with the response.
• If an error response is returned, please double-check whether the configuration matches the interface requirements, or whether the problem lies with the interface provider.

VII. Release and Launch

1. Once the tool has been successfully debugged , click "Save" to apply the changes immediately .

   

2. Add your configured tools to the AI employee's tools module.
3. (Optional) Describe the usage conditions of the tool in the AI employee settings , such as "When user information includes content such as 'Where is my order?' or 'When will it be shipped?', it can be determined that the user's intention is to query the order. When the user provides an order number, the Get_order tool can be used to query the user's order." This allows the AI to use the tool more flexibly to meet business needs.

Tool Configuration Guidelines

• A tool should do only one thing : correspond to a single API, making it easy to debug and trace.
• Input descriptions should be readable : written for both model and business colleagues, avoiding abbreviations and using natural language as much as possible.
• Simplify the output : retain key fields; for list fields, it is recommended to limit necessary sub-items.
• Unified authentication : Place it in the plugin layer as much as possible; only supplement a few differentiated headers in the tool layer.
• Fault tolerance and prompts : Provide clear error messages for common error codes to facilitate frontline problem localization.

Example for reference: Retrieving a list of agents (GET)

Method and address: GET https://api.helpbots.ai/api/chats/agent-list

Input parameters

Output parameters

 {
  "data": {
    "list": [
      {
 "add_time": "2024-12-01 10:00:00",
 "model": "gpt-4o-mini
 }
    ]
  }
}