CreateManagedAgent
Creates a managed Harness agent in a specified workspace, configures the harness, model, skills, and runtime resources, and deploys it asynchronously.
Operation description
Creates an agent by using a platform-managed runtime framework. This corresponds to the "Managed Harness" creation method in the console, where you can configure the model, instructions, and skills.
Required configurations
Submit name, model, and runtime. The runtime parameter must include both compute and sessionPolicy. The agent is deployed and run by the platform, so you do not need to provide a code package or container image.
Harness and model
| Harness | Model and connector configurations |
qwenpaw | If harness is omitted during creation, this type is used by default. Set model.modelConnectionId to the workspace model connection ID, and set model.modelName to the name of the model created under this connection. |
qodercli | The qodercli connector must be enabled in the workspace. Set model.modelConnectionId to the model identifier returned by ListConnectorModels. model.modelName can be omitted. |
harness is an object, such as {"type":"qwenpaw"}. For qodercli, set harness.configuration.connectorServiceAccountKey to the account key record ID returned by ListConnectors, not the original service account key. This parameter can be omitted if there is only one key record, but must be specified if there are multiple records. connectorServiceAccountName is the account name. Do not specify these two binding fields for qwenpaw.
The harness type cannot be changed after creation.
Instructions, templates, and skills
skills uses the skill names in the workspace AI registry. If sourceType=REFERENCE, versions are referenced by versionSelector: use LABEL with a tag name, or VERSION with a specific version number. If the selector is omitted, LABEL/latest is used. If sourceType=STATIC, static files bundled with the package are used, and no version selector is provided.
For template.aiRegistry, specify the agent template name and an optional version. If the version is omitted during creation, the published version is resolved and fixed. When a template is used, instruction, promptVariables, and subAgents are derived from the template, and the corresponding fields in the current request do not take effect. Explicit skills and template skills are recorded separately. You can query the target and effective versions by using configuredSkills and skills.
If no template is used, you can set instructions by using instruction, declare variables by using promptVariables, and configure up to 20 sub-agents by using subAgents. The name and instruction of a sub-agent cannot be empty, and the name of each sub-agent must be unique. Tools currently use tools[].type=MCP.
Runtime configurations and mounts
Omitted fields in runtime.hpa use the following default values:
| Field | Default value | Valid values and description |
enabled | false | Specifies whether to enable elastic scaling. |
minSandboxCount | 1 | The minimum number of instances. Valid values: 0 to 100. |
maxSandboxCount | 10 | The maximum number of instances. Valid values: 0 to 100. The value cannot be less than the minimum number. |
maxConcurrentSessionsPerSandbox | 20 | The maximum number of concurrent sessions per instance. Valid values: 1 to 20. |
sessionTtlSeconds | 600 | The maximum idle time of a session, in seconds. Valid values: 60 to 86400. |
If sessionPolicy.type=ISOLATED_HEADER_FIELD, you must provide headerName. Do not specify this parameter for other policies.
If network is provided, you must specify both accessInternet.enabled and accessVpc.enabled. Actual access is restricted by the workspace network configurations.
The total number of ossMounts and agenticFsMounts cannot exceed 10. The mount target mountPath uses an absolute path in the container, such as /data/train. It cannot conflict with platform-reserved directories, and cannot be duplicated or form parent-child directory overwrites.
File mounts are used to allow the agent to access persistent data. When you use AgenticFS, you can first complete the access point authorization by using GetWorkspaceAgenticFsMountRamAuthorizeUrl.
The path for an OSS mount must be a non-empty directory prefix in a bucket. The server for an AgenticFS mount is the access point domain name, without a protocol, port, or path. The path is an existing non-empty relative directory in the access point. You cannot mount the root directory of the access point. If readOnly is omitted, the default value is false.
environment.variables configures environment variables, and environment.credentialReferences references workspace credentials. Environment variable names must be non-empty and unique, and values must be strings.
Query deployment results
A successful response indicates that the request is accepted. Save the agentId and use GetManagedAgent to query latestVersionStatus, status, and sandboxPhaseCounts to confirm the configuration processing and instance status. clientToken is a reserved query parameter and currently does not provide idempotency guarantees.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:CreateManagedAgent |
create |
*ManagedAgent
|
None | None |
Request syntax
POST /workspaces/{workspaceId}/managed-agents HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-1 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| body |
object |
No |
The request body. |
|
| contextConfiguration |
object |
No |
The optional JSON object. Only |
|
| enabled |
boolean |
No |
The optional Boolean value. Null is not accepted. If this field is omitted during creation, the value is false. If it is omitted during an update, the current value is retained and cannot be automatically filled with false by the client. When updated to true, saved |
true |
| bindings |
array<object> |
No |
The optional array. Null or null items are not accepted. Each item only allows |
|
|
object |
No |
|||
| type |
string |
No |
The required field validated by the backend for each binding item. Only |
KNOWLEDGE_BASE |
| resourceId |
string |
No |
The required field validated by the backend for each binding item. Null, blank, or control characters are not accepted. The backend trims leading and trailing spaces and then validates that the length is 1 to 128 characters. The first character must be a letter or digit, and the remaining characters can contain letters, digits, periods, hyphens, or underscores. Only resources in the current workspace can be referenced. |
kb-example |
| agenticFsMounts |
array<object> |
No |
The NAS storage mount configuration. Currently, only the AgenticFS type is supported, which is used to mount file directories in access points to agent runtime instances. The list of AgenticFS directory mounts. The total number of AgenticFS mounts and |
|
|
object |
No |
|||
| server |
string |
No |
The access point domain name. This is a required field validated by the backend for each mount item. It does not contain a protocol, port, or path. Use the |
ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com |
| path |
string |
No |
The existing non-empty relative directory under the access point. This is a required field validated by the backend for each mount item. Root directories, absolute paths, or parent directory segments are not allowed. |
workspace/data |
| mountPath |
string |
No |
The absolute mount path in the container, such as |
/mnt/agenticfs/data |
| readOnly |
boolean |
No |
Specifies whether the mount is read-only. If omitted, the default value is false. This is not the read-only policy of a RAM role. |
false |
| name |
string |
Yes |
The name of the managed Harness agent. |
my-agent |
| description |
string |
No |
The description of the managed Harness agent. |
Agent for code review |
| accessMode |
string |
No |
The inbound access mode. Valid values:
|
API_KEY |
| accessScope |
string |
No |
The user access scope. Valid values:
|
ALL |
| harness |
object |
No |
The runtime framework object. If omitted, the default value is qwenpaw. Supported values are qwenpaw and qodercli. The type cannot be changed after creation. |
|
| type |
string |
No |
The runtime framework type. This field is required when Valid values:
|
qodercli |
| configuration |
object |
No |
The runtime framework configuration. |
|
| connectorServiceAccountKey |
string |
No |
The account key record ID in the qodercli connector. You can query it by using |
key-example |
| connectorServiceAccountName |
string |
No |
The connector account name bound to qodercli. Do not specify this parameter for qwenpaw. |
my-connector-key |
| model |
object |
Yes |
The model configuration. |
|
| modelConnectionId |
string |
Yes |
For qwenpaw, use the workspace model connection ID. For qodercli, use the available model identifier returned by |
mc-1 |
| modelName |
string |
No |
For qwenpaw, use the name of the upstream model created under the model connection. This parameter is required. For qodercli, this parameter can be omitted. |
qwen-max |
| quota |
object |
No |
The model token quota configuration. If this parameter is not passed, no quota is configured. |
|
| enabled |
boolean |
No |
Specifies whether to enable the token quota. If not specified, the default value is true. If set to false, the quota is disabled and existing quota rules are deleted. |
true |
| limitType |
string |
No |
The quota limit type. This field is required and validated by the backend when the quota is enabled. Fixed value: token. Valid values:
|
token |
| usageLimit |
integer |
No |
The maximum number of tokens allowed to be consumed in a single period. This field is required and validated by the backend when the quota is enabled. The value must be greater than 0. |
1000000 |
| periodType |
string |
No |
The statistical period of the quota. This field is required and validated by the backend when the quota is enabled. Valid values: day (daily) and month (monthly). Valid values:
|
day |
| thinkingLevel |
string |
No |
Valid values: off, low, medium, high, xhigh, and max. If not passed or set to null during creation, the default value is used. When updating and submitting the model configuration, if the thinking level is not passed or is null, it is restored to the default value. Except for off, which is converted to none, the value is passed to the runtime framework as is. The system does not validate model support or automatically downgrade the level. If the model does not support the specified level, adjust the level. Valid values:
|
high |
| instruction |
string |
No |
The agent instruction, which is used to guide the behavior of the agent. |
You are a code review assistant |
| promptVariables |
array<object> |
No |
The prompt variable declaration. |
|
|
object |
No |
|||
| name |
string |
No |
The variable name. |
brand |
| defaultValue |
string |
No |
The default value. |
default |
| description |
string |
No |
The variable description. |
desc |
| tools |
array<object> |
No |
The list of tool configurations. |
|
|
object |
No |
|||
| name |
string |
Yes |
The name of the tool. |
code-reviewer |
| type |
string |
Yes |
The type of the tool. Valid values:
|
MCP |
| skills |
array<object> |
No |
The list of skill configurations. |
|
|
array<object> |
No |
|||
| name |
string |
Yes |
The name of the skill. |
code-analysis |
| version |
string |
No |
The skill version field for backward compatibility with legacy requests. For new requests, use sourceType and versionSelector. Do not submit this field in combination with sourceType. |
1.0.0 |
| sourceType |
string |
No |
The source type of the skill. Valid values:
|
REFERENCE |
| versionSelector |
object |
No |
The version selector for the skill reference. Supports LABEL for tags and VERSION for specific versions. Defaults to LABEL/latest when omitted. Not applicable for STATIC sources. |
|
| type |
string |
No |
The type of the version selector. Valid values:
|
LABEL |
| value |
string |
No |
The value of the selector. For LABEL, specify the tag name, such as latest. For VERSION, specify the exact version number. |
latest |
| subAgents |
array<object> |
No |
The list of sub-agent configurations. |
|
|
array<object> |
No |
|||
| name |
string |
Yes |
The name of the sub-agent. |
reviewer-agent |
| instruction |
string |
Yes |
The instruction for the sub-agent. |
Review the code |
| skills |
array<object> |
No |
The list of skills for the sub-agent. |
|
|
object |
No |
|||
| name |
string |
No |
The name of the skill. |
web-search |
| version |
string |
No |
The version of the skill. |
1.0.0 |
| template |
object |
No |
The agent template configuration. |
|
| aiRegistry |
object |
No |
The AI registry template configuration. |
|
| name |
string |
Yes |
The name of the template in the AI registry. |
code-review-template |
| version |
string |
No |
The version of the template in the AI registry. |
1.0.0 |
| runtime |
object |
Yes |
The runtime configuration. You must provide both compute and sessionPolicy. Omitted fields in hpa use default values. |
|
| compute |
object |
Yes |
The compute configuration. |
|
| computeClass |
string |
Yes |
The compute specification. Valid values:
|
STANDARD |
| sessionPolicy |
object |
Yes |
The session policy configuration. |
|
| type |
string |
Yes |
The type of the session policy. Valid values:
|
DISABLED |
| headerName |
string |
No |
The name of the request header used for session identification. Required when type is set to ISOLATED_HEADER_FIELD. Must be a valid HTTP request header name. Do not specify this parameter for other policy types. |
X-Session-Id |
| hpa |
object |
No |
The elastic scaling and session configuration. Omitted fields use default values. To retain the original policy during an update, submit the complete hpa object or omit the entire runtime object. |
|
| enabled |
boolean |
No |
Specifies whether to enable elastic scaling. Default value: false. |
|
| minSandboxCount |
integer |
No |
The minimum number of instances. Valid values: 0 to 100. Default value: 1. The value cannot be greater than maxSandboxCount. |
1 |
| maxSandboxCount |
integer |
No |
The maximum number of instances. Valid values: 0 to 100. Default value: 10. The value cannot be less than minSandboxCount. |
3 |
| maxConcurrentSessionsPerSandbox |
integer |
No |
The maximum number of concurrent sessions allowed per instance. Valid values: 1 to 20. Default value: 20. |
20 |
| sessionTtlSeconds |
integer |
No |
The maximum idle time for a session, in seconds. Valid values: 60 to 86400. Default value: 600. |
3600 |
| environment |
object |
No |
The environment configuration. |
|
| variables |
array<object> |
No |
The list of environment variables. |
|
|
object |
No |
|||
| name |
string |
Yes |
The name of the environment variable. |
API_KEY |
| value |
string |
Yes |
The value of the environment variable. |
sk-xxxx |
| credentialReferences |
array<object> |
No |
The list of credential references. |
|
|
object |
No |
|||
| credentialId |
string |
Yes |
The ID of the credential. |
cred-1 |
| network |
object |
No |
The runtime network configuration. If provided, you must include both accessInternet.enabled and accessVpc.enabled. Actual access is subject to workspace network restrictions. |
|
| accessInternet |
object |
No |
The public network access configuration. |
|
| enabled |
boolean |
No |
Specifies whether to allow Internet access. |
false |
| accessVpc |
object |
No |
The VPC access configuration. |
|
| enabled |
boolean |
No |
Specifies whether to allow VPC access. |
true |
| ossMounts |
array<object> |
No |
The list of OSS directory mounts. The total number of items in this list and agenticFsMounts cannot exceed 10. Updates replace the entire list. Pass an empty array [] to clear the list. |
|
|
object |
No |
|||
| bucketName |
string |
No |
The name of the OSS bucket. This field is required for each mount item and is validated by the backend. |
bucket-001 |
| path |
string |
No |
The non-empty relative object directory prefix in the bucket. This field is required for each mount item. |
datasets |
| mountPath |
string |
No |
The absolute mount path in the container, such as |
/mnt/oss/datasets |
| readOnly |
boolean |
No |
Specifies whether the mount is read-only. Default value: false. |
|
| clientToken |
string |
No |
A reserved query parameter. The backend currently does not provide idempotency guarantees, such as deduplication or recovery of the original processing result based on this token. |
client-token-1 |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The information about the managed Harness agent after creation. |
||
| requestId |
string |
The request ID. |
1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| message |
string |
The request processing result message. |
success |
| httpStatusCode |
integer |
The HTTP status code. A value of 200 indicates success. |
200 |
| code |
string |
The business status code. A value of SUCCESS indicates success. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
true |
| data |
object |
The information about the managed Harness agent after creation. |
|
| contextConfiguration |
object |
The target configuration accepted by the managed agent, which does not mean it has taken effect at runtime. This field is used in the detail responses of CreateManagedAgent, UpdateManagedAgent, and GetManagedAgent. In the configuration of a fixed version, it represents the configuration snapshot saved for that version. A returned object with enabled:false indicates that the configuration is disabled. The absence of the entire object indicates that the response does not provide the configuration. |
|
| enabled |
boolean |
Read-only. When the configuration object is returned, this field indicates the enabling status of the configuration. A value of false indicates that the configuration is disabled. The absence of the entire configuration object indicates that the response does not provide the configuration, which cannot be treated as false. |
true |
| bindings |
array<object> |
Read-only resource references. This field may be omitted when no selection is made. A disabled configuration can still retain non-empty selections. You cannot determine whether the configuration is enabled solely based on whether the array is empty. |
|
|
object |
|||
| type |
string |
Read-only string. Currently known types are KNOWLEDGE_BASE (knowledge base) and DATA_CONNECTOR (data connector). The response may be extended with new types. The client should retain unknown values and should not fail to parse the entire response due to unknown types. New request types are subject to the actual support scope of the server. |
KNOWLEDGE_BASE |
| resourceId |
string |
The context resource ID in the current workspace. |
kb-example |
| effectiveContextConfiguration |
object |
Read-only. This field is provided only by GetManagedAgent when an effective version exists, and corresponds to the configuration snapshot of effectiveSpecVersion. When a new version is being prepared or fails to be published, it remains the original effective configuration. It is not returned before the first time it takes effect, or in CreateManagedAgent, UpdateManagedAgent, and the configuration of a fixed version. Omission does not mean it is disabled, and the client cannot automatically fill it with enabled:false. |
|
| enabled |
boolean |
Read-only. When the configuration object is returned, this field indicates the enabling status of the configuration. A value of false indicates that the configuration is disabled. The absence of the entire configuration object indicates that the response does not provide the configuration, which cannot be treated as false. |
true |
| bindings |
array<object> |
Read-only resource references. This field may be omitted when no selection is made. A disabled configuration can still retain non-empty selections. You cannot determine whether the configuration is enabled solely based on whether the array is empty. |
|
|
object |
|||
| type |
string |
Read-only string. Currently known types are KNOWLEDGE_BASE (knowledge base) and DATA_CONNECTOR (data connector). The response may be extended with new types. The client should retain unknown values and should not fail to parse the entire response due to unknown types. New request types are subject to the actual support scope of the server. |
KNOWLEDGE_BASE |
| resourceId |
string |
The context resource ID in the current workspace. |
kb-example |
| agenticFsMounts |
array<object> |
The NAS storage mount configuration. Currently, the AgenticFS type is supported, which is used to mount file directories in the access point to the agent runtime instance. For NAS mounts, a maximum of 10 items are allowed in total including ossMounts. |
|
|
object |
|||
| server |
string |
The access point domain name. This is a required field validated by the backend for each mount item. It does not contain a protocol, port, or path. Use the |
ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com |
| path |
string |
The existing non-empty relative directory under the access point. This is a required field validated by the backend for each mount item. Root directories, absolute paths, or parent directory segments are not allowed. |
workspace/data |
| mountPath |
string |
The absolute mount path in the container, such as |
/mnt/agenticfs/data |
| readOnly |
boolean |
Specifies whether the mount is read-only. If omitted, the default value is false. This is not the read-only policy of a RAM role. |
false |
| agentId |
string |
The managed Harness agent ID. |
agent-1 |
| workspaceId |
string |
The workspace ID. |
ws-1 |
| name |
string |
The name of the managed Harness agent. |
my-agent |
| description |
string |
The description of the managed Harness agent. |
Agent for code review |
| status |
string |
The status of the managed Harness agent. Valid values:
|
Running |
| harness |
object |
The agent runtime framework. |
|
| type |
string |
The runtime framework type. Valid values:
|
qodercli |
| configuration |
object |
The runtime framework configuration. |
|
| connectorServiceAccountKey |
string |
The connector account key record ID bound to qodercli, which is not the original service account key. |
key-xxxx |
| connectorServiceAccountName |
string |
The connector account name bound to qodercli. |
my-connector-key |
| version |
string |
Returned only in queries. Currently returns the pool target image tag. It is empty when it cannot be parsed, and cannot be replaced by the agent configuration version. |
202611031754 |
| outdatedInstanceCount |
integer |
Returned only in queries. The server calculates this based on the complete instance distribution, which is not affected by the pagination and filtering of the instance list. It is empty when the image tag is missing, pagination is incomplete, or it cannot be confirmed, which is not equivalent to 0. |
2 |
| latestSpecVersion |
integer |
The latest specification version number. |
1 |
| latestVersionStatus |
string |
The status of the latest version. Valid values:
|
succeeded |
| createMode |
string |
The creation mode. |
Managed |
| deployType |
string |
The deployment type. |
Managed |
| accessMode |
string |
The inbound access mode. Valid values:
|
API_KEY |
| accessScope |
string |
The user access scope. Valid values:
|
ALL |
| createdAt |
string |
The creation time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| updatedAt |
string |
The update time in RFC 3339 format. |
2026-01-01T00:00:00Z |
| regionId |
string |
The region ID. |
cn-hangzhou |
| sandboxPhaseCounts |
object |
The instance counts of managed Harness agents by sandbox phase. Current keys: PENDING (creating or initializing), RUNNING (running), HIBERNATING (hibernating), HIBERNATED (hibernated), RESUMING (resuming), TERMINATING (terminating), and FAILED (failed at runtime). Only phases that actually occur are returned, and missing keys are treated as 0. This field is a dynamic map and new keys may be added in the future. The frontend can use FAILED > 0 to determine whether abnormal instances exist. |
|
|
integer |
The instance count for the corresponding sandbox phase. |
1 |
|
| model |
object |
The model configuration information. |
|
| modelConnectionId |
string |
The model connection ID. |
mc-1 |
| modelName |
string |
The upstream model name. |
qwen-max |
| quota |
object |
The model token quota configuration and usage status for the current period. This field is empty if no quota is configured. |
|
| enabled |
boolean |
Indicates whether the quota is enabled. This field is not returned if no quota is configured. |
true |
| limitType |
string |
The quota limit type. Currently, only token is supported. Valid values:
|
token |
| usageLimit |
integer |
The maximum number of tokens allowed to be consumed in a single period. |
1000000 |
| periodType |
string |
The quota statistical period. A value of day indicates daily, and a value of month indicates monthly. Valid values:
|
day |
| ruleStatus |
string |
The gateway quota rule status. This field is read-only and returned by the backend. |
ACTIVE |
| usedAmount |
integer |
The number of tokens consumed in the current period. This field is read-only and returned by the backend. |
12345 |
| overLimit |
boolean |
Indicates whether the quota is exceeded in the current period. This field is read-only and returned by the backend. |
false |
| thinkingLevel |
string |
The thinking level. If not configured, the value defaults to default. Empty strings, null values, or omitted fields are handled according to the default behavior of the model and Harness. Valid values: off, low, medium, high, xhigh, and max. If this parameter is not passed or is null during creation, default is used. When updating and submitting the model configuration, if the thinking level is not passed or is null, it reverts to default. Except for off, which is converted to none, the value is passed to the runtime framework as-is without validating model support or automatically downgrading. If the model does not support the specified level, adjust the level accordingly. Valid values:
|
high |
| instruction |
string |
The agent instruction, which is used to guide the behavior of the agent. |
You are a code review assistant |
| promptVariables |
array<object> |
The prompt variable declaration. |
|
|
object |
|||
| name |
string |
The variable name. |
brand |
| defaultValue |
string |
The default value. |
default |
| description |
string |
The variable description. |
desc |
| template |
object |
The template configuration information. |
|
| aiRegistry |
object |
The AI registry template configuration. |
|
| name |
string |
The name of the template in the AI registry. |
code-review-template |
| version |
string |
The version of the template in the AI registry. |
1.0.0 |
| runtime |
object |
The runtime configuration information. |
|
| compute |
object |
The compute configuration. |
|
| computeClass |
string |
The compute specification. Valid values:
|
STANDARD |
| sessionPolicy |
object |
The session policy configuration. |
|
| type |
string |
The type of the session policy. Valid values:
|
DISABLED |
| headerName |
string |
The HTTP header name used for session affinity. This field takes effect when sessionPolicy.type is set to ISOLATED_HEADER_FIELD. |
X-Session-Id |
| hpa |
object |
The sandbox auto-scaling and session configuration. |
|
| enabled |
boolean |
Indicates whether elastic auto-scaling is enabled in the current configuration. |
|
| minSandboxCount |
integer |
The minimum number of instances in the current configuration. |
1 |
| maxSandboxCount |
integer |
The maximum number of instances in the current configuration. |
3 |
| maxConcurrentSessionsPerSandbox |
integer |
The maximum number of concurrent sessions per instance in the current configuration. |
5 |
| sessionTtlSeconds |
integer |
The maximum session idle time in the current configuration, in seconds. |
3600 |
| environment |
object |
The environment configuration information. |
|
| variables |
array<object> |
The list of environment variables. |
|
|
object |
|||
| name |
string |
The name of the environment variable. |
API_KEY |
| value |
string |
The value of the environment variable. |
sk-xxxx |
| credentialReferences |
array<object> |
The list of credential references. |
|
|
object |
|||
| credentialId |
string |
The ID of the credential. |
cred-1 |
| network |
object |
The network configuration information. |
|
| accessInternet |
object |
The public network access configuration. |
|
| enabled |
boolean |
Specifies whether to allow Internet access. |
false |
| accessVpc |
object |
The VPC access configuration. |
|
| enabled |
boolean |
Specifies whether to allow VPC access. |
true |
| ossMounts |
array<object> |
The list of OSS mounts. A maximum of 10 items are supported. |
|
|
object |
|||
| bucketName |
string |
The name of the OSS bucket. This field is required for each mount item and is validated by the backend. |
bucket-001 |
| path |
string |
The non-empty relative directory prefix in the configured bucket. |
datasets |
| mountPath |
string |
The absolute mount path in the container, such as |
/mnt/oss/datasets |
| readOnly |
boolean |
Specifies whether the mount is read-only. Default value: false. |
|
| tools |
array<object> |
The list of tool configurations. |
|
|
object |
|||
| name |
string |
The name of the tool. |
code-reviewer |
| type |
string |
The type of the tool. Valid values:
|
MCP |
| skills |
array<object> |
The list of skill configurations. |
|
|
array<object> |
|||
| name |
string |
The name of the skill. |
code-analysis |
| version |
string |
The current target version for legacy client compatibility. New clients use resolvedVersion and determine the effective runtime version based on appliedVersion. |
1.0.0 |
| sourceType |
string |
The source type of the skill. Valid values:
|
REFERENCE |
| versionSelector |
object |
The version selector for the skill reference. Supports LABEL for tags and VERSION for specific versions. Defaults to LABEL/latest when omitted. Not applicable for STATIC sources. |
|
| type |
string |
The type of the version selector. Valid values:
|
LABEL |
| value |
string |
The value of the selector. For LABEL, specify the tag name, such as latest. For VERSION, specify the exact version number. |
latest |
| fromTemplate |
boolean |
Indicates whether the skill is from a fixed template. This field is read-only. Template items cannot be removed. |
false |
| resolvedVersion |
string |
The current target version. This field is read-only. |
1.0.0 |
| appliedVersion |
string |
The effective runtime version. This field is read-only. |
1.0.0 |
| configuredSkills |
array<object> |
The explicitly configured skills. |
|
|
array<object> |
|||
| name |
string |
The name of the skill in the Workspace AI Registry. |
web-search |
| version |
string |
The legacy compatibility field. New requests use sourceType and versionSelector. |
1.0.0 |
| sourceType |
string |
The source type of the skill. Valid values:
|
REFERENCE |
| versionSelector |
object |
The version selector for the skill reference. Supports LABEL for tags and VERSION for specific versions. Defaults to LABEL/latest when omitted. Not applicable for STATIC sources. |
|
| type |
string |
The type of the version selector. Valid values:
|
LABEL |
| value |
string |
The value of the selector. For LABEL, specify the tag name, such as latest. For VERSION, specify the exact version number. |
latest |
| subAgents |
array<object> |
The list of sub-agent configurations. |
|
|
array<object> |
|||
| name |
string |
The name of the sub-agent. |
reviewer-agent |
| instruction |
string |
The instruction for the sub-agent. |
Review the code |
| skills |
array<object> |
The list of skills for the sub-agent. |
|
|
object |
|||
| name |
string |
The name of the skill. |
web-search |
| version |
string |
The version of the skill. |
1.0.0 |
Examples
Success response
JSON format
{
"requestId": "1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": true,
"data": {
"contextConfiguration": {
"enabled": true,
"bindings": [
{
"type": "KNOWLEDGE_BASE",
"resourceId": "kb-example"
}
]
},
"effectiveContextConfiguration": {
"enabled": true,
"bindings": [
{
"type": "KNOWLEDGE_BASE",
"resourceId": "kb-example"
}
]
},
"agenticFsMounts": [
{
"server": "ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com",
"path": "workspace/data",
"mountPath": "/mnt/agenticfs/data",
"readOnly": false
}
],
"agentId": "agent-1",
"workspaceId": "ws-1",
"name": "my-agent",
"description": "Agent for code review",
"status": "Running",
"harness": {
"type": "qodercli",
"configuration": {
"connectorServiceAccountKey": "key-xxxx",
"connectorServiceAccountName": "my-connector-key"
},
"version": "202611031754",
"outdatedInstanceCount": 2
},
"latestSpecVersion": 1,
"latestVersionStatus": "succeeded",
"createMode": "Managed",
"deployType": "Managed",
"accessMode": "API_KEY",
"accessScope": "ALL",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"regionId": "cn-hangzhou",
"sandboxPhaseCounts": {
"key": 1
},
"model": {
"modelConnectionId": "mc-1",
"modelName": "qwen-max",
"quota": {
"enabled": true,
"limitType": "token",
"usageLimit": 1000000,
"periodType": "day",
"ruleStatus": "ACTIVE",
"usedAmount": 12345,
"overLimit": false
},
"thinkingLevel": "high"
},
"instruction": "You are a code review assistant",
"promptVariables": [
{
"name": "brand",
"defaultValue": "default",
"description": "desc"
}
],
"template": {
"aiRegistry": {
"name": "code-review-template",
"version": "1.0.0"
}
},
"runtime": {
"compute": {
"computeClass": "STANDARD"
},
"sessionPolicy": {
"type": "DISABLED",
"headerName": "X-Session-Id"
},
"hpa": {
"enabled": false,
"minSandboxCount": 1,
"maxSandboxCount": 3,
"maxConcurrentSessionsPerSandbox": 5,
"sessionTtlSeconds": 3600
}
},
"environment": {
"variables": [
{
"name": "API_KEY",
"value": "sk-xxxx"
}
],
"credentialReferences": [
{
"credentialId": "cred-1"
}
]
},
"network": {
"accessInternet": {
"enabled": false
},
"accessVpc": {
"enabled": true
}
},
"ossMounts": [
{
"bucketName": "bucket-001",
"path": "datasets",
"mountPath": "/mnt/oss/datasets",
"readOnly": false
}
],
"tools": [
{
"name": "code-reviewer",
"type": "MCP"
}
],
"skills": [
{
"name": "code-analysis",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
},
"fromTemplate": false,
"resolvedVersion": "1.0.0",
"appliedVersion": "1.0.0"
}
],
"configuredSkills": [
{
"name": "web-search",
"version": "1.0.0",
"sourceType": "REFERENCE",
"versionSelector": {
"type": "LABEL",
"value": "latest"
}
}
],
"subAgents": [
{
"name": "reviewer-agent",
"instruction": "Please review the code",
"skills": [
{
"name": "web-search",
"version": "1.0.0"
}
]
}
]
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter.%s | The specified parameter %s is not valid. Reason: %s Expected format: %s | |
| 403 | AgenticFsRamUnauthorized | Authorize the Workspace role for this AgenticFS AccessPoint. | |
| 403 | AgenticFsMountDisabled | New or changed AgenticFS mounts are not enabled. | |
| 404 | AgentSpecNotFound | The referenced AI Registry agent spec %s does not exist. Publish it in AI Registry, or change the agent's template reference. | |
| 404 | SkillNotFound | The referenced AI Registry skill %s does not exist. Publish it in AI Registry, or change the agent's skill reference. | |
| 404 | AgenticFsAccessPointNotFound | The AccessPoint is not available in this Workspace account and region. | |
| 404 | Agent.ContextResource.NotFound | The %s context resource %s does not exist in this workspace. | |
| 503 | AgenticFsIntegrationNotConfigured | The NAS discovery and RAM authorization integration is not configured. | |
| 503 | AgenticFsServiceUnavailable | NAS resource or RAM authorization lookup failed. | |
| 503 | AcrAuthorizationServiceUnavailable | Workspace role authorization verification is unavailable. | |
| 503 | Agent.Context.Unavailable | Context resource lookup is unavailable. | |
| 409 | AgenticFsPrerequisiteNotReady | AgenticFS requires an active RAM-enabled AccessPoint and user VPC access. | |
| 409 | AcrRoleConflict | Workspace resource roles conflict; contact the administrator. | |
| 409 | Agent.ContextResource.NotReady | The %s context resource %s is not ready to be associated with an agent. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.