Alibaba Cloud Model Studio:How to create a custom plug-in

Create a custom plug-in

Step 1: Create a plug-in

1. Log on to the Model Studio console. In the left-side navigation pane, choose Application Component > Custom plug-in.

2. Click Add Custom Plug-in.

   

3. Specify the plug-in information.

   

   Parameter	Description
   Plug-in Name	Enter a semantically meaningful name, in English or Chinese.
   Plug-in Description	Enter a description of the plug-in to help better understand the features and scenarios of the plug-in.
   Plug-in URL	The URL of the plug-in. Under the same HTTP request, different paths are split into different APIs (which is the Tool Path parameter in the tool section below). Different tools of a plug-in use the same URL, and each tool's path corresponds to an independent API. For example, the xx plug-in contains two APIs: Query: https://xxx.com/query Delete: https://xxx.com/delete In this example, https://xxx.com is the Plug-in URL. /query and /delete correspond to Tool Path. This indicates that the plug-in contains two tools.
   Headers	(Optional) When authentication is required, authentication information can be passed through the custom Header.
   Enable Authentication	(Optional) Specifies whether authentication is needed when applications call your custom plug-in. Whether authentication is required mainly depends on the security policy of the API provider. : No authentication. : Enable authentication.
   Authentication Type	Authentication includes Service-level Authentication and User-level Authentication. If you select Service-level Authentication, a token is not required for each call. Instead, you must specify a token when creating the plug-in. If you select User-level Authentication, a token is required for each call. Service-level Authentication Location: The authentication information can be included in the Header or the Query. Header: Include authentication details within the Authorization field of the HTTP request header to keep them concealed from the URL. Query: Include authentication information within the URL, for example, https://example.com?api_key=123456. Parameter Name: If you select Query, specify the parameter used for authentication, such as api_key. If you select Header, the parameter is Authorization by default. Type: basic: The provided token is used without any preceding content. bearer: Prepend "Bearer" to the token. appcode: Prepend "APPCODE" to the token. For example, if you select bearer: ("Authorization": "Bearer <YOUR_TOKEN>"). Token: This is the authentication token, such as an API Key from the API provider. User-level Authentication Location: The authentication information can be included in the Header or the Query. Header: Include authentication details within the Authorization field of the HTTP request header to keep them concealed from the URL. Query: Include authentication information within the URL, for example, https://example.com?api_key=123456. Parameter Name: If you select Query, specify the parameter that is required for authentication, such as api_key. If you select Header, the parameter is Authorization by default. Type: basic: The provided token is used without any preceding content. bearer: Prepend "Bearer" to the token. appcode: Prepend "APPCODE" to the token. For example, if you select bearer: ("Authorization": "Bearer <YOUR_TOKEN>"). When you call the application using the SDK or HTTP, pass the user-level authentication information from the plug-in to the application through the biz_params and user_defined_tokens parameters. The value passed by user_token is the authentication information required by the plug-in. For more information, see Parameter pass-through for applications.

4. Click Confirm Create Plug-in > Create Tool or click Continue To Add Tool.

Step 2: Create a tool

1. Specify the tool information, configure the input and output parameters, and set the advanced configurations.

   

   Parameter	Description
   Tool Name	Enter a semantically meaningful name, in English or Chinese. Tool Name helps the LLM determine whether it needs to call the tool for a given task.
   Tool Description	The tool description helps the LLM better understand the features and scenarios of the tool. Use natural language to write the description and provide examples if possible. For example: "This tool retrieves weather and temperature information for a specified time and location, such as 'Query the weather and temperature in Singapore tomorrow'". Tool Description helps the LLM determine whether it needs to call the tool for a given task.
   Tool Path	The relative path to the Plug-in URL. The field name must start with a forward slash (/). This path is appended to the Plug-in URL to construct the complete URL.
   Request Method	Choose from HTTP methods such as GET or POST to interact with the API interface according to your requirements.
   Submission Method	The encoding type of the request or response. application/json: Indicates that the body content of the request or response is encoded in JSON format. application/x-www-form-urlencoded: Used to encode form data in an HTTP request as key-value pairs and transmit them through URL encoding. Multiple key-value pairs are separated by &, and each key and value are separated by =. URL encoding converts special characters into a % followed by two hexadecimal digits. For example, a space is encoded as %20, & is encoded as %26, and = is encoded as %3D. Form data name=John Doe&age=25 is encoded as name=John%20Doe&age=25.
   Configure Input Parameters	Click Add Input Parameter and configure parameter information. All fields are required. Parameter Name should be meaningful if possible to help the LLM understand what parameter information needs to be identified. For example, a meaningful word like city. Parameter Description is the description of the function of the input parameter. It should be concise and accurate to help the LLM further understand how to generate the value for the parameter. For example, for date, describe it as The date, in the yyyy-MM-dd format. Type is the parameter type. To add new parameters under an Object, click the icon at the end of the row. Passing Method should be set accurately. LLM Recognition: The value of the parameter is extracted from the user's query by the LLM. Business Pass-through: The value of the parameter is passed from the outside, and the data is not processed or modified during the transmission. When calling the application using the SDK or HTTP, pass the value through the biz_params and user_defined_params parameters. For more information, see Parameter pass-through for applications.
   Configure Output Parameters	Click Add Output Parameters and configure parameter information. All fields are required. The LLM will filter and recombine the returns from the API based on the definition of the output parameters and the user's query, and then deliver the final response to the user. Therefore, like input parameters, output parameters need to be as concise and accurate as possible, with minimal nesting levels.
   Advanced Configuration	(Optional) Add call examples to reduce missed and incorrect recalls. This is for scenarios where input parameters are complex and the LLM frequently makes mistakes. Examples can help the LLM call the plug-in more accurately. Value is the expected input value constructed by the LLM when the user enters the corresponding query.

2. Click Save Draft.

3. Test the tool API.

   If the run fails, adjust the settings based on the error message shown in the Run Result.

   

   Input parameter values can be entered manually or through code. For complex input parameters, we recommend that you use Code Editing. Submit the input parameters and their values in the JSON format in the editor.

   

4. Once the test is passed, click Publish. Only published tools can be used by applications.

5. Once the test is passed, click Publish. Only published tools can be used by applications.

Call a custom plug-in

• Method 1: On the Tools page, add a published tool to an agent application.

  Tools can only be added to agent applications in the same workspace.

  1. Click Add To Application, and follow the instructions to add the plug-in to an agent application.

     

  2. On the application configuration page, you can find the tool added automatically.

     You can click Select Plug-in to add up to 10 tools. The agent application will select and call one or more appropriate tools based on user input.

     

  3. Test the plug-in to ensure it meets your requirements.

     • Without authentication: Enter your query in the input box and chat with the LLM.

     • With user-level or service-level authentication: Before starting the conversation, click to configure the authentication token. This configuration is required only once per session. But if you exit the page, you will need to configure it again next time.

       

     • If the Parameter Passing Method for the tool's input parameter is set to Business Pass-through: Before starting the conversation, click to configure the variable value. This configuration is required only once per session. But if you exit the page, you will need to configure it again the next time.

  4. After testing, publish the application.

• Method 2: In the Plug-ins list, add a tool under a plug-in to an agent application.

  1. Find the desired plug-in and click Add to Agent. Follow the instructions to add the plug-in to an agent application.

     Tools can only be added to agent applications in the same workspace.

     By default, only published tools are added. You can add up to 10 published tools to the agent application.

     

  2. Refer to Method 1 to test the plug-in and then publish the application.

• Method 3: In My Applications, add the tool to an agent or workflow application, test the plug-in, and publish the application. For more information, see Extend capabilities by plug-ins and Workflow application.

• Method 4: Use the plug-in by making an API call. If the plug-in has business pass-through parameters or user-level authentication enabled, pass the authentication or parameter information using the biz_params parameter. For more information, see Application API reference.

Obtain tool ID

The tool ID uniquely identifies a specific tool. When calling the tool through the API, you must accurately pass the tool ID.

1. In the Plug-ins list, find the desired plug-in and click View.

2. Hover the mouse over the icon next to the tool name.

3. Click the icon to copy the tool ID.

   

Manage custom plug-ins and tools

FAQ

Error message when publishing a tool