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

Step 1: Create a plug-in

1. On the Plug-ins page, click Add Custom Plug-in.

   

2. Enter the plug-in information.

   

   Parameter	Description
   Plug-in Name	Enter a name that is easy to understand. The name can be in Chinese or English.
   Plug-in Description	Enter a description to help users better understand the plug-in's features and scenarios.
   Plug-in URL	The endpoint of the plug-in. For the same HTTP request, different paths are split into different APIs. These paths correspond to the Tool Path parameter that you configure when you create a tool. Different tools under the same plug-in use the same domain name. The tool path of each tool corresponds to an independent API. For example, a 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 the Tool Path. This indicates that the plug-in contains two tools.
   Headers	(Optional) If authentication is required, you can pass authentication information through a custom header.
   Enable Authentication	(Optional) Specifies whether authentication is required when a Model Studio application calls your custom plug-in. Whether authentication is required depends on the security policy of the API provider. : No authentication. : Authentication required.
   Authentication Type	The authentication methods are Service-level Authentication and User-level Authentication. If you select Service-level Authentication, a token is not required for each call. The token that you specify when you configure the plug-in is used for all calls. If you select User-level Authentication, a token is required for each call. Service-level Authentication Location: You can place the authentication information in the header or query. Header: Place the authentication information in the Authorization field of the HTTP request header. This information is not visible in the URL. Query: Place the authentication information in the URL. For example, https://example.com?api_key=123456. Parameter Name: If you place the authentication information in the query, specify the parameter used for authentication, such as "api_key". If you place the authentication information in the header, the parameter is "Authorization" by default. Type: basic: No content is added before the token that you provide. bearer: "Bearer" is added before the token. appcode: "APPCODE" is added before the token. The prefix is placed in the authentication parameter field. For example, if you select bearer, the call becomes ("Authorization": "Bearer <YOUR_TOKEN>"). Token: The authentication token obtained from the API provider, such as an API key. User-level Authentication Location: You can place the authentication information in the header or query. Header: Place the authentication information in the Authorization field of the HTTP request header. This information is not visible in the URL. Query: Place the authentication information in the URL. For example, https://example.com?api_key=123456. Parameter Name: If you place the authentication information in the query, specify the parameter used for authentication, such as "api_key". If you place the authentication information in the header, the parameter is "Authorization" by default. Type: basic: No content is added before the token that you provide. bearer: "Bearer" is added before the token. appcode: "APPCODE" is added before the token. The prefix is placed in the authentication parameter field. For example, if you select bearer, the call becomes ("Authorization": "Bearer <YOUR_TOKEN>"). When you call an application using the DashScope SDK or an HTTP interface, pass the user-level authentication information from the plug-in to the application through the biz_params and user_defined_tokens parameters. The value of user_token is the authentication information required by the plug-in. For more information, see Pass plug-in parameters through an API.

3. After you enter the information, click Confirm Create Plug-in > Create Tool or click Continue To Add Tool.

Step 2: Create a tool

1. Enter the tool information, configure the input and output parameters, and configure the advanced settings.

   

   Parameter	Description
   Tool Name	Enter a name that is easy to understand. The name can be in Chinese or English. Tool Name helps the model determine whether to call the tool for the current task.
   Tool Description	The tool description helps the model better understand the tool's features and scenarios. Describe the tool in natural language and provide examples. For example: "This tool is used to obtain the weather and temperature for a specified time and location. For example, 'Query the weather and temperature in Hangzhou for tomorrow'." Tool Description helps the model determine whether to call the tool for the current task.
   Tool Path	The relative path to the Plug-in URL. The path must start with a forward slash (/). This path is appended to the Plug-in URL to construct the complete URL.
   Request Method	You can select an HTTP method, such as GET or POST, to operate the API operation as needed.
   Submission Method	The codec of the request or response. application/json: The body of the request or response is data encoded in the JSON format. application/x-www-form-urlencoded: This method is used to encode form data in an HTTP request. It is mainly used for POST requests. It encodes form data into key-value pairs and transmits them through URL encoding. Multiple key-value pairs are separated by ampersands (&). Each key and value are separated by an equal sign (=). URL encoding converts special characters into a percent sign (%) followed by two hexadecimal digits. For example, a space is encoded as %20, & is encoded as %26, and = is encoded as %3D. The form data name=John Doe&age=25 is encoded as name=John%20Doe&age=25.
   Configure Input Parameters	Click Add Input Parameter and configure the parameters. All parameters are required. The Parameter Name should be as meaningful as possible. This helps the model understand what parameter information needs to be identified. For example, use a meaningful word such as city. The Parameter Description describes the function of the input parameter. It must be concise and accurate to help the model better understand how to retrieve the parameter. For example, for a date parameter, you can describe the date format, such as yyyy-MM-dd. Type specifies the parameter type. To add a new parameter under the Object type, click the icon at the end of the Object row. Set the Passing Method accurately. LLM Recognition: The value of the parameter needs to be extracted from the user input by the model. Business Pass-through: The value of the parameter is actively passed from an external source. The data is not processed or modified during the transmission. When you call an application using the DashScope SDK or an HTTP interface, pass the business pass-through parameter information in the plug-in to the application through the biz_params and user_defined_params parameters. For more information, see Pass plug-in parameters through an API.
   Configure Output Parameters	Click Add Output Parameter and configure the parameters. All parameters are required. The model filters and reorganizes the results returned by the API based on the definition of the output parameters and the user's question. The final answer is then returned to the user. Therefore, similar to input parameters, output parameters must be described as concisely and accurately as possible, with as few nested levels as possible.
   Advanced Configuration	(Optional) Add call examples for the model to reduce missed recalls and incorrect recalls. This is typically used in scenarios where input parameters are complex and the model is prone to construction errors. Providing examples improves the accuracy of the model in calling the plug-in. Value indicates the expected call input parameters that the model should construct when the user enters the current query.

2. After you complete the configuration, click Save Draft.

3. Test the tool API online to verify that it can be called successfully.

   Click Test Tool. If authentication is enabled, enter the authentication information and the values of the input parameters, and then click Start Running.

   If the run fails, adjust the configuration based on the error message in the Run Result section and test again until the run succeeds.

   

   You can enter the values for the input parameters manually or using code. For complex input parameters, use the Code Editing. In the code editor, you can submit the complete input parameters and their corresponding values in JSON format.

   

4. After the test succeeds, click Publish. Only published tools can be called in applications.

Step 3: Call the plug-in

Error messages when you publish a tool