DocsICP FilingConsole
Documentation

ModifyCustomAgent

Updated at:
Copy as MD
Product
My Favorites

Modifies a custom agent in a personal or team workspace.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dms:ModifyCustomAgent

update

*All Resource

*

 None None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter

Type

Required

Description

Example
WorkspaceId

string

No

The workspace ID.

56kv1pvl9uvt9**********bb
CustomAgentId

string

Yes

The ID of the custom agent.

ca-4y3ca4khkcu**********ysf
Name

string

No

The name of the custom agent.

Test agent name
Description

string

No

The description of the custom agent.

Test agent description
DataJson

string

No

The specified data scope in JSON character string format.

  • General metric descriptions:

    • tableFlag: true indicates that a data scope is specified.

    • scope: The fixed value personal.

    • personal: The parameters for file and database types.

File type: Pass parameters in the following format:

  • DataSourceType: The fixed value remote_data_center.

  • FileId: The file ID.

  • Database: The database name returned by the ListDataCenterTable operation, which is usually the file name.

  • Tables: The table names returned by the ListDataCenterTable operation.

  • TableIds: The table IDs returned by the ListDataCenterTable operation.

  • RegionId: The current region.

{
  "tableFlag": true,
  "scope": "personal",
  "personal": {
    "DataSourceType": "remote_data_center",
    "FileId": "f-f0jksn001ibmkoo********6v2zn6",
    "Database": "diamonds.csv",
    "Tables": [
      "diamonds"
    ],
    "TableIds": [
      "35hfn94pxl********50pi"
    ],
    "RegionId": "cn-hangzhou"
  }
}

Database type: Pass parameters in the following format:

  • DataSourceType: The fixed value database.

  • DmsInstanceId: The DMS instance ID returned by the data center operation.

  • DmsDatabaseId: The DMS database ID returned by the data center operation.

  • FileId: The instance name. [Deprecated]

  • DbName: The database name returned by the data center operation.

  • Database: The database name returned by the data center operation.

  • Tables: The table names returned by the data center operation.

  • TableIds: The table IDs returned by the data center operation.

  • Engine: The DPI engine type (mysql or postgresql).

  • RegionId: The current region.

{
  "tableFlag": true,
  "scope": "personal",
  "personal": {
    "DataSourceType": "database",
    "DmsInstanceId": "284***8",
    "DmsDatabaseId": "769***45",
    "FileId": "pgm-bp15095e*******6t",
    "DbName": "pg_catalog",
    "Database": "pg_catalog",
    "Tables": [
      "pg_aggregate"
    ],
    "TableIds": [
      "5263****31"
    ],
    "Engine": "postgresql",
    "RegionId": "cn-hangzhou"
  }
}

{ "tableFlag" : true, "scope" : "personal", "personal" : { "DataSourceType" : "remote_data_center", "FileId" : "f-5qlrwaw10********s3gpw1z", "Database" : "Test table******.xlsx", "Tables" : [ "Sheet1" ], "TableIds" : [ "******" ], "RegionId" : "cn-hangzhou" } }
Instruction

string

No

The instructions.

  • Input limit: Maximum of 10,000 characters.

Analysis framework: 1. Monitor core metrics (GMV, order volume, UV, conversion rate) on a daily, weekly, and monthly basis, and analyze trend changes and year-over-year or month-over-month fluctuations. 2. Segment by new and existing customers, channels, and regions to identify growth drivers and weaknesses. 3. Conduct funnel analysis based on user behavior paths (browse → add to cart → pay) to locate churn points
Knowledge

string

No

The knowledge.

  • Input limit: Maximum of 10,000 characters.

Core metric definitions: 1. GMV (Gross Merchandise Volume) refers to the total order amount, including both successfully paid and unpaid orders. 2. Order volume is the number of valid orders placed per day. 3. UV (Unique Visitors) refers to the number of deduplicated users who visit the website or app. 4. Conversion rate = Number of paid orders / UV, reflecting the traffic conversion efficiency
KnowledgeConfigList

array<object>

No

The external knowledge bases.

object

No

The external knowledge base structure.

AccessType

string

No

The access type. If you do not specify this parameter, the default value is mcp. Valid values:

  • mcp: Access through MCP. You must pass the McpServerId parameter.

  • dms_kb: Access through DMS knowledge base. You must pass the KbUuid parameter.

Valid values:

  • mcp :

    Access through MCP.

mcp
KbUuid

string

No

The knowledge base ID.

kb-HZ-6anhdzx7hddf9*******obx
McpServerId

string

No

The ID of the MCP server.

nhdpt9adf6ac**********ca
KnowledgeSemanticConfigList

array<object>

No

The knowledge semantic configuration list.

object

No

The knowledge semantic configuration structure.

DbId

string

No

The DMS database ID.

69305251
InstanceId

string

No

The DMS instance ID.

2086427
KnowledgeUuid

string

No

The knowledge UUID.

7ca8f50d78*****1f4b8410f02e87
Type

string

No

The knowledge semantic type. Valid values:

  • sql_template: SQL template.

  • ossie_model: Ossie semantic view.

sql_template
UserSpecifiedSkillList

array

No

The list of user-specified skills.

string

No

The skill ID.

ski-sldk8v******3owd
RecommendQuestionList

array

No

The list of recommended questions.

  • You can configure up to 10 recommended questions.

string

No

The recommended question.

Help me find some business insight from this data
ExecutionConfig

object

No

The execution configuration.

ForbiddenAppendDataSource

boolean

No

Specifies whether to prohibit appending data sources in a session.

true
SkipAskHuman

boolean

No

Specifies whether to disable user inquiries during the process.

true
SkipPlan

boolean

No

Specifies whether to skip the plan confirmation step.

true
SkipSqlConfirm

boolean

No

Specifies whether to skip all SQL confirmations.

true
SkipWebReportConfirm

boolean

No

Specifies whether to skip the confirmation for generating a web report.

true
ScheduleTaskConfig

object

No

The scheduled task configuration.

CronExpression

string

No

The cron expression for time-based scheduling.

0 0 0,1 ? * 1-7
Query

string

No

The query for the scheduled task.

Analyze this data and provide a brief report
RelatedSessionId

string

No

The ID of the referenced historical session.

4m24*****mg7j2v
TextReportConfig

string

No

The text report format.

  • Input limit: Maximum of 10,000 characters.

The text report requires that all numbers be spelled out in words instead of using Arabic numerals
WebReportConfig

string

No

The web report format.

  • Input limit: Maximum of 50,000 characters.

The web report requires that all numbers be spelled out in words instead of using Arabic numerals
WebReportTheme

string

No

The web report theme. Valid values:

  • default: Default.

  • journal: Journal.

  • legacy: Legacy.

  • neobrutalism: Neobrutalism.

  • infographic: Infographic.

default
DMSUnit

string

No

The current DMS unit.

cn-hangzhou
CallbackConfig

object

No

The callback feature configuration.

CallbackArgs

string

No

The invoke parameters for callback tool calling.

{"ID":"test"}

CallbackPrompt

string

No

The prompt for generating invoke parameters for callback tool calling.

send web report to 123456@163.com

CallbackTime

integer

No

The invoke timing for callback tool calling.

0

ToolId

string

No

The callback tool identifier.

Mcp serverId (6te...g7a)

Type

string

No

The callback tool type.

Mcp

RelatedSessionId

string

No

The ID of the referenced historical session.

ski-sldk8v******3owd

Response elements

Element

Type

Description

Example

object

Schema of Response

Data

object

The returned struct.

AgentType

string

The custom agent type. Valid values:

  • Default: The system-built-in custom agent. Each workspace can have at most one Default type, and it cannot be deleted.

  • Common: A common custom agent.

Common
AliyunParentUid

string

The ID of the Alibaba Cloud main account.

16738266********
AliyunUid

string

The Alibaba Cloud account ID.

20372822********

CallbackConfig

object

The callback feature configuration.

CallbackArgs

string

The parameters to invoke callback tool calling.

{"ID":"test"}

CallbackPrompt

string

The prompt for generating parameters to invoke callback tool calling.

send web report to 123456@163.com

CallbackTime

integer

The timing to invoke callback tool calling.

0

ToolId

string

The callback tool identifier.

Mcp serverId (6te...g7a)

Type

string

The callback tool type.

Mcp

CreatorUserName

string

The name of the creator.

HaoY*****
CustomAgentId

string

The ID of the custom agent.

ca-4y3ca4khkcu**********ysf
DMSUnit

string

The current DMS unit.

cn-hangzhou
DataJson

string

The specified data scope in JSON string format.

{ "tableFlag" : true, "scope" : "personal", "personal" : { "DataSourceType" : "remote_data_center", "FileId" : "f-5qlrwaw10********s3gpw1z", "Database" : "Test table******.xlsx", "Tables" : [ "Sheet1" ], "TableIds" : [ "******" ], "RegionId" : "cn-hangzhou" } }
Description

string

The description of the custom agent.

Test agent description
DmsUnit

string

The current DMS unit.

cn-hangzhou
ExecutionConfig

object

The execution configuration.

ForbiddenAppendDataSource

boolean

Specifies whether to prohibit appending data sources in a session.

true
SkipAskHuman

boolean

Specifies whether to disable user inquiries during the process.

true
SkipPlan

boolean

Specifies whether to skip the plan confirmation step.

true
SkipSqlConfirm

boolean

Specifies whether to skip all SQL confirmations.

true
SkipWebReportConfirm

boolean

Specifies whether to skip the confirmation for generating a web report.

true
GmtCreated

string

The creation time.

2025-12-11T14:04:32.000+00:00
GmtModified

string

The modification time.

2025-12-11T14:04:32.000+00:00
Instruction

string

The instruction.

Analysis framework: 1. Monitor core metrics (GMV, order volume, UV, conversion rate) on a daily, weekly, and monthly basis, and analyze trend changes and year-over-year or month-over-month fluctuations. 2. Segment by new and existing customers, channels, and regions to identify growth drivers and weaknesses. 3. Conduct funnel analysis based on user behavior paths (browse → add to cart → pay) to locate churn points
IsScheduleTask

boolean

Indicates whether a scheduled task is configured.

false
Knowledge

string

The knowledge.

Core metric definitions: 1. GMV (Gross Merchandise Volume) refers to the total order amount, including both successfully paid and unpaid orders. 2. Order volume is the number of valid orders placed per day. 3. UV (Unique Visitors) refers to the number of deduplicated users who visit the website or app. 4. Conversion rate = Number of paid orders / UV, reflecting the traffic conversion efficiency
KnowledgeConfigList

array<object>

The external knowledge bases.

object

The external knowledge base structure.

AccessType

string

The access type. Valid values:

  • mcp: Access through MCP.

  • dms_kb: Access through the DMS knowledge base.

Valid values:

  • mcp :

    Access through MCP.

mcp
KbUuid

string

The knowledge base ID.

kb-HZ-6anhdzx7hddf9*******obx
McpServerId

string

The ID of the MCP server.

nhdpt9adf6ac**********ca
KnowledgeSemanticConfigList

array<object>

The knowledge semantic configuration list.

object

The knowledge semantic configuration structure.

DbId

string

The DMS database ID.

69305251
InstanceId

string

The DMS instance ID.

2844854
KnowledgeUuid

string

The knowledge UUID.

7ca8f50d78234******e87
Type

string

The knowledge semantic type. Valid values:

  • sql_template: SQL template.

  • ossie_model: Ossie semantic view.

sql_template
Modifier

string

The modifier.

20372822********
ModifierUserName

string

The name of the modifier.

HaoY*****
Name

string

The name of the custom agent.

Test agent name
NextRuntime

integer

The next run time of the scheduled task.

  • Timestamp format.

1767715200
OfflineTime

string

The offline time.

2025-12-11T14:04:32.000+00:00
RecommendQuestionList

array

The list of recommended questions.

  • You can configure up to 10 recommended questions.

string

The recommended question.

Help me find some business insight from this data
Region

string

The region.

cn-hangzhou
RelatedSessionId

string

The ID of the referenced historical session.

99crainsjnv*******vynid
ReleaseTime

string

The release time.

2025-12-11T14:04:32.000+00:00
ScheduleTaskConfig

object

The scheduled task configuration.

CronExpression

string

The cron expression for time-based scheduling.

0 0 0 ? * 1-7
Query

string

The query for the scheduled task.

Analyze this data and provide a brief report
RelatedSessionId

string

The ID of the referenced historical session.

4m24*****mg7j2v
Status

string

The status of the custom agent.

RELEASED
TextReportConfig

string

The text report format.

The text report requires that all numbers be spelled out in words instead of using Arabic numerals
UserSpecifiedSkillList

array

The list of user-specified skills.

string

The skill ID.

ski-sldk8v******3owd
WebReportConfig

string

The web report format.

The web report requires that all numbers be spelled out in words instead of using Arabic numerals
WebReportTheme

string

The web report theme. Valid values:

  • default: Default.

  • journal: Journal.

  • legacy: Legacy.

  • neobrutalism: Neobrutalism.

  • infographic: Infographic.

default
WorkspaceId

string

The workspace ID.

56kv1pvl9uvt9**********bb
ErrorCode

string

The error code.

success
ErrorMessage

string

The error message returned when the call fails.

Specified parameter Tid is not valid.
RequestId

string

Id of the request

67E910F2-4B62-5B0C-ACA3-7547695C****
Success

boolean

Indicates whether the request is successful. Valid values:

  • true: The request is successful.

  • false: The request fails.

true

Examples

Success response

JSON format

{
  "Data": {
    "AgentType": "Common",
    "AliyunParentUid": "16738266********",
    "AliyunUid": "20372822********\n",
    "CallbackConfig": {
      "CallbackArgs": "\t\n{\"ID\":\"test\"}\n",
      "CallbackPrompt": "send web report to 123456@163.com\n",
      "CallbackTime": 0,
      "ToolId": "Mcp serverId (6te...g7a)\n",
      "Type": "Mcp\n"
    },
    "CreatorUserName": "HaoY*****",
    "CustomAgentId": "ca-4y3ca4khkcu**********ysf",
    "DMSUnit": "cn-hangzhou",
    "DataJson": "{\n  \"tableFlag\" : true,\n  \"scope\" : \"personal\",\n  \"personal\" : {\n    \"DataSourceType\" : \"remote_data_center\",\n    \"FileId\" : \"f-5qlrwaw10********s3gpw1z\",\n    \"Database\" : \"Test table******.xlsx\",\n    \"Tables\" : [ \"Sheet1\" ],\n    \"TableIds\" : [ \"******\" ],\n    \"RegionId\" : \"cn-hangzhou\"\n  }\n}",
    "Description": "Agent test description",
    "DmsUnit": "cn-hangzhou",
    "ExecutionConfig": {
      "ForbiddenAppendDataSource": true,
      "SkipAskHuman": true,
      "SkipPlan": true,
      "SkipSqlConfirm": true,
      "SkipWebReportConfirm": true
    },
    "GmtCreated": "2025-12-11T14:04:32.000+00:00",
    "GmtModified": "2025-12-11T14:04:32.000+00:00",
    "Instruction": "Analysis framework:\n1. Monitor core metrics (GMV, order volume, UV, and conversion rate) on a daily, weekly, and monthly basis, and analyze trend changes and year-over-year or month-over-month fluctuations.\n2. Segment by new and existing customers, channels, and regions to identify growth drivers and weaknesses.\n3. Conduct funnel analysis based on user behavior paths (browse -> add to cart -> pay) to locate churn points",
    "IsScheduleTask": false,
    "Knowledge": "Core metric definitions:\n1. GMV (Gross Merchandise Volume) refers to the total order amount, including both successfully paid and unpaid orders.\n2. Order volume is the number of valid orders placed per day.\n3. UV (Unique Visitors) refers to the number of deduplicated users who visit the website or app.\n4. Conversion rate = paid orders / UV, reflecting the traffic conversion efficiency",
    "KnowledgeConfigList": [
      {
        "AccessType": "mcp",
        "KbUuid": "kb-HZ-6anhdzx7hddf9*******obx",
        "McpServerId": "nhdpt9adf6ac**********ca"
      }
    ],
    "KnowledgeSemanticConfigList": [
      {
        "DbId": "69305251",
        "InstanceId": "2844854",
        "KnowledgeUuid": "7ca8f50d78234******e87",
        "Type": "sql_template"
      }
    ],
    "Modifier": "20372822********",
    "ModifierUserName": "HaoY*****",
    "Name": "Agent test name",
    "NextRuntime": 1767715200,
    "OfflineTime": "2025-12-11T14:04:32.000+00:00",
    "RecommendQuestionList": [
      "Help me find some business insight from this data"
    ],
    "Region": "cn-hangzhou",
    "RelatedSessionId": "99crainsjnv*******vynid",
    "ReleaseTime": "2025-12-11T14:04:32.000+00:00",
    "ScheduleTaskConfig": {
      "CronExpression": "0 0 0 ? * 1-7",
      "Query": "Analyze this data and provide a brief report",
      "RelatedSessionId": "4m24*****mg7j2v"
    },
    "Status": "RELEASED",
    "TextReportConfig": "The text report requires that all numbers use Chinese numerals instead of Arabic numerals",
    "UserSpecifiedSkillList": [
      "ski-sldk8v******3owd"
    ],
    "WebReportConfig": "The web report requires that all numbers use Chinese numerals instead of Arabic numerals",
    "WebReportTheme": "default",
    "WorkspaceId": "56kv1pvl9uvt9**********bb"
  },
  "ErrorCode": "success",
  "ErrorMessage": "Specified parameter Tid is not valid.",
  "RequestId": "67E910F2-4B62-5B0C-ACA3-7547695C****",
  "Success": true
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.