DescribeCustomAgent-阿里云帮助中心

Retrieves the detailed description of a custom agent based on the custom agent ID.

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

get

*All Resource

*

None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	No	The workspace ID.	56kv1pvl9uvt9**********bb
CustomAgentId	string	No	The custom agent ID.	ca-4y3ca4khkcu**********ysf

Response elements

Element	Type	Description	Example
	object	Schema of Response
Data	object	The response struct.
AgentType	string	The custom agent type. Valid values: Default: system-built-in custom agent Common: 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 custom agent ID.	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" } }
DefaultAgent	integer	Specifies whether the agent is displayed by default.	1
Description	string	The custom agent description.	Description for the test agent
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.	false
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 drawing a web report.	false
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 instructions.	Analytical framework: Monitor core metrics (GMV, order volume, UV, and conversion rate) on a daily, weekly, and monthly basis to analyze trends and identify year-over-year and month-over-month fluctuations. Segment by new vs. returning customers, channels, and regions to identify growth drivers and areas of weakness. Conduct funnel analysis based on user behavior paths (browse → add to cart → purchase) to pinpoint stages where user drop-off occurs.
IsScheduleTask	boolean	Specifies whether a periodic task is configured.	true
Knowledge	string	The knowledge.	Core metric definitions: GMV (Gross Merchandise Volume) refers to the total sum of order amounts, including both paid and unpaid orders. Order volume refers to the number of valid orders placed per day. UV (Unique Visitors) refers to the deduplicated number of users who visit the website or app. Conversion rate = paid orders / UV, reflecting the efficiency of traffic conversion.
KnowledgeConfigList	array<object>	The external knowledge bases.
	object	The external knowledge base structure.
AccessType	string	The access type. Valid values: mcp: MCP access dms_kb: DMS knowledge base access	mcp
KbUuid	string	The knowledge base ID.	kb-HZ-6anhdzx7hddf9*******obx
McpServerId	string	The MCP server ID.	nhdpt9adf6ac**********ca
KnowledgeSemanticConfigList	array<object>	The knowledge semantic configuration list.
	object	The knowledge semantic configuration struct.
DbId	string	The DMS database ID.	71991648
InstanceId	string	The DMS instance ID.	2190779
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 custom agent name.	Test agent name
NextRuntime	integer	The next run time of the periodic task.	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 referenced historical session ID.	5xyz...
ReleaseTime	string	The release time.	2025-12-11T14:04:32.000+00:00
ScheduleTaskConfig	object	The periodic task configuration.
CronExpression	string	The cron expression for time-based periodic scheduling.	0 0 0 ? * 1-7
Query	string	The question for the periodic task.	Analyze the data and provide the report
RelatedSessionId	string	The referenced historical session ID.	4m24*****mg7j2v
Status	string	The custom agent status. Valid values: NEW : New - unpublished. RELEASED : Published. DRAFT : Draft - unpublished. OFFLINE : Offline.	RELEASED
TextReportConfig	string	The text report format.	The text report requires that all numbers be written in Chinese numerals rather than 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 written in Chinese numerals rather than Arabic numerals.
WebReportTheme	string	The web report theme. Valid values: default: default journal: journal legacy: classic neobrutalism: stylized 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	Specifies 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********",
    "CallbackConfig": {
      "CallbackArgs": "{\"ID\":\"test\"}",
      "CallbackPrompt": "send web report to 123456@163.com",
      "CallbackTime": 0,
      "ToolId": "Mcp serverId (6te...g7a)\n",
      "Type": "Mcp"
    },
    "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}",
    "DefaultAgent": 1,
    "Description": "Description for the test agent",
    "DmsUnit": "cn-hangzhou",
    "ExecutionConfig": {
      "ForbiddenAppendDataSource": true,
      "SkipAskHuman": false,
      "SkipPlan": true,
      "SkipSqlConfirm": true,
      "SkipWebReportConfirm": false
    },
    "GmtCreated": "2025-12-11T14:04:32.000+00:00",
    "GmtModified": "2025-12-11T14:04:32.000+00:00",
    "Instruction": "Analytical framework:\n\nMonitor core metrics (GMV, order volume, UV, and conversion rate) on a daily, weekly, and monthly basis to analyze trends and identify year-over-year and month-over-month fluctuations.\nSegment by new vs. returning customers, channels, and regions to identify growth drivers and areas of weakness.\nConduct funnel analysis based on user behavior paths (browse → add to cart → purchase) to pinpoint stages where user drop-off occurs.",
    "IsScheduleTask": true,
    "Knowledge": "Core metric definitions:\n\nGMV (Gross Merchandise Volume) refers to the total sum of order amounts, including both paid and unpaid orders.\nOrder volume refers to the number of valid orders placed per day.\nUV (Unique Visitors) refers to the deduplicated number of users who visit the website or app.\nConversion rate = paid orders / UV, reflecting the efficiency of traffic conversion.",
    "KnowledgeConfigList": [
      {
        "AccessType": "mcp",
        "KbUuid": "kb-HZ-6anhdzx7hddf9*******obx",
        "McpServerId": "nhdpt9adf6ac**********ca"
      }
    ],
    "KnowledgeSemanticConfigList": [
      {
        "DbId": "71991648",
        "InstanceId": "2190779",
        "KnowledgeUuid": "7ca8f50d78234******e87",
        "Type": "sql_template"
      }
    ],
    "Modifier": "20372822********",
    "ModifierUserName": "HaoY*****",
    "Name": "Test agent 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": "5xyz...",
    "ReleaseTime": "2025-12-11T14:04:32.000+00:00",
    "ScheduleTaskConfig": {
      "CronExpression": "0 0 0 ? * 1-7",
      "Query": "Analyze the data and provide the report",
      "RelatedSessionId": "4m24*****mg7j2v"
    },
    "Status": "RELEASED",
    "TextReportConfig": "The text report requires that all numbers be written in Chinese numerals rather than Arabic numerals.\n\n\n",
    "UserSpecifiedSkillList": [
      "ski-sldk8v******3owd"
    ],
    "WebReportConfig": "The web report requires that all numbers be written in Chinese numerals rather than Arabic numerals.\n\n\n",
    "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.