Passing Plugin Parameters via API - 阿里云百炼 Agent Studio

Passing Parameters to Custom Plugins

This article demonstrates how the API invokes the custom parameter passing feature of an application using the Dormitory Agreement Content Query Tool as an example.

Custom plugin parameters are passed either through an associated Agent Application, or through a Plugin Node within a Workflow Application.

The example below shows how to pass custom plugin parameters in an Agent Application.

How to Use

Step 1: Create a Custom Plugin Tool

Skip this step if you have already created or imported a plugin.

Create a Custom Plugin

Navigate to the Plugins page in the Bailian console, click Add Custom Plugin, fill in the plugin information. If authentication is required, enable the Enable Authentication toggle and provide the corresponding authentication configuration.

Example plugin description: Dormitory Agreement Query Tool — retrieves a specific clause based on the provided numeric index.

Example plugin URL: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run

Example authentication configuration: Select User-level Authentication, set Location to Header, and Type to Basic.Note: The Plugin Description is a brief natural-language explanation of the plugin’s purpose, helping the large language model determine whether to invoke it for a given task.

Create a Tool

Fill in tool information and configure input and output parameters. Note the following:

The Tool Description helps the large language model better understand the tool’s functionality and usage scenarios. Use natural language and include usage examples where possible.
Choose meaningful parameter names, which help the model identify what information needs to be extracted.
The Parameter Description should concisely and accurately describe the function of each input parameter, aiding the model in understanding how to extract values.
For input parameters, the Parameter Transmission Method must be set to Business Pass-through.

In this example, the dormitory agreement content index article_index is configured as a business pass-through parameter.Set the tool name to Dormitory Agreement Query Tool, select POST as the request method, and application/json as the content type. Configure the input parameter article_index as type Number, transmission method Body, and mark it as Required. For the output parameter, set the name to article, description to "Dormitory Agreement Content", and type to String.

Test and Publish

Click Test Tool. Once testing passes, click Publish to deploy the plugin.

Step 2: Associate the Plugin with an Agent Application

A plugin tool can only be associated with an Agent Application residing in the same workspace.

On the published plugin card, click Add to Agent, then select the target Agent Application.
Alternatively, inside the Agent Application, click + Plugin, then select the desired custom plugin.
Finally, click Publish to deploy the updated application.

Step 3: API Invocation

Without Authentication: To invoke a custom plugin via API, pass plugin-specific parameters using the user_defined_params field under biz_params. Replace your_plugin_code with the actual plugin ID, and provide key-value pairs matching the plugin’s configured input parameters.

You can find the plugin ID on its plugin card.

In this example, we pass article_index = 2 to retrieve the second clause of the dormitory agreement and return the correct result.

import os
from http import HTTPStatus
# Recommended dashscope SDK version >= 1.14.0
from dashscope import Application

biz_params = {
    # Pass custom plugin input parameters for Agent Applications; replace 'your_plugin_code' with your actual plugin ID
    "user_defined_params": {
        "your_plugin_code": {
            "article_index": 2}}}

response = Application.call(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_APP_ID',
        prompt='Dormitory Agreement Content',
        biz_params=biz_params)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'Refer to documentation: https://help.aliyun.com/zh/model-studio/developer-reference/error-code')
else:
    print('%s\n' % (response.output.text))

Sample Response

The second provision of the Dormitory Agreement states:
"Roommates shall support, care for, learn from, and improve together; practice tolerance and humility, respect one another, and treat each other sincerely."

With Authentication Required: Add the user_defined_tokens field to biz_params to pass authentication tokens. Replace your_plugin_code with your actual plugin ID and provide the required authentication details.

biz_params = {
    "user_defined_params": {
        "your_plugin_code": {
            "article_index": 2
        }
    },
    "user_defined_tokens": {
        "your_plugin_code": {
            "user_token": "your_token_value"
        }
    }
}

​Passing Parameters to Custom Plugins

​How to Use

​Step 1: Create a Custom Plugin Tool

​Step 2: Associate the Plugin with an Agent Application

​Step 3: API Invocation

​Related Documentation

Passing Parameters to Custom Plugins

How to Use

Step 1: Create a Custom Plugin Tool

Step 2: Associate the Plugin with an Agent Application

Step 3: API Invocation

Related Documentation