CreateManagedAgent

Updated at:
Copy as MD

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

HarnessModel and connector configurations
qwenpawIf 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.
qodercliThe 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:

FieldDefault valueValid values and description
enabledfalseSpecifies whether to enable elastic scaling.
minSandboxCount1The minimum number of instances. Valid values: 0 to 100.
maxSandboxCount10The maximum number of instances. Valid values: 0 to 100. The value cannot be less than the minimum number.
maxConcurrentSessionsPerSandbox20The maximum number of concurrent sessions per instance. Valid values: 1 to 20.
sessionTtlSeconds600The 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

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

agentcore:CreateManagedAgent

create

*ManagedAgent

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/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 and bindings are allowed. Null, JSON character strings, or the legacy contextSpaceId field is not accepted. If the entire object is omitted, the server-side default configurations are used, which is typically disabled. Pass {} or {enabled:false} to explicitly keep it disabled. If enabled is set to true, you must select at least one resource in the current workspace. Non-empty bindings are validated for resource ownership and readiness even when disabled. Platform-managed context channels are not configured through regular tools.

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 bindings can be reused. The merged enabled configuration must contain at least one resource. When updated to false, the resources are only disabled, and the original resource selection is not cleared.

true

bindings

array<object>

No

The optional array. Null or null items are not accepted. Each item only allows type and resourceId. The combination of the same type and normalized resource ID cannot be duplicated. If omitted during creation, no resource is selected. If omitted during an update, the original selection is retained. A non-empty array replaces the entire selection. An empty array can only clear the selection when the merged enabled value is false. To disable and clear the selection at the same time, pass enabled:false and bindings:[]. Explicitly submitted non-empty selections are validated for resource ownership and readiness, including selections saved when disabled.

object

No

type

string

No

The required field validated by the backend for each binding item. Only KNOWLEDGE_BASE (knowledge base) or DATA_CONNECTOR (data connector) is accepted. The value is case-sensitive. Null or blank values are not accepted.

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 ossMounts cannot exceed 10. If omitted or set to [] during creation, no mount is configured. If omitted during an update, the original mounts are retained. If set to [] during an update, the mounts are cleared. Null is not accepted.

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 DomainName from the NAS ListAccessPoints response.

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 /data/train. Mount targets cannot be duplicated or form parent-child overwrites, and must avoid platform-reserved directories.

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

    API key authentication.

  • USER :

    User identity.

API_KEY

accessScope

string

No

The user access scope.

Valid values:

  • ALL :

    All scopes.

  • SPECIFIED :

    Specified scope.

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 harness is provided. Valid values: qwenpaw and qodercli.

Valid values:

  • qwenpaw :

    qwenpaw runtime framework.

  • qodercli :

    qodercli runtime framework.

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 ListConnectors. It is not the original key. This parameter can be omitted if there is only one record, but must be specified if there are multiple records. Do not specify this parameter for qwenpaw.

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

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 :

    Limit by token count.

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:

  • month :

    Monthly statistics.

  • day :

    Daily statistics.

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:

  • off
  • low
  • medium
  • high
  • xhigh
  • max

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 :

    MCP service.

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 :

    References an AI Registry asset.

  • STATIC :

    Statically provided with the deployment artifact.

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:

  • VERSION :

    Selects by specific version.

  • LABEL :

    Selects by tag.

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:

  • HEAVY :

    High specification (4 vCPUs, 8 GiB).

  • INTERACTIVE :

    Interactive specification (1 vCPU, 2 GiB).

  • STANDARD :

    Standard specification (2 vCPUs, 4 GiB).

STANDARD

sessionPolicy

object

Yes

The session policy configuration.

type

string

Yes

The type of the session policy.

Valid values:

  • DISABLED :

    Disabled.

  • AFFINITY :

    Session affinity.

  • ISOLATED_HEADER_FIELD :

    Isolates sessions by a specified request header.

  • ISOLATED_COOKIE :

    Isolates sessions by a cookie.

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 /data/train. Mount targets cannot be duplicated or form parent-child overwrites, and must avoid platform-reserved directories.

/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 DomainName from the NAS ListAccessPoints response.

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 /data/train. Mount targets cannot be duplicated or form parent-child overwrites, and must avoid platform-reserved directories.

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

  • Creating :

    Creating.

  • Failed :

    Failed.

  • Running :

    Running.

  • Updating :

    Updating.

  • Deleted :

    Deleted.

  • Deleting :

    Deleting.

Running

harness

object

The agent runtime framework.

type

string

The runtime framework type.

Valid values:

  • qwenpaw :

    qwenpaw runtime framework.

  • qodercli :

    qodercli runtime framework.

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:

  • waiting_retry :

    Waiting for retry.

  • pending :

    Pending.

  • processing :

    Processing.

  • failed :

    Failed.

  • superseded :

    Superseded by a new version.

  • succeeded :

    Succeeded.

succeeded

createMode

string

The creation mode.

Managed

deployType

string

The deployment type.

Managed

accessMode

string

The inbound access mode.

Valid values:

  • API_KEY :

    API key authentication.

  • USER :

    User identity.

API_KEY

accessScope

string

The user access scope.

Valid values:

  • ALL :

    All scopes.

  • SPECIFIED :

    Specified scope.

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 :

    Limit by token count.

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:

  • month :

    Monthly statistics.

  • day :

    Daily statistics.

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:

  • off
  • low
  • medium
  • high
  • xhigh
  • max

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:

  • HEAVY :

    High specification (4 vCPUs, 8 GiB).

  • INTERACTIVE :

    Interactive specification (1 vCPU, 2 GiB).

  • STANDARD :

    Standard specification (2 vCPUs, 4 GiB).

STANDARD

sessionPolicy

object

The session policy configuration.

type

string

The type of the session policy.

Valid values:

  • DISABLED :

    Disabled.

  • AFFINITY :

    Session affinity.

  • ISOLATED_HEADER_FIELD :

    Isolates sessions by a specified request header.

  • ISOLATED_COOKIE :

    Isolates sessions by a cookie.

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 /data/train. Mount targets cannot be duplicated or form parent-child overwrites, and must avoid platform-reserved directories.

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

    MCP service.

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 :

    References an AI Registry asset.

  • STATIC :

    Statically provided with the deployment artifact.

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:

  • VERSION :

    Selects by specific version.

  • LABEL :

    Selects by tag.

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 :

    References an AI Registry asset.

  • STATIC :

    Statically provided with the deployment artifact.

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:

  • VERSION :

    Selects by specific version.

  • LABEL :

    Selects by tag.

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.