Custom plugins

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-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.

   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. 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: 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. 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 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.

1. Go to the Plugins page and click Import from Marketplace.

2. If this is your first time importing an API from Alibaba Cloud Marketplace as a plugin, you must authorize a service-linked role.

   Alibaba Cloud account

   If you are logged in to Model Studio with an Alibaba Cloud account, select the checkbox to agree to the terms in the Service-linked Role Authorization dialog box, and then click Confirm Authorization.

   The dialog box displays the role name as AliyunServiceRoleForSFMAccessCloudAPI and the role policy as AliyunServiceRolePolicyForSFMAccessCloudAPI, which authorizes Alibaba Cloud Model Studio to access your Alibaba Cloud Marketplace product list and make API calls based on the plugin configuration.

   RAM user (sub-account)

   If you are logged in to Model Studio with a RAM user (sub-account), select the checkbox to agree to the terms in the Service-linked Role Authorization dialog box. When you click Confirm Authorization, a prompt appears.

   An Authorization Failed dialog box appears, indicating that the current user does not have permission to create the service-linked role. The service-linked role name is AliyunServiceRoleForSFMAccessCloudAPI.

   This error occurs because the RAM user (sub-account) does not have permission to create a service-linked role. Follow these steps to grant the permission. After authorization, the RAM user can import plugins from Alibaba Cloud Marketplace to Model Studio or use plugins that are already imported by the Alibaba Cloud account.

   1. Grant the RAM user (sub-account) permission to create a service-linked role.

      1. Log in to the RAM console by using an Alibaba Cloud account.

      2. In the left-side navigation pane, choose Permissions > Policy.

      3. Click Create Policy.

      4. In the Script Editor, enter the corresponding content from the following script into the Effect, Action, Resource, and Condition fields.

         {
             "Action": [
                 "ram:CreateServiceLinkedRole"
             ],
             "Resource": "*",
             "Effect": "Allow",
             "Condition": {
                 "StringEquals": {
                     "ram:ServiceName": "cloundapi-access.sfm.aliyuncs.com"
                 }
             }
         }

      5. Click OK.

      6. Set a name for the policy and click OK.

         The Name is set to service-linked role.

      7. In the left-side navigation pane, choose .

      8. Find the RAM user (sub-account) that you want to authorize and click Actions in the Add Permission column.

      9. Select the policy that you just created and click Add Authorization.

         The RAM user (sub-account) now has permission to create a service-linked role.

         In the Resource Scope section, select Account Level. From the policy filter drop-down list, select Custom Policy to find and select the target policy.

   2. The RAM user can now import plugins from Alibaba Cloud Marketplace to Model Studio or use plugins already imported by the Alibaba Cloud account.

      Return to the Alibaba Cloud Model Studio console, click Import from Marketplace, select the checkbox to agree to the terms in the Service-linked Role Authorization dialog box, and then click Confirm Authorization.

3. In the Import Plug-ins from Marketplace dialog box, click Click to View to go to Alibaba Cloud Marketplace and enable the required API.

4. Go to the Marketplace page and wait until the Status of the product changes to Enabled.

   This page also provides the AppKey, AppSecret, and AppCode for the API. If the plugin requires authentication, you can get the authentication information from this page.

5. After the API is enabled, return to the Alibaba Cloud Model Studio console and click Import from Marketplace to reopen the Import Plug-ins from Marketplace dialog box. Select the enabled API, click OK, and the system redirects you to the Tools page.

6. Plugins imported from Alibaba Cloud Marketplace are in a draft state. You must test and publish them before use.

   1. In the row that contains the tool, click Debug to go to the Tool Test page.

   2. Enter the parameters and click Start Running.

      A Success status indicates the API is working correctly. Otherwise, use the error messages to adjust the configuration.

   3. Return to the Edit Tool page and click Publish to publish the tool.

      When you import a plugin from Alibaba Cloud Marketplace, the system autofills the input and output parameters, but some information may be missing. When you publish the tool, review any errors that prevent publishing and fix them based on the prompts.

      For example, if the Tool name exceeds the 20-character limit, the character count to the right of the input box will appear in red (such as 22/20). You must shorten the name to meet the limit before you can publish.

   4. Applications can only call tools that are Published and Enable.

      Also, ensure that the Debug status of the tool is Successful.

Get the tool ID

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.