Alibaba Cloud Model Studio:Custom plugins

Create a custom plugin

Step 1: Create a plugin

1. Go to the Plugins page and click Create Plugin.

2. Enter the plugin information.

   Plug-in Name: Enter a descriptive name. Chinese and English are supported. Example: Dormitory Agreement Query Tool Test

   Plug-in Description: Briefly describe the plugin's features and purpose in natural language. This description helps the model decide when to use the plugin. Example: Queries the content of a specific dormitory agreement entry based on the input numeric index.

   Plug-in URL: The access endpoint of the plugin. Example:https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run Model Studio treats different paths under the same domain as different APIs. These paths correspond to the Tool Path you configure when creating a tool. Tools within the same plugin share a domain name, but each tool's path maps to a unique API. For example, a plugin contains two APIs: Query: https://xxx.com/query Delete: https://xxx.com/delete In this example, https://xxx.com is the Plug-in URL, while /query and /delete are the Tool Path values. This indicates that the plugin contains two tools.

   If authentication is required, enable the Enable Authentication switch and enter the authentication settings.

   Authentication parameters

   Headers (Optional)	If authentication is required, you can pass authentication information in a custom header.
   Enable Authentication (Optional)	Determines whether an application must provide authentication to call your custom plugin. This depends on your API provider's security policy.
   Authentication Type	There are two authentication methods: service-level authentication and user-level authentication. Location: You can place the authentication information in the request header or query string. Header: This option places the authentication information in the Authorization header of the HTTP request, keeping it hidden from the URL. Query: This option places 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 string, specify the parameter name used for authentication, such as api_key. If you place it in the header, the parameter is Authorization by default. Type: basic: Does not add any prefix to the token you provide. bearer: Adds the Bearer prefix to the token. appcode: Adds the APPCODE prefix to the token. The prefix is included in the authentication field. For example, if you select bearer, the Authorization header becomes Authorization: Bearer <YOUR_TOKEN>. Token (for service-level authentication): The authentication token from the API provider, such as an API key.

3. After completing the form, click Confirm Create Plug-inCreate Tool or click Continue to Add Tool.

Step 2: Create a tool

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

   In this example, enter "Dormitory Rules Query Tool" for Tool Name and "Queries the content of a specific dormitory rule based on the input numeric index" for Tool Description. Set the Tool Path to /article, select POST for the Request Method, and select application/json for the Submission Method. For the input parameter, set the parameter name to article_index, the parameter description to "index", and the type to Number. This parameter is passed in the Body, is required, and its passing method is LLM recognition. For the output parameter, set the parameter name to article, the parameter description to "dormitory rule content", and the type to String. In the advanced settings, the user input query is "Query the content of the corresponding dormitory rule based on the input index value", and the value of the article_index input parameter is 5.

   Tool parameters

   Tool information

   Tool Name	Enter a descriptive name. Chinese and English are supported.
   Tool Description	A brief description of the tool's features and use cases. This helps the model decide when to call the tool. Use natural language and provide examples where possible.
   Tool Path	The relative path to the Plug-in URL. The path must start with a forward slash (/). The system appends this path to the Plug-in URL to construct the full request URL.
   Request Method	Select GET or POST as the request method for calling the API.
   Submission Method	The encoding type for the request body. application/json: The body content is JSON-formatted data. application/x-www-form-urlencoded: Encodes form data as key-value pairs. This encoding method applies to POST requests. It encodes form data into key-value pairs, separates pairs with ampersands (&), and separates keys from values with equal signs (=). The data is then URL-encoded, which converts special characters into a percent sign (%) followed by two hexadecimal digits. For example, a space is encoded as %20, & as %26, and = as %3D. Example: name=John Doe&age=25 is encoded as name=John%20Doe&age=25.

   Configure input and output parameters

   Configure Input Parameters	Click Add Input Parameter to configure parameters.
   	Parameter Name: Use a descriptive name to help the model understand what the parameter represents. For example, city.
   	Parameter Description: A concise and accurate description of the function of the input parameter. This helps the model better understand how to retrieve the parameter value. For example, for a parameter named date, you can describe it as a date and also specify its format, such as yyyy-MM-dd.
   	Type: The data type of the parameter. Sub-properties of an Object type cannot be empty. Click the icon at the end of the object's row to add a sub-property.
   	Passing Method: Defines how the parameter value is passed. This setting is critical for correct operation. LLM Recognition: The model extracts the parameter value from the user's input. Business Pass-through: The system passes the parameter value directly from an external source without processing or modification. When you call an application by using the DashScope SDK or an HTTP API, the system passes input parameters of the business pass-through type to the application by using biz_params and user_defined_params. For more information, see Pass parameters to an application.
   Configure Output Parameters	Click Add Output Parameters and configure the parameters. All parameters are required. The model uses the output parameter definitions to filter and restructure the API response based on the user's query, and then returns the final answer. Like input parameters, output parameters must be described concisely and accurately, with minimal nesting. Both GET and POST request methods support the Object type for parameters. However, sub-properties of an Object type cannot be empty. Click the icon at the end of the object's row to add a sub-property.

   Advanced configuration (Optional)

   Advanced Configuration	Provide call examples to help the model avoid missed or incorrect tool calls. If input parameters are complex and the model might construct them incorrectly, providing examples improves the call accuracy.
   	Value: Specifies the invocation parameters that you expect the model to generate from a user's query. For example, for the user input "What is the weather in Hangzhou tomorrow?", the expected parameters are {"city": "Hangzhou", "date": "2025-04-25"}.

2. After completing the configuration, click Save Draft.

3. Debug the tool online to verify that the API is callable.

   Click Test Tool. If you enabled authentication, enter the authentication information and input parameter values. 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 input parameter values manually or as code. For complex parameters, use Code Editing. In the code editor, you can submit the complete JSON-formatted input parameters and their corresponding values.

4. After the test passes, click Publish. Applications can only call tools that are Published.

Console

• Method 1: Publish the plugin as an MCP service, and then add the service to an agent application.

  Step 1: Publish the plugin as an MCP service

  1. On the Plugins page, hover over the target plugin card and click Publish as MCP Service.

     If the plugin has already been converted to an MCP service, the button changes to View MCP Service. Click it to go to the MCP Management page and view the service details.

  2. After successful publication, you can view the details of the MCP service on the MCP Management page, including the service name, description, and ID.

  Step 2: Add the MCP service to an agent application

  1. Go to the orchestration canvas of the Agent Application application. In the MCP block, click +.

  2. In the Select MCP Service panel, switch to the Custom MCPS tab, find the MCP service converted from the plugin, and click Add All to add it to the application.

     You can also click Convert from Plugin to MCP to directly publish a plugin that has not yet been converted.

  3. Test whether the plugin works as expected.

     • No authentication: Chat with the model in the input box to test the plugin's functionality.
     • user-level authentication or service-level authentication: Before you start a conversation, click to configure the authentication token. You only need to configure the token once per session on this page.
     • If the Passing Method for a tool's input parameter is set to Business Pass-through, you must click to configure the variable value before you start a conversation. You only need to enter the value once per session on this page.

  4. After completing the test, Publish the application.

• Method 2: On the Application Management page, go to the orchestration canvas for your Agent Application application, add the MCP service from the MCP block, test its functionality, and then Publish the application.

API

The tool ID identifies a specific tool. When you call a tool via an API, you must pass the correct tool ID to ensure the system correctly identifies the request.

1. In the Plugins list, find the plugin that contains the tool and click View Details.
2. Hover the pointer over the icon next to the tool name.
3. Click the icon to copy the tool ID.

• When you call an application by using an API, if the application's plugin uses business pass-through parameters or requires User-level Authentication, you must use the biz_params parameter to pass the authentication information or pass-through parameter information. For more information, see DashScope API Reference for Workflows and Legacy Agent Applications.