in-Custom plug-ins

When the official plugins in Alibaba Cloud Model Studio do not meet your business requirements, you can create custom plugins to integrate your APIs and extend model capabilities.

Workflow

1. Create a plugin: Define the plugin's basic information.

2. Add a tool : Configure the specific API path, request parameters, and response data for the plugin.

3. Debug and publish: Test the API connectivity online and publish the tool once it works as expected.

4. Use in an application: Associate the plugin with an agent and call it through conversational testing or API integration.

Create a custom plugin

Custom development

Step 1: Create a plugin

1. Go to the Plug-ins page and click Create Plug-in.

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**: In natural language, provide a brief description of the plugin's features and use cases. This description helps the model determine when to call 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 - Under the same domain, different paths are treated 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, turn on 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)	Whether a Model Studio application must authenticate when calling your custom plugin. This depends on your API provider's security policy.
Authentication Type	Authentication includes two methods: service-level authentication and user-level authentication. - Location: You can place the authentication information in the request header or query string. Header: Places the authentication information in the Authorization field of the HTTP request header. This information is not visible in the URL. - Query: 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 is set to Authorization: Bearer . \ - Token (for service-level authentication): The authentication token from the API provider, such as an API key.

3. After you complete the form, click Confirm Create Plug-in > Create 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.

   Tool parametersTool 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 (/). This path is appended 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 or response 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 is used for POST requests. Form data is encoded as key-value pairs and transmitted with URL encoding. Key-value pairs are separated by ampersands (\&), and each key is separated from its value 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, an ampersand as %26, and an equal sign 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 the information that the parameter represents. For example, city.
Parameter Description: A concise and accurate description of the input parameter's function. This helps the model understand how to retrieve the parameter value. For example, if the parameter is date, you can describe it as a date and specify its format, such as yyyy-MM-dd.
Type: The data type of the parameter. * **Important ** 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: Select the correct method for how the parameter value is passed. - LLM Recognition: The parameter value is extracted from the user's input by the model. - Business Pass-through: The parameter value is passed directly from an external source without being processed or modified. When you call an application by using the DashScope SDK or an HTTP interface, business-through input parameters in a plugin are passed to the application by using biz_params and user_defined_params. 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, then returns the final answer. Like input parameters, output parameters must be described concisely and accurately, with minimal nesting. * **Important ** 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 the model with call examples to reduce missed or incorrect tool calls. This is useful when input parameters are complex and the model might construct them incorrectly.
Value: The input parameters that you expect the model to generate based on the user's query. For example, if a user enters "Check the weather in Hangzhou for tomorrow", the expected input parameters are {"city": "Hangzhou", "date": "2025-04-25"}.

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

3. Debug the tool online to verify that the API works.

Click Test Tool. If you enabled authentication, enter the authentication information and input parameter values, 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. Enter input parameter values manually or in code. For complex parameters, use the Code Editing mode to submit parameters and values in JSON format.

4. After the test passes, click Publish . Only Published tools can be called in an application.

Use a plugin

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 , hover over the 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 a 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 . 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 plug-in, 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 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 starting a conversation. You only need to enter the value once per session on this page.

  4. After the test is complete, Publish the application.

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

API

Get the tool ID

When calling a tool via an API, you must provide its tool ID.

1. In the Plugins , 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 associated plugin has business-through parameters or has User-level Authentication enabled, you need to use the biz_params parameter to pass the authentication information or business-through parameter information. See DashScope API Reference for Workflows and Legacy Agent Applications.

Manage custom plugins and tools

Delete a pluginImportant

Deleting a plugin also deletes all its tools, causing any applications that call the plugin to fail. This action is irreversible.

In the Plugins , find the target plugin and click Delete. Edit a plugin

1. In the Plugins , find the target plugin and click View Details.

2. In the upper-right corner, click Modify Plug-in, modify the plugin information, and save the changes.

Changes take effect immediately. If you modify the plugin URL, headers, or authentication information, tool calls might be affected. You must test and publish the tools again. Edit a tool After modifying a tool, test and publish it again for changes to take effect.

1. In the Plugins , find the plugin that contains the tool and click View Details.

2. In the row that contains the tool, click Modify , modify the tool information, and then click Save Draft.

3. Click Test Tool to debug the tool online.

4. After the run succeeds, click Publish.

Delete a toolImportant

Deleting a tool causes any applications that call it to fail. This action is irreversible.

1. In the Plugins , find the plugin that contains the tool and click View Details.

2. In the row that contains the tool, click Delete.

Error codes

The following table describes common error messages that may occur when publishing a tool.

Error code	Error message	Description
130040	The parameter description for xx is missing.	Cause: The description for the xx parameter is missing. Solution: Add the parameter description and publish the tool again.
130022	Failed to save the tool information. Check whether the sample parameters are correct.	Possible cause 1: An input or output parameter of the Object type has an empty sub-property. Solution: Click the icon at the end of the object's row to add a sub-property. Possible cause 2: The request method is GET, but an input parameter is of the Object type. Solution: GET requests do not support the Object type for input parameters. Select a different data type.